<default_to_action>
When detecting visual regressions or validating UI:
CAPTURE baseline screenshots (first run establishes baseline)
COMPARE new screenshots against baseline (pixel-by-pixel or AI)
MASK dynamic content (timestamps, ads, user counts)
TEST across devices (desktop, tablet, mobile viewports)
REVIEW and approve intentional changes, fail on regressions
Quick Visual Testing Steps:
Set up baseline on main branch
Compare feature branch against baseline
Mask dynamic elements (timestamps, avatars)
Use AI-powered comparison to reduce false positives
Integrate in CI/CD to block visual regressions
Critical Success Factors:
Functional tests don't catch visual bugs
AI-powered tools reduce false positives
Review diffs, don't just auto-approve
</default_to_action>
Quick Reference Card
When to Use
UI component changes
CSS/styling modifications
Responsive design validation
Cross-browser consistency checks
Visual Bug Types
Bug Type
Description
Layout shift
Elements moved position
Color change
Unintended color modification
Font rendering
Typography issues
Alignment
Spacing/alignment problems
Missing images
Broken image paths
Overflow
Content clipping
Comparison Algorithms
Algorithm
Best For
Pixel diff
Exact match requirement
Structural similarity
Handle anti-aliasing
AI semantic
Ignore insignificant changes
PRIMARY PATH: qe-browser visual-diff
Most visual regression work should go through the qe-browser fleet skill. It wraps Vibium (WebDriver BiDi) and provides pixel-diff against stored baselines with threshold enforcement and diff-image output. See .
.claude/skills/qe-browser/SKILL.md
# Navigate
vibium go https://example.com
vibium wait load
# First run — creates baseline in .aqe/visual-baselines/homepage.png
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage
# Subsequent runs — compare, non-zero exit on mismatch
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage --threshold 0.02
# Scope to a single region
node .claude/skills/qe-browser/scripts/visual-diff.js --name hero --selector "#hero"# Responsive — run diff at each breakpointfor viewport in"375 667""768 1024""1920 1080"; doread w h <<< "$viewport"
vibium viewport $w$h
node .claude/skills/qe-browser/scripts/visual-diff.js --name "homepage-${w}x${h}"done# Reset baseline after an intentional design change
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage --update-baseline
Baselines live in .aqe/visual-baselines/. The script uses pixelmatch when installed, with a hash-based exact-match fallback otherwise. Non-zero exit when similarity < 1 - threshold, so CI gating is $?-based.
When to keep Playwright visual regression
Use the Playwright recipe below only when you need:
AI semantic comparison (Percy, Applitools) to ignore insignificant pixel drift
Cross-browser rendering checks in Firefox/WebKit (Vibium is Chrome-only today)
Tight integration with an existing Playwright test suite
LEGACY: Visual Regression with Playwright (fallback)
Functional tests don't catch visual bugs. Layout shifts, color changes, font rendering, alignment issues - all invisible to functional tests but visible to users.
AI-powered tools reduce false positives. Percy, Applitools use AI to ignore insignificant differences (anti-aliasing, minor font rendering).
With Agents:qe-visual-tester automates visual regression across browsers and devices, uses AI to filter noise, and generates visual diff reports. Catches UI regressions before users see them.
