e2e

# 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 ```bash 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). ```bash source "${CLAUDE_PROJECT_DIR}/.claude/lib/detect-toolchain.sh" pm_run e2e # or: pm_run e2e <spec-path> pm_run e2e:report # open the last HTML report on failure ``` 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 - [ ] Spec lives in `e2e/`, not colocated with source. - [ ] Queries are role/label/text-based; assertions target user-visible behavior. - [ ] No dev servers started by hand; relies on Playwright's `webServer`. - [ ] No hardcoded ports — uses `baseURL` and relative URLs. - [ ] Persisted-data flows seed the isolated `e2e.db`, never the dev DB. - [ ] Responsive captures write 375/1440 screenshots to `e2e/screenshots/`. - [ ] Suite passes via the detected package manager (`pm_run e2e`).