visual-review

name	visual-review
description	Screenshot comparison and visual regression detection: pixel diffing, before/after overlays, threshold-based change detection.
category	frontend
maturity	stable
tags	["visual-regression","screenshot-diff","pixel-diffing","overlay","ui-testing"]

visual-review

Screenshot comparison and visual regression detection: pixel diffing, before/after overlays, threshold-based change detection.

When to Use

• Comparing UI states before and after changes
• Detecting visual regressions in CI or manual review
• Creating before/after diff images for stakeholder review
• Validating that CSS/layout changes didn't break other components
• Generating visual regression reports across multiple pages

Scripts

screenshot-diff.py

Compares two PNG screenshots pixel-by-pixel and generates a diff image.

python3 scripts/screenshot-diff.py \
  --before before.png \
  --after after.png \
  --output diff.png \
  --threshold 0.5

Arguments:

• --before — Path to the baseline screenshot (required)
• --after — Path to the new screenshot (required)
• --output — Path for the diff image output (default: diff.png)
• --threshold — Maximum allowed change percentage, 0-100 (default: 0.5)

Output:

• Diff image with changed pixels highlighted in red on a dimmed background
• Prints change percentage to stdout
• Exit code 0 if change% ≤ threshold, exit code 1 if above

Notes:

• Images must be the same dimensions (script will error if not)
• Uses per-pixel RGB distance comparison (threshold per-pixel: 30/255)

visual-report.py

Generates a Markdown report from a directory of before/after screenshot pairs.

python3 scripts/visual-report.py \
  --dir ./screenshots \
  --output report.md \
  --threshold 0.5

Arguments:

• --dir — Directory containing before/after pairs (required)
• --output — Output report path (default: stdout)
• --threshold — Pass/fail threshold percentage (default: 0.5)

Naming convention: Files must be named <name>-before.png and <name>-after.png.

Report includes:

• Each pair with change percentage and pass/fail status
• Sorted by most changed first
• Summary: total pairs, pass count, fail count

overlay-gen.py

Creates visual comparison images in different modes.

python3 scripts/overlay-gen.py \
  --before before.png \
  --after after.png \
  --mode side-by-side \
  --output comparison.png

Arguments:

• --before — Baseline image (required)
• --after — New image (required)
• --mode — Comparison mode: side-by-side, overlay, swipe (default: side-by-side)
• --output — Output path (default: comparison.png)

Modes:

• side-by-side — Before and after placed next to each other with labels
• overlay — Semi-transparent blend (50/50) of both images
• swipe — Left half shows before, right half shows after, with a divider line

References

• references/visual-testing-guide.md — Threshold tuning, dynamic content handling, stabilization tips

Dependencies

• Python 3 with Pillow (pip3 install Pillow)