visual-diff

Visual Regression Testing

Automated screenshot comparison using Playwright. Catch visual bugs before they ship.

Process

Phase 1: Determine Test Scope

Ask the user:

1. What URL(s) to test? (localhost, staging, or production)
2. What changed? (CSS update, component refactor, dependency upgrade, etc.)

If the user already described what changed, skip asking.

Phase 2: Take "Before" Screenshots

If comparing against the current state (before making changes):

Use the Playwright MCP to capture screenshots:

1. Navigate to the URL:

   • Use browser_navigate to go to the target URL

2. Take full-page screenshot:

   • Use browser_take_screenshot to capture the current state

3. Capture key viewports:

   • Desktop (1920x1080): browser_resize then browser_take_screenshot
   • Tablet (768x1024): browser_resize then browser_take_screenshot
   • Mobile (375x812): browser_resize then browser_take_screenshot

4. Save screenshots with descriptive names noting they are "before" state.

Phase 3: Make Changes

Let the user make their changes, or make them yourself if that's the task.

Phase 4: Take "After" Screenshots

Repeat the same screenshot process for the same URLs and viewports.

Phase 5: Visual Comparison

Compare before and after screenshots:

1. Layout shifts — did any elements move unexpectedly?
2. Color changes — did colors, gradients, or shadows change?
3. Typography — did font sizes, weights, or spacing change?
4. Responsive issues — does it look correct on all viewports?
5. Missing elements — did anything disappear?
6. Overflow issues — is content clipping or overflowing?

Use browser_snapshot to get the accessibility tree and compare DOM structure between before/after.

Phase 6: Report

Present findings in a clear format:

No Visual Regressions Found:

• "All pages look identical across desktop, tablet, and mobile viewports."

Regressions Detected: For each regression:

• Page: URL where the issue appears
• Viewport: Which screen size is affected
• What changed: Description of the visual difference
• Severity: Critical (broken layout), High (noticeable shift), Medium (minor difference), Low (pixel-level)
• Suggested fix: How to resolve the regression

Phase 7: Targeted Testing

For specific component changes, also test:

• Hover states (use browser_hover)
• Click interactions (use browser_click)
• Form states (use browser_fill_form)
• Dark mode (if applicable)
• Loading states
• Error states
• Empty states

Key Pages to Always Test

When the user doesn't specify pages, test these by default:

1. Homepage / Landing page (/)
2. Login/signup page (if exists)
3. Main app page (dashboard, etc.)
4. Any page the user recently modified

Key Principle

Trust screenshots, not assumptions. CSS changes cascade unpredictably. A "small tweak" in one component can break layouts across the entire app. Always verify visually.