Agents

Three agents, one pipeline

This is a relatively new feature — AI agents that automate the test-writing workflow itself. Instead of I writing tests by hand, I describe what to test and the agents do the work. The three agents form a pipeline:

- planner — explores the app and produces a Markdown test plan describing what scenarios to test and expected results - generator — reads the Markdown plan and writes actual Playwright test files, verifying locators and assertions live as it goes - healer — runs the test suite, finds what fails, and automatically patches the tests to make them pass

Each agent can be run independently too — I don't have to use all three together.

Setting up agents

First, I generate the agent definition files — these are instructions and MCP tools that tell my AI coding tool how to run Playwright agents. I pick the AI tool I'm using:

After running this, the agent definitions appear in .github/ (for Claude Code) or similar. I regenerate them whenever Playwright updates to pick up new instructions.

# Для Claude Code
npx playwright init-agents --loop=claude

# Для VS Code Copilot
npx playwright init-agents --loop=vscode

# Для OpenCode
npx playwright init-agents --loop=opencode

Planner — exploring and planning

I give planner a description of what to test and a seed test that sets up the environment (authentication, fixtures). Planner navigates the app, explores the relevant flows, and produces a Markdown test plan with steps and expected outcomes.

A typical prompt: 'Using seed.spec.ts, generate a test plan for the order creation flow on /orders/new'. The output is a file like specs/order-creation.md — human-readable, precise enough for generator to work from.

// tests/seed.spec.ts — мінімальний seed для planner
import { test } from '@playwright/test'

test('seed', async ({ page }) => {
  // Planner запустить цей тест щоб отримати готову сторінку
  await page.goto('/orders')
})

# Приклад структури Markdown-плану від planner
# specs/order-creation.md

## Test Scenarios

### 1. Create valid order
Steps:
1. Click "New order" button
2. Fill customer name field with "Acme Corp"
3. Fill amount with "5000"
4. Click Save

Expected Results:
- Success toast "Order created" is visible
- Order appears in the list with correct data

Generator — plan to code

Generator reads the Markdown plan and writes actual Playwright test files. It opens the app and verifies each locator and assertion live as it writes — so the generated tests are already verified against the real UI, not just guessed.

A typical prompt: 'Using specs/order-creation.md and seed.spec.ts, generate Playwright tests'. The output is a test file under tests/ aligned with the spec.

// tests/order-creation.spec.ts — згенерований generator
import { test, expect } from '@playwright/test'

test.describe('Create valid order', () => {
  test('fills form and saves', async ({ page }) => {
    await page.goto('/orders')
    await page.getByRole('button', { name: 'New order' }).click()
    await page.getByLabel('Customer name').fill('Acme Corp')
    await page.getByLabel('Amount').fill('5000')
    await page.getByRole('button', { name: 'Save' }).click()
    await expect(page.getByText('Order created')).toBeVisible()
  })
})

Healer — fixing what breaks

After the UI changes, tests that were passing start failing. Healer runs the failing test, replays the failing steps in the browser, inspects the current UI to find the equivalent elements or flows, and patches the test — updating locators, wait strategies, or test data.

A typical prompt: 'Heal failing test tests/order-creation.spec.ts'. Healer loops — run, fail, patch, re-run — until the test passes or until it determines the functionality itself is broken (in which case it skips the test and reports the issue).

File structure conventions

The three-agent workflow produces a clean, auditable structure:

repo/
  .github/                    # визначення агентів (для Claude Code)
  specs/                      # Markdown-плани від planner
    order-creation.md
    dashboard.md
  tests/                      # Playwright-тести від generator
    seed.spec.ts              # seed для planner і generator
    order-creation.spec.ts
    dashboard.spec.ts
  playwright.config.ts