| name | e2e |
| description | Author and run Playwright browser e2e specs against the real Express + Vite stack — specs in e2e/, role-based queries, the auto-starting webServer, port-overridable isolation, and the responsive screenshot-artifact pattern. |
| when_to_use | Use WHEN adding or changing a browser end-to-end flow, a Playwright spec, a cross-stack smoke/health check, or a responsive screenshot capture — whether the user asks directly or an implementation agent is realizing a matching To-Do item from a `tasks/task-N.md` plan. Do NOT use for unit/integration tests (those are colocated vitest/RTL specs — use /write-tests), and do NOT use just to run the existing quality gate (use /run-checks; e2e stays out of that gate by design). |
| argument-hint | [flow-or-spec-name] |
| arguments | ["target"] |
| model | sonnet |
Author e2e to convention
Add a Playwright spec for $target against the real running stack. Specs live in
e2e/, are vendor-neutral (no model-specific browser tool), and drive a real
Express API + Vite web server that Playwright starts and stops itself.
Step 1 — Detect toolchain and read conventions
source "${CLAUDE_PROJECT_DIR}/.claude/lib/detect-toolchain.sh"
Open e2e/app.spec.ts and e2e/responsive.spec.ts first and match their style.
Skim playwright.config.ts comments for the isolation model. Reuse the existing
patterns before inventing new ones.
Step 2 — Place the spec
- Write to
e2e/<name>.spec.ts — e2e specs are not colocated with source.
- Import from
@playwright/test; query by role/label/text, not CSS selectors or
test IDs, mirroring app.spec.ts.
- One observable user outcome per test; assert behavior, not internals.
Step 3 — Respect the webServer + isolation model
- Do not start
pnpm dev by hand. Playwright's webServer boots the API and
web server and waits on /api/health.
- If the flow needs persisted data, restore migrate + seed of the isolated
./e2e.db in the API webServer command (the starter shell skips this) — use
/scaffold-seed for the seed itself; never seed the dev database.
- Parse any data the test sets up through the feature's existing zod schema.
- Assume ports are env-overridable (
E2E_WEB_PORT / E2E_API_PORT) so concurrent
task agents don't collide; never hardcode localhost:3100/3000 — use
baseURL and relative paths. For parallel task runs, also isolate the database
per task, e.g. E2E_WEB_PORT=$((3100 + $task)) E2E_API_PORT=$((3200 + $task)) E2E_DATABASE_URL=./e2e-$task.db pnpm e2e. Single-agent runs need none of this.
Step 4 — Capture responsive artifacts (when graded)
For visual review, extend the responsive.spec.ts pattern: drive the two graded
breakpoints (375px mobile, 1440px desktop) and write fullPage screenshots to
e2e/screenshots/. These specs capture artifacts; they do not assert aesthetics.
Step 5 — Run and report
pm_run is a shell function from the detector, not a binary — source it in the
same block that calls it (shell state does not persist between blocks).
source "${CLAUDE_PROJECT_DIR}/.claude/lib/detect-toolchain.sh"
pm_run e2e
pm_run e2e:report
On failure, diagnose from the report and trace rather than re-running blind:
pm_run e2e:report opens the HTML report, and npx playwright show-trace
replays a run with console + network captured.
Iterate until green. Report the flows covered and any screenshots written; don't
paste full Playwright logs.
Checklist
