Claude 2d66b68c7f tests/emulator: byte-exact golden-image diffs ... The smoke test used to check a per-example `nonBlack` floor — "at least one sprite rendered," plus a per-example minimum for the multi-sprite examples. That catches gross regressions (a compiler bug that makes everything go black) but silently lets through anything that changes a handful of pixels without dropping below the sprite floor. The whole point of this harness is to catch compiler miscompiles before they land; a softer check means bugs can still sneak in. This swap makes every run diff the raw canvas framebuffer against a committed PNG golden. One mismatched byte at pixel (120, 119) is enough to fail CI — there's nowhere for a regression to hide. Workflow: # normal — fails on any pixel change node tests/emulator/run_examples.mjs # when the diff is intentional, rewrite the goldens UPDATE_GOLDENS=1 node tests/emulator/run_examples.mjs # or: node tests/emulator/run_examples.mjs --update-goldens git diff tests/emulator/goldens/ # review the change git add tests/emulator/goldens/ git commit # explain WHY in the message When a run fails without `UPDATE_GOLDENS`, the runner writes: tests/emulator/actual/<name>.png the run's raw output tests/emulator/actual/<name>.diff.png red-highlighted pixel diff so reviewers can eyeball what changed without rerunning locally. `actual/` is gitignored and re-created on every run. The CI job now uploads `actual/`, `goldens/`, and `report.json` together as a single `emulator-diff` artifact on failure — side by side means the "what changed" story is obvious without cloning. Implementation: - `tests/emulator/screenshots/` is renamed to `tests/emulator/goldens/`. All 18 existing PNGs are preserved as the initial goldens (git detected them as pure renames). - `harness.html` gets a new `window.nesHarness.rawPixelsBase64()` that returns the 245760-byte (256 × 240 × 4 bytes) RGBA canvas buffer as base64. The runner compares raw pixels, not PNG bytes, so encoder quirks (zlib level, filter heuristics) can't cause false positives across Chrome versions or platforms. - The runner uses `pngjs` (pure-JS, no native deps) to decode goldens and to write diff PNGs. `PNG.sync.write` is byte-deterministic for identical pixels, so `git diff` on a committed golden only ever shows up when the actual rendered pixels changed — not because two machines produced slightly different compression. - The committed goldens were re-encoded with pngjs in this commit so the baseline is consistent from day one. File sizes are a touch larger than Chrome's output (~1KB vs ~800B on average), but that's negligible and it eliminates one entire class of flaky-looking diffs in the future. Determinism verification: I ran each of the 18 ROMs twice through fresh `NES` instances in fresh puppeteer pages, hashed the 245760-byte framebuffers at frame 180 with SHA-256, and confirmed `run1 == run2` for every single one. Exact-pixel diffs are safe for this ROM set. Negative path verification: I corrupted one golden (flipped one pixel to pure red via pngjs) and reran the runner. It printed DIFF hello_sprite 1/61440 pixels differ; first at (120,120) expected [255,0,0] got [0,0,0] actual: tests/emulator/actual/hello_sprite.png diff: tests/emulator/actual/hello_sprite.diff.png and exited 1 as expected. The diff PNG shows a dim-grayscale silhouette of the expected frame with a bright-red dot on the one mismatched pixel — enough visual context to locate the regression at a glance. All 18 examples match their goldens in strict mode. `cargo fmt --check`, `cargo clippy --release --all-targets -- -D warnings`, and `cargo test --release` (313 unit + 37 integration) are all still green. https://claude.ai/code/session_014Z5y3Q9krLcAxYpZQJhZ5V		2026-04-12 21:30:18 +00:00
..
workflows	tests/emulator: byte-exact golden-image diffs	2026-04-12 21:30:18 +00:00