E2E

# playwright-e2e-mcp

[![CI](https://github.com/xsignon-secure/E2E/actions/workflows/ci.yml/badge.svg)](https://github.com/xsignon-secure/E2E/actions/workflows/ci.yml) [![release](https://img.shields.io/github/v/release/xsignon-secure/E2E)](https://github.com/xsignon-secure/E2E/releases) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.xsignon--secure%2FE2E-2563eb)](https://registry.modelcontextprotocol.io/)
[![M8ven Score](https://m8ven.ai/badge/mcp/trajectiq-ai/e2e)](https://m8ven.ai/mcp/trajectiq-ai/e2e?s=readme)

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=playwright-e2e&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBsYXl3cmlnaHQtZTJlLW1jcCJdfQ==)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright-e2e%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522playwright-e2e-mcp%2522%255D%257D)
[![Add to Claude Desktop](https://img.shields.io/badge/Claude_Desktop-.mcpb_bundle-D97757)](https://github.com/xsignon-secure/E2E/releases/latest)

An [MCP](https://modelcontextprotocol.io) server that **diagnoses and fixes failing Playwright
tests**. It is the layer that sits next to a browser-driving MCP: Playwright MCP gives an agent
hands in the browser; this server gives it a test runner, a failure analyst and a verified fixer.

```
run-test ──▶ get-failure ──▶ suggest-fix (apply + re-run) ──▶ green
   │              │                 └─ refuses when the element is really gone (app bug)
   │              └─ DOM at failure, failed requests, console errors
   └─ background runs, progress ──▶ analyze-history (flaky / broken / regressed)
```

What it does that a browser-driving MCP or a raw `npx playwright test` does not:

- **Structured runs.** Stats plus each failure's `file:line`, kind (assertion, timeout,
  dead dev server, syntax error, crash, full disk…) and a concrete fix hint. Failures that
  share one cause are grouped, so 30 tests broken by one dead server read as one problem.
  Long suites run in the background with live progress.
- **Diagnosis from the trace.** The DOM at the moment of failure, the failed action, the
  4xx/5xx requests and console errors, read from Playwright's own trace.
- **Fixes that are proven, not guessed.** `suggest-fix` matches a broken locator against the
  DOM at failure, swaps in a Playwright locator proven unique on the page
  (`getByRole('button', { name: 'Proceed to checkout' })`), re-runs the test and reverts the
  edit if it is still red. When nothing on the page plausibly matches, it says the element is
  missing and does not patch the test to hide a real bug.
- **Flakiness with evidence.** `diagnose-flaky` repeats failing tests in one process and
  gives a verdict per test; with `isolate: true` it re-runs them alone to tell a shared-state
  bug that only bites in parallel from a race inside the test, and with `order: true` it runs
  the files in random orders to catch a test that only passes when another one ran first,
  naming that test and the seed that reproduces it. Every run is recorded locally;
  `analyze-history` separates tests that flip (flaky) from ones that started failing
  (regressed) or always fail (broken), and groups failures that share one cause.
- **In CI too.** A [GitHub Action and `ci` command](#ci-github-action-and-ci-command) post the
  same diagnosis, flaky verdict and fix diffs to the job summary and the PR.
- **Accessibility.** `audit-accessibility` runs axe-core against WCAG 2.2 AA on any page,
  signed in or after steps, and returns each violation with the offending elements as verified
  locators and a regression check to paste into the spec.
- **Pages behind a login.** Every page tool accepts a Playwright `storageState`, extra
  headers, and click/fill steps to reach a modal or a later step.
- **An agent skill that teaches the craft.** The bundled skill drives the tools and carries a
  guide to writing tests that stay green (locators, waiting, auth, data isolation, mocking,
  flake patterns, review checklist).
- **Small on the wire.** In the [benchmark](bench/RESULTS.md), diagnosing and fixing one
  drifted locator cost about 5,300 tokens here against about 7,400 with Playwright MCP plus a
  shell, and the fix was applied and verified without the agent editing anything.

### What it does not do

It does not drive an exploratory browsing session step by step, and it does not replace
Playwright's own Test Agents (planner, generator, healer) inside VS Code. Use Playwright MCP
for interactive browsing and this server for running, diagnosing and fixing the suite; they
work side by side in the same client.

## Demo

**Hosted endpoint** — what an `initialize` + `tools/list` round-trip against
`https://playwright-e2e-mcp.vercel.app/api/mcp` returns for a client that sends the
bearer token (without one, only `list-tests` and `get-failure` are listed):

![Token-protected endpoint: initialize handshake and the tool list](https://raw.githubusercontent.com/xsignon-secure/E2E/main/docs/demo-endpoint.png)

**A real test run** — `run-test` served over stdio by `npx -y playwright-e2e-mcp`
against the bundled `examples/sample-test.spec.ts` (actual output, unedited):

![run-test result: 4 passed, 0 failed, 5.1s](https://raw.githubusercontent.com/xsignon-secure/E2E/main/docs/demo-run-test.png)

Images are rendered with `node scripts/gen-demo-images.mjs`: the run-test card is real
captured output; the endpoint card is an illustration of the authenticated listing.

> If this saves you a debugging session, a ⭐ on the repo helps other Playwright users find it.

## Install

Works with Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Gemini CLI, Freebuff
and every other MCP client — pick whichever route fits:

**Let your agent do it.** Paste this into Claude Code, Cursor, Codex, Gemini CLI or any
other coding agent:

> Install the playwright-e2e-mcp server and skill by following
> https://raw.githubusercontent.com/xsignon-secure/E2E/main/llms-install.md

or run the installer yourself from the project root. It merges the server into each
client's project config it finds (Claude Code, Cursor, VS Code, Gemini CLI, Codex) and
installs the agent skill, leaving your other servers alone:

```bash
npx -y playwright-e2e-mcp init            # --client all | cursor,vscode … · --dry-run
```

| Route | How |
| --- | --- |
| **One command, any project** | `npx -y playwright-e2e-mcp init` |
| **Claude Code plugin (server + skill)** | `/plugin marketplace add xsignon-secure/E2E` then `/plugin install playwright-e2e-mcp@xsignon-secure` |
| **Gemini CLI extension (server + skill)** | `gemini extensions install https://github.com/xsignon-secure/E2E` |
| **Skill only, any agent** | `npx skills add xsignon-secure/E2E` |
| **npm (canonical, fastest)** | `npx -y playwright-e2e-mcp` |
| **MCP Registry** (registry-aware clients discover it automatically) | `io.github.xsignon-secure/E2E` — [listing](https://registry.modelcontextprotocol.io/) |
| **Any client, no npm account needed** | `npx -y github:xsignon-secure/E2E#v0.4.0` (pin a release tag) |
| **Claude Desktop, zero Node setup** | double-click the [`.mcpb` extension](https://github.com/xsignon-secure/E2E/releases) |
| **Remote-only clients (ChatGPT connectors)** | `https://playwright-e2e-mcp.vercel.app/api/mcp` |

One line for the common clients:

```bash
claude mcp add playwright-e2e -- npx -y playwright-e2e-mcp
code --add-mcp '{"name":"playwright-e2e","command":"npx","args":["-y","playwright-e2e-mcp"]}'
```

Only need the fix loop? `--tools=core` (or `PW_MCP_TOOLS=core`) exposes six tools and
halves the tool-definition context; see [Configuration](#configuration).

Details and per-client config: [Installation](#installation) ·
[MCP client configuration](#mcp-client-configuration).

---

## Tools

| Tool | Purpose |
| --- | --- |
| `run-test` | 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 |
| `suggest-fix` | Patch a failure: a drifted locator is replaced with one **proven unique** on the DOM at failure, 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 |
| `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 |
| `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 |
| `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 fa