playwright-agents

Overview

Playwright ships three things built for coding agents, and they solve different problems:

The official guidance on the first two (getting-started-cli): "playwright-cli is best for coding agents (Claude Code, GitHub Copilot, etc.) that favor token-efficient, skill-based workflows", while "MCP is best for specialized agentic loops that benefit from persistent state and iterative reasoning over page structure".

This skill covers choosing between them, setting them up, and the review a human still owes their output. Writing Playwright tests by hand (locators, web-first assertions, config, sharding) is playwright-testing; scaffolding a whole harness for a repo with no suite is the automation-harness-bootstrapper agent; cleaning up a recorded codegen spec is playwright-codegen-reviewer.

Facts below are checked against Playwright 1.65 docs and a local npx playwright init-agents --loop=claude run on @playwright/test 1.65.0. Agent definitions change between releases, so re-check after an upgrade.

When to use

• "Have Claude open the app and check X" or "reproduce this UI bug in a browser".
• "Set up Playwright MCP / playwright-cli for Claude Code."
• "Generate Playwright tests for this app with the planner / generator / healer agents", or "the healer changed my tests, is that OK?"
• A Playwright test fails only on CI and the agent has to debug it from a trace in the terminal.
• A reviewer wants proof the agent actually ran the flow (video receipt).

Not a fit: hand-writing or refactoring specs (playwright-testing), cross-browser matrix planning (browser-matrix-strategy-reference).

Step 1 - Pick the tool

Do not install all three "just in case": each MCP server adds its tool schemas to every conversation.

Step 2 - Set up playwright-cli

Per pw-cli (Node.js 20+ for the CLI itself):

npm install -g @playwright/cli@latest
playwright-cli --help
playwright-cli install --skills        # skill files for the agent, this project
# or: playwright-cli install --skills -g   (into ~/.claude/skills)

Since 1.62, a project that already has @playwright/test can run the bundled copy as npx playwright cli (pw-notes).

First run, headless by default:

playwright-cli open http://localhost:3000/login
playwright-cli snapshot                 # element refs like e15
playwright-cli fill e15 "user@example.com"
playwright-cli click "role=button[name=Sign in]"
playwright-cli screenshot --filename=after-login.png
playwright-cli console                  # browser console messages
playwright-cli requests                 # network since page load
playwright-cli close

Sessions: -s=<name> runs several browsers side by side; list, close-all, kill-all manage them; playwright-cli show opens a live dashboard of every session. The profile lives in memory unless you pass --persistent. A headless session closes itself after an hour without commands; change that with open --idle-timeout=<ms>. Project defaults go in .playwright/cli.config.json, loaded automatically.

Step 3 - Set up Playwright MCP

Claude Code (pw-mcp):

claude mcp add playwright npx @playwright/mcp@latest

Other clients take the standard config:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated"]
    }
  }
}

Prefer --isolated for test work: the default persistent profile keeps yesterday's login and cart, which makes "it works" depend on leftover state.

Step 4 - Set up the Test Agents

npm init playwright@latest            # only if the repo has no Playwright yet
npx playwright init-agents --loop=claude

(npm init playwright@latest is the standard installer, pw-intro.) Other loops: --loop=vscode, --loop=codex, --loop=opencode (pw-agents). With --loop=claude on 1.65.0 the command writes:

Then:

1. Edit seed.spec.ts so it does the real setup: your custom fixtures, sign-in, base URL. The planner runs it and "will also use this seed test as an example of all the generated tests" (pw-agents). A blank seed gives plans for the login page only.
2. Restart Claude Code so it loads .mcp.json and approve the playwright-test server.
3. Commit the agent files. The docs say the definitions "should be regenerated whenever Playwright is updated to pick up new tools and instructions" (pw-agents): re-run init-agents in the same PR as every @playwright/test bump.

Step 5 - Run the loop with review gates

The agents run unattended, so each hand-off gets a human check.

Reviewing what the healer changed

