playwright-e2e-mcp 0.2.2 → 0.3.1

package/skill/playwright-e2e-mcp/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: playwright-e2e-mcp
+description: Runs, debugs and fixes Playwright end-to-end tests through the playwright-e2e-mcp server, using structured run results, trace-based failure diagnostics, verified locators, self-healing fixes that re-run and revert if still red, per-test flaky verdicts that separate parallelism bugs from races, signed-in page inspection and local run history. Use when the user asks to run Playwright tests, fix a failing or broken e2e test, find out why a test is flaky or which tests are unstable, repair a selector that no longer matches, write a new Playwright test, or check a page for visual regressions.
+---
+
+# Playwright E2E with playwright-e2e-mcp
+
+This skill drives the `playwright-e2e-mcp` MCP server. The server runs Playwright
+for you and returns structured results instead of raw terminal output: pass/fail
+stats, each failure with `file:line`, a failure kind, the DOM at the moment of
+failure (read from the Playwright trace), failed network requests, console errors
+and concrete next steps. It can also propose and apply a verified fix for a broken
+locator, inspect pages behind a login, run long suites in the background and keep
+a local history of every run.
+
+This skill is written for playwright-e2e-mcp 0.3.0 and works with 0.2.0 or
+newer. If `suggest-fix`, `get-run-status` or `analyze-history` is missing, the
+server is older than 0.2.0: use the steps that do not need those tools and tell
+the user to update it. `diagnose-flaky`'s per-test table and `isolate` option
+arrived in 0.3.0.
+
+## Before you start
+
+1. Check that the server's tools are available. They are named `run-test`,
+   `get-run-status`, `get-failure`, `suggest-fix`, `inspect-page`,
+   `validate-selector`, `list-tests`, `generate-e2e-test`,
+   `compare-visual-state`, `diagnose-flaky` and `analyze-history` (your client
+   may prefix them, e.g. `mcp__playwright-e2e__run-test`).
+2. If they are all missing, stop and tell the user the MCP server is not
+   connected. Point them to `references/setup.md` for the one-line install for
+   their client. Do not fall back to shelling out to `npx playwright test` unless
+   the user asks. If only some are missing, the server may run a smaller tool
+   profile (`--tools=core` exposes `run-test`, `get-run-status`, `get-failure`,
+   `suggest-fix`, `diagnose-flaky` and `list-tests`); work with what is there and
+   mention the profile when a task needs a page tool.
+3. Every tool except `get-run-status` takes an optional `projectRoot`. Leave it
+   out unless the user works in a sub-project; the server defaults to `PW_MCP_PROJECT_ROOT` or its working
+   directory, and rejects any root outside its allowed roots.
+4. If the client offers the server's prompts as slash commands,
+   `/fix-failing-test` and `/triage-flaky-tests` start the two main workflows
+   below.
+
+## The core loop: fix a failing test
+
+Follow these steps in order. Do not edit code before step 3.
+
+1. **Run.** Call `run-test` with the narrowest scope you know:
+   `{ "testFiles": ["tests/checkout.spec.ts"] }`, or `file:line`, or `grep`.
+   Omit `testFiles` only when the user asks for the whole suite. Failing tests are
+   retried once by default, so a test that passes on retry is reported as
+   **flaky**, not failed. For a long suite pass `background: true` and poll
+   `get-run-status` with `waitSeconds: 30`.
+2. **Read the failure.** For each failure, call `get-failure` with its 1-based
+   `index`. Read the message and code frame, expected vs actual, the failure kind,
+   the DOM snapshot at failure, the failed action and its selector, failed network
+   requests and console errors.
+3. **Decide what is wrong** using the failure kind (see
+   `references/failure-kinds.md`):
+   - `server-unreachable` / `SERVER_NOT_RUNNING`: the app is not running. Tell the
+     user to start the dev server, or suggest `webServer` in the Playwright config.
+     Do not edit tests.
+   - A locator or selector in the message, or "0 elements": call `suggest-fix`
+     with the same `index`. If it returns a diff with `high` confidence, call it
+     again with `apply: true`; it re-runs the test and reverts if still red. If it
+     says the element is missing, treat it as an app bug and report the evidence.
+     Otherwise go to the selector loop below.
+   - `assertion` with a sensible selector: compare expected vs actual and the DOM
+     snapshot. Decide whether the app regressed or the test expectation is stale,
+     and say which before changing anything.
+   - `timeout`: check the DOM snapshot and failed requests for a slow or failed
+     API call before raising any timeout.
+   - Failed network request (4xx/5xx/no response) right before the failure: the
+     backend is the likely cause; report it.
+4. **Fix** the spec or the app code, the smallest change that addresses the cause.
+5. **Re-run only what failed:** `run-test` with `{ "lastFailed": true }`. Repeat
+   from step 2 until green.
+
+## Selector loop: a locator no longer matches
+
+1. `inspect-page` with the page URL and `view: "locators"`
+   (e.g. `{ "url": "http://localhost:3000/checkout", "view": "locators" }`).
+   Behind a login, pass `storageState` (the project's saved auth file); to reach a
+   modal or later step, pass `actions`. Every locator listed was checked to match
+   exactly one element.
+2. Pick a replacement. Prefer, in order: role + accessible name (`getByRole`),
+   `getByTestId`, label/placeholder, then a short stable CSS selector. Avoid
+   positional selectors such as `:nth-child` and generated class names.
+3. `validate-selector` with `{ "url": ..., "selector": ... }` before editing the
+   spec. It accepts locator expressions as written in the spec. Only use one that
+   comes back `✅ VALID` with exactly 1 match.
+4. Update the spec and re-run with `lastFailed: true`.
+
+## Pages behind a login
+
+`inspect-page`, `validate-selector` and `compare-visual-state` open the page in a
+fresh browser, so a signed-in page shows the login screen unless you pass state:
+
+- `storageState`: path inside the project to a Playwright storageState JSON, such
+  as `playwright/.auth/user.json` written by the project's setup project. Look for
+  it in `playwright.config.*` before asking the user. The server can default to
+  `PW_MCP_STORAGE_STATE`.
+- `headers`: extra HTTP headers, e.g. an API token the user gave you. Never invent
+  or log credentials.
+- `actions`: up to 20 steps after load (`click`, `fill`, `press`, `check`,
+  `select`, `hover`, `wait`, `goto`, ...) to open a modal or reach a later step.
+- `viewport`: `{ "width": 390, "height": 844 }` for mobile layouts.
+
+When a response says the page landed on a login screen, retry with
+`storageState`. `suggest-fix` takes `storageState` and `headers` too when you heal
+against a live `url`.
+
+## Flaky or intermittent failures
+
+Start with `analyze-history` (default view `flaky`) to see which tests flip
+between pass and fail across recorded runs, which regressed, and which are simply
+broken; `view: "patterns"` groups failures that share a cause. Then call
+`diagnose-flaky` on the worst ones (optionally `{ "testFiles": [...], "runs": 5 }`;
+with no `testFiles` it takes the tests that failed in the last run). It repeats
+them with retries disabled, in one Playwright process, and returns a table with
+one verdict **per test** (passes, failures, duration spread, first error):
+
+- **CONSISTENTLY FAILING**: not flaky; treat it as a real failure (core loop).
+- **FLAKY**: some runs passed. Same error signature each time points to a real
+  race in the app or test; varying errors point to timing or environment. Look for
+  missing awaits, assertions without auto-waiting, shared state between tests and
+  fixed `waitForTimeout` sleeps. Never "fix" flakiness by only adding retries or
+  sleeps.
+- **NOT REPRODUCING**: passed every run. Report that the failure was one-off.
+
+When a test is FLAKY and the suite runs in parallel, call `diagnose-flaky` again
+with `isolate: true`. It repeats the tests fully parallel, then repeats the
+failing ones with one worker, and reads each one:
+
+- **fails only in parallel**: the test shares state with others (same user or
+  account, DB rows, files, ports, a global fixture). Fix the data isolation, for
+  example per-worker data from `testInfo.workerIndex`; do not just serialize the
+  whole suite.
+- **flaky even alone**: the race is inside the test or the app.
+- **fails alone too**: a real bug, not parallelism.
+
+Pass `separateProcesses: true` only when the flake seems tied to global setup or
+a cold start, since one process per run is slower. `get-failure` works on the
+last failing diagnose run straight after, and each repetition is recorded in the
+history, so `diagnose-flaky` with `runs: 5` is also the quickest way to seed
+history for `analyze-history`.
+
+Every `run-test`, `diagnose-flaky` and `suggest-fix` run is recorded in
+`<project>/.playwright-e2e-mcp/history.jsonl` on the user's machine;
+`analyze-history` with `view: "test"` and a `test` filter shows one test's
+pass/fail timeline.
+
+## Other tasks
+
+- **List tests:** `list-tests`, with `filter` for a substring of `file › title`.
+- **Write a new test:** `generate-e2e-test` with a `description` (and `pageUrl` if
+  there is no `baseURL`). It scaffolds a spec from selectors the project actually
+  declares, from recent git changes, and reports each selector's source. Review the
+  file it writes, then `run-test` it. Pass `write: false` to preview without
+  writing.
+- **Set up CI:** when the user wants the same diagnosis on every pull request,
+  point them to the GitHub Action (`uses: xsignon-secure/E2E@v0.3.0`) or the
+  `npx -y playwright-e2e-mcp ci` command in `references/setup.md`. It writes the
+  run, flaky verdicts and fix diffs to the job summary and one PR comment.
+- **Visual regression:** `compare-visual-state` with `url` and a `name`. The first
+  call saves a baseline under `.pw-mcp/visual/`; later calls report changed
+  regions and color shifts and write a diff image. Use `action: "baseline"` only
+  when the user confirms the new look is intended.
+
+## Reporting back
+
+When you finish, tell the user, in this order:
+
+1. The result: which tests now pass, fail or are flaky (counts from the last
+   `run-test`).
+2. The cause of each failure you fixed, with the `file:line` you changed.
+3. Anything you did not fix and why (app bug, server down, needs a decision).
+
+## Things to avoid
+
+- Do not raise timeouts, add retries, add `waitForTimeout`, or delete or
+  `test.skip` a test to make a run green, unless the user explicitly asks.
+- Do not accept a new visual baseline without the user's confirmation.
+- Do not pass `allowExpectationUpdate: true` to `suggest-fix` unless the user
+  confirms the new text is intended; a changed expected value can be a real bug.
+- Do not point `inspect-page` or `validate-selector` at sites the user did not
+  name; they open real pages in a headless browser.
+- `run-test` executes the project's own test code. Run it only in projects the
+  user has asked you to work on.
+
+## References
+
+- `references/setup.md`: install and client configuration, environment variables.
+- `references/tools.md`: every tool's arguments.
+- `references/failure-kinds.md`: failure kinds and error codes, and what to do.
+- `references/example-session.md`: a worked fix-a-failing-test session with
+  `suggest-fix`.

package/skill/playwright-e2e-mcp/references/example-session.md

@@ -0,0 +1,53 @@
+# Example session: fixing a failing checkout test
+
+**User:** The checkout test started failing after the redesign. Can you fix it?
+
+1. Agent calls `run-test` with `{ "testFiles": ["tests/checkout.spec.ts"] }`.
+
+   ```
+   ## Playwright run — ❌ FAILED
+   | passed | failed | flaky | skipped |
+   | 2 | 1 | 0 | 0 |
+   ### 1 of 1. checkout.spec.ts › pays with card
+   File: checkout.spec.ts:18 | failed · timeout
+   ```
+
+2. Agent calls `get-failure` with `{ "index": 1 }`. The failed action is
+   `locator('#pay-now').click()`. The DOM snapshot at failure has no `#pay-now`,
+   but it does have a `Pay now` button. No network requests failed and the console
+   is clean, so the app itself looks healthy.
+
+3. The failure kind is `timeout`, but the cause is a locator that no longer
+   matches, so the agent calls `suggest-fix` with `{ "index": 1 }`:
+
+   ```
+   ### Proposed locator fix — confidence **high**
+   The button's accessible name matches "pay", and
+   `getByRole('button', { name: 'Pay now' })` is proven to resolve to exactly
+   that element.
+   -  await page.locator('#pay-now').click();
+   +  await page.getByRole('button', { name: 'Pay now' }).click();
+   ```
+
+4. Confidence is high, so the agent calls `suggest-fix` with
+   `{ "index": 1, "apply": true }`. The server writes the change, re-runs the test
+   with retries off, and reports `✅ Verified — the test passes with the fix`.
+   Had the test still failed, the server would have restored the original file.
+
+5. Agent calls `run-test` with `{ "lastFailed": true }` to confirm, then
+   `{ "testFiles": ["tests/checkout.spec.ts"] }` for the whole file: 3 passed.
+
+**Agent's reply:**
+
+> All 3 checkout tests pass now. "pays with card" failed because the redesign
+> removed the `#pay-now` id from the pay button. I changed the locator at
+> `tests/checkout.spec.ts:18` to `getByRole('button', { name: 'Pay now' })`,
+> which matches exactly one element, and the server re-ran the test to confirm
+> the fix.
+
+## When suggest-fix refuses
+
+If `suggest-fix` says the element is most likely missing, do not weaken the test.
+Read `get-failure` again for failed network requests and console errors, check the
+page with `inspect-page` (with `storageState` if it needs a login), and report it
+to the user as a probable app bug with that evidence.

package/skill/playwright-e2e-mcp/references/failure-kinds.md

@@ -0,0 +1,32 @@
+# Failure kinds and error codes
+
+## Per-test failure kinds (from `run-test` and `get-failure`)
+
+| Kind | Meaning | What to do |
+| --- | --- | --- |
+| `assertion` | An `expect` did not hold | Compare expected vs actual and the DOM snapshot; decide whether the app regressed or the expectation is stale, and say which before editing |
+| `timeout` | An action or the test ran out of time | Check the DOM snapshot and failed network requests for the real cause (element never appeared, API failed) before touching timeouts |
+| `server-unreachable` | The app under test did not respond | Ask the user to start the dev server, or configure `webServer` in the Playwright config; do not edit tests |
+| `browser-crash` | The browser or page closed unexpectedly | Re-run once; if it repeats, suggest `npx playwright install` to repair browsers |
+| `syntax` | The spec or config does not compile | Fix the reported `file:line` first; nothing else will run until it does |
+| `config` | The Playwright config is invalid | Read the message and fix the config |
+| `unknown` | Not classified | Read the message, stack and DOM snapshot directly |
+
+A test reported as **flaky** passed on the automatic retry. Run
+`diagnose-flaky` before deciding how to treat it.
+
+## Tool error codes
+
+| Code | Meaning | What to do |
+| --- | --- | --- |
+| `NO_PLAYWRIGHT` | `@playwright/test` is not installed in the project | Show the user the install command the error includes |
+| `NO_CONFIG` | No `playwright.config.*` found | Ask where the config is, or pass `projectRoot` / `config` |
+| `MULTIPLE_CONFIGS` | Several configs found; the error lists them numbered | Ask the user which one, or pick the obvious one, and pass `config: "2"` or its path |
+| `INVALID_PATH` | A path or `projectRoot` leaves the allowed roots | Use a path inside the project; to allow another root the user must set `PW_MCP_ALLOWED_ROOTS` |
+| `SERVER_NOT_RUNNING` | The app is not reachable | As `server-unreachable` above |
+| `TIMEOUT` | The whole run hit `timeoutMs`; results are partial | Narrow the run (`testFiles`, `grep`) or raise `timeoutMs` for this call |
+| `BROWSER_CRASH` | Browser failed | As `browser-crash` above |
+| `SYNTAX_ERROR` | A spec has a syntax error | Fix the reported file; `list-tests` still works via a source scan |
+| `DISK_FULL` | No space left on device | Ask the user to free disk space |
+| `SPAWN_FAILED` / `REPORT_MISSING` | Playwright could not start or wrote no report | Check Node and Playwright are installed; re-run with `LOG_LEVEL=debug` |
+| `CLIENT_DISCONNECT` | The run was cancelled | Re-run if still needed |

package/skill/playwright-e2e-mcp/references/setup.md

@@ -0,0 +1,120 @@
+# Setup: connecting the playwright-e2e-mcp server
+
+This skill only gives the agent instructions. The tools come from the
+`playwright-e2e-mcp` MCP server, which must be connected to the agent.
+
+## Requirements
+
+- playwright-e2e-mcp **0.2.0 or newer**, 0.3.0 recommended. `suggest-fix`,
+  `get-run-status`, `analyze-history`, verified locators and signed-in page
+  inspection arrived in 0.2.0; per-test flaky verdicts, `isolate`, tool profiles
+  and the `ci` command in 0.3.0. Check with
+  `npx -y playwright-e2e-mcp --version`.
+
+- Node.js 20 or newer.
+- A project with `@playwright/test` installed and a browser available:
+  `npx playwright install chromium`.
+
+## Install the server
+
+The server is published on npm as `playwright-e2e-mcp` and in the official MCP
+Registry as `io.github.xsignon-secure/E2E`. Pin a version in shared configs
+(`playwright-e2e-mcp@<version>`) so every machine runs the same build.
+
+**Claude Code**
+
+```bash
+claude mcp add playwright-e2e -- npx -y playwright-e2e-mcp
+```
+
+**Claude Desktop, Cursor, Windsurf, Gemini CLI, Qwen Code and other JSON-config clients**
+
+```json
+{
+  "mcpServers": {
+    "playwright-e2e": {
+      "command": "npx",
+      "args": ["-y", "playwright-e2e-mcp"],
+      "env": { "PW_MCP_PROJECT_ROOT": "/absolute/path/to/your/project" }
+    }
+  }
+}
+```
+
+Claude Desktop also has a one-click `.mcpb` extension on the project's
+[GitHub releases](https://github.com/xsignon-secure/E2E/releases); it asks for the
+project root on install.
+
+**Codex CLI**
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.playwright-e2e]
+command = "npx"
+args = ["-y", "playwright-e2e-mcp"]
+startup_timeout_sec = 60
+tool_timeout_sec = 600
+```
+
+Raise the timeouts as shown: a Playwright run with retries takes longer than
+Codex's 60-second default tool timeout.
+
+## Install the skill
+
+Copy the `playwright-e2e-mcp/` folder (the one holding `SKILL.md`) into your
+agent's skills directory, for example:
+
+- Claude Code: `~/.claude/skills/` (personal) or `.claude/skills/` (project)
+- Codex CLI: `~/.codex/skills/`
+- Other agents: their documented skills folder
+
+## Environment variables
+
+Set these in the server's `env` block. None of them are secrets except
+`PW_MCP_HTTP_TOKEN`; never put a token in a committed config file.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `PW_MCP_PROJECT_ROOT` | server working directory | Default project root for every tool |
+| `PW_MCP_TOOLS` | all | Tools to expose: names and/or profiles `core`, `triage`, `inspect`, `author` (same as the `--tools=` flag). `core` halves the tool-definition context |
+| `PW_MCP_ALLOWED_ROOTS` | none | Extra directories allowed as `projectRoot` (`:`-separated, `;` on Windows) |
+| `PW_MCP_BLOCK_PRIVATE_URLS` | off for stdio | `1` makes the URL tools refuse loopback, private-network and cloud-metadata addresses |
+| `PW_MCP_STORAGE_STATE` | none | Default Playwright storageState JSON (inside the project) for the page tools, so signed-in pages open logged in |
+| `PW_MCP_HISTORY` | on | `0` stops recording runs to `<project>/.playwright-e2e-mcp/history.jsonl` (this turns off `analyze-history`) |
+| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` or `silent` |
+| `PW_MCP_HTTP_TOKEN` | none | HTTP bridge only: bearer token that unlocks all tools |
+
+## Hosted endpoint
+
+Clients that only accept remote MCP servers can use the Streamable HTTP bridge
+(`https://playwright-e2e-mcp.vercel.app/api/mcp`, or your own deployment of the
+repo). Without a bearer token the bridge serves only `list-tests`,
+`get-failure` and `analyze-history`, so the core loop in `SKILL.md` needs a local install or a token.
+
+## Check it works
+
+Ask the agent to "list my Playwright tests". It should call `list-tests` and
+return files and titles. Clients that show MCP prompts also list
+`/fix-failing-test` and `/triage-flaky-tests`. If it says the tools are missing, the server is not
+connected: restart the client after editing its config.
+
+## CI (0.3.0+)
+
+The same diagnosis runs without an agent:
+
+```bash
+npx -y playwright-e2e-mcp ci --flaky-runs 3 --suggest 2 --output report.md
+```
+
+Exit code 0 means passed, 1 tests failed, 2 the run itself failed. On GitHub
+Actions it also writes to the job summary. As an Action:
+
+```yaml
+- uses: xsignon-secure/E2E@v0.3.0
+  with:
+    flaky-runs: 3
+    suggest: 2
+```
+
+It keeps one PR comment up to date when the run fails (needs
+`pull-requests: write`).

package/skill/playwright-e2e-mcp/references/tools.md

@@ -0,0 +1,161 @@
+# Tool reference
+
+All paths are relative to the project root. Every tool except `get-run-status`
+accepts an optional `projectRoot`, which must sit inside the server's allowed roots.
+
+## run-test
+
+Runs Playwright and returns stats, failures, failure kinds and fix hints.
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `testFiles` | string[] | Files or directories; `file:line` supported. Omit to run everything |
+| `grep` | string | Only tests whose title matches this regex |
+| `browser` | `chromium` \| `firefox` \| `webkit` | Matched against config project names |
+| `background` | boolean | Return a run id at once and keep running; follow it with `get-run-status` |
+| `headed` | boolean | Visible browser window |
+| `timeoutMs` | number | Wall-clock limit for the run (default 120000); partial results are returned past it |
+| `testTimeoutMs` | number | Per-test timeout |
+| `workers`, `retries` | number | Passed to Playwright |
+| `config` | string | Config path, or 1-based index when there are several |
+| `retryOnFailure` | boolean | Retry failures once before reporting (default true; ignored when `retries` is set) |
+| `lastFailed` | boolean | Re-run only the tests that failed last time |
+| `args` | string[] | Allowlisted Playwright flags such as `--repeat-each=N`, `--max-failures=N`, `--update-snapshots`, `--shard=1/3`, `--trace=on`; path-taking flags are rejected |
+
+Traces are captured on failure automatically so `get-failure` can show the DOM.
+Clients that send a progress token get live progress while the run goes.
+
+## get-failure
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `index` | number | 1-based failure index from the last run (default 1) |
+
+Returns the message and code frame, expected vs actual, stack, failure kind and
+diagnosis, console output, the DOM snapshot at failure with the failed action and
+its selector, failed network requests, console errors and warnings, and next steps.
+
+## inspect-page
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `url` | string | Required, full http(s) URL |
+| `selector` | string | Inspect only matches of this CSS selector |
+| `waitFor` | string | Wait for a selector (CSS or `text=...`) first |
+| `waitUntil` | `load` \| `domcontentloaded` \| `networkidle` | Navigation wait |
+| `includeHtml` | boolean | Include rendered HTML (capped by `maxHtmlChars`, default 20000) |
+| `timeoutMs` | number | Default 45000 |
+| `view` | `elements` \| `locators` | `locators`: compact map of interactive elements with verified locators |
+| `storageState` | string | Playwright storageState JSON inside the project (signed-in session); defaults to `PW_MCP_STORAGE_STATE` |
+| `headers` | object | Extra HTTP headers |
+| `actions` | array | Up to 20 steps after load: `{ type: click\|dblclick\|fill\|press\|check\|uncheck\|select\|hover\|wait\|goto, locator?, value?, url?, ms? }` |
+| `viewport` | object | `{ width, height }` |
+
+Returns each element's Playwright locators proven unique on the page (role +
+name first), unique CSS selector, tag, visibility, box, text and attributes,
+plus console messages. `validate-selector` and `compare-visual-state` take the
+same `storageState`, `headers`, `actions` and `viewport`.
+
+## validate-selector
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `url` | string | Required |
+| `selector` | string | Required: CSS, a Playwright selector, or a locator such as `getByRole('button', { name: 'Save' })` |
+| `timeoutMs` | number | Default 45000 |
+
+Verdicts: `✅ VALID — N matches` with samples and a unique locator for each,
+a strict-mode warning when more than one matches, `✅ VALID — 0 matches` with
+advice, or `❌ INVALID` with the parse error.
+
+## list-tests
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `config` | string | Config path or index |
+| `testDir` | string | Restrict to a directory |
+| `filter` | string | Case-insensitive substring of `file › title` |
+| `limit` | number | Default 500 |
+
+Falls back to a source scan when Playwright cannot list (broken install or spec).
+
+## generate-e2e-test
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `description` | string | Required: what the test should cover |
+| `pageUrl` | string | Start page (default: `baseURL` / `webServer.url`) |
+| `testDir`, `file` | string | Where to write; `file` must end in `.spec.*` or `.test.*` |
+| `write` | boolean | Write to disk (default true) |
+| `overwrite` | boolean | Replace a spec this tool generated earlier |
+| `liveInspect` | boolean | Cross-check selectors on the live page |
+| `config` | string | As above |
+
+## compare-visual-state
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `url` | string | Required |
+| `name` | string | Baseline id, e.g. `checkout-page` |
+| `action` | `compare` \| `baseline` | Default `compare`; `baseline` re-captures the reference |
+| `selector` | string | Capture one element |
+| `fullPage` | boolean | Full scrollable page |
+| `tolerance` | number | Percent of pixels allowed to differ (default 0.1) |
+| `pixelThreshold` | number | Per-pixel channel delta (default 60) |
+| `waitUntil`, `waitFor`, `timeoutMs` | | As `inspect-page` |
+
+Baselines live in `.pw-mcp/visual/`.
+
+## diagnose-flaky
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `testFiles` | string[] | Default: tests that failed in the last run |
+| `runs` | number | 2 to 10 (default 3) |
+| `isolate` | boolean | Repeat fully parallel (`workers` default 4), then repeat the failing tests with one worker (0.3.0+) |
+| `separateProcesses` | boolean | One Playwright process per run instead of one `--repeat-each` process; slower (0.3.0+) |
+| `browser`, `headed`, `workers`, `config` | | As `run-test` |
+| `timeoutMs` | number | Per run (default 120000); the single `--repeat-each` process gets this × `runs` |
+
+Runs with retries disabled and returns, per test, passes, failures, duration
+spread, first error and `CONSISTENTLY FAILING`, `FLAKY` or `NOT REPRODUCING`,
+plus the verdict block for the worst test. With `isolate`, a second table reads
+each failing test as "fails only in parallel", "flaky even alone" or "fails
+alone too". Versions before 0.3.0 return one run-level verdict and a per-run
+table instead.
+
+## suggest-fix
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `index` | number | 1-based failure index from the last run (default 1) |
+| `apply` | boolean | Write the fix (default false: diff only) |
+| `verify` | boolean | After applying, re-run and revert if still failing (default true) |
+| `allowExpectationUpdate` | boolean | Allow applying a changed expected text (default false) |
+| `url`, `storageState`, `headers` | | Heal against a live page instead of the trace snapshot |
+| `config`, `timeoutMs` | | As `run-test` |
+
+Returns a unified diff: a locator fix rated `high` or `medium` confidence, or an
+expectation update rated `low` that is applied only with
+`allowExpectationUpdate: true`. Otherwise it refuses and says the element is most
+likely missing.
+
+## get-run-status
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `runId` | string | From `run-test` with `background: true` (default: latest) |
+| `waitSeconds` | number | Wait up to this long (max 55) |
+| `cancel` | boolean | Stop the run |
+
+## analyze-history
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `view` | `flaky` \| `patterns` \| `test` | Default `flaky` |
+| `test` | string | Substring of a test's file or title |
+| `lastRuns` | number | Default 30 |
+| `limit` | number | Default 15 |
+
+Reads `.playwright-e2e-mcp/history.jsonl`, written by every run
+(`PW_MCP_HISTORY=0` disables it).