Repository navigation
feat(snapshots): add snapshots diff - #1179
Conversation
Ports `sentry snapshots diff` — compares two local directories of snapshot images. Uses pure-JS pixelmatch (the same YIQ, anti-aliasing-aware algorithm as the legacy CLI's native odiff) + pngjs/jpeg-js for decoding — no native/WASM deps, bundles cleanly into the SEA binary. Collects images recursively (png/jpg/jpeg), categorizes matched/added/removed (or skipped with --selective), byte-identical pairs short-circuit, then diffs matched pairs: dimension mismatch → layout_changed, differing pixels → changed with a PNG diff mask written to --output. Emits a JSON report + summary; --fail-on-diff exits non-zero on any change. --threshold (0-1) and --no-antialiasing tune the comparison. - src/lib/snapshots/diff.ts: compareImages, collectImageFiles (shared walkFiles), categorizeImages. - src/commands/snapshots/diff.ts + route registration. - devDeps: pixelmatch, pngjs, jpeg-js, @types/pngjs (all bundled). - Tests: compare (match/changed/layout), categorize (+selective), collect; command (mask write, fail-on-diff exit, missing-dir rejection).
|
Codecov Results 📊✅ Patch coverage is 91.51%. Project has 5198 uncovered lines. Files with missing lines (2)
Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
+ Coverage 81.62% 81.65% +0.03%
==========================================
Files 408 410 +2
Lines 28227 28334 +107
Branches 18384 18437 +53
==========================================
+ Hits 23040 23136 +96
- Misses 5187 5198 +11
- Partials 1886 1893 +7Generated by Codecov Action |
- H1 (parity): emit diffPercentage as a percentage (0–100), matching legacy
odiff output — was a fraction (0–1), 100× off for JSON/threshold consumers.
Drop the compensating *100 in the human formatter; update the test.
- L1: colorTag("red", ...) for error detail ("error" is not a valid tag).
- Tests: add JPEG decode, undecodable-image (lib throw + command error entry),
added/removed reporting, --selective (skipped vs removed via exit code), and
--no-antialiasing coverage.
Self-review (subagent-assisted) + fixesH1 (parity, fixed): the legacy odiff/Rust output emits Also fixed: L1 — Test gaps closed (M1): JPEG decode path, undecodable-image (lib throw + command The subagent confirmed the rest is a faithful port: pixelmatch option mapping (threshold + |
- Only claim 'diff masks written' when pixel-changed images produced masks (layout_changed/added/removed write none); reword the no-change hint. - diffMaskRelPath: non-PNG sources append .png (a.jpg → a.jpg.png) so a .png and .jpg with the same stem don't overwrite the same mask.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 66e0555. Configure here.
| const diffCount = pixelmatch(base.data, head.data, output, width, height, { | ||
| threshold: opts.threshold, | ||
| includeAA: !opts.antialiasing, | ||
| diffMask: true, |
There was a problem hiding this comment.
Antialiasing flag inverted
High Severity
compareImages passes includeAA: !opts.antialiasing to pixelmatch, but includeAA: true means detect and ignore anti-aliased pixels. With default options, AA edges are counted as diffs; --no-antialiasing turns ignoring on instead of off, opposite of the CLI and legacy odiff behavior.
Reviewed by Cursor Bugbot for commit 66e0555. Configure here.


Fifth PR of the build/Emerge workstream. Completes the local
snapshotstooling (aftersnapshots download#1176).snapshots diff <base-dir> <head-dir>Compares two local directories of snapshot images and writes a PNG diff mask per changed image + a JSON report. No network requests.
pixelmatchimplements the same YIQ-color-space, anti-aliasing-aware algorithm as the legacy CLI's nativeodiff;pngjs/jpeg-jsdecode PNG/JPEG. All pure-JS devDeps — bundle into the SEA binary, no per-platform binaries, no postinstall, no runtime deps.walkFiles), categorize matched/added/removed (orskippedwith--selective), byte-identical fast-path, then diff matched pairs — dimension mismatch →layout_changed, differing pixels →changed(mask written).--threshold(0–1 per-pixel sensitivity),--no-antialiasing,--fail-on-diff(non-zero exit on any change),--output(default./diff-output/).Why pure-JS over WASM/native (per your call)
odiff has no WASM build (native Zig+SIMD, per-platform prebuilts + postinstall — incompatible with the bundled single-binary model), and its algorithm is equivalent to pixelmatch's. For a local baseline diff on screenshots, JS perf is more than adequate (and the byte-identical fast-path skips unchanged images). The diff core sits behind a module boundary, so a WASM engine can be swapped in later if perf ever matters.
Files
src/lib/snapshots/diff.ts—compareImages,collectImageFiles,categorizeImages.src/commands/snapshots/diff.ts+ route registration.pixelmatch,pngjs,jpeg-js,@types/pngjs(all bundled;check:depsgreen).--fail-on-diffexit codes, missing-dir rejection).Follow-ups
Streaming extraction for very large snapshot archives (from #1176);
snapshots upload(objectstore session); iOSbuild upload.typecheck,lint,check:deps,check:fragmentsall pass.