Visual Regression Threshold: Public Worked Example

visual-regression-threshold compares two local screenshot pixel exports and returns a deterministic failure summary and an inline diff image. It does not capture pages, decode PNG files, call a browser, or write images to disk. Node.js 22+; zero dependencies.

This walkthrough uses the tool's public README and checked-in example files. Run the command from a repository checkout with Node.js 22+.

Run the checked-in example

node bin/visual-regression-threshold.mjs --root examples --input passing.json
node bin/visual-regression-threshold.mjs --root examples --input failing.json
npm run check

Read the result

The passing example exits 0: a timestamp-area pixel changed under an explicit mask. The failing example exits 1: a second pixel outside that mask changed. Invalid CLI configuration exits 2 with empty stdout; unreadable or unusable evidence exits 2 with an incomplete JSON report. Stdout otherwise holds exactly one JSON report. Input realpaths must stay inside the real --root.

Scope

Strict UTF-8; at most 1,048,576 bytes, width/height 1–64, 4,096 pixels per raster, 20 masks, JSON depth 4 (root 0), and 5,000 ms injected processing time. Thresholds: pixelThreshold 0–255, maxChangedPixels 0–4,096, maxMeanLumaDelta 0–255. Exact N and N+1 cases are tested for upper bounds. Duplicate JSON keys, including escaped spellings, and unknown fields are refused.