visual-testing-advanced

高级视觉测试

<default_to_action> 检测视觉回归或验证 UI 时：

1. CAPTURE 基线截图（首次运行时建立基线）
2. COMPARE 新截图与基线（逐像素或使用 AI）
3. MASK 动态内容（时间戳、广告、用户数量）
4. TEST 多种设备（桌面、平板、移动设备视口）
5. REVIEW 并批准有意的更改，出现回归时则判定失败

快速视觉测试步骤：

• 在主分支上设置基线
• 将功能分支与基线进行比较
• 遮盖动态元素（时间戳、头像）
• 使用 AI 驱动的比较来减少误报
• 集成到 CI/CD 中，以阻止视觉回归

关键成功因素：

• 功能测试无法捕获视觉错误
• AI 驱动的工具可以减少误报
• 检查差异，不要直接自动批准 </default_to_action>

速查卡

适用场景

• UI 组件更改
• CSS/样式修改
• 响应式设计验证
• 跨浏览器一致性检查

视觉错误类型

错误类型	描述
布局偏移	元素位置发生移动
颜色变化	非预期的颜色修改
字体渲染	字体排版问题
对齐	间距/对齐问题
图片缺失	图片路径失效
溢出	内容被裁切

比较算法

算法	最适用于
像素差异	要求精确匹配
结构相似性	处理抗锯齿
AI 语义比较	忽略无关紧要的更改

---

首选方案：qe-browser visual-diff

**大多数视觉回归工作都应通过 qe-browser fleet 技能完成。**它封装了 Vibium（WebDriver BiDi），可针对存储的基线执行像素差异比较，并提供阈值强制检查和差异图像输出。请参阅 .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

基线存储在 .aqe/visual-baselines/ 中。脚本在安装了 pixelmatch 时使用它，否则使用基于哈希的精确匹配回退方案。当相似度低于 1 - threshold 时，脚本会以非零状态码退出，因此 CI 门禁基于 $?。

何时继续使用 Playwright 视觉回归

仅在以下情况下使用下方的 Playwright 配方：

• 需要 AI 语义比较（Percy、Applitools）来忽略无关紧要的像素偏移
• 需要在 Firefox/WebKit 中进行 跨浏览器渲染检查（目前 Vibium 仅支持 Chrome）
• 需要与现有 Playwright 测试套件 紧密集成

---

旧版：使用 Playwright 进行视觉回归（回退方案）

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');
});

---

处理动态内容

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 驱动的视觉测试（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 配置

// playwright.config.js
export default {
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,      // Allow 100 pixel difference
      maxDiffPixelRatio: 0.01, // Or 1% of image
      threshold: 0.2,          // Color similarity threshold
      animations: 'disabled',  // Disable animations
      caret: 'hide'            // Hide cursor
    }
  }
};

---

Agent 驱动的视觉测试

// Comprehensive visual regression
await Task("Visual Regression Suite", {
  baseline: 'main-branch',
  current: 'feature-branch',
  pages: ['homepage', 'product', 'checkout'],
  devices: ['desktop', 'tablet', 'mobile'],
  browsers: ['chrome', 'firefox', 'safari'],
  threshold: 0.01
}, "qe-visual-tester");

// Returns:
// {
//   comparisons: 27,  // 3 pages × 3 devices × 3 browsers
//   differences: 2,
//   report: 'visual-regression-report.html'
// }

---

Agent 协调提示

记忆命名空间

aqe/visual-testing/
├── baselines/*          - Baseline screenshots
├── comparisons/*        - Diff results
├── components/*         - Component snapshots
└── reports/*            - Visual regression reports

Fleet 协调

const visualFleet = await FleetManager.coordinate({
  strategy: 'visual-testing',
  agents: [
    'qe-visual-tester',   // Screenshot comparison
    'qe-test-executor',   // Cross-browser execution
    'qe-quality-gate'     // Block on visual regressions
  ],
  topology: 'parallel'
});

---

相关技能

• 无障碍测试 - 视觉无障碍检查
• 兼容性测试 - 跨浏览器视觉检查
• 回归测试 - 回归测试套件

---

请记住

**功能测试无法捕获视觉错误。**布局偏移、颜色变化、字体渲染、对齐问题——这些对功能测试都不可见，但用户可以看到。

**AI 驱动的工具可以减少误报。**Percy、Applitools 使用 AI 忽略无关紧要的差异（抗锯齿、轻微的字体渲染差异）。

使用 Agent：qe-visual-tester 可自动执行跨浏览器和设备的视觉回归测试，使用 AI 过滤噪声，并生成视觉差异报告。在用户发现 UI 回归之前将其捕获。