Vibe Testing
You can use this MCP server to perform code-aware, browser-based testing of web applications from an AI editor or CLI.
Scan a codebase to discover routes, forms, components, existing tests, coverage gaps, and generate test scenarios.
Configure a project by detecting its framework, running server, and authentication method.
Retrieve relevant source files for a feature or route so test steps use real selectors and field names.
Log in and reuse saved credentials for authenticated browser sessions.
Inspect pages for interactive elements and explore pages by clicking, filling forms, testing tabs, and observing API calls and failures.
Execute custom test scenarios with steps such as navigate, fill, click, select, wait, assert, and upload.
Check coverage, find untested routes, and get prioritized test suggestions.
Run complete end-to-end test suites or iterative convergence runs until pass-rate and coverage-gap thresholds are met.
Take screenshots, generate HTML reports, detect regressions with snapshot diffs, and clean up browser sessions.
Integrates with Windsurf (powered by Codeium) to provide browser testing capabilities: codebase scanning, scenario execution, and automated report generation.
Enables GitHub Copilot (VS Code) to perform browser-based testing of web applications, including login, element exploration, and full test run.
vibe-testing
Code-aware browser testing for AI coding agents.
Product site · npm · MCP Registry · Smithery · Privacy · Launch status
Listed in Awesome MCP Servers. The download badge shows npm's cumulative package downloads; npx package fetches contribute to that total.
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 initThen open your editor and say:
"Scan this codebase and test it against http://localhost:3000"
No source code? Point it at a URL from an empty folder and it tests the app black-box:
npx vibe-testing@latest run https://staging.example.comIt finds bugs you didn't write a test for
While it explores, vibe-testing checks for server crashes, console errors, broken values (NaN, [object Object], Invalid Date), totals that don't match their line items, saved values that never appear, a logout that doesn't end the session, and one user opening another user's pages. No scenarios to write.
Measured on intentionally buggy apps (0.5.0, details in #13):
App | Mode | Before | 0.5.0 |
react-simple-project (7 planted functional bugs) | with source code | 1 of 7 | 7 of 7 |
react-simple-project | URL only | 0 of 7 | 7 of 7 |
OWASP NodeGoat | with source code | 0 issues |
|
restful-booker-platform (no planted bugs) | both | 3 pages, 4 false errors | 8+ pages, 1 real bug: |
No false findings on these three apps in either mode. Run it against a test environment: exploration creates records and lists every change it made.
Using it on your project? Add the badge:
[](https://github.com/AishwaryShrivastav/vibe-testing)Related MCP server: Vigilis
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/usersThe 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
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 stepNo 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.json,~/.cursor/mcp.json,~/.codex/config.toml, and so on) so the tools are available in every project, every sessionCreates 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) andvibe.config.jsonInstalls 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-testingas an Agent Plugin.Claude Code:
claude plugin marketplace add AishwaryShrivastav/vibe-testing claude plugin install vibe-testing@vibe-testingOther compatible agents: load the repository root containing
plugin.json,skills/, andmcp.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:mcpbThe 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 initDetects Claude Code, Cursor, Codex, Windsurf, VS Code and Roo Code, registers vibe-test in each, and prints what to do next in each editor. It never overwrites a config file it cannot parse, and running it twice changes nothing.
Option 2: one command per editor
Editor | Run this | Then |
Claude Code |
| Start a new |
Codex (CLI, IDE extension, desktop app) |
| Start a new |
VS Code (Copilot) |
| Use Agent mode in Copilot Chat. |
Cursor | Add the JSON below to | Cursor Settings > MCP: check vibe-test is switched on. |
Windsurf | Add the JSON below to | Press Refresh in the Cascade MCP panel. |
Then say to your agent:
"Scan this codebase and test it against http://localhost:3000"
The first run downloads a Chromium build (one-time, roughly 150 MB). npx vibe-testing@latest install-browser does it ahead of time.
Option 3: edit the config file yourself
Claude Code
For every project, the user-scope config is ~/.claude.json (top-level mcpServers). Claude Code does not read MCP servers from ~/.claude/settings.json. For one project, use .mcp.json in the project root, which you can commit for your team:
{
"mcpServers": {
"vibe-test": {
"type": "stdio",
"command": "npx",
"args": ["-y", "vibe-testing@latest", "--mcp"]
}
}
}Claude Code asks you to approve a project-scoped server the first time it sees it.
Codex
Add to ~/.codex/config.toml. The Codex CLI, IDE extension and desktop app share this file:
[mcp_servers.vibe-test]
command = "npx"
args = ["-y", "vibe-testing@latest", "--mcp"]init also writes AGENTS.md, which Codex reads for project instructions.
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": {
"type": "stdio",
"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 | When to call | Returns |
| Start here on a new project. Detects framework, server, and authentication | Structured setup result and idempotent project files |
| Always first. Reads source code, finds routes/forms/tests/gaps | Routes, forms, coverage map, generated scenarios, |
| Before writing test steps. Returns source files for a feature | Actual source code with real field names and selectors |
| When app requires authentication | Post-login screenshot, token state, API calls observed |
| To see all interactive elements on a page | Element list with selectors plus page screenshot |
| Broad "does everything work?" testing | Interaction results, API calls, |
| Run specific test steps | Step-by-step logs plus screenshots |
| View coverage map and untested routes | Coverage entries, gaps, available scenarios |
| Find coverage gaps after exploration | Prioritized, ready-to-run scenarios with steps |
| Quick visual verification | Screenshot of any URL |
| Build HTML report (auto-opens) | Report path plus summary |
| One-shot: scan, execute, explore, report | Full results, |
| Iterative testing until thresholds | Summary across all rounds (incl. |
| Close browsers, free resources | - |
explore_page replaces the old errors field with problems (real app failures: server errors, console errors, broken values, functional failures) and diagnostics (vibe-test's own notes, such as navigation or discovery issues). It also returns warnings (possible missing data such as "Category: Unknown"; not failures) and changes_made_to_app (data-changing requests it sent, per explore.writes), and sets isError when there are problems.
Run results (run_full_test, run_converge, generate_report) carry summary.failed_scenarios, a list of { name, route, status, reason } for every failed or errored scenario, alongside explorer_failures, explorer_warnings, retry_findings and app_changes. The Markdown and HTML reports list the same findings.
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
}execute_scenario
{
"scenario": {
"id": "create-item",
"name": "Create a new item",
"route": "/items",
"steps": [
{ "action": "navigate", "url": "/items", "description": "Open items page" },
{ "action": "click", "selector": "text=Add Item", "description": "Open create form" },
{ "action": "fill", "selector": "[name='title']", "value": "Test Item", "description": "Fill title" },
{ "action": "fill", "selector": "[name='description']", "value": "Test description", "description": "Fill description" },
{ "action": "click", "selector": "button[type='submit']", "description": "Submit form" }
],
"expected_outcome": "New item appears in the list",
"requires_auth": true
}
}Step actions: navigate, fill, click, select, wait, assert, upload
CLI and MCP use the same scenario runner. An assert step evaluates every
supplied condition:
selector: the target must be visible. CSS,text=,label=, andplaceholder=are supported; the named locators match exactly.value: visible text must contain this string, on the selected element or on the page body when no selector is supplied.url: the current URL must exactly match this absolute URL or path resolved against the configured base URL, including query and fragment.
For example:
{ "action": "assert", "selector": "#confirmation", "value": "Saved", "url": "/settings", "timeout": 5000, "description": "Check saved settings" }These checks wait up to the step timeout (default 15000 ms per check). A failed
assertion stops the scenario, records a failed step and reason, and returns
status: "fail"; MCP also sets isError: true. Explicit conditions are used as
the verdict after the existing authentication and form API checks. The
description and expected_outcome prose are not executable assertions.
Without selector, value, or url, assert only checks page health: at least
10 characters of visible body text and no nonempty visible error indicators.
This compatibility check does not prove a described business outcome.
upload requires a file-input selector and a nonempty file path in value.
Relative paths resolve against the codebase root. Hidden file inputs are
supported. A missing file, directory, missing target, or target that is not a
file input returns status: "error". The action selects one file using
Playwright; add an assertion of the resulting UI to verify application-side
processing. It does not automate native file-picker dialogs.
Scenarios must contain at least one step. Unknown actions are errors.
take_screenshot
{ "url": "/settings", "authenticated": true, "full_page": false }run_full_test
{ "url": "http://localhost:3000", "codebase_path": "/path/to/project", "mode": "deep" }run_converge
{
"url": "http://localhost:3000",
"max_followup_rounds": 4,
"target_pass_rate": 0.92,
"max_high_severity_gaps": 2
}Recommended workflow
Full test session
Tell your AI editor:
Scan this codebase and test it against http://localhost:3000.
Log in with test@example.com / pass123. Explore the dashboard and
settings pages, run the suggested tests, and generate a report.The AI will:
scan_codebase, to understand routes, forms, existing testsget_context("login"), to read the actual login form source codelogin, to authenticate in a real browserexplore_page("/dashboard"), clicking everything and observing what breaksexplore_page("/settings"), samesuggest_tests, to find coverage gapsexecute_scenariox N, running targeted test flowsgenerate_report, HTML report opens automaticallycleanup, closing browsers
Test a specific feature
Test the checkout flow using vibe-test. Get context for checkout,
then run the full purchase flow with card number 4242424242424242.The AI will:
scan_codebase(if not already done)get_context("checkout"), readingCheckoutForm.tsx,api/orders/route.tsand so onloginexecute_scenario, filling the real form fields from source codegenerate_report
Verify a bug fix
I fixed the login redirect bug. Use vibe-test to confirm it's working.The AI will:
login, testing the login flowtake_screenshot, visual confirmation of the post-login stateReport back what it sees
Find what's broken
Explore every page and tell me what's broken.The AI will run explore_page on every route, collecting API errors, broken elements, and failed interactions, then suggest_tests with the broken items marked as high priority.
init command
npx vibe-testing@latest init [options]What it creates:
File | Where | Purpose |
| Project root | Claude Code MCP config (project-level) |
| Global | Claude Code MCP config, user scope (all projects) |
| Global | Codex MCP config (CLI, IDE extension, desktop app) |
| Project root | Cursor MCP config |
| Global | Cursor MCP config (all projects) |
| Project | Cursor rules, |
| Project | Windsurf instructions |
| Global | Windsurf MCP config (all projects) |
| Project | VS Code Copilot MCP config |
| Project | GitHub Copilot instructions |
| Project | Roo Code MCP config |
| Project | Claude Code session instructions |
| Project | Universal agent instructions (Codex, Devin, Zed) |
| Project | Test guidance, edit with your credentials |
| Project | Config, URL auto-detected from your project |
Options:
npx vibe-testing@latest init # auto-detect editors, register globally + project
npx vibe-testing@latest init --no-global # project-level only, skip global registration
npx vibe-testing@latest init --skip-browser-install
npx vibe-testing@latest init --editor cursor # only configure Cursor
npx vibe-testing@latest init --editor claude-code windsurf
npx vibe-testing@latest init --editor codex # register Codex even if ~/.codex is not there yetAfter init, edit VIBE.md with your login URL and test credentials.
CLI commands
# Set up in current project
npx vibe-testing@latest init
# Install or repair the matching browser build
npx vibe-testing@latest install-browser
# Run tests against a URL
npx vibe-testing@latest run http://localhost:3000
npx vibe-testing@latest run https://staging.myapp.com --mode deep
npx vibe-testing@latest run http://localhost:3000 --codebase /path/to/project --scope /login /dashboard
# After a small change: test what changed thoroughly, everything else lightly
npx vibe-testing@latest run http://localhost:3000 --mode auto
npx vibe-testing@latest run http://localhost:3000 --mode changed --since main
# Iterative testing until coverage thresholds
npx vibe-testing@latest converge http://localhost:3000
npx vibe-testing@latest converge http://localhost:3000 --max-rounds 6 --target-pass-rate 0.95
# Open last report in browser
npx vibe-testing@latest report
# Reset memory and screenshots for a clean run
npx vibe-testing@latest resetrun options
Option | Default | Description |
| config file, else | How much to test each page; see Test depth and modes |
| last run | For |
| - | Run browser headless (default: visible) |
| cwd | Path to project root |
| all | Test only specific routes |
|
| Config file path |
run and converge fail with a nonzero exit when no scenarios are discovered
or an execution batch is empty. MCP run_full_test and run_converge return
isError: true for these cases. Empty runs do not write a successful run
snapshot or replace the prior report.
converge options
Option | Default | Description |
|
| Max follow-up rounds after baseline |
|
| Stop when pass rate reaches this (0-1) |
|
| Stop when critical plus important gaps fall to this |
VIBE.md, project guidance
Create VIBE.md in your project root. vibe-testing reads it automatically on every run.
## Login URL
/login
## Test Credentials
- Email: test@example.com
- Password: TestPass123!
## Never Automate
- delete account
- cancel subscription
- [data-testid="danger-zone"]
- .billing-section
## Known Flaky
- /notifications (WebSocket dependent, skip or expect retry)
- /live-feed
## Notes
- Admin panel at /admin, use admin@example.com / adminpass
- Dashboard data loads async, wait for [data-loaded="true"]
- Profile page: click "Edit Profile" before form fields appearSee VIBE.example.md for the full template.
Configuration
vibe.config.json
Created automatically by init with auto-detected URL. Edit as needed:
{
"url": "http://localhost:3000",
"mode": "deep",
"auth": {
"strategy": "credentials",
"login_url": "/login",
"credentials": {
"email": "test@example.com",
"password": "TestPass123!"
}
},
"never_interact": [
"delete account",
"cancel subscription",
"[data-testid='danger-zone']"
],
"scope": {
"include": ["/**"],
"exclude": ["/admin/**", "/api/**"],
"max_routes": 30,
"seed_routes": ["/live/dev-mode-a-now"]
},
"browser": {
"headed": true,
"slowMo": 40,
"timeout": 30000
}
}Key | Description |
| App URL, localhost or staging. Auto-detected by |
|
|
|
|
| Explicit login route for non-standard paths keyword matching would miss |
| Login credentials, used for login and for generated scenarios, persisted across runs |
| More accounts on the same login form: |
| Text patterns or CSS selectors to skip during exploration |
| What exploration may change in the app. |
| Route patterns to include; default |
| Route patterns to exclude from testing (code and crawled pages) |
| For mode |
| Cap how many routes are tested per run |
| Concrete URLs for dynamic-segment routes the parser can't enumerate (e.g. |
|
|
| Milliseconds between actions (useful for debugging) |
| Deprecated and ignored; use |
Test depth and modes
Each page is tested at one of three depths:
Depth | What runs |
light | Load the page; server errors, console errors, broken values and resources, crash text. No clicks or submissions. |
standard | Light, plus tabs, fills, toggles, buttons that don't change data (with the empty-state check), and links checked by request. |
thorough | Everything: data-changing buttons, the in-app journey, totals after actions, create-then-verify, boundary probes, and the logout and cross-user session checks. |
mode decides the depth per page:
| Pages |
| Every page thoroughly. |
| Every page lightly. |
| Pages changed since |
| Only changed and affected pages, thoroughly; nothing else. |
With source code, "changed" comes from version control: files changed since the baseline (plus uncommitted and untracked files) are followed through the import graph to the pages that use them. A page's own file or a component it imports makes it thorough; a file most pages use (layout, context, API client) makes every page standard; a style sheet asks for a light check; a server handler makes the pages that called its endpoint thorough. Without a repository, auto/changed test every page thoroughly and say why. Without source code (black-box), every page gets a light visit and pages whose structure changed since the last run (controls, links, forms, headings, API calls; data and counts are ignored) are tested thoroughly.
In every mode, pages built from one template (same route pattern such as /tutorial/:page, or the same controls under one parent path) are tested thoroughly once and lightly after that, and any page that shows a problem at light or standard depth, or whose scenario failed, is re-tested thoroughly in the same run. The run summary (summary.plan) and the report's "Test plan" section list every page's depth and the reason; nothing is skipped silently.
Supported frameworks
Framework | Routes | API endpoints | Forms |
Next.js App Router | yes | yes | yes |
Next.js Pages Router | yes | yes | yes |
Next.js (src/ variant) | yes | yes | yes |
React SPA (react-router) | yes | - | yes |
Vue + Vite (vue-router) | yes | - | yes |
Nuxt | yes | yes | yes |
SvelteKit | yes | yes | yes |
Express / Fastify | - | yes | yes |
Monorepos (Turborepo, pnpm, Lerna) | yes | yes | yes |
Existing test files are also read to build a coverage map: Jest, Vitest, Playwright, and Cypress suites are all parsed.
Memory and regression detection
vibe-testing learns across runs and stores state in .vibe/:
Working selectors: remembers
[name='email']worked on/login, uses it next runRoute timings: adjusts timeouts based on measured load times
Auth credentials: saved after first login, reused automatically
Flaky routes: tracks high fail-rate routes, marks them for retry
Skip routes: routes that consistently error (need URL params) are auto-skipped
Route manifest (
.vibe/route-manifest.json): every scan diffs against the previous one; new and removed routes surface asroute_changesonscan_codebaseresults so the AI can cover them immediatelyRun snapshot (
.vibe/run-snapshot.json): every run captures per-route pass/fail and diffs against the prior run;snapshot_diffflagsnewly_passing(fixes),newly_failing(regressions),still_failing, plus added and removed routes
{
"snapshot_diff": {
"newly_passing": ["/login"],
"newly_failing": ["/checkout"],
"still_failing": [],
"new_routes": ["/admin/users"],
"removed_routes": []
}
}run_converge returns the same shape, so iterative runs in your editor highlight what you just broke.
Reset with npx vibe-testing@latest reset to start fresh.
What a session looks like
When you ask your editor to "test the login flow", here is what it does:
User: "Test the login flow"
AI calls:
scan_codebase({ codebase_path: ".", url: "http://localhost:3000" })
-> Finds /login route, LoginForm component, POST /api/auth/login endpoint
-> Returns 8 generated test scenarios
get_context({ feature: "login" })
-> Returns src/app/login/page.tsx (has name="email", name="password" fields)
-> Returns src/app/api/auth/login/route.ts (POST handler, returns { token })
-> AI now knows the real selectors: [name='email'], [name='password']
login({ email: "test@example.com", password: "pass123" })
-> Opens Chromium, fills the form, clicks submit
-> Returns: { success: true, final_url: "/dashboard", tokens_found: 2 }
-> Returns screenshot of post-login dashboard
execute_scenario({ scenario: { name: "Login with invalid password", ... } })
-> Returns screenshot showing error state
generate_report()
-> Writes .vibe/report.html, opens in browser
AI reports: "Login works. Invalid password shows an error. All 3 login scenarios passed."FAQ
Does vibe-testing use an LLM internally? No. It uses heuristic verification (URL changes, toast detection, API errors). Your editor's model is the brain: it sees screenshots and decides what to test next. Runs have no API cost.
What's the difference between explore_page and execute_scenario?
explore_page is broad: it clicks every button and input it finds and reports the results. execute_scenario is precise: you give it specific steps and it follows them exactly. Use explore_page to find what's on a page, then execute_scenario to test specific flows.
What's get_context for?
It returns the actual source code for a feature, so the AI knows [name='email'] instead of guessing #email-input. Always call it before writing test steps for a specific feature.
Does it handle SPAs with client-side routing? Yes. Playwright navigates the real browser, so client-side routing (React Router, Vue Router, and the rest) works naturally.
Does it handle login / authentication?
Yes. The login tool fills credentials in a real browser, captures auth tokens from localStorage/cookies, and keeps that session alive for authenticated tests. Credentials are persisted in .vibe/memory/ and reused automatically.
Will it click "Delete Account" or other destructive buttons?
No. Set never_interact in vibe.config.json or VIBE.md to blocklist dangerous actions. Any button whose text or selector matches is skipped during exploration.
Can I use it without an AI editor?
Yes. vibe-test run https://your-app.com runs standalone. It scans, generates scenarios, executes them, and produces an HTML report without needing an editor.
How do I test a staging environment?
Set url in vibe.config.json to your staging URL, or pass it as a CLI argument: npx vibe-testing@latest run https://staging.myapp.com.
Does it work with monorepos?
Yes. init detects Turborepo/pnpm/yarn workspaces and finds the frontend app automatically.
Requirements
Node.js >= 20 (the test suite uses vitest 4.x which requires Node 20+)
Playwright Chromium.
initinstalls the matching build. To install or repair it directly:npx vibe-testing@latest install-browser
run and converge check for the browser before scanning your project and print the same recovery command when it is missing.
Docker
A Node 20 + Chromium image is included for environments that prefer container-based MCP servers:
docker build -t vibe-test .
# wire into your editor's MCP config:
# { "command": "docker", "args": ["run", "--rm", "-i", "vibe-test"] }Contributing
git clone https://github.com/AishwaryShrivastav/vibe-testing.git
cd vibe-testing
npm install
npx playwright install chromium
npm run build # tsc -> dist/
npm run dev # run CLI without building
npm run mcp # run MCP server without building
npm test # unit and isolated integration tests
VIBE_REAL_BROWSER=1 npm test # also run real Chromium CLI/MCP regressionsSee CHANGELOG.md for version history. Bug reports and feature requests: GitHub issues.
License
MIT, Aishwary Shrivastav
Links
Issues: https://github.com/AishwaryShrivastav/vibe-testing/issues
Official MCP registry: listed as
io.github.AishwaryShrivastav/vibe-testingat https://registry.modelcontextprotocol.io
Available Tools
14 toolscleanupA
Close all open browsers and reset the session state. Call when done testing.
Inputs: no named parameters.
configureB
Idempotently configure a project and detect its framework, running server, and authentication method. Existing VIBE.md and vibe.config.json files are preserved.
Inputs: codebase_path (required), url.
execute_scenarioA
Execute a single test scenario (a sequence of navigate/fill/click/assert steps) and return detailed results with step-by-step logs, screenshots after each state-changing step, API errors observed, and the final page state. The editor LLM can construct scenarios based on scan_codebase output or create custom ones.
Inputs: scenario (required), authenticated.
explore_pageA
Perform a full interactive exploration of a page: discover all elements, click buttons, fill inputs, test tabs, observe API calls, and report what happened. Returns detailed interaction outcomes, API observations, "problems" (real failures in the app: server errors, console errors, broken values, functional failures — these mark the result as an error), "diagnostics" (vibe-test's own notes, e.g. navigation issues), "warnings", "changes_made_to_app" (data-changing requests it sent), and a screenshot. This is the "senior tester" mode — it tries every element and reports what works and what breaks.
Inputs: route (required), authenticated.
generate_reportA
Generate a self-contained HTML test report with embedded screenshots from all collected results, explorations, and coverage data. Returns the report path and a summary listing failed scenarios (with reasons), problems found while exploring, retries that need attention, warnings, and changes made to the app — the same findings as run_full_test; it is an error result when a scenario failed or a problem was found. The report includes: pass/fail results per scenario, step-by-step screenshots, element exploration findings, API error monitoring, and coverage gap suggestions. Call this after executing scenarios and explorations. The report auto-opens in the browser.
Inputs: title.
get_contextA
Retrieve the most relevant source files for a given feature or route. Returns actual source code (budget-capped) so you understand real field names, API endpoints, and component structure before writing test steps. Call this after scan_codebase when you want to write precise test scenarios for a specific feature — it eliminates guesswork about selectors and form fields.
Inputs: feature (required), max_files.
get_coverageA
Return the current test coverage map, identified gaps, and suggested tests. Prerequisite: scan_codebase must have been called first. Returns JSON with: coverage entries per route (tested/untested, test frameworks used), gap analysis with priority scores (high/medium/low), and concrete test suggestions for missing coverage. Use this to understand what has been tested and what still needs testing.
Inputs: no named parameters.
loginA
Establish an authenticated browser session by executing a login scenario. Returns the post-login URL, token state, and a screenshot. Uses saved credentials from previous runs if available, or accepts provided credentials.
Inputs: email, password, login_url, identity_field, +1 more.
run_convergeA
Iterative coverage: runs the full baseline suite, then automatically runs follow-up rounds targeting coverage gaps and failed scenarios until pass rate and gap thresholds are met (or max rounds reached). Use for "keep testing until coverage is good". Returns results across all rounds and opens the final HTML report.
Inputs: url (required), mode, since, headed, +4 more.
run_full_testA
Run a complete end-to-end test suite: scan codebase → generate scenarios → execute all → explore pages → generate report. This is the all-in-one command. Returns a summary listing failed scenarios (with reasons), problems found while exploring, retries that need attention, warnings, and changes made to the app; it is an error result when a scenario failed or a problem was found. For more granular control, use the individual tools (scan_codebase, login, explore_page, execute_scenario, generate_report).
Inputs: url, mode, since, headed, +1 more.
scan_codebaseA
Analyze a project's codebase to understand its structure, routes, forms, components, existing tests, and coverage gaps. Returns a ProductModel with routes, behaviours, coverage map, gaps, and generated test scenarios. Call this first before any testing.
Inputs: url (required), codebase_path (required), mode, since.
scan_page_elementsA
Navigate to a specific page and discover all interactive elements (buttons, links, inputs, selectors, checkboxes, tabs). Returns a structured list of elements with their types, text, selectors, and disabled state. Also returns a screenshot of the page. Use this to understand what's on a page before deciding what to test.
Inputs: route (required), authenticated.
suggest_testsA
Analyze codebase features, existing test coverage, and results from previous runs to suggest concrete test scenarios that should be written or executed. Returns prioritized, executable scenario objects with steps. Use this after scan_codebase to understand what testing is missing and get ready-to-run scenarios.
Inputs: route.
take_screenshotA
Navigate to a URL and take a screenshot. Returns the screenshot as a base64 data URI that the editor LLM can see and reason about. Use this for quick visual verification.
Inputs: url (required), full_page, authenticated.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools target clearly distinct phases of the testing workflow, but there are overlapping clusters: run_full_test/run_converge versus the granular pipeline, scan_codebase/get_context/get_coverage/suggest_tests, and scan_page_elements/explore_page/take_screenshot. The descriptions do a good job distinguishing high-level automation from focused inspection, so an agent can usually select correctly.
All tool names use snake_case and are action-oriented, which makes the set predictable. The main minor deviation is that a few tools are single verbs (login, configure, cleanup) rather than the dominant verb_noun pattern.
At 14 tools, the set fits comfortably in the well-scoped range and each tool covers a meaningful part of the testing lifecycle. The all-in-one and granular tools coexist without making the surface feel bloated.
The server covers configuration, authentication, codebase scanning, scenario suggestion/execution, exploration, coverage analysis, reporting, and cleanup, which is a strong lifecycle surface. Minor gaps remain around persistent scenario/test authoring and explicit test-data setup or teardown beyond browser cleanup.
Maintenance
Related MCP Connectors
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Website checker for AI coding agents. Measures your site in a real browser, with evidence.
Write, run and check natural-language browser tests of your web app from your AI assistant.
Browser-backed QA with evidence and fix-ready reports for coding agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server + Chrome extension that gives AI coding agents control of your real browser with existing sessions, logins, and cookies. Works with Cursor, Claude, Windsurf.24154 npm59MIT
- AlicenseNot gradedqualityDmaintenanceAn agentic QA framework that authors, generates, triages, and self-heals Playwright tests for any web app, usable from Claude Code/Desktop as an MCP server or from CI as a CLI.5MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to autonomously interact with and test web applications in a real browser, providing DOM/Accessibility tree extraction, runtime telemetry, screenshot capture, and Markdown test reports.9 npm1MIT
- AlicenseNot gradedqualityAmaintenanceAn MCP server that gives Claude Code a real browser to navigate, click, type, screenshot, and inspect pages via accessibility snapshots. It also runs multi-step test scenarios with assertions, session recording, visual regression, and console/network monitoring from the terminal.106 npmMIT