k11 Playwright QA — MCP server & Claude Code plugin

Turn user stories into Playwright tests that actually pass, and fix the ones a redesign just broke.

AI coding assistants write Playwright tests quickly, but they guess selectors. The tests look right, then fail on the first run, or break the next time someone renames a CSS class. This MCP server gives the assistant the facts it can't guess:

• Verified locators. It opens the real page and returns locators that match exactly one element, most stable first (getByTestId, getByRole, getByLabel, ...).

• Story → spec. It turns "As a… I want… so that…", Gherkin scenarios or acceptance-criteria bullets into a Playwright Test skeleton: one test per scenario, one test.step per step.

• Structured test runs. It runs Playwright and returns per-test results, including the exact locator a failing test was waiting for.

• Self-healing locators. When the UI changes, it finds the element the test meant and suggests a verified replacement with a confidence score and the reasons. It never silently edits your tests.

Works with Claude Code (as a plugin with /story-to-test and /heal-tests commands), Claude Desktop, and any other MCP client.

See it heal

The demo app ships in two versions. In v2 a redesign renamed every id, changed the button text from "Sign in" to "Log in", swapped the CSS classes and added a "Continue with Google" button. A test using page.locator('#login-btn') fails. heal_locator returns (trimmed):

{
  "status": "healed",
  "original": "page.locator('#login-btn')",
  "suggestion": "page.getByRole('button', { name: 'Log in' })",
  "confidence": 0.87,
  "reasons": [
    "name equivalent: \"Sign in\" → \"Log in\"",
    "id similar (50%): \"login-btn\" → \"signin-submit\"",
    "role matches", "type matches", "tag matches",
    "classes similar (64%): \"btn btn-primary\" → \"cta cta-primary\""
  ],
  "candidates": [
    { "locator": "page.getByRole('button', { name: 'Log in' })", "score": 0.87 },
    { "locator": "page.getByRole('button', { name: 'Continue with Google' })", "score": 0.42 },
    { "locator": "page.getByRole('heading', { name: 'Log in to Acme Store' })", "score": 0.15 }
  ],
  "referenceSource": "baseline"
}

It picked the right button over the look-alike, and the suggestion is a role-based locator that would have survived the redesign in the first place.

Related MCP server: RunAutomation MCP Server

Tools

Prompt: story_to_playwright, a guided workflow from story to passing test.

How self-healing works

1. Baseline. While tests pass, capture_baseline records each element's fingerprint: role, accessible name, test id, id, name, type, label, placeholder, classes, text and href.

2. Detect. When run_tests reports a failure, it includes the locator Playwright was waiting for.

3. Match. heal_locator scores every visible element on the current page against the fingerprint. It uses exact matching for stable attributes and fuzzy, synonym-aware matching for text and ids ("Sign in" ≈ "Log in", btn ≈ button).

4. Verify. The best match gets the most stable locator that matches exactly one element on the live page.

5. Decide. It reports healed only when the confidence is at least 0.55 and clearly ahead of the runner-up. Otherwise it reports needs_review with the top candidates, or not_found if nothing resembles the original. Without a baseline it falls back to what the locator itself implies and says so.

Install

Requires Node 20+.

Claude Code

git clone https://github.com/K11-Software-Solutions/k11techlab-playwright-qa-mcp
cd k11techlab-playwright-qa-mcp
npm install
npx playwright install chromium
# from your app's project folder:
claude mcp add playwright-qa -- node /path/to/k11techlab-playwright-qa-mcp/dist/cli.js

As a plugin (adds /story-to-test and /heal-tests), once the package is published to npm:

/plugin marketplace add K11-Software-Solutions/k11techlab-playwright-qa-mcp
/plugin install playwright-qa@k11-qa-tools

Claude Desktop and other MCP clients

{
  "mcpServers": {
    "playwright-qa": {
      "command": "node",
      "args": ["/path/to/k11techlab-playwright-qa-mcp/dist/cli.js"],
      "env": { "QA_MCP_ROOT": "/path/to/your/app" }
    }
  }
}

The server works on the project in QA_MCP_ROOT, or the current directory if that isn't set. That project needs @playwright/test installed for run_tests.

Try it

In Claude Code, inside your app's repository:

/story-to-test http://localhost:3000/login As a customer, I want to sign in so that I can see my orders.
- Valid credentials show "Welcome back"
- A wrong password shows an error and keeps me on the login page

After a UI change:

/heal-tests tests/login.spec.ts

Safety

• Locator strings are parsed, never eval'd. Only single getByRole / getByTestId / getByLabel / getByPlaceholder / getByText / locator(css) expressions are accepted.

• Writes are confined to tests/, limited to .spec/.test files, and never overwrite unless you ask.

• Tests run through the project's own Playwright CLI with Node directly, with no shell, so arguments can't inject commands.

• Healing only suggests. You, or the agent with your review, decide what to change.

Development

npm install
npx playwright install chromium
npm test        # unit, browser and MCP-protocol tests (22)
npm run build

Roadmap

• Healing across multi-step flows (navigate, then heal on the page the test reached)

• Visual (screenshot) fingerprints as an extra healing signal

• Optional auto-apply mode for healed results in CI, opening a pull request

• npm package and one-command plugin install

Built by K11 Software Solutions. Part of the K11 Tech Lab agentic QA series. MIT licensed.