1
0
Fork 0
mirror of https://github.com/imjasonh/nescript synced 2026-07-11 10:10:49 +00:00

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
This commit is contained in:
Claude 2026-04-12 21:30:18 +00:00
parent d9bf0b06cb
commit 2d66b68c7f
No known key found for this signature in database
42 changed files with 301 additions and 135 deletions

View file

@ -1,15 +1,15 @@
{
"name": "emulator",
"name": "nescript-emulator-tests",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "emulator",
"name": "nescript-emulator-tests",
"version": "1.0.0",
"license": "ISC",
"dependencies": {
"jsnes": "^2.1.0",
"pngjs": "^7.0.0",
"puppeteer": "^24.40.0"
}
},
@ -774,6 +774,15 @@
"integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
"license": "ISC"
},
"node_modules/pngjs": {
"version": "7.0.0",
"resolved": "https://registry.npmjs.org/pngjs/-/pngjs-7.0.0.tgz",
"integrity": "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==",
"license": "MIT",
"engines": {
"node": ">=14.19.0"
}
},
"node_modules/progress": {
"version": "2.0.3",
"resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz",