视觉 QA

面向 Web 应用的视觉回归测试流水线。捕获应用的基准截图，使用像素级差异比对新截图与基准图，并依据可配置的相似度阈值判定通过/失败。

适用场景

• 部署前视觉校验 — 将 UI 变更审批作为合并/部署的准入门禁
• 回归测试 — 在 CI 中捕获非预期的视觉变更
• UI 评审工作流 — 为设计/代码评审生成差异图像
• 跨浏览器/视口测试 — 验证响应式布局一致性
• 组件库 QA — 确保设计系统变更不会破坏下游消费者

快速开始

1. 捕获基准截图

# 捕获单个 URL
python scripts/capture.py http://localhost:3000 --output .visual-qa/baselines

# 捕获多个视口尺寸
python scripts/capture.py http://localhost:3000 --viewports desktop mobile tablet --output .visual-qa/baselines

# 根据配置文件捕获多个页面
python scripts/capture.py --config .visual-qa.json --output .visual-qa/baselines

2. 与基准图比对

# 比对新截图
python scripts/diff.py --baseline .visual-qa/baselines --current .visual-qa/current --threshold 99

3. 一体化门禁命令

# 一键完成截图 + 差异比对
python scripts/gate.py --baseline .visual-qa/baselines --url http://localhost:3000 --threshold 99

# 启动本地开发服务器后执行
python scripts/gate.py --baseline .visual-qa/baselines --server "npm run dev" --port 3000 --threshold 99

# 使用配置文件
python scripts/gate.py --config .visual-qa.json

配置文件格式

在项目根目录创建 .visual-qa.json：

{
  "urls": ["/", "/about", "/pricing"],
  "baseUrl": "http://localhost:3000",
  "viewports": ["desktop", "mobile"],
  "threshold": 99,
  "server": "npm run dev",
  "port": 3000,
  "baselineDir": ".visual-qa/baselines",
  "ignore": [".visual-qa/diffs", ".visual-qa/current"]
}

脚本说明

所有脚本均支持 --help 参数以查看详细用法。

capture.py

使用 Playwright（无头 Chromium）捕获截图。

特性：

• 支持多种视口尺寸：桌面端（1280×800）、平板（768×1024）、移动端（375×812）
• 等待网络空闲（networkidle）后再截图
• 可选自动启动/停止本地服务器
• 支持自定义输出目录
• 生成描述性文件名：{url-slug}_{viewport}.png

用法：

python scripts/capture.py  --output  [options]
python scripts/capture.py --config  --output 

diff.py

使用 Pillow 进行像素级差异比对。

特性：

• 逐像素比对
• 生成差异图像，以红色/品红色叠加高亮显示变更区域
• 为每组图像对输出相似度百分比
• 依据阈值判定通过/失败（默认 99%）
• 输出包含通过/失败状态的汇总报告
• 将差异图像保存至指定输出目录

用法：

python scripts/diff.py --baseline  --current  --output  --threshold 

gate.py

一体化门禁脚本：单条命令完成截图 + 差异比对。

特性：

• 整合 capture 和 diff 流程
• 按需自动启动/停止本地服务器
• 返回标准退出码：0（通过）、1（失败）
• 输出人类可读的摘要信息
• 支持配置文件或命令行参数两种方式

用法：

python scripts/gate.py --baseline  --url  --threshold 
python scripts/gate.py --baseline  --server  --port  --threshold 
python scripts/gate.py --config 

工作流示例

初始基准图捕获

# 启动你的应用
npm run dev

# 捕获桌面端和移动端基准图
python scripts/capture.py http://localhost:3000 --viewports desktop mobile --output .visual-qa/baselines

CI/CD 集成

# 在 CI 流水线构建完成后执行
python scripts/gate.py --baseline .visual-qa/baselines --server "npm start" --port 3000 --threshold 99

# 退出码 0 = 通过，1 = 失败
if [ $? -eq 0 ]; then
  echo "Visual QA passed ✓"
else
  echo "Visual QA failed ✗"
  exit 1
fi

评审工作流

# 1. 开发者修改 UI
# 2. 捕获新截图
python scripts/capture.py http://localhost:3000 --output .visual-qa/current

# 3. 生成差异图像
python scripts/diff.py --baseline .visual-qa/baselines --current .visual-qa/current --output .visual-qa/diffs

# 4. 在 .visual-qa/diffs/ 目录中审阅差异图像
# 5. 若变更是预期行为，则更新基准图：
rm -rf .visual-qa/baselines
mv .visual-qa/current .visual-qa/baselines

多页面测试

创建 .visual-qa.json：

{
  "urls": ["/", "/products", "/about", "/contact"],
  "baseUrl": "http://localhost:3000",
  "viewports": ["desktop", "mobile"],
  "threshold": 99,
  "baselineDir": ".visual-qa/baselines"
}

# 捕获全部页面
python scripts/capture.py --config .visual-qa.json --output .visual-qa/baselines

# 对全部页面执行门禁检查
python scripts/gate.py --config .visual-qa.json

依赖项

脚本依赖 Playwright 和 Pillow：

pip install playwright pillow
python -m playwright install chromium

脚本会在运行时检查依赖，若缺失则自动打印安装提示。

相似度阈值

--threshold 参数控制相似度百分比（取值范围：0–100）：

• 99%（默认）—— 严格模式，可捕获绝大多数视觉变更
• 95% —— 中等模式，允许细微渲染差异（如抗锯齿、字体渲染）
• 90% —— 宽松模式，允许多样化变化（适用于含动态内容的页面）

建议通过实验为你的应用确定合适阈值：从严格模式（99%）起步，若出现误报再逐步放宽。

忽略动态内容

对于含动态内容的页面（例如日期、用户专属数据）：

1. 使用 data 属性 在测试期间隐藏动态元素：

   [data-test-hide] { visibility: hidden !important; }
   

2. 仅截取特定视口区域（未来增强功能）

3. 为允许含动态内容的页面调低阈值

故障排查

“Command not found: python”

• 改用 python3 替代 python

“Playwright not installed”

• 执行：pip install playwright && python -m playwright install chromium

“相似度低于阈值但图像看起来一致”

• 可能由字体渲染、抗锯齿或亚像素差异引起。可将阈值下调至 98–95%。

“服务器未能启动”

• 确认 --port 参数与服务器实际监听端口一致
• 确保服务器启动命令正确（如 npm run dev、npm start 等）
• 在 gate.py 中增加等待时间（默认为 5 秒）

“未找到图像文件”

• 确认基准图目录存在且包含 PNG 文件
• 确认当前截图已正确写入目标目录
• 确认文件名符合命名规范：{url-slug}_{viewport}.png

使用建议

• 将基准图提交至 Git，确保团队共享同一参考基准
• 将 .visual-qa/diffs 和 .visual-qa/current 加入 .gitignore
• 在 CI 中作为合并前必检项运行
• 在实施预期 UI 变更后及时更新基准图
• 使用多种视口尺寸，以发现响应式布局问题
• 显式捕获空状态/错误状态/加载状态页面，覆盖完整 UI 场景

与其他能力的集成

• ux-qa-gate — 将 visual-qa 纳入 UX QA 检查清单
• webapp-testing — 与 Playwright 功能性测试协同使用
• coding-agent — UI 构建子代理必须通过 visual-qa 才能完成任务

如需查看各脚本完整参数说明，请运行：

python scripts/capture.py --help
python scripts/diff.py --help
python scripts/gate.py --help