Visual Testing

Visual testing compares screenshots between runs to detect unexpected UI changes. Catch CSS regressions, layout shifts, and missing elements automatically.

How It Works

1. Baseline - First successful run establishes the baseline screenshot
2. Compare - Subsequent runs compare against the baseline
3. Diff - Pixel differences are calculated as a percentage
4. Alert - If diff exceeds threshold, an alert is triggered

Enabling Visual Testing

Visual testing is enabled per-journey:

1. Go to your journey settings
2. Enable Visual Testing
3. Set the Diff Threshold (default: 5%)

Journey Settings:
  Visual Testing: enabled
  Diff Threshold: 5%
  Full Page Capture: true

Diff Threshold

The diff threshold determines how much change triggers an alert:

Understanding Visual Diffs

When a visual diff is detected, you'll see:

• Baseline Image - The expected appearance
• Current Image - What the page looks like now
• Diff Image - Highlighted differences (usually in pink/red)
• Diff Percentage - Numerical difference

Types of Changes Detected

Managing Baselines

Viewing Current Baseline

1. Go to your journey
2. Click Visual Testing tab
3. View the current baseline image

Updating Baseline

When an intentional UI change occurs:

1. Review the failed run
2. Verify the change is expected
3. Click Promote to Baseline

This sets the new screenshot as the baseline for future comparisons.

Automatic Baseline Updates

You can configure automatic baseline updates:

Visual Testing:
  Auto-update Baseline: true
  After: 3 consecutive matches

This promotes a new baseline after consistent results, useful for frequently changing pages.

Screenshot Configuration

Full Page vs Viewport

Specific Element Capture

Target specific elements instead of full page:

Visual Testing:
  Target Selector: .main-content
  Ignore Selectors:
    - .dynamic-timestamp
    - .ad-banner
    - .user-avatar

Ignoring Dynamic Content

Exclude elements that change between runs:

Ignore Regions:
  - selector: .current-time
  - selector: .random-ad
  - selector: .live-counter
  - area: { x: 0, y: 0, width: 200, height: 50 }  # Header area

Alert Rules for Visual Testing

Create alert rules specifically for visual changes:

Alert Rule:
  Name: Visual Regression Alert
  Type: visual_diff
  Threshold: 5%
  Channels:
    - Slack (#design-alerts)
    - Email ([email protected])

Alert Conditions

Best Practices

1. Use Stable Selectors

Target stable elements, not dynamic content:

# Good - specific component
Target: [data-testid="product-grid"]

# Bad - includes dynamic content
Target: body

2. Set Appropriate Thresholds

Match threshold to your use case:

• E-commerce product pages: 5% (images may vary)
• Documentation pages: 2% (should be stable)
• Dashboards with live data: 15% (expect variation)

3. Exclude Known Dynamic Elements

Ignore Selectors:
  - .timestamp
  - .live-visitor-count
  - .ad-container
  - .chat-widget

4. Run at Consistent Times

Schedule visual tests during low-activity periods to reduce variance:

Schedule: 0 3 * * *  # 3 AM daily

5. Use Consistent Viewport Sizes

Set explicit viewport dimensions:

Viewport:
  Width: 1280
  Height: 720

Troubleshooting

High False Positive Rate

Problem: Alerts triggering for acceptable changes

Solutions:

• Increase diff threshold
• Add ignore selectors for dynamic content
• Use element-specific capture instead of full page

Missing Important Changes

Problem: UI bugs not being caught

Solutions:

• Lower diff threshold
• Capture full page instead of viewport
• Add specific assertions for critical elements

Baseline Drift

Problem: Baseline gradually becomes outdated

Solutions:

• Manually review and update baselines periodically
• Set up baseline review schedule
• Use automatic baseline updates cautiously

Visual Testing vs Snapshot Testing

tracer uses visual (pixel) testing for the most accurate representation of what users see.