@andwhy/playwright-agents

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

Quick start

pnpm dlx @andwhy/playwright-agents init

The CLI copies agent definitions, orchestration rules, config templates, and documentation into your project. The install is purely additive — it never creates or overwrites CLAUDE.md.

Options

pnpm dlx @andwhy/playwright-agents init [--format ts|mjs] [--force]

| Flag | Description | | ---------- | ------------------------------------------------------------------------------------------ | | --format | Config file format (ts or mjs). Use mjs if TS causes conflicts. Prompted if omitted. | | --force | Overwrite existing package-owned files (default: skip if present). Safe — never touches CLAUDE.md or other user files. |

What gets created

• .claude/agents/ — Planner, Generator, Healer agent definitions (3 agents, each defines its own MCP server)
• .claude/rules/playwright-workflow.md — orchestration rules for the Plan → Generate → Heal pipeline, auto-loaded into the main session alongside any existing CLAUDE.md
• .mcp.json — Playwright MCP server config (project root)
• 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
• .gitignore entries — Playwright/test output and seed files

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 pnpm exec checkly pw-test after local tests pass (see INSTALL)
• 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