Vibe Framework

Natural language automation framework with AI-powered element healing for Playwright.

Built on @sdetsanjay/autoheal-locator for intelligent element detection and self-healing capabilities.

Features

• 🗣️ True Natural Language: Write commands ANY way you want
• 🤖 Multi-AI Provider Support: OpenAI, Gemini, Anthropic, DeepSeek, Groq, Grok, and local models
• ⚡ Smart Caching: 95-99% latency reduction on cached runs
• 🎯 Training Mode: Record once, replay forever in CI/CD without AI calls
• 🔧 Self-Healing: Automatically adapts to UI changes via autoheal-locator
• 🎥 Video Recording: Playwright-compatible video recording with HTML embedding
• 🚀 Parallel Testing: Thread-safe execution with file locking (2.5x-3.5x speedup)
• 📊 Rich Reporting: HTML, JSON, CSV, and console reports

Quick Start

Get started with Vibe Framework in 5 minutes!

Prerequisites

• Node.js 16 or higher (Download here)
• npm (comes with Node.js)
• Basic knowledge of Playwright

Step 1: Install Dependencies

Create a new Playwright project or use an existing one:

# Create new Playwright project (if you don't have one)
npm init playwright@latest

# Install Vibe Framework
npm install @sdetsanjay/vibe-framework

# Install dotenv for environment variables
npm install dotenv

Step 2: Get Your API Key

Choose an AI provider (we recommend Groq for getting started):

• Groq (Recommended - Fast & Free): Get API Key
• Gemini (Free Tier Available): Get API Key
• OpenAI (Paid): Get API Key

Step 3: Configure Environment

Create a .env file in your project root:

# Add your API key (choose one)
GROQ_API_KEY=your-groq-api-key-here

Step 4: Create Your First Test

Create a file tests/example.spec.ts:

import { test } from '@playwright/test';
import { vibe } from '@sdetsanjay/vibe-framework';
import dotenv from 'dotenv';

dotenv.config();

test('Login with natural language', async ({ page }) => {
  // Create Vibe session
  const session = vibe()
    .withPage(page)
    .withMode('smart-cache')
    .withAIProvider('GROQ', process.env.GROQ_API_KEY!)
    .build();

  // Navigate to the site
  await page.goto('https://www.saucedemo.com');

  // Use natural language to interact!
  await session.do('type "standard_user" into username field');
  await session.do('type "secret_sauce" into password field');
  await session.do('click the login button');

  // Verify the result
  const result = await session.check('verify products page loaded');
  console.log('Login successful:', result.success);

  // Always cleanup
  await session.shutdown();
});

Step 5: Run Your Test

npx playwright test

That's it! 🎉 You've just run your first natural language test!

What happens:

• First run: AI analyzes the page and finds elements (~1-2 seconds)
• Subsequent runs: Cached selectors used (~0.1 seconds, $0 cost!)

Next Steps

Explore more features:

• Complete Examples - 15+ working examples
• Parallel Testing - Run tests 2.5x-3.5x faster
• Training Mode - Zero-cost CI/CD runs
• Video Recording - Capture test execution
• Advanced Features - Smart caching, reporting, and more

Installation

npm install @sdetsanjay/vibe-framework playwright

Note: Playwright is a peer dependency and must be installed separately.

Complete Examples

See the vibe-framework-demo repository for complete working examples:

• ✅ Basic login flows
• ✅ Advanced element handling (select boxes, alerts, windows)
• ✅ Hybrid Playwright + Natural Language approach
• ✅ Parallel test execution
• ✅ Multiple AI provider configurations
• ✅ Training mode for CI/CD
• ✅ Utility scripts and workflows

Supported AI Providers

Choose the provider that fits your needs:

| Provider | Speed | Cost | Free Tier | Get API Key | |----------|-------|------|-----------|-------------| | Groq | ⚡⚡⚡⚡⚡ Fastest | Free | ✅ Generous | console.groq.com | | Gemini | ⚡⚡⚡⚡ Very Fast | ~$0.03/100 cmds | ✅ Yes | aistudio.google.com | | OpenAI | ⚡⚡⚡ Fast | ~$0.10/100 cmds | ❌ No | platform.openai.com | | DeepSeek | ⚡⚡⚡ Fast | ~$0.01/100 cmds | ✅ Yes | platform.deepseek.com | | Anthropic | ⚡⚡⚡ Fast | ~$0.30/100 cmds | ❌ No | console.anthropic.com | | Local | Varies | Free | ✅ Unlimited | Self-hosted (Ollama, etc.) |

Note: With smart caching, subsequent runs cost $0 regardless of provider!

Environment Configuration

Add API keys to your .env file:

# Choose one or more providers:
GROQ_API_KEY=your_key_here          # Groq (Extremely fast, free tier)
GEMINI_API_KEY=your_key_here        # Google Gemini (Free tier available)
OPENAI_API_KEY=your_key_here        # OpenAI (GPT-4, GPT-4o-mini)
ANTHROPIC_API_KEY=your_key_here     # Anthropic Claude
DEEPSEEK_API_KEY=your_key_here      # DeepSeek
GROK_API_KEY=your_key_here          # Grok

# Or use local models (FREE!)
AUTOHEAL_AI_PROVIDER=LOCAL
LOCAL_MODEL_URL=https://your-tunnel.trycloudflare.com

