/visual-testing-advanced

name: visual-testing-advanced
description: "Advanced visual regression testing with pixel-perfect comparison, AI-powered diff analysis, responsive design validation, and cross-browser visual consistency. Use when detecting UI regressions, validating designs, or ensuring visual consistency."
category: specialized-testing
priority: high
tokenEstimate: 900
agents: [qe-visual-tester, qe-test-executor, qe-quality-gate]
implementation_status: optimized
optimization_version: 1.0
last_optimized: 2025-12-02
dependencies: []
quick_reference_card: true
tags: [visual, regression, screenshot, pixel-diff, percy, playwright, responsive]
trust_tier: 3
validation:
  schema_path: schemas/output.json
  validator_path: scripts/validate-config.json
  eval_path: evals/visual-testing-advanced.yaml

Advanced Visual Testing

<default_to_action> When detecting visual regressions or validating UI: 1. CAPTURE baseline screenshots (first run establishes baseline) 2. COMPARE new screenshots against baseline (pixel-by-pixel or AI) 3. MASK dynamic content (timestamps, ads, user counts) 4. TEST across devices (desktop, tablet, mobile viewports) 5. 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 breakpoint
for viewport in "375 667" "768 1024" "1920 1080"; do
  read 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)

import { test, expect } from '@playwright/test';

test('homepage visual regression', async ({ page }) => {
  await page.goto('https://example.com');

  // Capture and compare screenshot
  await expect(page).toHaveScreenshot('homepage.png');
  // First run: saves baseline
  // Subsequent runs: compares to baseline
});

test('responsive design', async ({ page }) => {
  // Mobile viewport
  await page.setViewportSize({ width: 375, height: 667 });
  await page.goto('https://example.com');
  await expect(page).toHaveScreenshot('homepage-mobile.png');

  // Tablet viewport
  await page.setViewportSize({ width: 768, height: 1024 });
  await expect(page).toHaveScreenshot('homepage-tablet.png');
});

---

Handling Dynamic Content

test('mask dynamic elements', async ({ page }) => {
  await page.goto('https://example.com');

  await expect(page).toHaveScreenshot({
    mask: [
      page.locator('.timestamp'),     // Dynamic time
      page.locator('.user-count'),    // Live counter
      page.locator('.advertisement'), // Ads
      page.locator('.avatar')         // User avatars
    ]
  });
});

---

AI-Powered Visual Testing (Percy)

import percySnapshot from '@percy/playwright';

test('AI-powered visual test', async ({ page }) => {
  await page.goto('https://example.com');

  // Percy uses AI to ignore anti-aliasing, minor font differences
  await percySnapshot(page, 'Homepage');
});

test('component visual test', async ({ page }) => {
  await page.goto('https://example.com/components');

  // Snapshot specific component
  const button = page.locator('.primary-button');
  await percySnapshot(page, 'Primary Button', {
    scope: button
  });
});

---

Playwright Configuration

// playwright.config.js
export default {
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,      // Allow 100 pi