63ed1f3c1f
Squash of experiment/ff-big-modules vs main.
Big-module routing removed: native-EH shrank kicad_editor below
SpiderMonkey's x86-64 code budget (runs 29355049705/29356152413 green on
stock Firefox), so BIG_MODULE_SPECS routing and the baseline-only-JIT
crutch are gone — kicad-firefox and kicad-chromium both run the full
suite, with the module compiled the way real users' browsers compile it.
Per-engine screenshots end to end: stableShot/shotPath write
test-results/<engine>/<name>.png; baselines move to
baseline-screenshots/{chromium,firefox}/ and the whole tools/screenshots
pipeline (compare/promote/manifest/spec-map/changelog/Discord) keys on
<engine>/<name>. Previously Firefox and Chromium renders of one spec
overwrote each other and Firefox renders were never actually gated.
Seeded from CI run 29421380806 (92 new firefox baselines, +24 chromium
web-suite shots); manifest generated from the baseline tree.
One merged playwright.config.ts (kicad/asyncify/coroutine/perf as
projects); ~25 dead npm scripts dropped. The web suite is gated in CI for
the first time ever (4 rotted specs fixed, 5 broken lib-bridge specs
triaged as fixme in docs/features/web-e2e-rot/); cheap lint step after
npm ci; last 26 blind-sleep violations fixed.
SwiftShader retired: CI Chromium renders WebGL on ANGLE → Mesa llvmpipe
(--use-gl=angle --use-angle=gl --ignore-gpu-blocklist; the blocklist flag
is mandatory — llvmpipe is blocklisted and WebGL is silently unavailable
without it) in BOTH configs. Under WORKERS=4 congestion SwiftShader
transiently failed the first post-board-load draw and the recovery
cascade ended in a silent permanent Cairo fallback — that engine flip was
the "~1.2% changedRatio both directions" occ-export baseline flake.
Validated 160/160 across two 80-repeat rigs; full analysis in
docs/features/wx-parity-bugs/occ-export-context-eviction.md. Chromium
baselines shift slightly on llvmpipe — promote once from the first green
run. Deflakes the new coverage exposed: presence baselines settle before
capture; presence fixtures declare current file formats; perf gets its
own outputDir so CI evidence survives; occ-export settles the board paint
before the export dialog; menu-item waits (waitForRenderedByLabel before
clickMenuItem) in 4 specs + the TESTING.md rule.
Web suite runs the PROD build, in parallel: webServer becomes backend
`start` + the standalone's e2e:preview (build-preview.mjs: link-wasm →
stash the public/wasm symlink aside during vite build, build-demo.mjs's
move — then vite preview as the persistent server). The wasm middleware
serves /wasm/* in preview and emits COOP/COEP/CORP itself (a pthread
worker script's own response must carry COEP or Chrome kills it with
ERR_BLOCKED_BY_RESPONSE). VITE_* flags bake at build time;
VITE_ALLOW_USER_OVERRIDE joins turbo globalEnv. fullyParallel + default
workers: 5.2m → 1.4m. Determinism fixes the parallel run exposed:
shared-page specs become serial groups; locks.spec grabs alice's exact
item via the new kicadCollabTestSelectByUuid hook (cross-tab "first
footprint" order is not a ysync invariant); quit specs poll page.url()
(quit supersedes its own navigation — NS_BINDING_ABORTED on Firefox).
Suite: 51 passed / 12 skipped / 0 failed in 1.6m.
CI-coverage gate (lint:ci-coverage): every tests/**/*.spec.ts must be
reachable from the npm scripts the workflows invoke — scraped from
.github/workflows/, resolved through package.json, coverage asked from
playwright --list itself. Rules: uncovered-spec + orphan-project (with a
documented LOCAL_ONLY_PROJECTS allowlist). Gating next to
lint:determinism; 138 spec files / 13 projects accounted for.
Product fixes kept from the investigations (reachable on real GPUs too):
wx 7799fd1be5 — paint flags clear before dispatch + Invalidate always
propagates; kicad 3dcfea5e45 — SwiftShader pass-boundary flush +
per-instance font texture + first-frame GL-error drain (GAL recovery
recovers instead of falling back to Cairo) + the user-facing eeschema
switch navigates again under __EMSCRIPTEN__ (project-sync's
FaceRegistered gate had rerouted it into the hidden sync player; caught
by the newly-gated web suite).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018eUxiPApHgGiu9NFyQfhAq
79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
# Testing rules
|
|
|
|
Determinism rules for the Playwright specs (`tests/e2e`, `tests/kicad`, `tests/web`).
|
|
Enforced by `npm run lint:determinism` (`tools/lint-determinism.ts`, gating in CI). Run specs
|
|
from `tests/` via `npm run test:e2e` (the full CI project set: wx-chromium, kicad-firefox,
|
|
kicad-chromium, asyncify-firefox, coroutine-firefox) or `npm run test:kicad` (kicad-firefox
|
|
only) — not playwright directly. One spec on one engine:
|
|
`npx playwright test --project=kicad-firefox kicad/pcbnew.spec.ts`.
|
|
|
|
## Waits — never blind
|
|
|
|
- **No `page.waitForTimeout(n)`.** Wait on a *condition*: `expect.poll(() => predicate)`, a
|
|
web-first assertion (`expect(locator).toBeVisible()`), or `waitUntil(page, fn, desc)` (throws
|
|
loudly on timeout).
|
|
- **App readiness:** `waitForWxApp(page)` (canvas visible + element registry populated) for
|
|
widget/editor harnesses; `waitForCanvasApp(page)` for registry-less canvas apps.
|
|
- The **only** allowed `waitForTimeout` is an irreducible interaction dwell — a canvas/keyboard
|
|
commit with no JS-observable signal — and it MUST carry a same-line marker:
|
|
`// eslint-disable-line -- documented interaction dwell: <why>`.
|
|
- **Menu clicks: wait for the specific item, not a count.** Popup items register in the element
|
|
registry progressively as they paint, so a coarse gate ("N menuitems rendered") can pass before
|
|
the item you're about to click exists — and `clickMenuItem` is single-shot. Before every
|
|
`clickMenuItem(page, 'X')`, `await waitForRenderedByLabel(page, 'X', { elementType: 'menuitem' })`
|
|
(same matcher as the click). `clickMenuItemByText` already waits internally and needs no guard.
|
|
A submenu click needs its own wait: the parent menu's still-rendered items satisfy any count gate
|
|
before the submenu paints.
|
|
|
|
## No defensive branches
|
|
|
|
- **No `if (await el.count()) el.click()`.** Assert the element exists, then act:
|
|
`expect(await clickByLabel(page, 'X'), '...').toBe(true)`. Use `clickMenuItemByText` (normalizes
|
|
`&` / `...` / `…`) instead of try-A-else-A…-else-A fallback chains.
|
|
- **No swallowed `.catch(() => {})`.** Let it throw, or assert the tolerated outcome. A genuinely
|
|
best-effort op must carry a marker explaining why.
|
|
|
|
## Screenshots — `stableShot`, compared offline
|
|
|
|
- Capture with **`stableShot(page, 'name.png', { fullPage })`** — it settles the render (in-page
|
|
canvas-hash over animation frames) then writes a raw PNG to
|
|
`test-results/<engine>/` (`chromium`/`firefox`, derived from the running browser — the same
|
|
spec on two engines writes two files). It does **not** assert. Never use Playwright's
|
|
`toHaveScreenshot`. Raw `page.screenshot`/fs writers must route through
|
|
`shotPath(page, 'name.png')` for the same engine scoping.
|
|
- Comparison is offline and per-engine: `npm run screenshots:check` diffs
|
|
`test-results/<engine>/` against the committed baselines in
|
|
`tests/baseline-screenshots/<engine>/` (+ `3d-regression/`, `gal-regression/`).
|
|
`tests/screenshot-manifest.json` (regen: `npm run screenshots:manifest`) is the authoritative
|
|
{name, engine} list — CI fails the lint step if it drifts from the baseline tree.
|
|
- **CI's Linux render is the source of truth**; baselines are promoted from CI
|
|
(`npm run screenshots:promote -- --run <ci-run-id>`). A local (Mac) check shows font/render
|
|
noise and is not the gate.
|
|
- A continuously-animating state (timer, mid-slide) can't be a stable baseline — drop the shot.
|
|
|
|
## Retries
|
|
|
|
- **`retries: 0`** in both configs (`playwright.config.ts` — the merged wasm-suite config —
|
|
and `playwright-web.config.ts`). A failure is real; don't mask it with a retry.
|
|
|
|
## Every spec runs in CI — `lint:ci-coverage`
|
|
|
|
`npm run lint:ci-coverage` (`tools/lint-ci-coverage.ts`, gating in CI next to the
|
|
determinism lint) proves every `*.spec.ts` under `tests/` is actually executed by CI:
|
|
it scrapes the `npm run test:…` invocations from `.github/workflows/`, resolves them
|
|
through `package.json` to their `playwright test --config/--project` flags, and asks
|
|
Playwright itself (`--list`) which files those runs cover. No hand-maintained lists —
|
|
adding a spec in a brand-new directory is exactly what it catches.
|
|
|
|
When it fires:
|
|
- `uncovered-spec` — your new spec matches no CI-run project. Put it in a covered
|
|
`testDir`, adjust a project's `testMatch`, or add the project to a CI npm script.
|
|
- `orphan-project` — you added a config project no CI script selects. Wire it into a
|
|
CI script, or (for deliberately-local system-browser projects) add it to
|
|
`LOCAL_ONLY_PROJECTS` in the lint with a comment saying why.
|
|
|
|
## Where things are
|
|
|
|
- Per-test logs (JS console + cpp): `tests/logs/{wxwidgets,kicad}/<test-name>/`.
|
|
- Guards: `npm run lint:determinism`, `npm run lint:ci-coverage`.
|
|
Screenshot gate: `npm run screenshots:check`.
|