testpilot-mcp

Vibe test your app. Just describe what to test.

testpilot-mcp is an MCP server that works alongside @playwright/mcp. You describe the feature to test in plain English — Claude handles the rest: scans your codebase, generates a test plan using your real routes and field names, drives the browser, takes screenshots, records pass/fail results, and writes an HTML report.

You: "test the login flow"
  ↓
testpilot   → scans code, finds /login route + LoginForm fields
            → generates a 12-step test plan with real field names
            → instructs Claude to drive the browser
playwright  → navigates, fills forms, clicks, takes screenshots
testpilot   → records every assertion + screenshot
            → writes HTML report with visual proof

Quick start

1. Add both MCP servers to Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "testpilot": {
      "command": "npx",
      "args": ["testpilot-mcp"]
    }
  }
}

2. Start your dev server (npm run dev, pnpm dev, etc.)

3. Open Claude Code and say:

"Scan this project with testpilot, then test the login flow"

That's it. Claude orchestrates everything.

What Claude does (automatically)

tp_scan_project   → framework: react-router, 7 routes, 4 forms detected
tp_start          → session "Login flow" started
tp_get_context    → reads Login.tsx, useAuth.ts (your actual source)
tp_plan           → generates 12 steps with real field names: email, password

── Claude executes using Playwright MCP ──

browser_navigate        → http://localhost:8080/login
browser_take_screenshot → 📸 (page load proof)
tp_assert               → "Login page loaded" ✅ PASS

browser_fill_form       → { email: "test@example.com", password: "SecureTest123!" }
browser_click           → submit button
browser_take_screenshot → 📸 (after submit proof)
tp_assert               → "Form submitted" ✅ PASS

browser_network_requests → POST /api/auth → 200 OK
tp_assert               → "Auth API returned 200" ✅ PASS

browser_snapshot        → confirms redirect to /clients
tp_assert               → "Redirected to dashboard" ✅ PASS

── Edge cases ──

browser_navigate        → /login (fresh)
browser_click           → submit (empty form)
browser_take_screenshot → 📸 (validation errors proof)
tp_assert               → "Empty form shows validation errors" ✅ PASS

tp_end  → PASSED · testpilot-reports/tp-1234567890.html

The HTML report

tp_end writes a self-contained HTML file to ./testpilot-reports/:

• PASSED / FAILED badge at the top
• Project summary: framework, routes scanned, forms, API endpoints
• Assertion table with actual vs. expected values
• Screenshots embedded under each assertion as visual proof
• Full step log with timing

Tools reference

testpilot exposes 6 tools. Playwright MCP handles all browser interactions.

Supported frameworks

Manual workflow (for more control)

tp_scan_project { path: "/absolute/path/to/your/project" }
tp_start { project_path: "/absolute/path/to/your/project", name: "Sprint 4 — Login" }
tp_get_context { feature: "login" }
tp_plan { feature: "login flow", edge_cases: true }

# Claude executes each step, then:
tp_assert { label: "Login page loaded", passed: true, screenshot: "<base64>" }
tp_assert { label: "Form submits successfully", passed: true, screenshot: "<base64>" }

tp_end

Local development

git clone https://github.com/AishwaryShrivastav/testpilot.git
cd testpilot
npm install
npm test   # all 28 integration checks — no browser needed

Point testpilot at the local copy:

"testpilot": {
  "command": "node",
  "args": ["/absolute/path/to/testpilot/src/index.js"]
}

Requirements

• Node.js 18+
• @playwright/mcp — browser driver (Chromium bundled)
• testpilot itself: zero heavy dependencies (MCP SDK + Zod only, ~2 MB)

Contributing

1. Fork → feature branch
2. Edit src/
3. npm test — must pass all 28 checks
4. Pull request

Issues & requests: GitHub Issues

License

MIT