visual-testing

用途

视觉测试（视觉回归测试）通过对比截图来捕捉非预期的 UI 变化。本技能覆盖三种实现方式：

Chromatic — 基于云端，支持无限并行化（推荐）
Lost Pixel — 可自托管的开源替代方案
Playwright 内置 — 简单的快照测试

主要能力与使用方式

Chromatic 快速开始（约 5 分钟）

安装：npm install --save-dev chromatic
获取项目令牌：前往 chromatic.com，用 GitHub 注册（免费层：5000 快照/月），创建项目后复制项目令牌
运行首次构建：

# Set token
export CHROMATIC_PROJECT_TOKEN=your_token_here

# Run visual tests with Playwright
npx chromatic --playwright

审查变更：Chromatic UI 展示视觉差异，通过或拒绝变更，通过后的变更成为新基线。

可与 Playwright 结合使用：在 playwright.config.ts 中配置 testDir、screenshot: 'on'，并使用 chromatic 报告器（引用 process.env.CHROMATIC_PROJECT_TOKEN）。视觉测试示例中使用 await expect(page).toHaveScreenshot('homepage.png') 进行整页截图，或对特定元素（如 .revenue-chart）截图。

CI 集成（GitHub Actions）：工作流需 fetch-depth: 0（Chromatic 必需），安装依赖与 Playwright，并运行 npx chromatic --playwright，通过 secrets 传入 CHROMATIC_PROJECT_TOKEN。

Chromatic 免费层特性：5000 快照/月、无限并行化、支持 Chrome/Firefox/Safari、提供审查 UI 与 GitHub 集成。

Lost Pixel（自托管）

适用于不能使用云服务的机密项目。

安装：npm install --save-dev lost-pixel
配置 lostpixel.config.ts：定义 pageShots.pages（路径与名称）与 baseUrl，本地存储基线/当前/差异图像路径，generateOnly: false、failOnDifference: true，比较阈值 threshold: 0.1（允许 0.1% 像素差异）
运行：npx lost-pixel update（首次生成基线）、npx lost-pixel（运行比较），差异可在 .lostpixel/difference/ 查看
Docker 设置（用于 CI）：基于 mcr.microsoft.com/playwright:v1.40.0-focal 构建镜像，CI 中构建并运行容器

Playwright 内置快照

最简单的方式，无需外部服务。

基本用法：await expect(page).toHaveScreenshot('homepage.png')；可用选项如 fullPage: true、maxDiffPixels: 100；也可对特定元素（如 header）截图
更新基线：npx playwright test --update-snapshots（可指定具体测试文件）
配置：设置 maxDiffPixels、maxDiffPixelRatio、threshold 以及 snapshotPathTemplate

跨平台问题：截图在 Mac/Linux/Windows 之间可能不同。解决方案包括：使用 Docker（推荐）在一致环境中运行；使用平台专属基线路径模板；提高阈值（如 maxDiffPixelRatio: 0.05）。

对比矩阵

特性	Chromatic	Lost Pixel	Playwright
免费层	5000 快照	无限	无限
自托管	否	是	是
并行化	无限	手动	手动
审查 UI	有（Web）	无（本地文件）	无（本地文件）
跨浏览器	是	是	是
AI 检测	是	否	否
设置时间	5 分钟	15 分钟	5 分钟
最适合	团队、CI/CD	机密项目	简单项目

最佳实践

稳定选择器：等待动态内容（waitForSelector('[data-loaded="true"]')、waitForLoadState('networkidle')）；隐藏动态元素（如时间戳）
一致的视口：在配置中设置 viewport（如 1280x720），或按测试设置（如移动端 375x667）
模拟时间/数据：冻结时间（重写 Date.now）；用 page.route 模拟 API 响应
组件级测试：测试按钮的默认、悬停、激活等状态

CI 中的视觉测试工作流

PR 流程：开发者推送代码 → CI 运行视觉测试 → Chromatic 检测变更 → 在 Chromatic UI 审查差异 → 通过则成为新基线，拒绝则修复后重新推送 → 合并 PR。

基线管理：本地更新基线后提交到 git（git add tests/__screenshots__/），或使用 Chromatic（基线存储在云端，可用 --auto-accept-changes 接受所有变更）。

参考资料

references/chromatic-setup.md — 完整的 Chromatic 配置
references/lost-pixel-self-hosted.md — 自托管设置指南
references/playwright-snapshots.md — 内置快照测试

限制

资料未提供各方案的具体价格（除免费层快照数量外）、平台可用性细节或超出上述配置范围的扩展能力说明。视觉测试能在用户之前捕捉 UI 回归——团队选 Chromatic，机密项目选 Lost Pixel。