Visual Regression Pipeline

tools/visual-regression/ houses the Playwright configuration with a projects matrix of 9 (Chromium + Firefox + WebKit × mobile + tablet + desktop). Per-app specs — www.spec.ts, web.spec.ts, admin.spec.ts, app.spec.ts and sys.spec.ts — cover roughly 25 key views; routes shipping in future tasks are marked test.skip behind an env flag so the catalogue can grow without breaking baselines.

Determinism is the hard part of screenshot diffing. tools/visual-regression/seed.py drops and recreates the MongoDB database with pinned ObjectIds, slugs and timestamps before every run; the RNG is seeded to 42 and the now() value is frozen at 2026-01-15T12:00:00Z. A docker-compose.yml at the monorepo root brings up MongoDB, Redis and the petanque-api with healthchecks (the same stack the integration suite reuses). In the browser, freezeRuntime(page) injects an init-script ahead of any application code that pins time, RNG and animations — without it, CSS transitions, lazy avatars and clock-driven UI generate diffs on every run.

The pipeline is a GitHub Actions workflow at .github/workflows/visual-regression.yml triggered on every PR. It caches Playwright browsers and node_modules and parallelises across projects. The break threshold is maxDiffPixelRatio: 0.001 globally, with documented per-test overrides for canvas-heavy views where antialiasing flicker is unavoidable. On failure the workflow uploads an HTML report as the visual-regression-report artefact (14-day retention) and posts a PR comment linking to it.

Baselines update through a deliberate gesture: putting [accept visual baseline] in a commit message tells the workflow to run with --update-snapshots and push the new baselines back to the PR branch, so the bump is reviewable in its own commit. Maintenance routines live in docs/product/design-system/visual-regression.md and tools/visual-regression/README.md. A native mobile screenshot suite using iOS and Android simulators is on the backlog if the web target proves insufficient.