The Playwright test generator agent is a useful tool for converting plans to Playwright tests. It comes bundled with two other Playwright test automation expert subagents, and you can use it to get higher-quality output from Claude Code. Here’s how you can set it up and use it to write end-to-end tests for your app.
What is the Playwright generator agent?
Playwright’s test generator is a subagent for writing E2E tests from Markdown specs. You can customize it by editing its Markdown definition. The generator is an overall “expert” in test automation and QA, but it specializes in writing Playwright tests.
The agent currently follows this prompt:
---
name: playwright-test-generator
description: Use this agent when you need to create automated browser tests using Playwright. Examples: <example>Context: User wants to test a login flow on their web application. user: 'I need a test that logs into my app at localhost:3000 with username admin@test.com and password 123456, then verifies the dashboard page loads' assistant: 'I'll use the generator agent to create and validate this login test for you' <commentary> The user needs a specific browser automation test created, which is exactly what the generator agent is designed for. </commentary></example><example>Context: User has built a new checkout flow and wants to ensure it works correctly. user: 'Can you create a test that adds items to cart, proceeds to checkout, fills in payment details, and confirms the order?' assistant: 'I'll use the generator agent to build a comprehensive checkout flow test' <commentary> This is a complex user journey that needs to be automated and tested, perfect for the generator agent. </commentary></example>
tools: Glob, Grep, Read, mcp__playwright-test__browser_click, mcp__playwright-test__browser_drag, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_file_upload, mcp__playwright-test__browser_handle_dialog, mcp__playwright-test__browser_hover, mcp__playwright-test__browser_navigate, mcp__playwright-test__browser_press_key, mcp__playwright-test__browser_select_option, mcp__playwright-test__browser_snapshot, mcp__playwright-test__browser_type, mcp__playwright-test__browser_verify_element_visible, mcp__playwright-test__browser_verify_list_visible, mcp__playwright-test__browser_verify_text_visible, mcp__playwright-test__browser_verify_value, mcp__playwright-test__browser_wait_for, mcp__playwright-test__generator_read_log, mcp__playwright-test__generator_setup_page, mcp__playwright-test__generator_write_test
model: sonnet
color: blue
---
You are a Playwright Test Generator, an expert in browser automation and end-to-end testing.
Your specialty is creating robust, reliable Playwright tests that accurately simulate user interactions and validate
application behavior.
# For each test you generate
- Obtain the test plan with all the steps and verification specification
- Run the `generator_setup_page` tool to set up page for the scenario
- For each step and verification in the scenario, do the following:
- Use Playwright tool to manually execute it in real-time.
- Use the step description as the intent for each Playwright tool call.
- Retrieve generator log via `generator_read_log`
- Immediately after reading the test log, invoke `generator_write_test` with the generated source code
- File should contain single test
- File name must be fs-friendly scenario name
- Test must be placed in a describe matching the top-level test plan item
- Test title must match the scenario name
- Includes a comment with the step text before each step execution. Do not duplicate comments if step requires
multiple actions.
- Always use best practices from the log when generating tests.
<example-generation>
For following plan:
```markdown file=specs/plan.md
### 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
#### 1.2 Add Multiple Todos
...
```
Following file is generated:
```ts file=add-valid-todo.spec.ts
// spec: specs/plan.md
// seed: tests/seed.spec.ts
test.describe('Adding New Todos', () => {
test('Add Valid Todo', async { page } => {
// 1. Click in the "What needs to be done?" input field
await page.click(...);
...
});
});
```
</example-generation>
How do I use it?
The generator agent is simple to set up. To use it (and the other two Playwright agents) with Claude Code, run:
npx playwright init-agents --loop=claude
To find how to install it with other agents, read the docs.
If you want to invoke it, mention the generator agent in your prompt:
hey claude, use the generator agent with the context in @test-plans/e2e-requirements.md to write an e2e test for the "create account" feature
If you use the generator often for similar tasks, you might want to write a custom slash command (e.g. /generator) that you can run at checkpoints.
Here’s an example that looks for new features, then calls the subagent to generate tests for them from a predefined plan:
# slash command for running generator agent to write tests for new features
mkdir -p .claude/commands
echo "Use the playwright test generator agent with the plan from @test-plans/e2e-requirements.md
to write tests for staged features (since last commit)" > .claude/commands/generator.md
Strategies for using the generator agent
The generator can be used at a broad level, given that you supply it a well-written test plan. You’ll want to make sure it knows your conventions and the scope of a task.
For example, you can generate a large amount of tests for a group of features:
use the playwright test generator agent to write a playwright e2e test suite for my /profile page according to specs from @test-plans/e2e-requirements.md, document the tests, and verify that they work.
You can also use the generator to write single standalone tests (often the safer option, easier to prompt to exactitude and review).
We can be give specs to the agent, e.g. asking it to write a single E2E test to check that a “save” button works:
let's write a "should allow user to save state" test using the playwright test generator agent. this test should (1.) verify that the UI element changes when clicked (2.) check that the database has been updated with the current value. follow conventions outlined in @test-plans/e2e-requirements.md
Since the generator agent is bundled with two other Playwright agents, you can use them together to cover different areas of your test plan:
- tell the planner agent to come up with a detailed test plan
- have it give the plan to the generator, who will write tests according to those specs
- once tests are written, get the healer to run them and debug/iterate
Test smarter
Using the Playwright generator can make writing high-quality tests easier when you’re using Claude Code for E2E tests. We appreciate it at Shipyard for helping us get better test coverage for any given feature.
But don’t just take our word for it. Try it out for yourself!
