vibe-testing

Code-aware browser testing for AI coding agents.

Product site · npm · MCP Registry · Launch status

vibe-testing reads your codebase so tests use your real routes and field names, runs them in a real Playwright browser, remembers what broke, and tells you what your last change fixed or regressed. It works as an MCP server that gives your editor (Claude Code, Cursor, Windsurf, VS Code Copilot, Roo Code) 14 testing tools, or as a standalone CLI.

The repository is also an Agent Plugin with a release-qa skill. Compatible agents get both the testing tools and a senior-QA workflow for coverage, evidence, regression checks, and a clear release verdict.

cd /path/to/your/project
npx vibe-testing@latest init

Then open your editor and say:

"Scan this codebase and test it against http://localhost:3000"

What code-aware testing adds

Playwright MCP gives your agent hands. vibe-testing gives it a testing workflow: code-derived scenarios, memory across runs, and a report. Two things a stateless browser tool cannot do:

1. Run it twice and it tells you what you broke. Every run writes .vibe/run-snapshot.json and diffs it against the previous run. Every scan writes .vibe/route-manifest.json and diffs your routes. The second run prints regressions and fixes instead of a wall of results:

Changes since last run
  Fixed:      /login
  Regression: /checkout
  New:        /admin/users

The same diff reaches your editor as snapshot_diff on run_full_test and run_converge, and as route_changes on scan_codebase, so the agent can flag "checkout broke after that commit" without anyone scrolling a report. Flaky routes, working selectors, and measured timeouts are also remembered between runs.

2. Zero LLM calls inside the tool. Pass/fail verification is heuristic: URL changes, toast detection, API errors. Your editor's model decides what to test; vibe-testing does the browsing and checking. No API key, no per-run cost beyond the editor subscription you already pay for.

Contents

• How it works
• MCP setup (per editor)
• MCP tools reference
• Recommended workflow
• init command
• CLI commands
• VIBE.md, project guidance
• Configuration (vibe.config.json)
• Supported frameworks
• Memory and regression detection
• FAQ

How it works

npx vibe-testing@latest init
        |
Registers 14 MCP tools in your editor
        |
You ask: "Test the checkout flow"
        |
AI calls: scan_codebase -> get_context("checkout") -> login -> explore_page -> execute_scenario -> generate_report
        |
HTML report opens in browser with screenshots of every step

No test cases to write. The AI reads your source code to understand real field names and routes, opens a browser, tests everything, and shows you what's broken.

init also:

• Detects which AI editors you have installed
• Registers vibe-test in global editor configs (~/.claude/settings.json, ~/.cursor/mcp.json, and so on) so the tools are available in every project, every session
• Creates project-level MCP configs and AI instruction files
• Auto-detects your app's URL (reads .env, vite.config, framework defaults)
• Creates VIBE.md (edit with your test credentials) and vibe.config.json
• Installs the matching Playwright Chromium build

MCP setup

Agent Plugin

Install this repository as a plugin when your agent supports the Agent Plugins standard. It includes the portable release-qa skill and starts the published npm MCP server with no API key.

• Cursor: submit or install https://github.com/AishwaryShrivastav/vibe-testing as an Agent Plugin.

• Claude Code:

  Terminal

  Copy

  claude plugin marketplace add AishwaryShrivastav/vibe-testing
  claude plugin install vibe-testing@vibe-testing
  

• Other compatible agents: load the repository root containing plugin.json, skills/, and mcp.json.

The direct MCP and CLI setup below remains available for editors without plugin support.

MCPB bundle

Claude Desktop and other MCPB hosts can install one local bundle. Build and validate it from this repository:

npm ci
npm run build:mcpb

The artifact is written to artifacts/vibe-testing-<version>.mcpb. See the MCPB distribution guide for the bundle contents, validation steps, Smithery handoff, and the one-time Playwright Chromium prerequisite.

Option 1: automatic (recommended)

npx vibe-testing@latest init

Detects and configures all installed editors. Done.

Option 2: manual per editor

Claude Code

Add to ~/.claude/settings.json (global, works in every project):

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

Or add to .mcp.json in your project root (project-level only):

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

Roo Code / Cline

Add to .roo/mcp.json:

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

From local build (development)

{
  "mcpServers": {
    "vibe-test": {
      "command": "node",
      "args": ["/path/to/vibe-testing/dist/mcp-server.js"]
    }
  }
}

MCP tools reference

14 tools available to your AI editor after setup:

Tool inputs

scan_codebase

{
  "codebase_path": "/path/to/project",
  "url": "http://localhost:3000",
  "mode": "deep"
}

get_context

{ "feature": "login" }
{ "feature": "/checkout" }
{ "feature": "user profile form" }

login

{
  "email": "test@example.com",
  "password": "TestPass123!",
  "login_url": "/login"
}

scan_page_elements / explore_page

{
  "route": "/dashboard",
  "authenticated": true
}