1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249---
id: test-agents
title: "Agents"
---
import LiteYouTube from '@site/src/components/LiteYouTube';
# Playwright Test Agents
## Introduction
Playwright comes with three Playwright Test Agents out of the box: **🎭 planner**, **🎭 generator** and **🎭 healer**.
These agents can be used independently, sequentially, or as the chained calls in the agentic loop.
Using them sequentially will produce test coverage for your product.
* **🎭 planner** explores the app and produces a Markdown test plan
* **🎭 generator** transforms the Markdown plan into the Playwright Test files
* **🎭 healer** executes the test suite and automatically repairs failing tests
<LiteYouTube
id="_AifxZGxwuk"
title="Playwright 1.56 - Introducing Playwright Test Agents"
/>
### Getting Started
Start with adding Playwright Test Agent definitions to your project using
the `init-agents` command. These definitions should be regenerated whenever Playwright
is updated to pick up new tools and instructions.
```bash tab=bash-vscode
npx playwright init-agents --loop=vscode
```
```bash tab=bash-claude
npx playwright init-agents --loop=claude
```
```bash tab=bash-opencode
npx playwright init-agents --loop=opencode
```
:::note
VS Code v1.105 (released October 9, 2025) is needed for the agentic experience to function properly in VS Code.
:::
Once the agents have been generated, you can use your AI tool of choice to command these agents to build Playwright Tests.
## 🎭 Planner
Planner agent explores your app and produces a test plan for one or many scenarios and user flows.
**Input**
* A clear request to the planner (e.g., “Generate a plan for guest checkout.”)
* A `seed test` that sets up the environment necessary to interact with your app
* *(optional)* A Product Requirement Document (PRD) for context
**Prompt**
<img src={require("../images/test-agents/planner-prompt.png").src} alt="planner prompt" width="472"/>
> - Notice how the `seed.spec.ts` is included in the context of the planner.
> - Planner will run this test to execute all the initialization necessary for your test including the global setup, project dependencies and all the necessary fixtures and hooks.
> - Planner will also use this seed test as an example of all the generated tests. Alternatively, you can mention the file name in the prompt.
```js title="Example: seed.spec.ts"
import { test, expect } from './fixtures';
test('seed', async ({ page }) => {
// this test uses custom fixtures from ./fixtures
});
```
**Output**
* A Markdown test plan saved as `specs/basic-operations.md`.
* The plan is human-readable but precise enough for test generation.
<details>
<summary>Example: <b>specs/basic-operations.md</b></summary>
```markdown
# TodoMVC Application - Basic Operations Test Plan
## Application Overview
The TodoMVC application is a React-based todo list manager that demonstrates standard todo application functionality. The application provides comprehensive task management capabilities with a clean, intuitive interface. Key features include:
- **Task Management**: Add, edit, complete, and delete individual todos
- **Bulk Operations**: Mark all todos as complete/incomplete and clear all completed todos
- **Filtering System**: View todos by All, Active, or Completed status with URL routing support
- **Real-time Counter**: Display of active (incomplete) todo count
- **Interactive UI**: Hover states, edit-in-place functionality, and responsive design
- **State Persistence**: Maintains state during session navigation
## Test Scenarios
### 1. Adding New Todos
**Seed:** `tests/seed.spec.ts`
#### 1.1 Add Valid Todo
**Steps:**
1. Click in the "What needs to be done?" input field
2. Type "Buy groceries"
3. Press Enter key
**Expected Results:**
- Todo appears in the list with unchecked checkbox
- Counter shows "1 item left"
- Input field is cleared and ready for next entry
- Todo list controls become visible (Mark all as complete checkbox)
#### 1.2 Add Multiple Todos
...
```
</details>
## 🎭 Generator
Generator agent uses the Markdown plan to produce executable Playwright Tests.
It verifies selectors and assertions live as it performs the scenarios. Playwright supports
generation hints and provides a catalog of assertions for efficient structural and
behavioral validation.
**Input**
* Markdown plan from `specs/`
**Prompt**
<img src={require("../images/test-agents/generator-prompt.png").src} alt="generator prompt" width="472"/>
> - Notice how the `basic-operations.md` is included in the context of the generator.
> - This is how generator knows where to get the test plan from. Alternatively, you can mention the file name in the prompt.
**Output**
* A test suite under `tests/`
* Generated tests may include initial errors that can be healed automatically by the healer agent
<details>
<summary>Example: <b>tests/add-valid-todo.spec.ts</b></summary>
```ts
// spec: specs/basic-operations.md
// seed: tests/seed.spec.ts
import { test, expect } from '../fixtures';
test.describe('Adding New Todos', () => {
test('Add Valid Todo', async ({ page }) => {
// 1. Click in the "What needs to be done?" input field
const todoInput = page.getByRole('textbox', { name: 'What needs to be done?' });
await todoInput.click();
// 2. Type "Buy groceries"
await todoInput.fill('Buy groceries');
// 3. Press Enter key
await todoInput.press('Enter');
// Expected Results:
// - Todo appears in the list with unchecked checkbox
await expect(page.getByText('Buy groceries')).toBeVisible();
const todoCheckbox = page.getByRole('checkbox', { name: 'Toggle Todo' });
await expect(todoCheckbox).toBeVisible();
await expect(todoCheckbox).not.toBeChecked();
// - Counter shows "1 item left"
await expect(page.getByText('1 item left')).toBeVisible();
// - Input field is cleared and ready for next entry
await expect(todoInput).toHaveValue('');
await expect(todoInput).toBeFocused();
// - Todo list controls become visible (Mark all as complete checkbox)
await expect(page.getByRole('checkbox', { name: '❯Mark all as complete' })).toBeVisible();
});
});
```
</details>
## 🎭 Healer
When the test fails, the healer agent:
* Replays the failing steps
* Inspects the current UI to locate equivalent elements or flows
* Suggests a patch (e.g., locator update, wait adjustment, data fix)
* Re-runs the test until it passes or until guardrails stop the loop
**Input**
* Failing test name
**Prompt**
<img src={require("../images/test-agents/healer-prompt.png").src} alt="healer prompt" width="469"/>
**Output**
* A passing test, or a skipped test if the healer believes the that functionality is broken.
## Artifacts and Conventions
The static agent definitions and generated files follow a simple, auditable structure:
```bash
repo/
.github/ # agent definitions
specs/ # human-readable test plans
basic-operations.md
tests/ # generated Playwright tests
seed.spec.ts # seed test for environment
tests/create/add-valid-todo.spec.ts
playwright.config.ts
```
### Agent Definitions
Under the hood, agent definitions are collections of instructions and MCP tools. They are provided by
Playwright and should be regenerated whenever Playwright is updated.
Example for Claude Code subagents:
```bash
npx playwright init-agents --loop=vscode
```
### Specs in `specs/`
Specs are structured plans describing scenarios in human-readable terms. They include
steps, expected outcomes, and data. Specs can start from scratch or extend a seed test.
### Tests in `tests/`
Generated Playwright tests, aligned one-to-one with specs wherever feasible.
### Seed tests `seed.spec.ts`
Seed tests provide a ready-to-use `page` context to bootstrap execution.