| name | e2e-testing |
| description | Enforces Playwright E2E conventions — canonical locators, semantic selectors, cross-page input→navigate→consume flow, exact assertions, dynamic mocks — and how to debug a runtime-only browser error by driving a headless Playwright probe. Auto-triggers when writing or editing any *.spec.ts file under e2e/ or its helpers/mocks, or when reaching for Playwright to read the browser console for a bug with no build/lint signal. |
| user-invocable | false |
E2E Testing Conventions
Playwright E2E specs live under an app's e2e/ directory (e.g. apps/main/e2e/). They cover user journeys that interact with APIs (fully mocked via page.route()): routing, auth, cross-component flows. Keep them lean — critical paths only. Component-level regression (form validation, edge cases, error states) belongs in Storybook play functions, not E2E (E2E has an ~8min CI timeout and is slower).
1. Locators — import from e2e/locators/, never hand-roll
The canonical locator source is the app's e2e/locators/ directory. Import the finder that matches the element's role/semantics. Do NOT write locators inline in specs.
| Module | Function | Use for | Strategy |
|---|
sections.ts | findSectionByRegion(page, title) | section / panel cards | getByRole('region', { name }) |
| findSectionByTestId(page, testId) | sections without a semantic handle (documented exception) | getByTestId |
tabs.ts | findCategoryTab(section, name) | category/chip tabs | getByRole('tab', { name, exact: true }) |
| findItemTab(page, name) | top-level nav tabs | getByRole('tab', { name }) |
| getActiveTab(section) | selected tab text | getByRole('tab', { selected: true }) |
lineItems.ts | findLineItemInputRow(container, name) | editable list/row inputs | getByRole('group', { name, exact: true }) |
totals.ts | findTotalRow(section, label='Total') | total/subtotal footer | getByLabel(label, { exact: true }) |
cardRows.ts | findCardRow(container, name) | read-only metric display rows | [aria-label="name"] |
tableRows.ts | findTableRow(container, name) | report table rows | getByRole('row', { name, exact: true }) |
The locator is chosen by the element's role, not by DOM convenience — an editable input row is a group, a read-only display row is a cardRow, a table row is a row. Each lives in its own module so the call site communicates intent.
DEPRECATED — do not copy: any locator-finding functions inside e2e/scenarios/*/shared/helpers.ts that use CSS-structure selectors (div:has(> button[aria-label=...])), input[value="..."], xpath ancestor walks, and data-testid fallbacks. When you touch one of these, migrate it to an e2e/locators/ finder — never replicate the pattern in a new spec.
2. Semantic selectors only
- Query by what the user perceives:
getByRole, getByLabel, getByText. Never data-testid or CSS class selectors (.MuiStack-root, .recharts-*, div:has(> ...)).
- If a target lacks a semantic handle, fix the component — add an
aria-label (or role) to the component, then select it. Never work around it in the test with data-testid, .locator('..'), or DOM traversal. Tests drive a11y adoption, they don't cement bad patterns.
- Calculated/derived display values get
role="status" + aria-label so they're both announceable and reliably targetable: getByRole('status', { name: 'Total duration' }).
- MUI Selects already expose
aria-label (e.g. Status, Category) — use those.
3. Exact assertions, always
- Pass
{ exact: true } to getByText / getByLabel name & presence checks from the first draft. Bare getByText('Chapter One') substring-matches and collides with accessible-name text like an svg titleAccess="Chapter One bookmark" → strict-mode violation. Treat bare getByText('Name') as a smell.
- Assert exact values —
code-conventions owns the exact-vs-fuzzy matcher rule; it applies here unchanged, with Playwright's own exact matchers (toHaveValue, toHaveAttribute).
- In metric cards, assert both the label and the value — don't use the label only as a container anchor.
- Reuse the app's real formatters (
formatDate, formatNumber, etc.) and named seed constants for expected values — no magic strings.
4. Cross-page = input → navigate → consume
A cross-page spec must follow the doc's steps literally: navigate to each input tab, verify the seeded/entered data renders there, then navigate to the consuming tab and assert the derived values. A spec that skips the input tabs and only asserts on the final view is a display test, not a cross-page test — it doesn't prove the pipeline.
- Container-first scoping: find the container (
findSectionByRegion, a tabpanel, etc.) first, then locate inside it. Never bare page-level page.getByText(...).
- Cover 100% of inputs that affect a calculated output — every input field that changes the result needs a case.
- Reference pattern: look at an existing cross-page journey under
e2e/scenarios/cross-page/.
5. Mocks — dynamic, no response-waiting
- Use dynamic/stateful mocks that mutate their state when a mutation fires (e.g.
setStatus('read')), so query refetches return the new data — just like the real server. Static mocks overwrite optimistic updates with stale data and cause races.
- Don't
waitForResponse for optimistic-rendering assertions — the point is the UI updates without the round-trip. Assert on the resulting UI state instead.
- Read the actual constants file for exact enum values — never guess.
6. Structure & helpers
- One folder per journey:
<feature>/<journey>/{journey.spec.ts, mocks.ts, helpers.ts}. Domain seeds in shared/, constants in e2e/constants/.
- Generic cross-domain helpers (tab switching, totals) live in
e2e/helpers/common.ts.
7. Running & CI
- Build then run against the preview server:
pnpm build --force then CI=1 npx playwright test. The dev server on port 3000 may serve a different worktree's code.
- Run
npx prettier --write on every touched file before pushing — the CI quality gate fails on unformatted code.
- Never run multiple E2E builds/tests in parallel — all preview servers share port 4173, so parallel runs conflict and flake. When fixing several E2E PRs, agents only write; build/test sequentially, one worktree at a time.
- Don't auto-rerun a flaky E2E failure when it cancelled at an infra/setup step (
Install Playwright OS dependencies, runner allocation, network) and the PR doesn't touch test code — that's noise, not a real failure.
8. Debugging a runtime-only browser error
When a bug only shows in the browser console (not in any build/lint log) and the Claude Chrome extension isn't connected, drive Playwright headlessly to read the console yourself instead of guessing — it's already a dep. Pattern (a throwaway probe.mjs inside the app dir so @playwright/test resolves; pnpm exec playwright install chromium first):
import { chromium } from '@playwright/test';
const b = await chromium.launch(); const p = await b.newPage();
const errs = [];
p.on('pageerror', e => errs.push(e.message));
p.on('console', m => { if (m.type()==='error') errs.push(m.text()); });
await p.goto('http://localhost:3001/', { waitUntil: 'load', timeout: 30000 });
await p.waitForTimeout(4000); await b.close();
console.log('MATCH=', errs.filter(e => /createTheme/i.test(e)).length, 'TOTAL=', errs.length);
Always reproduce the baseline first — run the probe against the broken state and confirm it detects the error — before trusting a "0 errors" result on a fix. Delete the probe file before committing. This technique is often used to confirm dist/HMR-staleness bugs, where a change silently doesn't take effect in the running dev server.
