# Vibe Test — Code-Aware Browser Testing Agent (MCP Server)

> npm package: `vibe-testing` | CLI command: `vibe-test`
> An MCP server + CLI for AI-powered browser testing. Gives AI code editors (Claude Code, Cursor, Windsurf, VS Code Copilot, Roo Code) 13 Playwright-based testing tools via Model Context Protocol.

## What is Vibe Test?

Vibe Test is a browser testing agent that reads your codebase, understands every route/form/component, opens a real Playwright browser, explores every interactive element, and reports what works and what breaks — with screenshots.

It works as an **MCP (Model Context Protocol) server** that gives your code editor 13 testing tools, or as a standalone CLI. No internal LLM — the editor's AI is the brain, vibe-test is the hands.

## When to Use

- Test, verify, or QA any web application feature
- Explore a page and find what's broken
- Reproduce or confirm bug fixes
- Generate test coverage reports with screenshots
- Find untested routes and auto-generate test scenarios
- Test login flows, CRUD operations, forms, and navigation
- Iterative testing until coverage thresholds are met

## Installation

```bash
npx vibe-testing@latest init    # auto-detects editors, configures everything
```

Supported editors: Cursor, Claude Code, Windsurf, VS Code (Copilot), Roo Code, Cline, Codex, Devin, Zed

### MCP server config (manual)

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

### CLI

```bash
npx vibe-testing@latest run http://localhost:3000
npx vibe-testing@latest converge http://localhost:3000
```

## MCP Tools (13)

1. `scan_codebase` — Analyze project: routes, forms, existing tests, coverage gaps, generated scenarios. Also returns `route_changes` (new/removed routes since last scan). **Call first.**
2. `get_context` — Return actual source files for a feature (real selectors, field names, API endpoints). **Call before writing test steps.**
3. `login` — Authenticate in a real browser, capture tokens and cookies
4. `scan_page_elements` — Discover all interactive elements on a page
5. `explore_page` — Click every button, fill every input, monitor API calls, report breakage
6. `execute_scenario` — Run a multi-step test scenario with step-by-step screenshots
7. `get_coverage` — View test coverage map and gap analysis
8. `suggest_tests` — Get prioritized, executable test scenarios for untested features
9. `take_screenshot` — Visual verification of any page
10. `generate_report` — HTML report with screenshots (auto-opens in browser)
11. `run_full_test` — All-in-one: scan → execute → explore → report. Includes `snapshot_diff` vs the previous run.
12. `run_converge` — Iterative testing: keeps running follow-up rounds until coverage thresholds met. Includes `snapshot_diff` vs the previous run.
13. `cleanup` — Close browsers and reset session

## Supported Frameworks

Next.js (App Router, Pages Router, src/ variants), React SPA, SvelteKit, Nuxt, Vue + Vite, Express, Fastify. Monorepos (Turborepo, pnpm, yarn, Lerna).

## Key Features

- **Code-aware**: Reads source code to understand real routes, forms, selectors — no guessing
- **Framework detection**: Auto-detects 8+ frameworks and parses their route conventions
- **Self-improving**: Learns working selectors, route timings, and failure patterns across runs
- **Route manifest diffing**: Detects new/removed routes between scans (`.vibe/route-manifest.json`)
- **Run snapshot regression detection**: Detects newly-passing fixes and newly-failing regressions between runs (`.vibe/run-snapshot.json`)
- **No LLM dependency**: Heuristic pass/fail verification — the editor LLM is the brain
- **Screenshot reports**: Interactive HTML reports with step-level screenshots
- **Action blocklist**: Skips destructive actions (delete account, cancel subscription)
- **Persistent auth**: Saves login credentials and reuses sessions across runs
- **HTTP Basic Auth**: Supports `basic` auth strategy for preview-gated staging sites
- **MCP-friendly defaults**: When launched as an MCP server, the browser defaults to headless so editor sessions aren't disrupted

## Technology

TypeScript, Node.js ≥20, Playwright, Model Context Protocol SDK, JSON-RPC stdio. Dockerfile (Node 20 + Chromium) included.

## Links

- GitHub: https://github.com/AishwaryShrivastav/vibe-testing
- npm: https://www.npmjs.com/package/vibe-testing