What are Playwright Agents?
This article distills the official guidance and demo video into a practical, production‑ready walkthrough. Playwright ships three agents you can run independently or in a loop: 🎭 Planner, 🎭 Generator, and 🎭 Healer.
🎭 Planner
Explores your app and produces a human‑readable Markdown plan.
- Input: a clear request (e.g. “Generate a plan for guest checkout”), a
seed test, optional PRD. - Output:
specs/*.mdwith scenarios, steps, and expected results.
🎭 Generator
Converts the Markdown plan into executable Playwright tests and validates selectors/assertions during generation.
- Input: Markdown from
specs/, seed test and fixtures. - Output:
tests/*.spec.tsaligned to the plan.
🎭 Healer
Runs tests, replays failures, proposes patches (locator updates, waits, data fixes) and re‑runs until passing or guardrails stop.
- Input: failing test name.
- Output: a passing test or a skipped test if functionality is broken.
📋
Table of Contents
1. Requirements
- Node.js 18+ and npm
- Playwright Test latest version
- VS Code 1.105+ (Insiders channel) for full agentic UI experience
- AI Assistant – Choose one: Claude Code, OpenCode, or VS Code with AI extensions
- Git for version control
- Modern web browser (Chrome, Firefox, Safari)
2. Step-by-Step Installation Guide
Step 1: Prerequisites
- Install Node.js 18+ from nodejs.org
- Install npm (comes with Node.js)
- Install VS Code 1.105+ from VS Code Insiders for agentic experience
- Choose and install an AI Assistant:
- Claude Code – for Claude integration
- OpenCode – for OpenAI integration
- VS Code with AI extensions – for built-in AI features
- Install Git for version control
Step 2: Navigate to Demo Directory
# Navigate to the demo directory C:\Users\ADMIN\Documents\AI_QUEST_LTP> cd "playwright Agent Test Example - PhatLT"
Step 3: Install Dependencies
playwright Agent Test Example - PhatLT> npm install playwright Agent Test Example - PhatLT> npx playwright install
Step 4: Initialize Playwright Agents
# Initialize agent definitions for Claude Code (recommended) playwright Agent Test Example - PhatLT> npx playwright init-agents --loop=claude # Or for VS Code playwright Agent Test Example - PhatLT> npx playwright init-agents --loop=vscode # Or for OpenCode playwright Agent Test Example - PhatLT> npx playwright init-agents --loop=opencode
Step 5: Verify Setup
# Test seed file playwright Agent Test Example - PhatLT> npx playwright test tests/seed-agents.spec.ts # Check project structure playwright Agent Test Example - PhatLT> dir .claude\agents playwright Agent Test Example - PhatLT> dir .github playwright Agent Test Example - PhatLT> dir specs
playwright Agent Test Example - PhatLT> npm init -y
Wrote to playwright Agent Test Example - PhatLT\package.json:
{
"name": "phatlt-playwright",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "playwright test",
"test:headed": "playwright test --headed",
"test:ui": "playwright test --ui",
"test:debug": "playwright test --debug",
"test:chromium": "playwright test --project=chromium",
"test:firefox": "playwright test --project=firefox",
"test:webkit": "playwright test --project=webkit",
"report": "playwright show-report",
"codegen": "playwright codegen"
},
"keywords": [],
"author": "",
"license": "ISC",
"type": "commonjs",
"description": "",
"devDependencies": {
"@playwright/test": "^1.56.0",
"@types/node": "^24.7.2"
}
}
playwright Agent Test Example - PhatLT> npm install -D @playwright/test
added 1 package, and audited 2 packages in 2s
found 0 vulnerabilities
playwright Agent Test Example - PhatLT> npx playwright install
Installing browsers...
✓ Chromium 120.0.6099.109
✓ Firefox 120.0
✓ WebKit 17.4
playwright Agent Test Example - PhatLT> npx playwright init
✓ Created playwright.config.ts
✓ Created tests/
✓ Created tests/example.spec.ts
✓ Created tests/seed.spec.ts
3. Step-by-Step Testing Guide
Step 1: Test Seed File
Run the seed test to verify Playwright Agents setup:
# Test seed file for agents playwright Agent Test Example - PhatLT> npx playwright test tests/seed-agents.spec.ts # Run with browser UI visible playwright Agent Test Example - PhatLT> npx playwright test tests/seed-agents.spec.ts --headed # Run in debug mode playwright Agent Test Example - PhatLT> npx playwright test tests/seed-agents.spec.ts --debug
Step 2: Test Generated Tests
Run the example generated tests from the Generator agent:
# Run generated Google search tests playwright Agent Test Example - PhatLT> npx playwright test tests/google-search-generated.spec.ts # Run specific test by name playwright Agent Test Example - PhatLT> npx playwright test --grep "Perform Basic Search" # Run all tests playwright Agent Test Example - PhatLT> npx playwright test
Step 3: Test Different Browsers
# Run tests only on Chromium playwright Agent Test Example - PhatLT> npx playwright test --project=chromium # Run tests only on Firefox playwright Agent Test Example - PhatLT> npx playwright test --project=firefox # Run tests only on WebKit playwright Agent Test Example - PhatLT> npx playwright test --project=webkit
Step 4: Generate Test Reports
# Generate HTML report playwright Agent Test Example - PhatLT> npx playwright show-report # Run tests with UI mode playwright Agent Test Example - PhatLT> npx playwright test --ui
Step 5: Using Playwright Agents
Now you can use the Playwright Agents workflow with Claude Code:
# In Claude Code, ask the Planner: "I need test scenarios for Google search functionality. Use the planner agent to explore https://www.google.com" # Then ask the Generator: "Use the generator agent to create tests from the test plan in specs/" # Finally, use the Healer if tests fail: "The test 'Perform Basic Search' is failing. Use the healer agent to fix it."
4. Project Structure and Files
playwright Agent Test Example - PhatLT/ ├── .claude/agents/ # Claude Code agent definitions │ ├── playwright-test-planner.md # 🎭 Planner agent │ ├── playwright-test-generator.md # 🎭 Generator agent │ └── playwright-test-healer.md # 🎭 Healer agent ├── .github/ # Official agent definitions │ ├── planner.md # 🎭 Planner instructions │ ├── generator.md # 🎭 Generator instructions │ └── healer.md # 🎭 Healer instructions ├── specs/ # Test plans (Markdown) │ └── google-search-operations.md # Example test plan ├── tests/ # Generated tests │ ├── seed-agents.spec.ts # Seed test for agents │ └── google-search-generated.spec.ts # Generated test example ├── .mcp.json # MCP server configuration ├── playwright.config.ts # Playwright configuration ├── package.json # Project dependencies └── test-results/ # Test execution results
5. How Playwright Agents Work (End‑to‑End)
- 🎭 Planner — explores your app and creates human-readable test plans saved in
specs/directory. - 🎭 Generator — transforms Markdown plans into executable Playwright tests in
tests/directory. - 🎭 Healer — automatically repairs failing tests by updating selectors and waits.
- Execution — run generated tests with
npx playwright test. - Maintenance — Healer fixes issues automatically, keeping tests stable over time.
playwright Agent Test Example - PhatLT> npx playwright test tests/seed-agents.spec.ts Running 1 test using 1 worker ✓ [chromium] › tests/seed-agents.spec.ts › seed (2.1s) 1 passed (2.1s) playwright Agent Test Example - PhatLT> npx playwright test tests/google-search-generated.spec.ts Running 5 tests using 1 worker ✓ [chromium] › tests/google-search-generated.spec.ts › Google Search - Basic Operations › Perform Basic Search (3.2s) ✓ [chromium] › tests/google-search-generated.spec.ts › Google Search - Basic Operations › Verify Search Box Functionality (1.8s) ✓ [chromium] › tests/google-search-generated.spec.ts › Google Search - Basic Operations › Search with Empty Query (1.5s) ✓ [chromium] › tests/google-search-generated.spec.ts › Google Search - Results Validation › Verify Search Results Display (4.1s) ✓ [chromium] › tests/google-search-generated.spec.ts › Google Search - Results Validation › Navigate Through Search Results (5.3s) 5 passed (16.0s)
6. How Playwright Agents Work
Playwright Agents follow a structured workflow as described in the official documentation. The process involves three main agents working together:
🎭 Planner Agent
The Planner explores your application and creates human-readable test plans:
- Input: Clear request (e.g., “Generate a plan for guest checkout”), seed test, optional PRD
- Output: Markdown test plan saved as
specs/basic-operations.md - Process: Runs seed test to understand app structure and creates comprehensive test scenarios
🎭 Generator Agent
The Generator transforms Markdown plans into executable Playwright tests:
- Input: Markdown plan from
specs/ - Output: Test suite under
tests/ - Process: Verifies selectors and assertions live, generates robust test code
🎭 Healer Agent
The Healer automatically repairs failing tests:
- Input: Failing test name
- Output: Passing test or skipped test if functionality is broken
- Process: Replays failing steps, inspects UI, suggests patches, re-runs until passing
// Example: Generated test from specs/basic-operations.md
// 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
await expect(page.getByRole('checkbox', { name: '❯Mark all as complete' })).toBeVisible();
});
});
7. Agent Deep Dives
🎭 Planner — author plans that generate great tests
- Goal: Convert product intent into executable, atomic scenarios.
- Inputs: business request,
seed.spec.ts, optional PRD/acceptance criteria. - Output quality tips: prefer user‑intent over UI steps, keep 1 scenario = 1 assertion focus, name entities consistently.
- Anti‑patterns: mixing setup/teardown into steps; over‑specifying selectors in Markdown.
🎭 Generator — compile plans into resilient tests
- Validates selectors live: uses your running app to confirm locators/assertions.
- Structure: mirrors
specs/*.md; adds fixtures fromseed.spec.ts; keeps tests idempotent. - Resilience: prefer roles/labels; avoid brittle CSS/XPath; centralize waits.
🎭 Healer — stabilize and protect correctness
- Scope: flaky selectors, timing, deterministic data; not business‑logic rewrites.
- Review gates: patches proposed as diffs; you accept/reject before merge.
- Outcomes: test fixed, or skipped with a documented reason when the feature is broken.
8. Project Structure and Artifacts
Playwright Agents follow a structured approach as described in the official documentation. The generated files follow a simple, auditable structure:
repo/
.github/ # agent definitions
planner.md # planner agent instructions
generator.md # generator agent instructions
healer.md # healer agent instructions
specs/ # human-readable test plans
basic-operations.md # generated by planner
tests/ # generated Playwright tests
seed.spec.ts # seed test for environment
add-valid-todo.spec.ts # generated by generator
playwright.config.ts # Playwright configuration
Agent Definitions (.github/)
Under the hood, agent definitions are collections of instructions and MCP tools provided by Playwright. They should be regenerated whenever Playwright is updated:
# Initialize agent definitions npx playwright init-agents --loop=vscode npx playwright init-agents --loop=claude npx playwright init-agents --loop=opencode
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. Generated tests may include initial errors that can be healed automatically by the healer agent.
Seed tests (seed.spec.ts)
Seed tests provide a ready-to-use page context to bootstrap execution. The planner runs this test to execute all initialization necessary for your tests including global setup, project dependencies, and fixtures.
// Example: seed.spec.ts
import { test, expect } from './fixtures';
test('seed', async ({ page }) => {
// This test uses custom fixtures from ./fixtures
// 🎭 Planner will run this test to execute all initialization
// necessary for your tests including global setup,
// project dependencies and all necessary fixtures and hooks
});
9. Examples from Official Documentation
🎭 Planner Output Example
The 🎭 Planner generates human-readable test plans saved as specs/basic-operations.md:
# TodoMVC Application - Basic Operations Test Plan ## Application Overview The TodoMVC application is a React-based todo list manager that demonstrates standard todo application functionality. 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 ## 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)
🎭 Generator Output Example
The 🎭 Generator transforms the Markdown plan into executable Playwright tests:
// Generated test from specs/basic-operations.md
// 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
await expect(page.getByRole('checkbox', { name: '❯Mark all as complete' })).toBeVisible();
});
});
10. Best Practices
- Keep plans atomic: Small, focused scenarios help 🎭 Generator produce clean tests. Avoid mixing multiple user flows in one scenario.
- Stabilize with seed: Centralize navigation, authentication, and data seeding in
seed.spec.tsto ensure consistent test environment. - Prefer semantic selectors: Use
getByRole,getByLabel, andgetByTextfor resilient element selection. - 🎭 Healer guardrails: Review patches carefully; accept locator/wait tweaks, but avoid broad logic changes that might mask real bugs.
- Version agent definitions: Commit
.github/changes and regenerate them whenever Playwright is updated. - Choose the right AI assistant: VS Code, Claude Code, or OpenCode — pick the one that fits your team’s workflow and preferences.
- Maintain traceability: Keep clear 1:1 mapping from
specs/*.mdtotests/*.spec.tsusing comments and headers. - Test the agents: Start with simple scenarios to understand how each agent works before tackling complex user flows.
11. Troubleshooting
🎭 Planner can’t explore the app
Ensure your app is running locally, seed test works, and the app is accessible. Check that authentication and navigation are properly set up in seed.spec.ts.
🎭 Generator can’t find elements
Run the app locally, ensure routes are correct, and verify that elements have proper roles, labels, or accessible names. The 🎭 Generator validates selectors live against your running app.
🎭 Healer loops without fixing
Set explicit timeouts, add deterministic test data, and reduce flakiness in network waits. The 🎭 Healer works best with stable, predictable test conditions.
AI assistant doesn’t trigger agents
Re-run npx playwright init-agents --loop=[assistant], reload the IDE, and ensure the correct workspace root is open with agent definitions in .github/.
Generated tests fail immediately
Check that your seed test passes first. Ensure the app state matches what the 🎭 Planner observed. Verify that test data and authentication are consistent between planning and execution.
Agent definitions are outdated
Regenerate agent definitions after Playwright updates: npx playwright init-agents --loop=[assistant]. This ensures you have the latest tools and instructions.
12. CI/CD Integration
You can run the same agent‑generated tests in CI. Keep agent definitions in the repo and refresh them on Playwright upgrades.
# .github/workflows/tests.yml (excerpt)
name: Playwright Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test --reporter=html
13. FAQ
Do I need Claude Code?
No. Playwright Agents work with VS Code (v1.105+), Claude Code, or OpenCode. Choose the AI assistant that fits your team’s workflow and preferences.
Where do test plans live?
In specs/ as Markdown files generated by the 🎭 Planner. Generated tests go to tests/.
What if a feature is actually broken?
The 🎭 Healer can skip tests with an explanation instead of masking a real bug. It distinguishes between flaky tests and genuinely broken functionality.
Can I run agent-generated tests in CI?
Yes. The agents produce standard Playwright tests that run with npx playwright test in CI. Agent definitions are only needed for test authoring, not execution.
How do I update agent definitions?
Run npx playwright init-agents --loop=[assistant] whenever Playwright is updated to get the latest tools and instructions.
What’s the difference between 🎭 Planner, 🎭 Generator, and 🎭 Healer?
🎭 Planner: Explores your app and creates human-readable test plans. 🎭 Generator: Transforms plans into executable Playwright tests. 🎭 Healer: Automatically fixes failing tests by updating selectors and waits.
14. Demo video and Source code
GitHub repository: phatltscuti/playwright_agents
