Perfector — Visual Regression Testing

Project Context

Classic web‑dev problem: with dozens or hundreds of pages sharing components and styles, a small CSS tweak can break layouts elsewhere.

Typical scenarios:

• Changed spacing in Button → login form shifted on another page
• Updated grid layout → catalog cards misaligned
• Added a new breakpoint → mobile version broke
• Refactored CSS variables → colors changed in unexpected places

Why manual testing fails:

• ❌ You can’t check every page after each change
• ❌ Human error — subtle changes slip through
• ❌ Time — checking hundreds of pages takes hours
• ❌ No history — hard to see when something broke

Goal

Build an automated visual regression testing system that:

• Takes baseline (reference) screenshots of critical pages
• Captures new screenshots on each deploy
• Compares via computer vision (OpenCV)
• Flags visual differences
• Sends a report with changes to the tech lead for review
• Integrates into CI/CD

Solution

Architecture

CI/CD Trigger (push / PR / schedule)
  → Screenshot Engine (Selenium + Headless Chrome in Docker)
  → Visual Comparison (OpenCV + Pillow)
  → Report Generator (HTML/email)
  → CI status + Slack/email notifications

1. Screenshot engine opens URLs from config, waits for full load, and saves full‑page images.
2. Comparator aligns images and computes diffs, aggregates changed regions, outputs annotated images and scores.
3. Reporter produces human‑readable reports and pushes artifacts to CI.

Code excerpts (trimmed for brevity) are kept close to the original implementation; logic is self‑documenting.

CI/CD Integration

• Runs on push/PR and on schedule
• Stores baseline artifacts
• Fails build on significant regressions (configurable threshold)
• Links to visual diff artifacts in the job summary

Results

Lessons

• Guardrails beat guidelines: automation prevents “I forgot to check page X.”
• Reproducibility matters: Dockerized headless browser = stable screenshots.
• Keep thresholds sane: reduce false positives so teams trust the signal.