ADR 0018: Headless tests run a lite profile and count frames; visuals are judged on a real GPU through snapshots
- Status: accepted
- Date: 2026-09, rewritten 2026-10
Context
Headless Chromium shades every pixel on the CPU (WebGPU over SwiftShader's Vulkan): seconds per frame at the full profile, and shadows and antialiasing nothing like a GPU. A green run once proved little — it skipped without a GPU and checked no layer. A reviewer needs to see a visual change at a place and time, reproducibly.
Decision
- Specs are budgeted in frames, not seconds (
__poc.frames,waitForFrames), and share one booted page per group. - The viewer specs run
?scene=lite: the spawn tile only, a small shadow map, a low pixel ratio, fewer AO samples — the knobs that cost seconds per frame — with the same loaders, layers and materials as the full profile. Lite is never used to look at pixels. - On CI a missing WebGPU adapter fails, never skips. Layers are checked by a scene census, not by pixels.
- Anything visual is judged on a real GPU with the snapshot harness
(
bun run shots, headed, full profile). - The Snapshot is a validated contract (
lib/city/snapshot.ts): the camera pose, the sun's time and the look's few controls (Nebel, the style, the data layers — one table,lib/city/look-controls.ts). Parsing never throws, rejects non-finite numbers and clamps ranges. A snapshot key is never renamed; a removed control's key is retired for good (RETIRED_SNAPSHOT_KEYS), ignored on read and never reused. - The look's fixed strengths are named constants in their owners, not controls. Tuning one is a code change judged by snapshots of place and time against production.
- A PR that changes what the viewer shows carries snapshots in its
description (the
pr-snapshotsskill).
Consequences
- A new spec drives
/dresden?scene=lite; untagged it lands in the whole-site CI shard. - A new control is a table row plus its owner's entry; a row without an owner is a type error.
bun run verify(lint, typecheck, unit tests) is the pre-push gate.
Alternatives
- The full profile headless: minutes per spec.
- Skipping when WebGPU is missing: hides a broken browser bump.
- Pixel diffs in CI: SwiftShader output is not the product.
- A slider for every look term: each cost a table row, a store value, a snapshot key and a guide line in two languages, and the maintainer did not need the look tunable.
