create-playwright-testgen

Scaffold AI-powered Playwright test generation agents into any project.

Usage

npx create-playwright-testgen@latest

Run the command from the root of the repository you want to scaffold. The package writes files into the current working directory.

This copies the AI agent layer into your existing Playwright project:

• .claude/agents/ — Four specialized agents (Coordinator, Planner, Generator, Healer)
• .agents/skills/ — Playwright best practices, CLI reference, POM patterns, and more
• mcp.json — MCP server config (Playwright + Context7)
• AGENTS.md — Project context for AI coding assistants

It does not create a new Playwright app or install project dependencies for you.

Existing files

The scaffold is designed to be safe for an existing Playwright repo:

• If mcp.json already exists, server entries are merged by name. Existing servers are preserved.
• If AGENTS.md already exists and already matches the framework version, it is updated in place.
• If AGENTS.md already exists and is clearly your own custom file, the scaffold writes its framework context to .agents/PLAYWRIGHT-TESTGEN.md and adds a pointer to that file in the existing AGENTS.md.
• Agent and skill files are copied from the latest template snapshot shipped with the package.

Requirements

• Node.js >= 20
• An existing Playwright project, or a repo where you will install Playwright yourself
• GitHub Copilot or Claude Code

What this package does not install

The scaffold adds files and config only. Users may still need to install:

• @playwright/test in the target repository
• Playwright browser binaries via npx playwright install
• @playwright/cli globally if they want the documented playwright-cli workflow
• VS Code / Copilot / Claude Code or another compatible assistant that can read the scaffolded files

mcp.json is just configuration. A compatible IDE uses it to launch MCP servers; the file itself does not install those tools.

After scaffolding

If the target repo does not already have Playwright set up:

npm i -D @playwright/test
npx playwright install

If you want to use the documented CLI-based selector verification flow (recommended):

npm install -g @playwright/cli@latest
playwright-cli --help

mcp.json configures:

• playwright-test via npx playwright run-test-mcp-server, which depends on Playwright being available in the target repo/environment
• context7 via npx -y @upstash/context7-mcp, which compatible IDEs can fetch on demand

Optional: YouTrack MCP for Claude Code

If you use Claude Code and want agent access to YouTrack, add the YouTrack MCP server manually:

claude mcp add --header "Authorization: Bearer <token>" --transport http youtrack <your-youtrack-instance-name>

Create the token in YouTrack under Profile -> Account Security -> Tokens -> Create new token, then replace <token> and <your-youtrack-instance-name> in the command above. For example: http://youtrack.instancename.domain/mcp.

No API keys needed

The framework uses your existing Copilot/Claude subscription. Agents are markdown instruction files — your AI assistant reads them automatically from the workspace.

Contributor workflow

Inside this monorepo, the package templates are generated from the canonical repo files rather than committed by hand.

From packages/create-playwright-testgen/:

npm run build
npm test

That command snapshots:

• .claude/agents/
• .agents/skills/
• mcp.json
• AGENTS.md

into the package's generated templates/ directory. Run it before npm pack, local manual testing, or publishing. If it fails, make sure you are working from a full playwright-testgen repository checkout with those source files present.

npm test runs focused regression tests for the scaffold behavior, including fresh setup, AGENTS.md handling, mcp.json merges, and merge failures.

Learn more

See playwright-testgen for full documentation and architecture details.

License

MIT