Visual Regression Gates

Screenshot diff that does not cry wolf.

How to start

1. Record the baseline and tie it to the buildThe fingerprint pins the baseline to the build it came from — a loose baseline is what makes the gate lie later.python scripts/visual_gate.py fingerprint baseline/home.png \ --url https://app.example/home --viewport 1280x720 \ --config baseline/home.masks.json
2. Block the new buildMaximum diff, number of regions and the evidence bundle go in the call.python scripts/visual_gate.py compare baseline/home.png actual/home.png \ --meta baseline/home.png.meta.json --masks baseline/home.masks.json \ --max-diff 0.001 --max-regions 1 --bundle artifacts/home
3. Every page at onceSweep all baselines against the current shots — the step that goes into CI.python scripts/visual_gate.py sweep baseline/ actual/ --bundle artifacts/ --json
4. The exit code is the contract0 PASS, 1 FAIL, 2 STALE, 3 ERROR. With --json the output carries the verdict, the diff percentage, how many regions changed and the bounding box of each.

When you will use it

• The screenshot fails when nothing changedAn animation, a caret or a font caught on the wrong frame: masking the unstable region fixes it without loosening the threshold for the whole diff.
• An old baseline approving a broken pageThe fingerprint ties the baseline to the build that produced it — an orphan baseline fails as stale instead of passing as green.
• CI without PIL or ImageMagickThe gate decodes PNG in the stdlib (zlib + struct): a gate that needs a C library on every runner is a gate that breaks on the machine that matters.
• Review what changed in the PRA failure bundle with the diff and the affected regions, ready to attach to the review.
• Sweep the whole appEvery viewport in one CI run, with a verdict per page instead of a single number.

What comes in the package

• scripts/visual_gate.py — the gate, pure stdlib (zlib + struct), zero dependencies
• tests/test_visual_gate.py — 15 tests: both directions of the verdict and the decoder checked against PIL/ImageMagick
• templates/capture.mjs.txt — Playwright capture with screenshots + mask rects — rename it to capture.mjs
• templates/masks.example.json — the mask file format
• references/capture-determinism.md — how to make the capture reproducible before blaming the gate
• references/masks-and-fingerprints.md — masking strategy, fingerprint format and the failure bundle

Requirements

• Python 3.8+, no PIL/OpenCV/ImageMagick
• PNGs from any capturer (Playwright or your own)
• one mask config per dynamic page

Where it does not fit: The gate does not launch a browser: the template capture is a reference, not a dependency. Without the meta and the mask next to the PNG, the four verdicts cannot be honest.

Prices in Brazilian real (BRL). Stripe charges in BRL.

← all skills