name: visual-testing-advanced description: “高级视觉回归测试，具有像素完美比较、AI驱动的差异分析、响应式设计验证和跨浏览器视觉一致性。用于检测UI回归、验证设计或确保视觉一致性。” 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: [视觉, 回归, 截图, 像素差异, percy, playwright, 响应式] trust_tier: 3 validation: schema_path: schemas/output.json validator_path: scripts/validate-config.json eval_path: evals/visual-testing-advanced.yaml

高级视觉测试

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

捕获基线截图（首次运行建立基线）
将新截图与基线比较（像素级或AI）
掩码动态内容（时间戳、广告、用户计数）
跨设备测试（桌面、平板、移动视口）
审查并批准有意更改，在回归时失败

快速视觉测试步骤：

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

关键成功因素：

功能测试无法捕获视觉错误
AI驱动工具减少误报
审查差异，不要只是自动批准 </default_to_action>

快速参考卡

何时使用

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

视觉错误类型

错误类型	描述
布局偏移	元素位置移动
颜色变化	意外颜色修改
字体渲染	排版问题
对齐	间距/对齐问题
缺失图像	图像路径损坏
溢出	内容裁剪

比较算法

算法	最佳用途
像素差异	精确匹配需求
结构相似性	处理抗锯齿
AI语义	忽略不重要更改

使用Playwright进行视觉回归

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

test('主页视觉回归', async ({ page }) => {
  await page.goto('https://example.com');

  // 捕获并比较截图
  await expect(page).toHaveScreenshot('homepage.png');
  // 首次运行：保存基线
  // 后续运行：与基线比较
});

test('响应式设计', async ({ page }) => {
  // 移动视口
  await page.setViewportSize({ width: 375, height: 667 });
  await page.goto('https://example.com');
  await expect(page).toHaveScreenshot('homepage-mobile.png');

  // 平板视口
  await page.setViewportSize({ width: 768, height: 1024 });
  await expect(page).toHaveScreenshot('homepage-tablet.png');
});

处理动态内容

test('掩码动态元素', async ({ page }) => {
  await page.goto('https://example.com');

  await expect(page).toHaveScreenshot({
    mask: [
      page.locator('.timestamp'),     // 动态时间
      page.locator('.user-count'),    // 实时计数器
      page.locator('.advertisement'), // 广告
      page.locator('.avatar')         // 用户头像
    ]
  });
});

AI驱动视觉测试（Percy）

import percySnapshot from '@percy/playwright';

test('AI驱动视觉测试', async ({ page }) => {
  await page.goto('https://example.com');

  // Percy使用AI忽略抗锯齿、次要字体差异
  await percySnapshot(page, '主页');
});

test('组件视觉测试', async ({ page }) => {
  await page.goto('https://example.com/components');

  // 快照特定组件
  const button = page.locator('.primary-button');
  await percySnapshot(page, '主要按钮', {
    scope: button
  });
});

Playwright配置

// playwright.config.js
export default {
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,      // 允许100像素差异
      maxDiffPixelRatio: 0.01, // 或图像的1%
      threshold: 0.2,          // 颜色相似性阈值
      animations: 'disabled',  // 禁用动画
      caret: 'hide'            // 隐藏光标
    }
  }
};

代理驱动视觉测试

// 全面视觉回归
await Task("视觉回归套件", {
  baseline: '主分支',
  current: '功能分支',
  pages: ['主页', '产品', '结账'],
  devices: ['桌面', '平板', '移动'],
  browsers: ['chrome', 'firefox', 'safari'],
  threshold: 0.01
}, "qe-visual-tester");

// 返回：
// {
//   comparisons: 27,  // 3页 × 3设备 × 3浏览器
//   differences: 2,
//   report: 'visual-regression-report.html'
// }

代理协调提示

内存命名空间

aqe/visual-testing/
├── baselines/*          - 基线截图
├── comparisons/*        - 差异结果
├── components/*         - 组件快照
└── reports/*            - 视觉回归报告

舰队协调

const visualFleet = await FleetManager.coordinate({
  strategy: 'visual-testing',
  agents: [
    'qe-visual-tester',   // 截图比较
    'qe-test-executor',   // 跨浏览器执行
    'qe-quality-gate'     // 阻止视觉回归
  ],
  topology: 'parallel'
});

记住

功能测试无法捕获视觉错误。 布局偏移、颜色变化、字体渲染、对齐问题——所有功能测试不可见但对用户可见。

AI驱动工具减少误报。 Percy、Applitools使用AI忽略不重要的差异（抗锯齿、次要字体渲染）。

使用代理： qe-visual-tester 自动化跨浏览器和设备的视觉回归，使用AI过滤噪声，并生成视觉差异报告。在用户看到之前捕获UI回归。

高级视觉测试Skill visual-testing-advanced