Playwright Agents — 🎭 Planner, 🎭 Generator, 🎭 Healer

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.

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)

1. 🎭 Planner — explores your app and creates human-readable test plans saved in specs/ directory.
2. 🎭 Generator — transforms Markdown plans into executable Playwright tests in tests/ directory.
3. 🎭 Healer — automatically repairs failing tests by updating selectors and waits.
4. Execution — run generated tests with npx playwright test.
5. 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 from seed.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.ts to ensure consistent test environment.
• Prefer semantic selectors: Use getByRole, getByLabel, and getByText for 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/*.md to tests/*.spec.ts using comments and headers.
• Test the agents: Start with simple scenarios to understand how each agent works before tackling complex user flows.

11. Troubleshooting

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