Visual Regression¶

The visual regression tool captures screenshots across viewports and compares them to detect visual changes between audit runs.

Usage¶

python scripts/visual_regression.py --url https://example.com --output-dir .fat-screenshots

Options¶

Flag	Default	Description
`--url`	Required	URL to screenshot
`--output-dir`	`.fat-screenshots`	Directory for screenshots
`--viewports`	`375x812,768x1024,1440x900`	Comma-separated viewport sizes
`--full-page`	`true`	Capture full page height
`--compare`	`false`	Compare against previous screenshots
`--threshold`	`0.1`	Pixel difference threshold (0--1)

Prerequisites¶

Visual regression requires Playwright:

pip install playwright
playwright install chromium

How It Works¶

Capture -- takes screenshots at each viewport size
Save -- stores screenshots with timestamped filenames
Compare (when --compare is set) -- pixel-diff against previous screenshots
Report -- outputs a diff summary with percentage changed

Output¶

.fat-screenshots/
  2026-04-14T10-30-00/
    mobile_375x812.png
    tablet_768x1024.png
    desktop_1440x900.png
  diff/
    mobile_375x812_diff.png    # Highlighted differences
    tablet_768x1024_diff.png
    desktop_1440x900_diff.png
  report.json                  # Diff percentages and status

Fallback Behaviour¶

When Playwright is not installed:

The script logs a warning
Returns a result with playwright_available: false
The main audit continues without visual regression data
No screenshots are captured

Use Cases¶

Pre/post deployment -- verify visual changes are intentional
Responsive design -- check layout across device sizes
CSS refactoring -- ensure visual parity after style changes
A/B testing -- document visual variants