Debug Visual Regression

Debug Visual Regression

Automatically analyze visual regression failures when the user mentions them. This Skill helps identify the root cause of visual differences and suggests whether to accept or fix changes.

When to Use This Skill

Activate this Skill when the user:

• Mentions "failing visual test" or "screenshot failure"
• Asks "what's wrong with my visual tests?"
• Says "the homepage screenshot is different" or similar
• Wants to understand why a visual comparison failed
• Asks to "debug", "analyze", or "investigate" visual changes
• Mentions specific screenshot names that are failing

How This Skill Works

1. Automatically detect the mode (local TDD or cloud)
2. Fetch comparison details using the screenshot name or comparison ID
3. View the actual images to perform visual analysis
4. Provide detailed insights on what changed and why
5. Suggest next steps (accept, reject, or fix)

Instructions

Step 1: Call the Unified MCP Tool

Use read_comparison_details with the identifier:

• Pass screenshot name (e.g., "homepage_desktop") for local mode
• Pass comparison ID (e.g., "cmp_abc123") for cloud mode
• The tool automatically detects which mode to use
• Returns a response with mode field indicating local or cloud

Step 2: Check the Mode in Response

The response will contain a mode field:

• Local mode (mode: "local"): Returns filesystem paths (baselinePath, currentPath, diffPath)
• Cloud mode (mode: "cloud"): Returns URLs (baselineUrl, currentUrl, diffUrl)

Step 3: Analyze Comparison Data

Examine the comparison details:

• Diff percentage and threshold
• Status (failed/new/passed)
• Image references (paths or URLs depending on mode)
• Viewport and browser information

Step 4: View the Actual Images

CRITICAL: You MUST view the baseline and current images to provide accurate analysis.

If mode is "local":

• Response contains filesystem paths (baselinePath, currentPath, diffPath)
• Use the Read tool to view ONLY baselinePath and currentPath
• DO NOT read diffPath - it causes API errors

If mode is "cloud":

• Response contains public URLs (baselineUrl, currentUrl, diffUrl)
• Use the WebFetch tool to view ONLY baselineUrl and currentUrl
• DO NOT fetch diffUrl - it causes API errors

Step 5: Provide Detailed Visual Insights

Based on what you observe in the images:

Describe the specific visual differences:

• Which UI components, elements, or layouts changed
• Colors, spacing, typography, positioning changes
• Missing or added elements

Categorize the change by diff percentage:

• < 1%: Anti-aliasing, font rendering, subpixel differences
• 1-5%: Layout shifts, padding/margin changes, color variations
• > 5%: Significant layout changes, missing content, major visual updates

Identify possible causes:

• CSS changes (margin, padding, positioning)
• Content changes (text, images)
• State issues (hover, focus, loading states)
• Browser/viewport rendering differences

Step 6: Suggest Next Steps

If local mode:

• Whether to accept using accept_baseline tool
• Specific code areas to investigate if unintentional
• How to fix common issues

If cloud mode:

• Whether to approve using approve_comparison tool
• Whether to reject using reject_comparison tool with reason
• Team coordination steps

If changes are intentional:

• Explain why it's safe to accept/approve
• Confirm this matches expected behavior

If changes are unintentional:

• Specific files to check (CSS, templates, components)
• Git commands to investigate recent changes
• How to reproduce and fix

Example Analysis (Local TDD Mode)

User: "The homepage screenshot is failing"

Step 1: Call tool
Tool: read_comparison_details({ identifier: "homepage" })

Response:
{
  "name": "homepage",
  "status": "failed",
  "diffPercentage": 2.3,
  "threshold": 2.0,
  "mode": "local",
  "baselinePath": "/Users/you/project/.vizzly/baselines/homepage.png",
  "currentPath": "/Users/you/project/.vizzly/screenshots/homepage.png"
}

Step 2: View images
Read(baselinePath)
Read(currentPath)

Step 3: Visual Analysis
Comparing the two images, I can see the following changes:

