Duolith docs

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 in spec/effects/effects.yaml through 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 as mockLocation, decision 0102) is re-exported as it is and cannot itself be mocked: render refuses 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.png and <name>.diff.png beside the baseline, and says how many pixels differ.
    • A missing baseline is written, except in CI, where it fails. duolith test --update-snapshots rewrites 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

OptionWhy not
A mock module written by hand for each effectIt falls behind effects.yaml, and a missing mock would mean a real call or a crash.
Pixel-exact comparisonIt fails across machines on anti-aliasing, and is too brittle to keep green.
Comparing in Node with an image libraryIt adds a dependency. The browser already decodes PNGs, and OffscreenCanvas compares them.

Consequences

  • examples/effects/pages/share.test.ts mocks share and camera, and checks the recorded calls and an effectError.
  • packages/testing/test/fixtures/snapshots and duolith-test.test.ts cover writing, comparing, a change that fails with a diff, --update-snapshots and --watch.