Skip to content
This repository was archived by the owner on Oct 23, 2026. It is now read-only.

feat(snapshots): add snapshots diff - #1179

Merged
BYK merged 3 commits into
mainfrom
byk/feat/snapshots-diff
Jul 2, 2026
Merged

BYK merged 3 commits into
mainfrom
byk/feat/snapshots-diff

Conversation

@BYK

@BYK BYK commented Jul 2, 2026

Copy link
Copy Markdown
Member

Fifth PR of the build/Emerge workstream. Completes the local snapshots tooling (after snapshots 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.

  • Pure-JS engine: pixelmatch implements the same YIQ-color-space, anti-aliasing-aware algorithm as the legacy CLI's native odiff; pngjs/jpeg-js decode PNG/JPEG. All pure-JS devDeps — bundle into the SEA binary, no per-platform binaries, no postinstall, no runtime deps.
  • Behavior (matches legacy): recursively collect images (png/jpg/jpeg via the shared walkFiles), categorize matched/added/removed (or skipped with --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.
  • devDeps: pixelmatch, pngjs, jpeg-js, @types/pngjs (all bundled; check:deps green).
  • Tests (13): compare (match/changed/layout), categorize (+selective), recursive collect; command (mask write, --fail-on-diff exit codes, missing-dir rejection).

Follow-ups

Streaming extraction for very large snapshot archives (from #1176); snapshots upload (objectstore session); iOS build upload.

typecheck, lint, check:deps, check:fragments all pass.

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).
@github-actions

github-actions Bot commented Jul 2, 2026 •

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.1

QR code for preview link

🚀 View preview at
https://cli.sentry.dev/_preview/pr-1179/

Built to branch gh-pages at 2026-07-02 20:06 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

Comment thread src/commands/snapshots/diff.ts Resolved
@github-actions

github-actions Bot commented Jul 2, 2026 •

Copy link
Copy Markdown
Contributor

Codecov Results 📊

✅ Patch coverage is 91.51%. Project has 5198 uncovered lines.
✅ Project coverage is 81.65%. Comparing base (base) to head (head).

Files with missing lines (2)
File Patch % Lines
src/commands/snapshots/diff.ts 89.04% ⚠️ 8 Missing and 5 partials
src/lib/snapshots/diff.ts 96.97% ⚠️ 1 Missing and 1 partials
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        +7

Generated by Codecov Action

Comment thread src/commands/snapshots/diff.ts Resolved
- 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.
@BYK

BYK commented Jul 2, 2026

Copy link
Copy Markdown
Member Author

Self-review (subagent-assisted) + fixes

H1 (parity, fixed): the legacy odiff/Rust output emits diff_percentage as a percentage (0–100) — confirmed by odiff's own type and the Rust deserialization test (42 px = 1.5% ⇒ 2800 px total, which is impossible as a fraction). My JSON was emitting a fraction (0–1), i.e. 100× off for any consumer gating on diffPercentage. Now emits 0–100 (and the human formatter no longer compensates with *100; test updated).

Also fixed: L1 — colorTag("red", …) for error detail ("error" isn't a valid color tag).

Test gaps closed (M1): JPEG decode path, undecodable-image (lib throw + command error entry, run still completes), added/removed reporting, --selective (skipped-vs-removed proven via exit code), and --no-antialiasing.

The subagent confirmed the rest is a faithful port: pixelmatch option mapping (threshold + includeAA: !antialiasing not inverted), decoder RGBA guarantees, walkFiles config skipping/truncating nothing (matches Rust WalkDir), byte-identical fast-path, categorization, exit-code logic, and clean bundling (all devDeps, no native/dynamic-require).

Comment thread src/commands/snapshots/diff.ts Resolved
- 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.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ 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.

Comment thread src/lib/snapshots/diff.ts
const diffCount = pixelmatch(base.data, head.data, output, width, height, {
threshold: opts.threshold,
includeAA: !opts.antialiasing,
diffMask: true,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 66e0555. Configure here.

@BYK
BYK merged commit 09db726 into main Jul 2, 2026
42 of 44 checks passed
@BYK
BYK deleted the byk/feat/snapshots-diff branch July 2, 2026 20:28
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant