310 lines
34 KiB
Markdown
310 lines
34 KiB
Markdown
# 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, except the canvas click proof (V1-2.2), which also
|
||
runs on Firefox and WebKit, desktop and the WebKit phone, when the pinned
|
||
engines are installed. 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 (since 2026-11-15 the ✕ measured at least 44 × 44 px, inside the viewport, beside a wrapped long title at 320, 375 and 1 280 px, with axe); `e2e/ui/working-copy.spec.ts`: the real `WorkingCopyAction` and its dialog on a test page (axe, layout, keyboard, fr and en, desktop and 375 px); `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; `e2e/shell/clients.spec.ts`: the client journeys (V1-1.5); `e2e/shell/animals.spec.ts`: the animal and relation journeys (V1-1.6, contract §11.8); `e2e/shell/responsive.spec.ts`: no sideways scroll on nine shell pages, the archive confirmations and the drawer at 320, 360, 375, 390 and 430 px (phone project) and 1280 px, long values, the dashboard e-mail shown whole (RESP-01); `e2e/shell/admin.spec.ts` (V1-2.5): A0 the owner's bootstrap (two TOTP factors from Sécurité, the step-up at `/app/admin` and inside a factor action, no second factor from `aal1`, refresh keeping `aal1` and `aal2`, rights granted and revoked with their reason), A1 a sheet created by an editor on a new inactive species, S1 a species created inactive then activated by the owner, the creation page when the own-grants read fails (« Impossible de vérifier vos autorisations » and « Réessayer », never the form; Retry brings the form back), access per right (a reviewer-only account refused on the creation page), axe and no sideways scroll on every admin page; `e2e/shell/catalogue.spec.ts` (V1-2.5): P1 a reader searches, opens a sheet, picks a zone, reads a retired version, drafts and archived sheets never listed, the same refusal for an existing and an unknown sheet without access, 320, 375 and 430 px with the whole drawing in the box at opening; at 320 and 375 px the zone panel's live region present before a pick and naming the picked zone, the « Références » card starting at or below the drawing's bottom; `e2e/shell/admin-sheets-list.spec.ts` (V1-2.6 R3): the official sheet list's search, sorts, count line and dates and the Administration home's latest changes (below, « The sheet list spec »); `e2e/shell/catalogue-integrity.spec.ts` (V1-2.6 R4, board 30): a sound and an altered catalogue sheet seeded per run; the integrity line in fr and en at desktop and 375 px (« Consulter » kept, 44 px, opening the unchanged sheet page notice, axe, no sideways scroll), the network line in fr with one version aborted (`route.fallback()` for the rest), the card remounted by search, « Réessayer » and the focus on « Consulter »; the run's sheets archived and its grant revoked by id (6 passed, 0 failed, 0 skipped, 0 flaky, twice, 2026-11-17); `e2e/shell/editor-*.spec.ts` (V1-2.6, the draft editor level 1, contract C16 to C34): `editor-drawings` (A2: a hostile file refused with no cleaning box, an Inkscape export cleaned after its preview, a valid file attached, a detail view by crop, the same bytes attached twice), `editor-annotations` (A3: points, zones and links by clicks and by keyboard only, move by drag, a click with jitter never moves, numeric edits, undo and redo, review and delete), `editor-geometry` (a click near a frame edge with the corrected position confirmed and cancelled, an inherited out-of-frame point repaired through the geometry group, a crop change refused when it would invalidate a point, an unmeasured view with its tools disabled, touch-action and a touch drag in real Chromium), `editor-structures` (A4: categories, references, regions, findings tree, reorder, mark reviewed, delete with dependents; since the finish findings and references go through their dialogs, the delete dialog stacked over the finding dialog), `editor-references` (R2 and finish: read-only tiles, the reference dialog from « Modifier » and « Ajouter » with axe, its draft and its read-only flip, a tile edited out of the search keeping its place), `editor-journey` (the steps of `V1-2-6_OWNER_TRIAL.md` §4 with two editor accounts, a finding created through its dialog and the dialog closed before the next add: creation, drawing, findings, annotations, save, reload with the beforeunload dialog and the recovery offer, conflict, submission, the round read back in SQL), `editor-recovery` (two sessions, an older local copy restored then saved over a newer revision, a pending offer blocking edits, an unreadable copy kept until « Ignorer », Escape on the conflict read, the editor grant revoked, the admin role removed and the grant expired under an open session), `editor-access` (the finding dialog and the references dialog scanned by axe at the widths; a reviewer-only account read-only, the not-found screen for an editor without the admin role and for an admin without a capability, 320, 375 and 800 px read-only, 1 024 px editing, axe on every tab edit and read-only), `editor-deselect` (R1, D5 and D6b: « Désélectionner » with its live region, the focus on the list row and the document unchanged; Escape over the canvas, a field, the delete dialog, the references dialog over the finding dialog (Escape closes the references dialog, a second one the finding dialog, a third deselects) and a tracing; mouse clicks on empty parts deselecting, on annotations selecting; zoom, pan, marker drag and Ctrl+wheel keeping the selection; a typed value applied by the deselecting click; at 1 280 px with `hasTouch` and CDP touch taps near annotations and the canvas bottom deselecting once, drags, two-finger taps and pinch keeping the selection, with the pointer events counted by a recorder; the read-only twin at 375 px and Escape closing « Plus » before deselecting; the drawing's top unchanged when a point, a zone and a link are selected then deselected, on desktop and on the read-only twin at 375 px, with the selection tag out of the visual flow), `editor-equine` (the sheet and the finding dialog closed between visits since the finish; the historical equine sheet opened as a working copy, a copy left active by an earlier run set aside and put back; commit latency on it and on a synthetic document near 2 MiB, printed as `LATENCY` lines and kept as test annotations, budget 500 ms per commit on the equine copy; one empty click on a bone of the horse drawing deselects, D6b). U1 shell (V1-2.6 U1, the tabbed shell): `editor-shell` (the Références tab keeping its search; kept-mounted places, focus on a named element, the open panel leaving the header and the tab row clickable at 1 024 and 1 280 px, the sidebar from 1 280 px and the drawer, canvas widths), `editor-shell-journeys` (a finding opening in its dialog in view mode, the row holding the focus once closed; five tabs, cross-tab undo, typed text then the header undo, a refused field kept through a real Shift+Tab to « Défaire », Ctrl+Z outside and inside a field, « Aller à » for each issue kind, the save line from the count to « Enregistrement… » to the time and revision), `editor-shell-crossing` (the findings creation form kept in its dialog while narrow, draft, focus and a notice kept; every edit-only part typed, a 1 024 px crossing, no edit control and the focus on the shown tab, widening with the values back; the section and the panel open; unsaved work and the recovery copy kept; a drag across the crossing commits nothing; delete and discard confirmations closing; a decision withheld under the panel waiting for « Reprendre »), `editor-shell-layout` (since the finish a citations dialog replaces the panel, since 2026-11-15 the references dialog replaces the side sheet: inside the viewport with the focus inside, no document size change, the Tab order kept inside it, inside the screen at 667 × 375 through a rotation, the cramped-landscape and swipe-reach cases gone; before: 667 × 375 reached by touch, and the worst case placed by script; no sideways scroll at 1 024, 1 180, 1 279 and 1 280 px on the five tabs, the sections and the references dialog, and at 320, 375 and 768 px read-only; axe from the top on every place; the canvas width without and with the panel as `canvas-width` and `canvas-width-panel` annotations; the keyboard order header, tab list, « Défaire », « Refaire », the panel when open, then tools, canvas and side column); the equine spec also times commit to paint with every place visited. `editor-history` (finish, R2F-1: tabs, an Annotations section, « Retour au dessin », arrow-key walks as one entry, the scroll offset, a reload, a DeleteDialog open at Back), `editor-finding-dialog` (finish, R2F-3: click, Enter and Space opening it, a pristine and a changed « Enregistrer », « Abandonner » and a width flip keeping the draft, a dirty Escape and Back asking, deletion landing on the nearest row, creation as a layer, a vanished element, Back and Forward walking the layers, and since 2026-11-14 a deletion followed by one « Défaire » restoring the row selected and focused, then Back moving), `editor-reference-journey` (finish, R2F-5 and R2F-6: the owner's eight steps at 1280 and 375 px, ending on finding A with the references dialog open (2026-11-15), every Back, a reload keeping the filtered tab and chip but no form, the chip × removing the filter by replace, a double click and a held Escape popping one entry, a dirty reference dialog kept across Back), `editor-more-menu` (finish, R2F-7: the « Plus » overlay at several widths with axe, closing on a choice, an outside tap and Escape; since 2026-11-15 at 375 and 320 px the tab row shows Général and Annotations then « Plus », its entries stack in tab order (Constats, Références, Vérification), each at least 44 px high and inside the viewport, axe with an active row, « Plus » found without an exact name because it may carry the error count; Enter on an entry at 375 px putting the focus on that tab's panel, 2026-11-14; the sidebar fixed at 1280 and 1024 px and scrolling alone at 1280 × 500) and `editor-leave-confirm` (2026-11-14, criterion 23: a history jump of several entries made through the DevTools protocol on the pinned Chromium, from a dirty finding dialog or a dirty reference dialog, is cancelled and asks « Abandonner les modifications ? », the URL and the draft kept, « Continuer la saisie » keeping both, « Abandonner » landing on the overview with no left-draft flag and no notice; a dirty reference over the references dialog of a dirty finding asking twice, the dialog closed before the second question, which has the focus on « Continuer la saisie »; since 2026-11-15 a dirty references draft asking before the jump goes; the history entry holding a 32-hex `tag` and no `userId`). Editor accounts, drafts and drawings are prepared by `e2e/support/editor.ts` (a drawing in its stored form, written by the core); `e2e/support/warm-up.ts` is the suite's global setup (the dev server reloads the page once when a route first loads a dependency, so one throwaway session visits the editor routes before the tests). Editing needs 1 024 px: these specs skip the 375 px project; `editor-citations` since 2026-11-15 (pre-closure): « Citer » and the arrow-key case, a pending reference saved or abandoned, the family wording, the 44 px ✕ with a long finding name |
|
||
|
||
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 test page `e2e/harness/working-copy.html` (same rules) renders the
|
||
application's own `WorkingCopyAction` twice, slot free and slot taken, under
|
||
`StrictMode` and a `MemoryRouter`; no request is made. Coverage change
|
||
(anomaly B, V1-2-6_U1_CORRECTIONS.md §5): the dialog's axe, layout and
|
||
keyboard checks moved there from the « admin screens » test of
|
||
`e2e/shell/admin.spec.ts`, because only the historical sheet offers the
|
||
action and the single working-copy slot is shared, mutable database state.
|
||
The shell test keeps the historical page in its axe and overflow loop and
|
||
checks that the button is disabled exactly when its reason is shown and
|
||
linked. Limit: the dialog is no longer checked in its real server context by
|
||
this accessibility test; the server refusals stay covered by
|
||
`packages/supabase/tests/sandbox/sheets-admin.sandbox.ts`.
|
||
|
||
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). Rows around the subject of a test (clients,
|
||
animals, relations) are written as postgres by `e2e/support/records.ts`,
|
||
every value quoted as an SQL literal. The V1-2.5 suites set up what lies
|
||
before the page the same way: platform roles, catalogue grants and other
|
||
accounts' verified TOTP factors by `e2e/support/admin.ts` (roles through the
|
||
operator path, grants as postgres, a factor enrolled and verified on the real
|
||
GoTrue, its secret kept in the test's memory); official sheets by
|
||
`e2e/support/catalogue.ts` as SQL fixtures (published, retired, archived and
|
||
draft-only versions carrying the curated equine draft under names of their
|
||
own, the drawing in the private bucket under its content key), each published
|
||
or retired version's fingerprint computed in Node by the shipped core module
|
||
(`packages/core-wasm/pkg`, `preview.state`), the one the page runs. A0, A1, S1
|
||
and the creation page's unreadable-permissions test are desktop journeys, skipped on the phone
|
||
project (8 skips by design); the admin screens at 375 px have their own test.
|
||
`pnpm db:sandbox down` removes all of it.
|
||
`pnpm db:sandbox e2e-shell <args>` passes its arguments to Playwright: one
|
||
spec file, `--project`, `--grep`. Every shell suite removes its routes after
|
||
each test without waiting for them (`dropLateReplays`), so an answer still in
|
||
flight when the last check passed is dropped with the context instead of
|
||
failing the test (the V1-1.6 verifier saw the client journey fail that way once
|
||
the client page reloads its animals after a restore).
|
||
|
||
### The Références specs (V1-2.6 R2)
|
||
|
||
`e2e/shell/editor-references.spec.ts` covers the Références tab. Tiles: closed and open with axe in each state; the
|
||
reference dialog from « Modifier » and « Ajouter » (axe, draft kept, read-only flip) since the R2 finish, which replaced
|
||
the inline edit view and the add tile; the tile headers as a keyboard walk (Tab between them, Enter and Space open);
|
||
« Aller à » on a citer opening Constats on it. Search, sort and add: the four sorts, search, clear, no result and the
|
||
move buttons with the server document never changing; adding a reference, saving it, then deleting an uncited one; an
|
||
edited tile keeping its place under a sort and a search. Read-only at 375 px: « Plus » lists Références, tiles keep
|
||
DOI, URL and « Aller à », no edit control.
|
||
|
||
`e2e/shell/editor-citations.spec.ts` covers the citations of a finding: a modal side sheet over its dialog at the R2
|
||
finish (2026-11-13), a references dialog stacked over it since the owner follow-up (2026-11-15). View mode: the dialog
|
||
opens over the finding dialog and only reads (no « Modifier » on its tiles; the finding's edit form cites nothing and
|
||
its save keeps the citations); a family opens the same dialog with its own citations, and « Tout afficher » from it
|
||
filters the library by the family, Back returning to the dialog; a long list scrolls inside the dialog and « 0 référence »
|
||
opens the empty one (a family's empty line reads « Cette famille ne cite aucune référence. »); « Tout afficher » closes both layers, clears the search, keeps the sort and the open tiles, and Back
|
||
returns to the dialog; the exiting dialog is inert and a second close finds nothing; keyboard (Enter opens, Tab in
|
||
order, Escape closes only it); each close path (✕, Escape, the backdrop, Back, « Tout afficher », « Aller à ») checks
|
||
where the focus lands, and the dialog scales in only when motion is allowed. Edit mode (2026-11-15, editing needs
|
||
1 024 px): cite (choose, then « Citer ») and remove, « Enregistrer », one header « Défaire » restores, axe on the edit mode;
|
||
ArrowDown on the select only chooses, « Enregistrer » with a choice not cited refuses (the line, the focus on « Citer »,
|
||
« Citer » level with the add button), and ✕ then asks nothing; the ✕ is a box of at least 44 × 44 px beside a long
|
||
finding name at 1 280 px; a dirty draft makes
|
||
✕ and Back ask, and « Abandonner » writes nothing; « Modifier la référence » stacks the reference dialog and, closed,
|
||
the draft is back; « Nouvelle référence » stays in the draft: then « Abandonner » leaves the library unchanged (no
|
||
« Défaire », nothing listed in the Références tab, nothing announced), then « Enregistrer » writes the reference and its
|
||
citation, and one « Défaire » removes both. Read-only at 375 px: the dialog inside the viewport through « Plus » then
|
||
Constats, no edit control, axe; the ✕ at 44 × 44 px beside a long name at 375 and 320 px; by touch, taps act on the references
|
||
dialog only and the finding dialog under it stays.
|
||
|
||
### The sheet list spec (V1-2.6 R3)
|
||
|
||
`e2e/shell/admin-sheets-list.spec.ts` needs the sandbox migrated to M9 (`pnpm db:sandbox migrate`) and never opens
|
||
the rights screen (`/app/admin/access`, BLK-015). Serial, one editor account at `aal2` per project, French and
|
||
English, desktop and 375 px (4 tests). Fixtures: three official draft sheets named with a run token (« R3 {token}
|
||
Alpha », « Émeu », « Zèbre », English names with the same token), seeded in that order, each id kept as soon as it
|
||
exists; then one more save of Alpha's draft through `save_sheet_draft`, so Alpha's sheet row is the oldest of the
|
||
three and only the true last modification puts it first. Checks: a search on the token gives three rows, and the
|
||
count line's total equals the length of the `list_official_sheets_admin` answer captured in the same load; the order
|
||
Alpha, Zèbre, Émeu by « Dernière modification », then Alpha, Émeu, Zèbre by « Nom »; each row's date in the ratified
|
||
format; the token followed by 100 characters without a space, cut at the field's limit, shows the no-result sentence
|
||
with no sideways scroll, and « Effacer la recherche » empties the field, gives it the focus and restores the count;
|
||
axe and no sideways scroll on the searched list, the empty state and `/app/admin` (never on the unsearched list of the
|
||
accumulated sandbox); the home's sub-heading, at most five items with non-increasing `time[datetime]`, and a footer
|
||
link that carries a number and opens the list. Teardown (owner decision D7): each id this run created is
|
||
soft-deleted through `delete_anatomical_sheet` with the same token, the returned id checked, each step independent of
|
||
the others. A sweep adds two accounts and two catalogue grants to the sandbox (BLK-015 counts grants), and leaves no
|
||
sheet listed. `allSheetsLink(scope, dict)` (`e2e/support/admin.ts`) finds the sheets card's link by
|
||
`admin.home.all_sheets` or by `admin.home.see_all` with any number; the three earlier locators of that link (A1 and
|
||
« access per right » in `admin.spec.ts`, `createSheetFromAdmin` in `editor-journey.spec.ts`) use it, their assertions
|
||
unchanged. Closed by the final fix wave (`ea5512a`): the spec runs with `timezoneId: 'UTC'`, so a regression to
|
||
local time fails on any host; the home's ordering loop first asserts one `<time>` per item; the date pattern escapes
|
||
the dictionary text (`escaped`, exported by `e2e/support/admin.ts`); the long-search check types the text again and
|
||
presses Escape (field empty and focused, count back); every value of the three fixture statements goes through
|
||
`literal()` (`e2e/support/records.ts`), the ids refused unless they have the uuid shape.
|
||
|
||
Results on 2026-11-16 (code at `b4a5254`): the spec alone, 4 passed, 0 failed. The sweep of 27 spec files without
|
||
`editor-equine.spec.ts`, 446 tests: 277 passed, 6 failed, 163 skipped, 0 flaky. The six failures, named: « admin
|
||
screens » (`admin.spec.ts:714`) ×4, fr and en at desktop and 375 px, `frame.evaluate: Target crashed` during axe at
|
||
`admin.spec.ts:747`, inside that test's loop over the admin pages (the page is not recorded in this run; BLK-015's
|
||
description below names the rights screen as the proven cause in earlier runs); A0 « the rights screen with grants » (`admin.spec.ts:220`) ×2, fr and en at desktop, the grant
|
||
lookup stuck on « Recherche… » until the « E-mail confirmé » check timed out at `:144`, about 7 600 grant rows
|
||
rendered. All six are counted as BLK-015, the A0 pair with another symptom than « Target crashed »; NOT proven by an
|
||
A/B run against the commit before R3. Green as required: A1 and « access per right » in both languages,
|
||
`editor-journey`, the new spec. The data guard found 0 pre-existing sheet or version row changed or missing.
|
||
|
||
Final fix wave run (2026-11-16, code at `ea5512a`), one run of `admin-sheets-list.spec.ts`, `admin.spec.ts` and
|
||
`editor-journey.spec.ts`: 15 passed, 6 failed, 9 skipped. The new spec 4 passed; A1 and « access per right » in both
|
||
languages and `editor-journey` passed. The six failures, all `admin.spec.ts`: « admin screens » (`:714`) fr desktop,
|
||
en desktop and fr 375 px, `frame.evaluate: Target crashed` during axe at `:747`; « admin screens » en 375 px,
|
||
`page.evaluate: Test timeout of 180000ms exceeded` during axe at `:747`, the failure screenshot on the rights screen;
|
||
A0 (`:220`) fr, the « E-mail confirmé » check at `:144`; A0 en, the « Right granted. » check at `:158`, the submit
|
||
button stuck on « Granting… ». Counted as BLK-015 (the timeout and the `:158` step being further symptoms), not proven
|
||
by an A/B run against the commit before R3. Data guard: 0 changed, 0 missing, 20 new lines (10 sheets and their 10
|
||
versions); the 6 sheets of the R3 spec read back `deleted`.
|
||
|
||
Layout additions in `e2e/shell/editor-shell-layout.spec.ts`: five tabs everywhere the four were checked (no
|
||
sideways scroll from 1 024 to 1 280 px, axe from the top, read-only at 320, 375 and 768 px); the open panel at most
|
||
34 rem and never wider than the viewport, the document size unchanged before, during and after; the canvas width
|
||
equal before the panel opens and after a tab switch closes it; at 375 px read-only the panel full width, its
|
||
bottom on the viewport bottom through a height change and a rotation, the drawing box unchanged.
|
||
`e2e/support/editor.ts` gains `openTab` (a tab at any width, through « Plus » below 640 px), `libraryRoot` (the
|
||
Références tab's place), `openCitations` (optional expansion budget, waits for the heading focus) and
|
||
`closeCitations`; `openReferences` and `closeReferences` are gone, and the warm-up (`e2e/support/warm-up.ts`)
|
||
opens the citations panel instead. The finish adds `findingDialog`, `referenceDialog`, `openFinding`, `closeFinding`,
|
||
`showCitations`, `startReference`, `addReference`, `referenceSettled`, `layersSettled`, `revealFinding` and
|
||
`expectNoDialog`.
|
||
|
||
Running them: `editor-equine.spec.ts` is never run on a persistent sandbox that holds data to preserve (owner,
|
||
2026-11-12), because it sets aside and puts back the working copy of the historical sheet. A shell run names every
|
||
spec by its full path, never a directory or a pattern. After the R2 commits `editor-equine.spec.ts` was updated
|
||
for typecheck only and never run.
|
||
|
||
## 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 <version>`).
|
||
- 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 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`. Each entry names the axe rule, the selector, the
|
||
opening markup of the element and the route where it lives; a node is let
|
||
through only when all four match, so a new screen or a new element never
|
||
inherits an exception (owner brief 2026-10-26).
|
||
- 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 the terminal output and a
|
||
screenshot of a failed test only: a trace would hold the session tokens, and
|
||
an HTML report the typed values, the fictitious accounts' passwords included
|
||
(found in the V1-1.5 report check, 2026-10-26; the HTML reporter was removed
|
||
from the shell config). Screenshots and the failure's page snapshot show
|
||
fictitious names and addresses only.
|
||
|
||
## 4. Reading a failure
|
||
|
||
The terminal shows each step and the failing assertion. The HTML report of
|
||
the UI suite: `pnpm --filter @faunosteo/app exec playwright show-report
|
||
e2e/playwright-report/ui` (the shell suite has none); a UI trace: `pnpm --filter @faunosteo/app exec playwright
|
||
show-trace <path printed in the failure>`. 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` (= `pnpm db:sandbox avatar-e2e`). The last lines of a green run state each browser suite:
|
||
`PASSED`, `SKIPPED` (environment missing, with the reason) or `NOT RUN`
|
||
(`e2e:shell`). A suite that runs and fails stops `check:all` with
|
||
`== FAILED: <stage>` and a non-zero exit, never a warning. Both suites keep
|
||
their own commands and run alone. 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, but `e2e/ui/canvas-clicks.spec.ts` (V1-2.2: projects
|
||
`chromium-320` (320 × 568, touch, the smallest preview the markers' visible
|
||
size is measured on), `firefox-desktop`, `webkit-desktop`, `webkit-375`, the
|
||
last three added when `playwright install firefox webkit` has put the pinned
|
||
engines in the cache; a missing one is named in the run's output and its
|
||
projects do not run; harness `e2e/harness/canvas.{html,tsx}`, dev server
|
||
only). WebKit snaps a real tap or click to whole CSS pixels (measured
|
||
2026-11-01: a tap at x 100.1 lands right of an edge at 100.4, a click at
|
||
100.9 left of it; Chromium keeps the fraction on a click, rounds a tap), so a
|
||
real press keeps 1.5 px of margin from any edge it tests; below that margin
|
||
the spec asks the browser's own hit test (`elementFromPoint`) at the exact
|
||
point. `e2e/ui/interior-clicks.spec.ts` runs on the same six projects
|
||
(V1-2.2, the interior rule): the core's probe cases
|
||
(`e2e/fixtures/interior-probe.json`, generated and drift-checked by
|
||
`crates/core/tests/interior_probe.rs`, `MAKE_INTERIOR_PROBE=1` rewrites it) in
|
||
the phone preview's 286 × 310 box (harness `e2e/harness/interior.{html,ts}`,
|
||
dev server only), then the equine zones in the canvas harness. Chromium's touch
|
||
adjustment gives a point the taps up to about 10 px around its disc
|
||
(measured 2026-11-01, `chromium-320` and `chromium-375`; WebKit 375 does
|
||
not), so the real press on an equine zone goes where its fill lies farthest
|
||
from every disc. Firefox, WebKit
|
||
and the 412 × 915 viewport join every suite 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.
|
||
- axe's target-size rule measures a control partly under the sticky top bar
|
||
as cut. Two phone states of the animal suite are reached at the bottom of a
|
||
long page (the client page after linking an animal, a refused duplicate);
|
||
they are scanned from the top of the page (`expectAccessibleFromTop`), where
|
||
nothing sits under the bar. The controls are 44 px high either way.
|
||
|
||
- `e2e/shell/admin.spec.ts` (A0, the owner's bootstrap, and the admin screens) can end in « Target crashed »
|
||
during axe. Proven cause (C0, 2026-11-13), not an R2 regression: the rights screen renders every catalogue grant
|
||
at once (`list_catalog_grants` takes no argument, `GrantList` shows all of them) and the persistent sandbox
|
||
accumulates e2e grants (2 269 rows at the start, `auth.users` 2 871, 25 grants and 25 accounts added per run).
|
||
Interleaved A/B, the spec alone, `65a8fd3` against `52aac41`: four runs, each 13 passed, 8 skipped, 3 failed, the
|
||
same crash. Dose-response in a quiet window, a temporary spec copy routing `list_catalog_grants` to its 753 newest
|
||
rows: capped (2 526 grants) 16 passed, 0 failed; full (2 551) 11 passed, 5 failed, 4 « Target crashed »; capped
|
||
again (2 570) 16 passed, 0 failed. Still failing on the accumulated sandbox: A0 « the rights screen with
|
||
grants » and « admin screens » (fr or en, desktop and 375). The cure, a paginated grant list, is RR-13; BLK-015
|
||
stays open. Unchanged by the R2 finish (2026-11-13). Rerun the spec alone to separate a crash from a real failure:
|
||
that isolated run is a diagnosis, never the gate.
|
||
R3 sweep (2026-11-16): the same four « admin screens » crashes, and A0 failing twice by a lookup timeout at about
|
||
7 600 grants (other symptom, counted as BLK-015, not A/B proven; « The sheet list spec » above).
|
||
- The layout spec covers the landscape 667 × 375 sample in two parts, in one test of the phone project. The citations
|
||
trigger sits at 811 to 855 px at scroll 0. (A) Touch only: CDP `Input.dispatchTouchEvent` swipes of 200 px
|
||
(`Input.synthesizeScrollGesture` with `touch` scrolls nothing in this Chromium) until the trigger is wholly on
|
||
screen and hit-testable (2 swipes in every run, scrollY 491 to 512); a tap opens the panel, heading and ✕ in the
|
||
viewport and hit-testable, scrollY unchanged. (B) Worst case: an instant programmatic scroll puts the trigger's
|
||
bottom on the viewport bottom (gap 0, scrollY 480); a tap opens the panel, heading and ✕ in view and hit-testable,
|
||
scrollY unchanged. B is programmatic because a touch swipe under about 60 px scrolls nothing (slop) and the gain
|
||
varies under load, so a pixel-exact touch landing is not reproducible (an earlier calibrated version oscillated
|
||
by 55 px in the full sweep). The remaining exception (the
|
||
rotation to 667 × 375 with the panel open at scroll 0) is gone with the finish: the panel became a modal side sheet, then (2026-11-15) the references dialog.
|
||
- A control placed below a field whose blur-commit is refused can lose its first click, because the error line
|
||
moves the layout between mouse down and click. An editor-wide pattern found while writing the Références specs
|
||
(« Terminer » got a `mousedown` guard); the general cure is not done.
|
||
|
||
## 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.
|
||
|
||
## Owner trial (V1-2.6)
|
||
|
||
`pnpm db:sandbox trial` serves the app on `127.0.0.1:5193` (Vite config `apps/app/vite/trial.config.ts`, proxy to a trial gateway on `127.0.0.1:57801`) for manual testing in the owner's browser, not a test suite. Ports 5193 and 57801 must be free. Guide: `docs/development/V1-2-6_OWNER_TRIAL.md`.
|