Playwright Mcp

---
name: playwright-mcp
description: Drive the live application through Playwright's MCP servers for exploration, locator discovery, test generation, and failure diagnosis. Use when planning coverage, confirming an accessible name, generating a case, or investigating a failure.
---

# Playwright MCP Skill

## Outcome

Agents inspect the **real** application instead of guessing. Every locator that reaches a page object
was confirmed against a live accessibility snapshot first.

## Two Servers, Two Jobs

`.mcp.json` registers both. Pick by task, not by habit.

| Server            | Command                              | Use for                                   |
| ----------------- | ------------------------------------ | ----------------------------------------- |
| `playwright-test` | `npx playwright run-test-mcp-server` | Planning, generating, and healing tests   |
| `playwright`      | `npx playwright-mcp`                 | Ad-hoc exploration outside test authoring |

**Prefer `playwright-test`.** It reads `playwright.config.ts`, so it already knows this project's
`baseURL`, the `data-qa` test id attribute and the 1920x1080 viewport, so an agent resolves locators
exactly as the suite will. It also exposes tools the general server has no equivalent for:

| Tool                                                                                    | Purpose                                                      |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `planner_setup_page`                                                                    | Initialise the page before any exploration. Call once, first |
| `planner_save_plan`                                                                     | Persist the finished plan                                    |
| `generator_setup_page`                                                                  | Set up the page for the scenario being generated             |
| `generator_read_log`                                                                    | Retrieve the recorded actions after walking a scenario       |
| `generator_write_test`                                                                  | Write the generated spec                                     |
| `browser_verify_text_visible`, `browser_verify_element_visible`, `browser_verify_value` | Record verifications as assertions rather than bare clicks   |

The agent definitions in `.claude/agents/` are generated by
`npx playwright init-agents --loop=claude` and carry the exact tool list for the installed Playwright
version. Regenerate them after upgrading Playwright, then re-append the "Project rules for this
repository" section each one ends with.

## When Not To Use MCP

- **Not for running the suite.** Tests run through `yarn test:e2e` and `yarn test:vr`. MCP explores
  and generates; it does not execute the suite.
- **Not as a recorder.** A transcribed click sequence is not a test: it has no page objects, no
  intent, and assertions only where someone remembered them. Use what the session established, then
  write the spec properly.

## Method

1. `planner_setup_page` (or `generator_setup_page`) once, before anything else.
2. `browser_snapshot`: the accessibility tree is the source of truth for locators. The `role` and
   the accessible `name` are what `getByRole` will match.
3. Interact to reach each state the plan needs; snapshot again at every state worth asserting on.
4. Use the `browser_verify_*` tools for checks, so verifications survive into the generated test as
   assertions instead of being lost as navigation.
5. Record the confirmed accessible names in the plan.

## Locator Discovery Rules

- A real role and name in the snapshot means the locator is `getByRole(role, { name })`.
- An element carrying `data-qa` is reachable through `getByTestId`, because `testIdAttribute` maps
  onto it in the project config and the authoring server picks that up.
- No accessible name and no `data-qa` is a finding worth recording: the page object will need a
  documented CSS fallback.
- Two elements sharing one accessible name is a scoping problem to solve in the page object, not a
  reason to reach for `nth()`.

## Known Traps In This Application

- The consent banner renders inside a **shadow DOM**. Playwright locators pierce open shadow roots,
  so `getByRole("button", { name: "Consent" })` resolves it, while `document.querySelector` from an
  evaluate call will not. Do not conclude the button is missing.
- Third-party ad iframes inject after load and shift layout. The test fixture aborts those hosts, so
  a suite run and an MCP session can render differently. Check which one you are looking at.
- `/delete_account` deletes immediately on GET. Do not navigate there while exploring with an
  account you still need.
- Search matches category names as well as product names.

## Vendor documentation

[references/playwright-mcp-best-practices.md](references/playwright-mcp-best-practices.md) maps the official guidance onto the repository: the two servers, the flags that make a session match the suite, and what MCP is not for.

- [Playwright MCP server](https://github.com/microsoft/playwright-mcp)
- [Accessibility snapshots](https://playwright.dev/mcp/snapshots)
- [Test agents](https://playwright.dev/docs/test-agents)