@andwhy/playwright-agents

Scaffold customized Playwright test agents (Planner, Generator, Healer) into any project. Supports Cursor and Claude Code.

Quick start

npx @andwhy/playwright-agents init

The CLI prompts for a target (Cursor, Claude Code, or both) and copies agent definitions, rules, config templates, and documentation into your project.

Options

npx @andwhy/playwright-agents init [--target cursor|claude|both] [--format ts|mjs] [--force]

| Flag | Description | | ---------- | ------------------------------------------------------------------------------------------ | | --target | Where to scaffold files. Prompted if omitted. | | --format | Config file format (ts or mjs). Use mjs if TS causes conflicts. Prompted if omitted. | | --force | Overwrite existing files (default: skip if present). |

What gets created

Cursor (--target cursor)

• .cursor/agents/ — Planner, Generator, Healer agent definitions
• .cursor/mcp.json — Playwright MCP server config (required by subagents)
• .cursor/rules/playwright-workflow.md — always-on orchestration rule for the Plan → Generate → Heal pipeline (delegates to subagents via the Task tool)

Claude Code (--target claude)

• .claude/agents/ — Planner, Generator, Healer agent definitions (each defines its own MCP server)
• .mcp.json — Playwright MCP server config (project root)

Shared (always created)

• playwright.config.{ts,mjs} — Playwright config template with BASE_URL support
• checkly.config.{ts,mjs} — Checkly config template with placeholders
• seed.spec.{ts,js} — seed file for Playwright MCP setup_page (placed at root, outside testDir to avoid test discovery conflicts)
• tests/INSTALL.md — installation guide
• tests/USAGE.md — day-to-day workflow guide

Agent customizations

These agents extend the vanilla Playwright test agents with:

• Extra tools: Generator gets terminal, edit, read_file; Healer gets terminal
• data-testid workflow: Generator reads recommended attributes from the plan and adds them to source components before recording
• Vercel share auth: every test.describe includes a beforeEach that authenticates with Vercel preview deployments
• Checkly verification: both Generator and Healer run checkly pw-test after local tests pass (use your project's package runner — yarn/pnpm/npx — see package manager gotcha)
• Numbered step comments: every logical step gets a comment (// 1. Navigate to…)
• Locale-awareness: no hardcoded domains or locale-specific URL patterns
• Optional draft input: Planner can validate a user-provided journey draft against the live page

License

MIT