Write an end-to-end browser test
An end-to-end test proves a user journey works through the real UI against a real (or
faithfully stubbed) backend. It is the slowest and most flake-prone test in the suite —
Google's data shows flakiness grows with test size and with WebDriver-style tooling — so
it earns its place by covering a journey no cheaper test can, and by being deterministic:
no sleeps, no order dependence, no data another test created.
Procedure
- Find the harness. Locate the repo's browser setup (
playwright.config.*,
cypress/, a test:e2e script). Use it exactly — its browsers, base URL, webServer
block and CI command. Do not add a second framework. If none exists and the ticket does
not ask for one, raise request_decision with the smallest viable setup. (Independent
tester: never raise request_decision; follow black-box-test — scaffold a disposable
rig in a test directory only with what the repo already has installed, run the spec
once, and record manual_note rows.)
- Push coverage down first. For each acceptance criterion ask whether a component or
integration test proves it (the
frontend-testing and add-integration-test skills).
Only journeys that need the real browser, routing, cookies or the full stack belong
here.
- Write the journey in plain words: start state → user actions → what the user must
observe. Map each AC to one observable outcome on screen or one persisted result. Name
the test after the journey and cite the AC.
- Own your data. Create what the test needs through an API call, seed script or
factory inside the test (or a fixture), with unique values, and clean up. Never depend
on another test's leftovers or a shared account; each test gets a fresh browser context.
Save authenticated state once (
storageState) rather than logging in through the UI in
every test.
- Locate like a user.
getByRole with the accessible name, then getByLabel,
getByText; chain and filter({ hasText }) to scope. getByTestId only when no
accessible handle exists, with a comment why. No XPath or styling-class CSS selectors.
- Use web-first assertions; never wait for time.
await expect(locator).toBeVisible(),
toHaveText, toHaveURL, page.waitForResponse. Never waitForTimeout/cy.wait(ms),
and never expect(await locator.isVisible()).toBe(true) — it does not retry. Every
Playwright call is awaited (@typescript-eslint/no-floating-promises catches misses).
- Assert the outcome, not the DOM. What the user sees, and what the system persisted:
reload the page or query the API to prove a save survived, check the stub outbox for the
email. A toast saying "Saved" is not proof the data was saved.
- Stub only what you do not control. Third-party services go through
page.route(...)/cy.intercept with recorded responses; your own backend stays real.
- When an AC concerns concurrent users or failure, drive it for real: two browser
contexts editing the same record (assert the documented conflict behaviour, no silent
overwrite); the backend returning an error or going offline via
page.route →
abort(); the user sees the documented error and can retry.
- Keep failures diagnosable. Traces on first retry (
trace: 'on-first-retry'),
screenshots on failure. Retries may be on in CI to collect traces, but a test that
passes only on retry is flaky and not done.
- Run it until stable: the spec three times in a row headless, e.g.
npx --no -- playwright test <spec> --repeat-each=3, then the repo's CI command. Record the
command and result with the record-evidence skill (test_output) per AC.
Done when
- Each AC that needs a browser has a journey test asserting its observable outcome.
- The spec passes three consecutive headless runs without retries, and in the CI command.
- No fixed sleeps, CSS-structure selectors, shared accounts or order dependence remain.
Rules
- One journey per test; keep the count small and the coverage wide.
- The backend under test is real or a faithful stub declared in the test; never mock the
browser side to make the assertion pass.
- Match the repo's harness, browser pins and CI command exactly.
- Work on the delivery branch the runner prepared (verify with
git branch --show-current),
never a protected branch.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While standing the app up for a browser journey you learn how it is really started, which env vars and ports it needs, and which selectors the design system exposes. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: e2e-browser-test3description: Use when a ticket asks for end-to-end or browser coverage of a user journey — sign-up, checkout, a form submission, a dashboard flow — driven through the real UI with Playwright, Cypress, or the repo's browser harness. Invoke for "add an e2e test", "cover the flow in the browser", or when an acceptance criterion can only be shown by clicking through the app.4stack: [react, web, next, vue, svelte, angular, node]5area: testing6metadata:7 source: https://skillmd.com/skills/tmj-90/e2e-browser-test8---910# Write an end-to-end browser test1112An end-to-end test proves a user journey works through the real UI against a real (or13faithfully stubbed) backend. It is the slowest and most flake-prone test in the suite —14Google's data shows flakiness grows with test size and with WebDriver-style tooling — so15it earns its place by covering a journey no cheaper test can, and by being deterministic:16no sleeps, no order dependence, no data another test created.1718## Procedure19201. **Find the harness.** Locate the repo's browser setup (`playwright.config.*`,21 `cypress/`, a `test:e2e` script). Use it exactly — its browsers, base URL, `webServer`22 block and CI command. Do not add a second framework. If none exists and the ticket does23 not ask for one, raise `request_decision` with the smallest viable setup. (Independent24 tester: never raise `request_decision`; follow `black-box-test` — scaffold a disposable25 rig in a test directory only with what the repo already has installed, run the spec26 once, and record `manual_note` rows.)272. **Push coverage down first.** For each acceptance criterion ask whether a component or28 integration test proves it (the `frontend-testing` and `add-integration-test` skills).29 Only journeys that need the real browser, routing, cookies or the full stack belong30 here.313. **Write the journey in plain words:** start state → user actions → what the user must32 observe. Map each AC to one observable outcome on screen or one persisted result. Name33 the test after the journey and cite the AC.344. **Own your data.** Create what the test needs through an API call, seed script or35 factory inside the test (or a fixture), with unique values, and clean up. Never depend36 on another test's leftovers or a shared account; each test gets a fresh browser context.37 Save authenticated state once (`storageState`) rather than logging in through the UI in38 every test.395. **Locate like a user.** `getByRole` with the accessible name, then `getByLabel`,40 `getByText`; chain and `filter({ hasText })` to scope. `getByTestId` only when no41 accessible handle exists, with a comment why. No XPath or styling-class CSS selectors.426. **Use web-first assertions; never wait for time.** `await expect(locator).toBeVisible()`,43 `toHaveText`, `toHaveURL`, `page.waitForResponse`. Never `waitForTimeout`/`cy.wait(ms)`,44 and never `expect(await locator.isVisible()).toBe(true)` — it does not retry. Every45 Playwright call is awaited (`@typescript-eslint/no-floating-promises` catches misses).467. **Assert the outcome, not the DOM.** What the user sees, and what the system persisted:47 reload the page or query the API to prove a save survived, check the stub outbox for the48 email. A toast saying "Saved" is not proof the data was saved.498. **Stub only what you do not control.** Third-party services go through50 `page.route(...)`/`cy.intercept` with recorded responses; your own backend stays real.519. **When an AC concerns concurrent users or failure,** drive it for real: two browser52 contexts editing the same record (assert the documented conflict behaviour, no silent53 overwrite); the backend returning an error or going offline via `page.route` →54 `abort()`; the user sees the documented error and can retry.5510. **Keep failures diagnosable.** Traces on first retry (`trace: 'on-first-retry'`),56 screenshots on failure. Retries may be on in CI to _collect_ traces, but a test that57 passes only on retry is flaky and not done.5811. **Run it until stable:** the spec three times in a row headless, e.g.59 `npx --no -- playwright test <spec> --repeat-each=3`, then the repo's CI command. Record the60 command and result with the `record-evidence` skill (`test_output`) per AC.6162## Done when6364- Each AC that needs a browser has a journey test asserting its observable outcome.65- The spec passes three consecutive headless runs without retries, and in the CI command.66- No fixed sleeps, CSS-structure selectors, shared accounts or order dependence remain.6768## Rules6970- One journey per test; keep the count small and the coverage wide.71- The backend under test is real or a faithful stub declared in the test; never mock the72 browser side to make the assertion pass.73- Match the repo's harness, browser pins and CI command exactly.74- Work on the delivery branch the runner prepared (verify with `git branch --show-current`),75 never a protected branch.7677## Capture lore7879This skill is one of the places durable, reusable knowledge naturally surfaces:80**While standing the app up for a browser journey you learn how it is really started, which env vars and ports it needs, and which selectors the design system exposes.** That kind of fact is *lore*. Capture it via the **lore-capture81protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):82call the Memory MCP `suggest_lore` once at the close of your work — reusable83conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.