Parallel Testing

Vibe Framework is thread-safe and supports parallel execution:

# Run with 4 workers (2.5x-3.5x faster)
npx playwright test --workers=4

# Run with 2 workers (safer for CI)
npx playwright test --workers=2

File-based locking prevents cache race conditions during parallel execution.

Configuration Modes

Smart Cache (Default)

Best for development and most test scenarios.

const session = vibe()
  .withPage(page)
  .withMode('smart-cache')
  .build();

Pure AI

Fresh AI analysis every time - most reliable for dynamic content.

const session = vibe()
  .withPage(page)
  .withMode('pure-ai')
  .build();

Training Mode (for CI/CD)

Record selectors once, replay without AI calls.

// Local: Record
const session = vibe()
  .withPage(page)
  .startTraining('my-test-suite')
  .build();

await session.do("click login");
await session.stopTraining();

// CI/CD: Replay
const ciSession = vibe()
  .withPage(page)
  .loadTrainingData('my-test-suite')
  .build();

await ciSession.do("click login"); // Instant, no AI call!

Video Recording (Playwright-Compatible)

Record videos of your tests with multiple modes.

// Create browser context with video
const browser = await chromium.launch();
const context = await browser.newContext({
  recordVideo: {
    dir: './videos',
    size: { width: 1280, height: 720 }
  }
});
const page = await context.newPage();

// Configure Vibe with video recording
const session = vibe()
  .withPage(page)
  .withVideo('retain-on-failure', {  // Keep only failed tests
    dir: './vibe-reports/videos'
  })
  .withReporting({
    html: true,
    includeVideos: true  // Embed in HTML report
  })
  .build();

// Run tests - videos automatically saved and embedded
await session.goto('https://example.com');
await session.do('click login');
await session.shutdown();
await context.close();

Video Modes:

• 'on' - Record all tests
• 'retain-on-failure' - Keep only failed tests
• 'on-first-retry' - Record only retries
• 'off' - No recording (default)

See VIDEO_RECORDING.md for complete documentation.

API Reference

VibeBuilder (Factory)

Create a vibe session using the builder pattern:

const session = vibe()
  .withPage(page)                    // Required: Playwright page
  .withMode('smart-cache')           // Optional: 'pure-ai', 'smart-cache', or custom
  .withAIProvider('GROQ', apiKey)    // Required: AI provider and key
  .withReporting({ html: true })     // Optional: Enable reports
  .withVideo('retain-on-failure')    // Optional: Video recording
  .build();

VibeSession Methods

do(command: string): Promise<VibeResult>

Execute any natural language action.

await session.do("click the login button");
await session.do("type [email protected] into email");
await session.do("select USA from country dropdown");

check(assertion: string): Promise<VibeResult>

Verify a condition.

await session.check("verify dashboard is loaded");
await session.check("the success message is visible");

extract(description: string): Promise<string>

Extract text or value from an element.

const name = await session.extract("user name from header");
const price = await session.extract("total price from cart");

find(description: string): Promise<Locator>

Find an element and return its Playwright locator.

const loginButton = await session.find("login button");
await loginButton.click();

waitUntil(condition: string): Promise<VibeResult>

Wait for a condition to be met.

await session.waitUntil("loading spinner disappears");

shutdown(): Promise<void>

Clean up and generate reports (call at end of test).

await session.shutdown();

Natural Language Examples

// Clicking - any phrasing works!
await session.do("click the login button");
await session.do("press the submit button");
await session.do("hit that blue checkout button");

// Typing
await session.do("type [email protected] into email");
await session.do("fill the password with secret123");
await session.do("enter John in the first name field");

// Selecting
await session.do("select USA from country dropdown");
await session.do("choose Premium from plan options");

// Navigation
await session.do("click on the Settings link");
await session.do("navigate to the Profile tab");

Supported AI Providers

| Provider | Speed | Cost | Free Tier | Best For | |----------|-------|------|-----------|----------| | Groq | ⚡⚡⚡⚡⚡ Fastest | Free | ✅ Generous | Development, CI/CD | | Gemini | ⚡⚡⚡⚡ Very Fast | ~$0.03/100 cmds | ✅ Yes | Development | | OpenAI | ⚡⚡⚡ Fast | ~$0.10/100 cmds | ❌ No | Production | | DeepSeek | ⚡⚡⚡ Fast | ~$0.01/100 cmds | ✅ Yes | Budget-friendly | | Anthropic | ⚡⚡⚡ Fast | ~$0.30/100 cmds | ❌ No | High accuracy |

Cost with caching: Subsequent runs cost $0 regardless of provider!

Documentation

• API Reference - Complete API documentation
• Parallel Testing Guide - Thread-safe parallel execution
• Video Recording Guide - Video recording configuration
• Demo Repository - Working examples

Requirements

• Node.js 16+
• Playwright 1.40+ (peer dependency)
• TypeScript 5.2+ (for TypeScript projects)
• AI API key (Groq or Gemini recommended for free tiers)

Dependencies

This package automatically installs:

• @sdetsanjay/autoheal-locator - AI-powered element healing
• dotenv - Environment variable management
• proper-lockfile - Thread-safe file locking
• uuid - Unique identifier generation

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Author

Sanjay Gorai

License

MIT - see LICENSE file for details