The healer's own instructions (generated playwright-test-healer.md, 1.65) tell it to fix "assertions and expected values", to "Do not ask user questions ... do the most reasonable thing possible to pass the test", and, when it is confident the test is right, to "mark this test as test.fixme()" with a comment. So a green healer run can hide a real bug. Review its diff with this table:

Run git diff tests/ after every healer session, and run the suite again yourself before merging.

Step 6 - Debug a failing test from the terminal

When a test fails on CI, the agent can read the trace without a GUI (1.59+, pw-notes):

npx playwright trace open test-results/checkout-chromium/trace.zip
npx playwright trace actions --grep="expect"   # failing step and its number
npx playwright trace action 9                  # error, expected vs received
npx playwright trace snapshot 9 --name after    # DOM after that step
npx playwright trace close

To step through a test live:

npx playwright test tests/checkout.spec.ts --debug=cli
# prints: Run "playwright-cli attach tw-87b59e" to attach to this test
playwright-cli attach tw-87b59e
playwright-cli --session tw-87b59e step-over

For flaky tests, set trace: 'retain-on-failure-and-retries' in the config: it "retains all traces when an attempt fails", so a passing and a failing attempt can be compared (1.59). PLAYWRIGHT_DASHBOARD=1 shows @playwright/test browsers in the playwright-cli show dashboard.

Step 7 - Leave evidence a human can check

An agent saying "I checked the page" is not evidence. Leave one of:

• A screenshot per checked state: playwright-cli screenshot --filename=....
• A video receipt with page.screencast (1.59+, pw-notes), which "serves as a receipt: chapter titles provide context, action annotations highlight each interaction":

await page.screencast.start({ path: 'receipt.webm' });
await page.screencast.showActions({ position: 'top-right' });
await page.screencast.showChapter('Verifying coupon', { description: 'SAVE20 applies 20%' });
await page.getByLabel('Coupon').fill('SAVE20');
await page.getByRole('button', { name: 'Apply' }).click();
await expect(page.getByTestId('discount')).toContainText('20%');
await page.screencast.stop();

• For generated tests: the npx playwright test output, with counts.

Security

• browser_run_code_unsafe "runs arbitrary JavaScript in the Playwright server process and is RCE-equivalent", so the docs say to enable it only for trusted MCP clients (pw-mcp). The generated planner definition lists this tool, so the planner can run code on your machine.
• Page content is untrusted input to the agent. WebMCP tool "names, descriptions, schemas and results are provided by the page, so treat them as untrusted input" (pw-cli); use --no-webmcp when you test sites you don't control.
• The default MCP profile is persistent: real logins in it are reachable by whatever the agent does next. Use --isolated plus a test-account --storage-state file, and keep that file out of git.

Anti-patterns

Limitations

• Agent definitions, tool names and CLI commands move fast (the CLI is 0.x). Check the release notes on upgrade.
• Test Agents generate @playwright/test code only (JS/TS); Python, Java and .NET Playwright users get the CLI and MCP but not this loop.
• The agents explore through the accessibility tree. Canvas apps and pages with poor ARIA give thin snapshots and weak locators.
• Generated plans and tests reflect what the agent saw in one session; they are a draft for review, not a coverage guarantee.

References

• pw-cli - Playwright, "Coding agents": install, --skills, commands, sessions, idle timeout, config file, CLI vs MCP, WebMCP.
• pw-mcp - Playwright, "Playwright MCP": claude mcp add, flags, profile modes, idle timeout, browser_run_code_unsafe.
• pw-agents - Playwright, "Agents": planner, generator, healer, init-agents --loop, seed test, regenerate on update.
• pw-notes - Playwright release notes: 1.56 Test Agents; 1.59 screencast, --debug=cli, npx playwright trace, retain-on-failure-and-retries, PLAYWRIGHT_DASHBOARD; 1.62 bundled npx playwright cli / mcp; 1.65 --no-webmcp.
• pw-intro - Playwright, "Installation": npm init playwright@latest.
• Local check: npx playwright init-agents --loop=claude on @playwright/test 1.65.0 (file list in Step 4, healer and planner definitions quoted in Steps 5 and Security).