mirror of
https://github.com/imjasonh/nescript
synced 2026-07-08 17:06:04 +00:00
2d66b68c7f
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
101 lines
3.3 KiB
HTML
101 lines
3.3 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<title>NEScript jsnes harness</title>
|
|
<style>
|
|
body { margin: 0; background: #222; color: #eee; font-family: monospace; }
|
|
canvas { image-rendering: pixelated; background: #000; display: block; }
|
|
#info { padding: 8px; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<canvas id="screen" width="256" height="240"></canvas>
|
|
<div id="info">waiting…</div>
|
|
<script src="./node_modules/jsnes/dist/jsnes.js"></script>
|
|
<script>
|
|
(function () {
|
|
const { NES } = window.jsnes;
|
|
const canvas = document.getElementById("screen");
|
|
const ctx = canvas.getContext("2d");
|
|
const image = ctx.createImageData(256, 240);
|
|
// Pre-fill alpha channel so we don't have to do it every frame.
|
|
const buf = new ArrayBuffer(image.data.length);
|
|
const buf8 = new Uint8ClampedArray(buf);
|
|
const buf32 = new Uint32Array(buf);
|
|
for (let i = 0; i < buf32.length; i++) buf32[i] = 0xff000000;
|
|
|
|
const nes = new NES({
|
|
onFrame(frameBuffer) {
|
|
for (let i = 0; i < 256 * 240; i++) {
|
|
// jsnes pixel is 0x00BBGGRR in little-endian = 0xFFBBGGRR when alpha set
|
|
buf32[i] = 0xff000000 | frameBuffer[i];
|
|
}
|
|
image.data.set(buf8);
|
|
ctx.putImageData(image, 0, 0);
|
|
},
|
|
// Silence audio; we are only checking video.
|
|
onAudioSample() {},
|
|
sampleRate: 44100,
|
|
});
|
|
|
|
// Expose an API for puppeteer to drive.
|
|
window.nesHarness = {
|
|
loadRomBase64(b64) {
|
|
// atob produces a binary string, which is exactly what jsnes wants.
|
|
const bin = atob(b64);
|
|
nes.loadROM(bin);
|
|
},
|
|
frame() {
|
|
nes.frame();
|
|
},
|
|
runFrames(n) {
|
|
for (let i = 0; i < n; i++) nes.frame();
|
|
},
|
|
buttonDown(player, button) {
|
|
nes.buttonDown(player, button);
|
|
},
|
|
buttonUp(player, button) {
|
|
nes.buttonUp(player, button);
|
|
},
|
|
// Return a hash and non-zero-pixel count for the current canvas contents.
|
|
frameStats() {
|
|
const data = ctx.getImageData(0, 0, 256, 240).data;
|
|
let nonBlack = 0;
|
|
let hash = 2166136261 >>> 0; // FNV-1a
|
|
for (let i = 0; i < data.length; i += 4) {
|
|
const r = data[i], g = data[i + 1], b = data[i + 2];
|
|
if (r !== 0 || g !== 0 || b !== 0) nonBlack++;
|
|
hash ^= r; hash = Math.imul(hash, 16777619);
|
|
hash ^= g; hash = Math.imul(hash, 16777619);
|
|
hash ^= b; hash = Math.imul(hash, 16777619);
|
|
}
|
|
return { nonBlack, hash: (hash >>> 0).toString(16), totalPixels: 256 * 240 };
|
|
},
|
|
// Raw canvas pixels as a base64-encoded RGBA buffer
|
|
// (256 * 240 * 4 bytes). Used by the golden-diff runner to
|
|
// compare pixel-for-pixel against a decoded PNG golden file.
|
|
// Base64 is cheap and avoids any puppeteer JSON-serialization
|
|
// pitfalls with typed arrays.
|
|
rawPixelsBase64() {
|
|
const data = ctx.getImageData(0, 0, 256, 240).data;
|
|
const chunks = [];
|
|
// Chunk to stay under String.fromCharCode's argument limit.
|
|
for (let i = 0; i < data.length; i += 4096) {
|
|
chunks.push(String.fromCharCode.apply(null, data.subarray(i, i + 4096)));
|
|
}
|
|
return btoa(chunks.join(""));
|
|
},
|
|
};
|
|
|
|
// Controller button enum constants (from jsnes Controller).
|
|
window.nesButtons = {
|
|
A: 0, B: 1, SELECT: 2, START: 3,
|
|
UP: 4, DOWN: 5, LEFT: 6, RIGHT: 7,
|
|
};
|
|
|
|
document.getElementById("info").textContent = "ready";
|
|
})();
|
|
</script>
|
|
</body>
|
|
</html>
|