Playwright Agents
What are Playwright Agents?
Playwright agents are ready-made instructions that turn an AI assistant into a helper for writing Playwright tests.
An AI agent is an AI assistant that works in steps on its own: it reads files, uses tools, looks at the result and decides the next step.
Playwright comes with three agents: the planner, the generator and the healer.
They control the browser with MCP tools, like the ones in the MCP chapter.
Playwright does not include the AI itself.
You run the agents inside an AI app you already use, like Claude Code, VS Code with GitHub Copilot, Codex or opencode.
The Three Agents
| Agent | What it does | What it writes |
|---|---|---|
| Planner | Opens your app in a browser, explores it, and writes a test plan in plain English | A Markdown file in the specs/ folder |
| Generator | Reads the plan, does each step in a real browser, and writes a test from the steps | Test files in your test folder |
| Healer | Runs the tests, finds the failing ones, looks at the page, and changes the test until it passes | Fixes in your test files |
A test plan is a list of scenarios.
A scenario is one thing a user does, with its steps and the expected result.
You can use each agent alone, or one after the other: plan, then generate, then heal.
Set Up the Agents
Run npx playwright init-agents in your project folder.
Use --loop to choose your AI app (the "loop" is the AI app that runs the agent):
| --loop | AI app | Where the agent files go |
|---|---|---|
| claude | Claude Code | .claude/agents/ and .mcp.json |
| vscode or copilot | VS Code with GitHub Copilot | .github/agents/ and .vscode/mcp.json |
| codex | Codex | .codex/agents/ |
| opencode | opencode | .opencode/prompts/ and opencode.json |
This is a project with the usual playwright.config.js and one test file, tests/seed.spec.js.
Set up the agents for Claude Code:
Example
npx playwright init-agents --loop=claude
Output:
🎭 Using project "chromium" as a primary project
📝 specs/README.md - directory for test plans
🤖 .claude/agents/playwright-test-generator.md - agent definition
🤖 .claude/agents/playwright-test-healer.md - agent definition
🤖 .claude/agents/playwright-test-planner.md - agent definition
🔧 .mcp.json - mcp configuration
✅ Done.
The command only writes files.
It does not download anything.
Run it again after you update Playwright, so the agents get the new tools and instructions.
Note: For VS Code, you need VS Code 1.105 or newer.
The Seed Test
The seed test is a small test that brings the browser to the place where the agents should start.
The planner and the generator run it first, before they do anything else.
The generator also uses it as an example of how your tests look.
Example
tests/seed.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('seed', async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/todo.html');
await expect(page.getByRole('heading', { name: 'Todo List' })).toBeVisible();
});
init-agents uses the first test file with "seed" in its name.
If there is none, it creates seed.spec.ts in your test folder, with an empty test.
Put everything the agents need at the start in the seed test: open the right page, log in a test user, or add test data.
Because it is a normal test, it can also use your fixtures, hooks and project setup.
The Files It Creates
After init-agents --loop=claude, the project has these new files:
.claude/agents/playwright-test-generator.md
.claude/agents/playwright-test-healer.md
.claude/agents/playwright-test-planner.md
.mcp.json
specs/README.md
Each agent file starts with a header: the agent's name, when to use it, and the tools it may use.
After the header come the instructions, in plain English.
This is the start of the healer:
.claude/agents/playwright-test-healer.md
---
name: playwright-test-healer
description: Use this agent when you need to debug and fix failing Playwright tests
tools: Glob, Grep, Read, LS, Edit, MultiEdit, Write, mcp__playwright-test__browser_console_messages, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_generate_locator, mcp__playwright-test__browser_network_request, mcp__playwright-test__browser_network_requests, mcp__playwright-test__browser_snapshot, mcp__playwright-test__test_debug, mcp__playwright-test__test_list, mcp__playwright-test__test_run
model: sonnet
color: red
---
You are the Playwright Test Healer, an expert test automation engineer specializing in debugging and
resolving Playwright test failures. Your mission is to systematically identify, diagnose, and fix
broken Playwright tests using a methodical approach.
The healer may read and edit files, and use tools to run and debug tests (test_run, test_debug).
The planner, on the other hand, may not edit files.
It can only explore the page and save a plan.
You can read and change these files.
They are normal text.
.mcp.json tells Claude Code how to start the MCP server for the agents:
.mcp.json
{
"mcpServers": {
"playwright-test": {
"command": "cmd",
"args": [
"/c",
"npx",
"playwright",
"run-test-mcp-server"
]
}
}
}
This file was made on Windows.
On macOS and Linux, the command is npx with the arguments playwright run-test-mcp-server.
run-test-mcp-server is a special MCP server for the agents.
It has the browser tools from the MCP chapter, plus tools to run tests, save plans and write test files.
specs/README.md only marks the specs/ folder, where the planner saves its plans.
From Plan to Test
In your AI app, ask the planner for a plan, for example:
Use the planner to make a test plan for adding todos.
Seed: tests/seed.spec.js
The planner saves a Markdown file in specs/.
A plan has a short overview, and then scenarios with numbered steps and expected results:
Example
specs/todo.plan.md
## Test Scenarios
### 1. Adding Todos
**Seed:** `tests/seed.spec.js`
#### 1.1 Add one todo
**Steps:**
1. Type "Buy milk" in the "New todo" field
2. Click the "Add" button
**Expected Results:**
- "Buy milk" is shown in the list
- The counter shows "1 item left"
- The "New todo" field is empty
Next, ask the generator to write tests from the plan.
It does each step in the browser, and writes one test file per scenario.
The test is in a test.describe() group named after the plan section, and each step from the plan becomes a comment above its code.
A test in this form looks like this:
Example
tests/add-one-todo.spec.js
// @ts-check
// spec: specs/todo.plan.md
// seed: tests/seed.spec.js
import { test, expect } from '@playwright/test';
test.describe('Adding Todos', () => {
test('Add one todo', async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/todo.html');
// 1. Type "Buy milk" in the "New todo" field
await page.getByRole('textbox', { name: 'New todo' }).fill('Buy milk');
// 2. Click the "Add" button
await page.getByRole('button', { name: 'Add' }).click();
// "Buy milk" is shown in the list
await expect(page.getByRole('list', { name: 'Todos' })).toContainText('Buy milk');
// The counter shows "1 item left"
await expect(page.getByTestId('todo-count')).toHaveText('1 item left');
// The "New todo" field is empty
await expect(page.getByRole('textbox', { name: 'New todo' })).toBeEmpty();
});
});
It is a normal Playwright test, so you run it the normal way:
Example
npx playwright test
Output:
Running 2 tests using 2 workers
[1/2] [chromium] › tests/add-one-todo.spec.js:7:3 › Adding Todos › Add one todo
[2/2] [chromium] › tests/seed.spec.js:4:1 › seed
2 passed (1.2s)
If a generated test fails, ask the healer to fix it.
The healer runs the test, looks at the page at the failing step, changes the test and runs it again, until it passes.
If the healer thinks the test is right and the app is wrong, it marks the test with test.fixme(), so it is skipped, and adds a comment that explains the problem (see Skip and Only).
Review What the Agents Wrote
The agents work fast, but they can make mistakes.
A human should check their work before it goes into the project:
- Read the plan first. Is every important scenario there? Are the expected results right for your app? A wrong plan gives wrong tests
- Read each test. Does it check what the scenario says? A test without good assertions passes even when the app is broken
- Check the locators. Prefer
getByRole(),getByLabel()and test ids over long CSS paths (see Locators) - Check the healer's changes. If it changed an expected value, ask why. The app may have a real bug, and the "fix" hides it
- Look at every
test.fixme(). It can mean a real bug in your app - Run the tests several times, for example with
--repeat-each=5, to see that they pass every time - Review the changes like a pull request from a colleague before you commit them
Note: The agents use the browser tools from the MCP chapter, so the same safety rules apply.
Let them work on a test website with test accounts.
Agent Skills
A skill is a folder with instructions (a SKILL.md file) that an AI assistant reads when a task needs it.
npx playwright init-skills copies Playwright's skills into your project:
Example
npx playwright init-skills
Output:
✅ Skill installed to `.claude/skills/playwright-cli`.
✅ Skill installed to `.claude/skills/playwright-component-testing`.
✅ Skill installed to `.claude/skills/playwright-trace`.
| Skill | What it teaches the AI |
|---|---|
| playwright-cli | How to control a browser and work with Playwright tests from the command line |
| playwright-component-testing | How to test React or Vue components with Playwright |
| playwright-trace | How to read trace files from the command line |
The default target is Claude Code (.claude/skills/).
Use --loop=agents to copy them to .agents/skills/ instead, for AI apps that read skills from that folder.
The skills are copied from your installed Playwright, so nothing is downloaded.