Without it, your agent sees Timeout 5000ms exceeded waiting for getByTestId('checkout'),
guesses a new selector, edits the test and hopes. Or it "fixes" the test around a real bug.
With it, your agent reads the page as it was when the test failed, swaps in a locator
proven unique on that page, re-runs the test, and keeps the edit only if it passes. When the
button is really gone, it tells you it's an app bug.
Diagnose and fix Playwright tests (TS, pytest): CI reports, traces, verified fixes, flaky verdicts.
2026-11-16
스타
—
도구
—
가동 시간
—
run-test ──────┐
load-report ───┴─▶ get-failure ──▶ suggest-fix (apply + re-run) ──▶ green
(CI job report) │ └─ refuses when the element is really gone (app bug)
└─ DOM at failure, failed requests, console errors
every run ──▶ analyze-history (flaky / broken / slow / which commit broke it)
test code ──▶ audit-tests (flake risks, ranked by history, verified rewrites)
red at HEAD ─▶ bisect-failure (runs it across git history, names the breaking commit)
Key features
Fixes are proven, not guessed. Every fix is re-run before it's kept, and undone if the test is still red.
Honest. It won't paper over a real bug to make a test pass.
Works on CI failures too. Load a CI job's report and traces and get the same diagnosis and fixes.
Flakiness with evidence. Names the flaky test, whether it's a race, shared state or test order, and the seed that reproduces it.
Lean. Finding and fixing a broken locator took about 5,300 tokens versus about 7,400
with Playwright MCP plus a shell (benchmark).
Free and open source. MIT, no account, no API key, no telemetry, no paid tier.
🚀 What only this MCP does
Most testing MCPs let an AI drive a browser: Microsoft's Playwright MCP, Chrome DevTools MCP,
ExecuteAutomation's mcp-playwright and the Selenium MCP. They're great for clicking through a
page. None of them, as of October 2026, does the following. This one does:
Capability
What you get
🎯 Find the commit that broke a test
bisect-failure runs the test across your git history, in a temporary worktree that leaves your checkout alone, and names the first bad commit with its diff and the failure
🧪 Flake-risk audit of your test code
audit-tests finds hard waits, one-shot assertions, missing awaits and fragile selectors. It ranks them by how flaky those tests really were, then applies the safe rewrites and re-runs them to prove them
✅ Fixes that prove themselves
suggest-fix swaps in a locator proven unique on the DOM at failure, re-runs the test and reverts if it's still red. It refuses to patch over a real app bug
🔬 Flaky-test verdicts with evidence
diagnose-flaky repeats tests with retries off and tells a race from shared state from test order, naming the test it depends on and the seed that reproduces it
📈 Memory of every run
analyze-history ranks flaky, regressed and broken tests, groups failures by cause, tracks slow tests and names the commit where each one went bad
🏗️ Diagnose CI failures locally
load-report loads a CI job's report and traces (sharded too), so the same diagnosis and verified fixes work on failures from CI
💬 One-click fixes on pull requests
The GitHub Action verifies each fix in CI and posts it as a suggested change reviewers apply with one click
♿⚡ Audits that hand back tests
Accessibility (axe-core) and Web Vitals audits return verified locators for each problem plus a ready regression or budget test
It works alongside a browser MCP rather than replacing it: that one drives the page, and this one
keeps your suite green.
What you can ask
You ask your AI…
It does this
🏃
"Run my tests"
Runs the suite and reports every failure with its file, line, cause and a fix hint. One root cause breaking 30 tests shows up as one problem.
🔍
"Why did this fail?"
Reads Playwright's trace: the page at the moment of failure, the broken request, the console error. No guessing.
🛠️
"Fix it"
Swaps in a locator proven unique on the page, re-runs the test, and undoes the edit if it's still red. If the button is really gone, it tells you it's an app bug instead of hiding it.
🎲
"Is this test flaky?"
Re-runs it many ways (repeated, alone, in random order) and names the exact test and seed that cause the flake.
📈
"What's been breaking lately?"
Keeps a local run history and separates flaky, newly broken and always-broken tests; shows the slowest tests, stability by day and the commit where each test went bad.
☁️
"Why did CI fail?"
Loads the CI job's report (or merges sharded blob reports), maps its paths onto your checkout and finds the traces in the downloaded artifact, so the same diagnosis and fixes work on CI failures.
✍️
"Write a test for this flow"
Walks the steps on the live page first, writes a spec that replays them with assertions on where the flow landed (URL and accessibility snapshot), and runs it once to prove it passes.
♿
"Check this page for accessibility"
Runs axe-core (WCAG 2.2 AA) and returns each problem with a ready-to-paste locator and regression test.
⚡
"Why is this page slow?"
Measures Web Vitals (LCP, CLS, INP, TBT) on desktop or a throttled phone, names the slow element and the elements that jump, and hands back a budget test.
🧪
"Show me the error state"
Mocks API responses (500s, empty lists, slow calls) so the AI can inspect, audit or measure states that are hard to reach.
🔐
"Test the page after login"
Works behind sign-in with saved sessions, headers and click/fill steps, in Chromium, Firefox or WebKit, and can record or replay network traffic from a HAR file.
A project that uses @playwright/test, with a browser installed (npx playwright install chromium)
Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex, Gemini CLI or any other MCP client
Getting started
Fastest: run this in your project root. It adds the server to every client config it finds
(Claude Code, Cursor, VS Code, Gemini CLI, Codex) and installs the agent skill, leaving your
other servers alone:
npx -y playwright-e2e-mcp init # --client all | cursor,vscode … · --dry-run
npx -y playwright-e2e-mcp doctor # checks Node, Playwright, browsers and client setup
Or let your agent do it. Paste this into any coding agent:
The server uses its working directory as the project root. If your client starts it somewhere
else (such as your home directory), add "env": { "PW_MCP_PROJECT_ROOT": "/path/to/your/project" }.
claude mcp add playwright-e2e -- npx -y playwright-e2e-mcp
Download the .mcpb extension from the latest release
and double-click it. It ships its own dependencies, so no Node setup is needed. On install it
asks for your project root: choose the project folder, not your home directory.
You can also add the standard config to claude_desktop_config.json.
Click Install in Cursor,
or go to Settings → MCP → Add new MCP server and paste the standard config. For one
project only, put it in .cursor/mcp.json.
Click the Install in VS Code button above, or run:
Or paste the standard config into .gemini/settings.json (Qwen Code: .qwen/settings.json).
Add the standard config to the client's MCP config file (Cline: MCP Servers → Configure).
Clients that take a command, such as Zed, run npx with the arguments -y playwright-e2e-mcp.
Drop an mcp.json with the standard config into your project's .agents/ folder. This repo
ships one in .agents/mcp.json, so opening the checkout attaches the
server workspace-wide. Freebuff asks you to trust a repository's .agents/ on first run.
Some clients only accept a remote HTTPS server. This repo ships a Streamable HTTP bridge you
can host for free on Vercel, with OAuth sign-in for claude.ai connectors. See
Hosted endpoint. On Vercel the page tools (inspect a page, check
selectors, accessibility and Web Vitals audits) run on a bundled Chromium against public URLs.
Running and fixing your own tests needs your project, so use the local install for that.
Route
How
Skill only, any agent
npx skills add xsignon-secure/E2E
MCP Registry
io.github.xsignon-secure/E2E (listing); registry-aware clients find it there
Straight from GitHub, no npm
npx -y github:xsignon-secure/E2E#v0.6.1 (pin a release tag)
Your agent should run the suite, read the failure, and propose a fix it has re-run. To check the
setup without your own tests, ask it to run examples/sample-test.spec.ts from this repo.
What's new in 0.6
Find the commit that broke a test:bisect-failure runs the test across git history in a
temporary worktree and names the first bad commit, its changes and the failure there.
Flake-risk audit:audit-tests finds hard waits, one-shot assertions, missing awaits and
fragile selectors, ranked by real flakiness, and applies the safe rewrites with a verifying run.
One-click fixes on pull requests: the GitHub Action proves each fix in CI and posts it as a
suggested change.
doctor:npx playwright-e2e-mcp doctor checks Node, Playwright, browsers and client setup.
Structured results: every tool returns JSON next to its Markdown, with output schemas.
Phones, tablets, Chrome and Edge:device presets and channel for every page tool, and a
Docker image on ghcr.io.
Node 22 or newer is now required, and the hosted endpoint limits guessing of its key.
Run Playwright tests and return stats, failures, diagnostics and hints; reports progress, and background: true returns a run id for long suites
get-run-status
Progress or final result of a background run; can wait for it or cancel it
get-failure
Deep analysis of one failure: stack, expected/actual, DOM snapshot at failure (from the Playwright trace), failed requests, console errors, next steps
load-report
Load a run from CI: a JSON report or a folder of sharded blob reports; CI paths are mapped onto the checkout and traces found in the unpacked artifact, so get-failure, suggest-fix and diagnose-flaky work on it, and the run joins the history with its commit
suggest-fix
Patch a failure: a drifted locator is replaced with one proven unique on the DOM at failure, an ambiguous one (strict mode violation) gets the unique locator of the intended match, changed copy gets the new expected text; apply: true writes it, re-runs the test and reverts if still red
inspect-page
Open a URL headlessly (optionally signed in, after steps) and return elements with verified Playwright locators, CSS selectors, visibility, text and console output, or the accessibility snapshot with a ready toMatchAriaSnapshot assertion
list-tests
List available tests (file, line, full title, projects) with filtering
validate-selector
Check a CSS selector, Playwright selector or locator expression against a live page: validity, match count, and a sturdier verified locator for each match
generate-e2e-test
Scaffold a Playwright test from a description using the project's real selectors and verified locators from the live page, or walk a flow step by step on the live page and write a spec that is run once to prove it passes
compare-visual-state
Visual regression: screenshot before/after a change and report what moved and how colors shifted
audit-accessibility
Run axe-core (WCAG 2.2 AA by default) on a page, signed in or after steps, and return violations worst first with verified locators for the offending elements and a regression check
audit-performance
Measure lab Web Vitals (LCP, CLS, TBT, FCP, TTFB, INP during steps), optionally as a throttled phone and the median of several runs; rate them or check budgets, name the LCP and shifting elements as verified locators, list heavy and render-blocking requests, and return a budget test
diagnose-flaky
Run a failing test 2–10 times with retries disabled and return an evidence verdict: CONSISTENTLY FAILING, FLAKY or NOT REPRODUCING; tells parallelism and test-order bugs from races
analyze-history
Rank flaky, regressed and broken tests from the local run history, group failures by cause, list the slowest tests, show stability by day, name the commit where each test went bad, or show one test's timeline
audit-tests
Audit the test code for flake risks (hard waits, one-shot assertions instead of web-first ones, missing awaits, .only, force clicks, networkidle, element handles, layout selectors), ranked by how flaky those tests have been in the run history; fix: true rewrites the mechanical ones, re-runs the files and reverts if they fail
bisect-failure
Find the commit that broke a test: binary-search git history between a good and a bad commit, running the test at each step in a temporary worktree (your checkout is untouched), and report the first bad commit, what it changed and how the test failed
Two prompts package the main workflows for clients that show them as slash commands:
fix-failing-test and triage-flaky-tests.
Every argument and example output is in the tool reference. All tools carry
MCP tool annotations (readOnlyHint, destructiveHint, …), so clients can show accurate safety
prompts.
Only need the fix loop?--tools=core (or PW_MCP_TOOLS=core) exposes six tools and cuts the
tool-definition context by about three quarters. Other profiles: triage, inspect, author.
run-test{ "testFiles": ["tests/checkout.spec.ts"] }, or { "background": true }
for a long suite and get-run-status{ "waitSeconds": 30 } until it finishes. For a
failure from CI, download the job's artifacts and call load-report{ "report": "ci-artifacts/results.json" } instead.
get-failure{ "index": 1 } to read the code frame, expected/actual, the DOM
snapshot at failure, the failed network requests and the page's console errors.
suggest-fix{ "index": 1 } for a locator or copy change: review the diff, then
{ "index": 1, "apply": true } to write it and verify with a re-run. If it reports the
element is missing, fix the app, not the test.
For anything it cannot patch: inspect-page{ "url": "…", "view": "locators" }
(add storageState or actions to reach the right screen), then validate-selector
to prove the new locator before editing.
If a failure looks intermittent: diagnose-flaky{ "runs": 3 } for fresh evidence,
and analyze-history to see how the test behaved across earlier runs
({ "view": "commits" } names the commit where it went bad).
After changing CSS or components: compare-visual-state{ "url": "…", "name": "checkout" }.
Re-run only what failed with run-test{ "lastFailed": true } until green.
To write a new test, find the locators with inspect-page{ "view": "locators" }, then call
generate-e2e-test with a description and the steps of the flow; it walks them on the live
page, writes the spec and runs it once. To check a page's speed or accessibility, use
audit-performance and audit-accessibility.
CI: GitHub Action and ci command
The same diagnosis runs without an agent. playwright-e2e-mcp ci runs the
suite (auto-retry once, so flaky tests are reported as flaky, not failed),
optionally drafts suggest-fix diffs and a flaky verdict for the failures, and
writes one Markdown report to stdout, to --output, and to the GitHub job
summary when GITHUB_STEP_SUMMARY is set. Exit code 0 passed, 1 tests
failed, 2 the run itself failed.
npx -y playwright-e2e-mcp ci --flaky-runs 3 --suggest 2 --output report.md
npx -y playwright-e2e-mcp ci --help
As a GitHub Action, it adds the report to the job summary and keeps one PR
comment up to date when the run fails. On a pull request it also re-runs each
failing test with its suggested fix and posts the fixes that pass as suggested
changes on the failing lines, so a reviewer applies one with the Commit
suggestion button (only on lines the PR changed; the rest stay in the report):
permissions:
contents: read
pull-requests: write # for the PR comment and the suggested fixes
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with: { node-version: 24 }
- run: npm ci && npx playwright install --with-deps chromium
- uses: xsignon-secure/[email protected]
with:
flaky-runs: 3 # 0 skips the flaky verdict
suggest: 2 # suggest-fix diffs for the first 2 failures
# args: --browser chromium tests/checkout
Which tools to expose, as tool names and/or profiles, comma separated (same as the --tools= flag). Profiles: core (run, status, failure, fix, flaky, list), triage (run, status, failure, CI report, flaky, history, test audit, bisect, list), inspect (page, selector, accessibility, performance, visual), author (list, page, selector, generate, run). All sixteen tool definitions cost about 12k tokens of context per request; core costs about 4k (10k and 2.3k with PW_MCP_OUTPUT_SCHEMAS=0)
PW_MCP_OUTPUT_SCHEMAS
on
0 leaves the output schemas out of the tool list to save context. Results still carry structuredContent (see Structured results)
PW_MCP_STORAGE_STATE
—
Default storageState file (inside the project) for the page tools
PW_MCP_SHUFFLE_SEEDS
random
Comma-separated seeds for diagnose-flaky's order pass, to replay the orders a diagnosis reported
PW_MCP_HISTORY
on
0 stops recording runs to .playwright-e2e-mcp/history.jsonl
PW_MCP_ALLOWED_ROOTS
—
Extra directories a caller may pass as projectRoot (:-separated, ; on Windows). Anything outside these and the default root is rejected
PW_MCP_HTTP_TOKEN
—
HTTP bridge only: bearer token that unlocks all tools: 16+ characters, 32+ recommended (see Hosted endpoint)
PW_MCP_ALLOWED_HOSTS
localhost + Vercel hostnames when there is no token
HTTP bridge only: comma-separated Host allowlist; * accepts any
PW_MCP_MAX_FAILED_AUTH
20
HTTP bridge only: wrong tokens or access keys one client address may send in 15 minutes before it gets 429
PW_MCP_OAUTH_REDIRECT_HOSTS
any https host
HTTP bridge only: comma-separated hosts OAuth apps may return to, e.g. claude.ai,chatgpt.com; .example.com covers subdomains; localhost always works
PW_MCP_TRUST_PROXY
off (on for Vercel)
HTTP bridge only: 1 trusts X-Real-IP / X-Forwarded-For from a reverse proxy in front, so the sign-in limit counts per client, not per proxy
PW_MCP_PASSTHROUGH_ENV
—
HTTP bridge only: comma-separated extra variables passed to test runs (e.g. BASE_URL)
PW_MCP_MAX_CHILDREN
4
HTTP bridge only: how many test runs and browser probes may run at once
PW_MCP_BLOCK_PRIVATE_URLS
off (on for the HTTP bridge)
1 makes the URL tools refuse loopback, private-network and cloud-metadata addresses, including redirects and subresources
PW_MCP_SERVERLESS_CHROMIUM
on for Vercel
Launch the page tools on the bundled serverless Chromium (@sparticuz/chromium, Linux x64, Node 22+); 0 turns it off, 1 turns it on elsewhere
LOG_LEVEL / MCP_LOG_LEVEL
info
debug | info | warn | error | silent; LOG_LEVEL wins when both are set
LOG_FORMAT / MCP_LOG_FORMAT
text
text, or json (also ndjson) for one structured JSON object per line — ready for a log ingester
Logs always go to stderr — stdout is reserved for the MCP protocol. Unrecognized values
fall back to the default, so a typo in LOG_LEVEL logs at info and one in LOG_FORMAT
logs as text rather than silencing the server. With LOG_FORMAT=json each line is a single
object (time, level, message plus context):
bench/token-benchmark.mjs breaks a checkout button's test id
on a storefront page and fixes it two ways: with this server (run-test → suggest-fix →
apply) and with Playwright MCP plus a shell (playwright test, browser_navigate +
browser_snapshot, edit, re-run). Latest result (full output):
Step
playwright-e2e-mcp
Playwright MCP + shell
Tool definitions (sent with every request)
4,565
4,726
Run the failing test
246
325
Find the element / propose the fix
260
2,286
Apply + verify (re-run)
257
34
Total for one fix
5,328
7,371
Tokens are characters ÷ 4. The Playwright MCP route is a lower bound: it assumes the agent
picks the right locator from the snapshot on the first try, which the server does for it here.
Demo
A real run-test call served over stdio by npx -y playwright-e2e-mcp against the bundled
examples/sample-test.spec.ts (actual output, unedited):
Free and open source
MIT licensed. Use it, change it, ship it in commercial work; no fees, no paid tier, no feature held back.
No account, no API key, no sign-up.npx -y playwright-e2e-mcp init is the whole setup.
No telemetry. It never phones home; your tests, traces and run history stay on your machine.
Free dependencies only: the MCP SDK (Apache-2.0), zod (MIT), axe-core (MPL-2.0) and the Playwright your project already has (Apache-2.0).
Free to host yourself, too: the HTTP bridge deploys to a free Vercel account (see Hosted endpoint).
What it does not do: it doesn't drive an exploratory browsing session step by step, and it
doesn't replace Playwright's own Test Agents inside VS Code. Use Playwright MCP for interactive
browsing and this server for running, diagnosing and fixing the suite. They work side by side.
More documentation
Tool reference: every argument, example outputs, edge cases handled
Hosted endpoint: the HTTP bridge for ChatGPT and claude.ai connectors
Security: the security model and how to report a vulnerability
Development: building, tests, Docker, signing and releasing