playwright-test-generator（Playwright 测试生成器）

playwright-test-generator

General-purpose Playwright E2E test generation pipeline. From zero to reviewed, passing tests.

Pipeline Overview

Step 1: Environment Detection
Step 2: Coverage Gap Analysis  (skipped if $ARGUMENT provided)
Step 3: Browser Exploration    (Playwright CLI / agent-browser)
Step 4: Scenario Design        (EnterPlanMode → user approve)
Step 5: Code Generation        (see code-rules.md)
Step 6: YAGNI Audit + e2e-reviewer
Step 7: TS Compile + Test Run  (playwright-debugger on failure)

Step 1: Environment Detection

Read project files to build a project profile before doing anything else.

Output (project profile):

baseURL: <detected or user-provided>
testDir: <detected path>
hasPOM: true | false
existingSpecs: [list of file paths]

If baseURL cannot be determined: stop and ask the user to provide the target URL before proceeding.

Step 2: Coverage Gap Analysis

Skipped if $ARGUMENT is provided — jump to Step 3 with that target.

When no argument is given:

1. Scan for routing files in priority order:

- Angular: app-routing.module.ts, *-routing.module.ts - Next.js: app/ directory (App Router), pages/ directory (Pages Router) - React Router: router.ts, routes.ts, routes.tsx - Fallback: grep source files for path:, route(, <Route patterns - If no routes found at all: ask user to list the pages they want covered

1. Map existing spec files to routes:

- Match by file name (e.g. login.spec.ts → /login) - Match by page.goto() calls inside spec files

1. Output uncovered routes. Flag as high priority:

- Auth-related paths (/login, /register, /forgot-password) - Form-heavy pages (any page with <form> or multiple inputs)

1. Ask the user which target to start with before continuing.

Step 3: Browser Exploration

Do not guess selectors from source code alone. Use live browser exploration to discover real element roles, labels, and testids.

Navigation target: <baseURL>/<target-path> from the project profile (Step 1) + selected route (Step 2). If the page requires authentication, open the login page first, authenticate, then navigate to the target.

Use agent-browser tools as the primary exploration method:

1. browser_navigate <target-URL>
2. browser_snapshot → identify interactive elements (do NOT paste raw content into responses)
3. For each key interaction (button click, form fill, modal open, nav link):
   a. browser_click / browser_type / browser_fill_form / browser_select_option
   b. browser_snapshot → capture resulting state
4. browser_close

Reference only — do not use as primary: npx playwright codegen <URL> launches an interactive browser recorder. It is useful for manually discovering selectors during development but cannot be automated in an agent pipeline.

If agent-browser tools are unavailable, use npx playwright codegen <URL> manually and paste discovered selectors into the Locator Mapping Table in Step 4.

Snapshot handling: Extract element roles, labels, testids, and visible text from snapshot output. Summarize findings — do NOT paste raw YAML into responses.

Collect before moving to Step 4:

• Interactive elements: buttons, links, inputs, selects, modals, dropdowns
• Locator candidates: role+name pairs, label text, data-testid values, attribute selectors
• Key state transitions: loading states, error messages, empty states, open/close toggles

Step 4: Scenario Design + User Approval

Call EnterPlanMode. This switches Claude Code into plan mode — the AI writes a plan in the conversation and waits for the user to explicitly approve before any files are written. Do not write any code until the user approves.

Write a plan containing:

Scenarios

## Scenario 1: [descriptive title]
- Given: [precondition — what state the app is in]
- When: [user action]
- Then: [expected result — what the user sees]

Cover at minimum: one happy path + one error/edge case per feature.

Locator Mapping Table

| Locator name   | File              | Selector                                 | Used in | New/Existing |
|----------------|-------------------|------------------------------------------|---------|--------------|
| submitButton   | login-page.ts     | getByRole('button', { name: 'Sign in' }) | 1, 2    | New          |
| emailInput     | login-page.ts     | getByLabel('Email')                      | 1, 2    | New          |
| errorMessage   | login-page.ts     | getByText('Invalid credentials')         | 2       | New          |

Rules:

• Do not create any locator not listed in this table
• No getter methods — locators are exposed directly as readonly properties
• .nth(), .first(), .last() require // JUSTIFIED: <reason> on the line immediately above

Call ExitPlanMode. Wait for user approval before proceeding to Step 5.

Step 5: Code Generation

Follow code-rules.md in this directory for:

• Structure detection (POM vs flat spec)
• Selector priority
• POM rules and composition pattern
• Spec rules and forbidden patterns

Key principle: detect project structure first, match existing patterns when extending.

Step 6: YAGNI Audit + e2e-reviewer

YAGNI audit (run immediately after writing code)

1. List every locator defined in the generated/modified POM file(s)
2. Grep each locator name across all spec files
3. Delete any locator with zero usages
4. Output the audit table:

| Locator        | File           | Used in          | Status  |
|----------------|----------------|------------------|---------|
| submitButton   | login-page.ts  | login.spec.ts:18 | IN USE  |
| unusedLocator  | login-page.ts  | (none)           | DELETED |

e2e-reviewer (automatic quality gate)

Invoke the e2e-reviewer skill using the Skill tool, targeting the generated spec and POM files.

• P0 issues found: fix immediately, re-invoke e2e-reviewer, repeat until 0 P0s
• P1/P2 issues found: output in the final report, do not block Step 7

Step 7: Verification + Failure Handling

# 1. Type check — must pass with 0 errors
# Use e2e-specific tsconfig if present (e.g. e2e/tsconfig.json), otherwise root tsconfig
npx tsc --noEmit -p <e2e/tsconfig.json or tsconfig.json>

# 2. Run generated tests
npx playwright test <generated-spec-file> --project=chromium

Failure handling (max 3 auto-fix attempts)

After 3 failed attempts: invoke playwright-debugger skill using the Skill tool. Do not attempt a 4th fix.

Completion report (on full pass)

## playwright-test-generator — Complete

Generated:
- <path to POM file> (new | modified)
- <path to spec file> (new, N scenarios)

Coverage added: <route path>

e2e-reviewer: N P0 (fixed), N P1 (listed below)
Tests: N passed

Reference

• Playwright best practices: see best-practices.md in this directory
• Code generation rules: see code-rules.md in this directory