# Browser tests (Playwright and axe) Status: V1-1.3, 2026-10-25 (decision D14, `V1-1_OWNERS_ANIMALS.md` §12.5). Chromium only until V1-5. The suites live in `apps/app/e2e`. ## 1. Suites | Command | Backend | Dev server | Content | |---|---|---|---| | `pnpm e2e:ui` | none | Vite on `127.0.0.1:5191` | `e2e/ui/dialog.spec.ts`: the D13 contract of the shared Dialog on a test page; `e2e/ui/local-tool.spec.ts`: the disclaimer, edit and replace dialogs on the real local-tool routes | | `pnpm e2e:shell` | the isolated stack of `pnpm db:sandbox` | Vite on `127.0.0.1:5192` | `e2e/shell/shell.spec.ts`: sign-in, dashboard, the account photo confirmation, the phone drawer | Each suite runs on two Chromium projects: `chromium-desktop` (1280 × 800) and `chromium-375` (375 × 667, mobile viewport, touch). A test tagged `@phone` runs on the phone project only (the drawer has no desktop counterpart). Both languages run: the local tool and the shell through the browser locale and the account's locale, the test page through `?lang=en`. The test page `e2e/harness/dialog.html` is served by the dev server only (`/e2e/harness/dialog.html`); the build has one entry, `index.html`, so it never ships. It holds the D13 cases (basic, long content, refused close, vanishing opener) and no product journey. The shell suite never reaches DEV. Its dev server is built with the Supabase URL `http://sandbox.faunosteo.invalid` (a name that resolves nowhere, RFC 6761); `e2e/support/sandbox.ts` replays `/auth/v1`, `/rest/v1` and `/storage/v1` on the sandbox's loopback ports, the way Kong maps them on the CLI stack. Each test creates its own confirmed account through the sandbox's GoTrue admin API (random address under `sandbox.local`, random password, a fictitious display name, the profile locale of the test), and seeds the clean avatar the worker would have produced (the `assets` row as postgres, the object with the service key). `pnpm db:sandbox down` removes all of it. ## 2. Prerequisites - The repository's Node and pnpm, `pnpm install`. - The Chromium build of the pinned Playwright (1.64.1, Chromium 1248): `pnpm --filter @faunosteo/app exec playwright install chromium`. It downloads into `~/.cache/ms-playwright` and needs no `sudo`. Never pass `--with-deps`: it installs system packages with `sudo`, an owner action. On the Ubuntu development machine the headless shell runs with the libraries already present. - `pnpm wasm:build`: the local tool runs the core, and the UI suite stops on a missing or stale module (`packages/core-wasm/tests/global-setup.ts`). - For `pnpm e2e:shell`: Docker (rootless works) and the sandbox up, `pnpm db:sandbox up fresh` (or `up upgrade `). - Ports 5191 and 5192 free: each server uses `--strictPort` and is never reused, so the owner's `pnpm dev` on 5173 is never picked up by mistake. ## 3. Guarantees - Request guard (`e2e/support/browser.ts`, automatic in every test): an allowlist of origins per suite (the dev server, plus the fake Supabase origin for the shell). Any other request, DEV's API on the LAN address included, is aborted and fails the test with its URL. - No fixture value in a URL: the local tool's names and the shell account's email, password and display name are checked against every request URL; a match fails the test and the report masks the value. - axe (`@axe-core/playwright` 4.14.0, rules tagged WCAG 2.0 to 2.2 A and AA plus best practices): zero serious or critical violation on each scanned state, colours measured once animations have settled. Three pre-existing findings, outside the V1-1.3 code, are let through by exact node and listed with their reason in `KNOWN_VIOLATIONS` and in TODO RR-7: the language switcher's names (« FR » shown, « Passer en français » announced), the top bar account link (display name shown, « Mon compte » announced), the dashboard's `dl` holding a status row without `dt`/`dd`. - Reports: `apps/app/e2e/test-results/` and `apps/app/e2e/playwright-report/`, git-ignored. The UI suite keeps a trace and a screenshot of a failed test (no backend, no secret). The shell suite keeps a screenshot only: a trace would hold the session tokens and the typed password. ## 4. Reading a failure The terminal shows each step and the failing assertion. The HTML report: `pnpm --filter @faunosteo/app exec playwright show-report e2e/playwright-report/ui` (or `.../shell`); a UI trace: `pnpm --filter @faunosteo/app exec playwright show-trace `. Setup failures are named: a missing Chromium (Playwright prints the install command), a stale core module (`run pnpm wasm:build`), the shell suite outside its wrapper (`SANDBOX_ANON_KEY missing: run pnpm e2e:shell`), the sandbox down (`db-sandbox: not running`). ## 5. In `pnpm check:all` and a future CI `pnpm check:all` runs `pnpm e2e:ui` when the pinned Chromium is installed; otherwise it prints `SKIPPED` with the reason and the install command, and goes on. `pnpm e2e:shell` needs the sandbox and stays a separate run, like `pnpm e2e:avatar`. A CI runner installs the same Chromium (`playwright install chromium` in its image) and runs `pnpm e2e:ui`; the shell suite needs Docker in the runner for the sandbox. ## 6. Limits - Chromium only. Firefox, WebKit and the 412 × 915 viewport join at V1-5 (contract §12.5). WebKit's system libraries may need `sudo` (owner action). Desktop WebKit is not iOS Safari: the owner's manual check on a real iPhone and on a computer over the LAN stays a validation criterion of every mobile step. - Tab past a modal dialog's last control reaches the browser's own interface for one step, then the first control (the platform's behaviour, D13); the page behind is never reached. The tests assert exactly that walk. - Safari does not focus a button on a pointer click, so a dialog opened by a click has no opener to return to there; a keyboard opening always has one. - The vitest suites (happy-dom) cover the React wiring of the dialogs only: happy-dom has no top layer, no inertness and no dialog focusing steps. ## 7. Adding a test Import `test` and `expect` from `e2e/support/browser.ts` (the request guard comes with them), read every visible string from `@/i18n/{fr,en}`, use fictitious values only, and pass the values a test creates to `requests.forbid(...)`. A new backend origin goes into the suite's `allowedOrigins`, never into a wildcard.