0147. Tests mock any effect named in effects.yaml, and compare screens with a tolerance
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-14
- Decided by: wave 5 developer tools agent (domain F), pending Mik
- Planning item: v1 gap audit, developer tools: testing package
Context
Pages call platform effects (camera, share, storage, sign-in) that a test browser cannot perform. Effects are being added in parallel, so a mock mechanism that lists them by hand would always lag. Tests also need to catch visual changes. Pixel-exact comparison fails on font smoothing.
Decision
- Effect mocks.
render(path, { effects: { share: () => "copied", camera: { capture: () => photo } } })replaces any export of@duolith/effects, a function or a method of an object effect.- The test site serves its own
/_duolith/effects/index.js. It re-exports every name inspec/effects/effects.yamlthrough a proxy, so a new effect can be mocked with no change to the testing package. - Every call is recorded as plain data (signals and functions named, not kept).
screen.effectCalls("camera.capture")returns the calls. effectError(code, message)makes a mock fail as the platform would.- An effect that is not mocked runs for real.
- An export marked
mock: true(a stand-in platform such asmockLocation, decision 0102) is re-exported as it is and cannot itself be mocked:renderrefuses it and says to mock the effect it stands in for.
- Visual baselines.
await expect(screen).toMatchSnapshot("name", { tolerance, threshold })compares the screen, in the browser, with__snapshots__/<test file>/<name>.png. By default up to 0.1% of pixels may differ, each by a colour distance of up to 0.1.- A failure writes
<name>.actual.pngand<name>.diff.pngbeside the baseline, and says how many pixels differ. - A missing baseline is written, except in CI, where it fails.
duolith test --update-snapshotsrewrites them.
- **
duolith test --watch** runs the tests again after each change to the project, except in__snapshots__/. With--json, it prints one document per run. - **
duolith test --file <path>** runs one test file. Editors use it.
Alternatives considered
| Option | Why not |
|---|---|
| A mock module written by hand for each effect | It falls behind effects.yaml, and a missing mock would mean a real call or a crash. |
| Pixel-exact comparison | It fails across machines on anti-aliasing, and is too brittle to keep green. |
| Comparing in Node with an image library | It adds a dependency. The browser already decodes PNGs, and OffscreenCanvas compares them. |
Consequences
examples/effects/pages/share.test.tsmocks share and camera, and checks the recorded calls and aneffectError.packages/testing/test/fixtures/snapshotsandduolith-test.test.tscover writing, comparing, a change that fails with a diff,--update-snapshotsand--watch.