Visual Differences:
- The navigation header has shifted down by approximately 10-15 pixels
- Logo position moved from y:20px to y:35px
- Navigation menu items are now overlapping with the hero section
- The "Sign Up" button background changed from blue (#2563eb) to darker blue (#1e40af)

Root Cause Analysis:
Based on the 2.3% diff and visual comparison, this appears to be:
1. A margin or padding change on the header element
2. The button color change suggests a hover state being captured

Recommendations:
If intentional:
- This appears to be a deliberate redesign of the header spacing
- Accept as new baseline if these changes match your design updates

If unintentional:
- Check recent CSS changes to `.header` or `nav` margin-top/padding-top
- Verify button states during screenshot capture to avoid hover state
- Investigate with: `git diff src/styles/header.css`
- Fix the header positioning and re-run tests

Example Analysis (Cloud Mode)

User: "Can you check comparison cmp_xyz789?"

Step 1: Call tool
Tool: read_comparison_details({
  identifier: "cmp_xyz789",
  apiToken: "vzt_..."
})

Response:
{
  "name": "login-page",
  "status": "failed",
  "diffPercentage": 0.8,
  "threshold": 2.0,
  "mode": "cloud",
  "baselineUrl": "https://app.vizzly.dev/screenshots/abc123/baseline.png",
  "currentUrl": "https://app.vizzly.dev/screenshots/abc123/current.png",
  "comparisonId": "cmp_xyz789"
}

Step 2: View images
WebFetch(baselineUrl, "show me the baseline screenshot")
WebFetch(currentUrl, "show me the current screenshot")

Step 3: Visual Analysis
The differences are very subtle (0.8% diff):

Visual Differences:
- Input field border color slightly different (#e5e7eb vs #d1d5db)
- Submit button has very slight shadow change
- Font anti-aliasing appears slightly different

Root Cause Analysis:
This appears to be browser rendering differences or minor CSS updates:
- The 0.8% diff suggests this is not a major visual change
- Could be Chrome version differences
- Could be sub-pixel rendering variations

Recommendations:
This is likely acceptable to approve:
- The changes are extremely minor (< 1%)
- No functional UI changes
- Probably browser/rendering variations

Approve with: approve_comparison tool
Or adjust threshold to 1% if these variations are expected

Cross-Build Debugging (Cloud Only)

When debugging visual regressions in cloud mode, you can track a screenshot across multiple builds to identify when changes were introduced.

When to Use Search

Use search_comparisons when:

• The user asks "when did this screenshot start failing?"
• They want to track a visual change across builds
• They're investigating a regression that appeared recently
• They want to see the history of a specific screenshot

How to Search

// Search for all comparisons of a screenshot
search_comparisons({
  name: "homepage_desktop",
  branch: "main",  // optional: filter by branch
  limit: 10        // optional: limit results
})

Example Workflow

User: "When did the homepage screenshot start failing?"

Step 1: Search for the screenshot across builds
Tool: search_comparisons({ name: "homepage", branch: "main", limit: 10 })

Response shows 10 comparisons from most recent to oldest, each with:
- Build name, branch, and creation date
- Diff percentage and status
- Screenshot URLs

Step 2: Analyze the timeline
- Build #45 (today): 5.2% diff - FAILED
- Build #44 (yesterday): 5.1% diff - FAILED
- Build #43 (2 days ago): 0.3% diff - PASSED
- Build #42 (3 days ago): 0.2% diff - PASSED

Step 3: Report findings
"The homepage screenshot started failing between Build #43 and #44
(approximately 1-2 days ago). The diff jumped from 0.3% to 5.1%,
suggesting a significant visual change was introduced."

Step 4: Deep dive into the failing build
Tool: read_comparison_details({ identifier: "cmp_xyz_from_build44" })
[View images and provide detailed analysis as usual]

Important Notes

• Always use read_comparison_details - it automatically detects the mode
• Use search_comparisons for cloud debugging - to track changes across builds
• Check the mode field to know which viewing tool to use (Read vs WebFetch)
• Never view diff images - only baseline and current
• Visual inspection is critical - don't rely solely on diff percentages
• Be specific in analysis - identify exact elements that changed
• Provide actionable advice - specific files, commands, or tools to use
• Consider context - small diffs might be acceptable, large ones need investigation