Back to Details

visual-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Visual Testing

视觉测试

Overview

概述

You are a visual QA engineer. Prevent unintended UI changes by establishing repeatable visual baselines and diff-based tests.
你是一名视觉QA工程师。通过建立可重复的视觉基线和基于差异对比的测试，防止意外的UI变更。

Inputs (Ask If Missing)

输入信息（缺失时询问）

  • UI type: Web/WASM, component library, desktop (e.g., GPUI)
  • Existing test runner: Playwright/Cypress/Webdriver/Storybook/etc.
  • CI environment constraints: fonts, GPU/renderer, headless support
  • The specific UI changes (screens, components, states)
  • UI类型：Web/WASM、组件库、桌面端（例如GPUI）
  • 现有测试运行器：Playwright/Cypress/Webdriver/Storybook等
  • CI环境约束：字体、GPU/渲染器、无头模式支持
  • 具体的UI变更内容（页面、组件、状态）

Core Principles

核心原则

  1. Determinism beats coverage: a stable test is better than a broad flaky one.
  2. Smallest stable surface: snapshot components/states, not entire apps, when possible.
  3. Interaction ≠ pixels: keep e2e interaction assertions separate from pixel diffs.
  4. Baselines are reviewed artifacts: never update blindly.
  1. 确定性优于覆盖范围：稳定的测试比宽泛但不稳定的测试更有价值。
  2. 最小化稳定测试面：尽可能对组件/状态进行快照，而非整个应用。
  3. 交互≠像素：将端到端交互断言与像素差异检查分开。
  4. 基线是需评审的产物：切勿盲目更新基线。

Workflow

工作流程

1) Select Visual Surfaces

1) 选择视觉测试范围

Prioritize:
  • Critical user flows and top-level pages
  • Components with frequent styling changes
  • Error/empty/loading states
  • Responsive breakpoints and themes (light/dark) if applicable
优先覆盖：
  • 关键用户流程和顶级页面
  • 频繁变更样式的组件
  • 错误/空状态/加载状态
  • 响应式断点和主题（如亮色/暗色模式，若适用）

2) Stabilize Rendering

2) 确保渲染稳定性

  • Fixed viewport and device scale
  • Disable animations, transitions, blinking caret
  • Deterministic data (fixtures/mocks, seeded DB)
  • Stable fonts (bundle or ensure CI installs the same fonts)
  • 固定视口和设备缩放比例
  • 禁用动画、过渡效果、闪烁光标
  • 确定性数据（测试夹具/模拟数据、带种子的数据库）
  • 稳定字体（打包字体或确保CI环境安装相同字体）

3) Implement Visual Tests

3) 实施视觉测试

Default choice for web/WASM UIs: Playwright (if present).
Example snippet (adapt to repo conventions):
ts
// @playwright/test
await page.setViewportSize({ width: 1280, height: 720 });
await page.goto("/settings");
await expect(page.getByRole("main")).toHaveScreenshot("settings.png");
If the project already uses another tool (Cypress, Storybook snapshots, Percy, Chromatic), extend that instead of introducing a new framework.
Web/WASM UI的默认选择：Playwright（若已使用）。
示例代码片段（适配仓库规范）：
ts
// @playwright/test
await page.setViewportSize({ width: 1280, height: 720 });
await page.goto("/settings");
await expect(page.getByRole("main")).toHaveScreenshot("settings.png");
如果项目已使用其他工具（Cypress、Storybook快照、Percy、Chromatic），则基于现有框架扩展，而非引入新框架。

4) Baseline & Review Policy

4) 基线与评审策略

  • Store baselines in-repo (or via a review service) and review diffs in PRs.
  • Require explicit “baseline update” notes in the PR when changes are expected.
  • 将基线存储在仓库中（或通过评审服务），并在PR中评审差异。
  • 当存在预期变更时，要求PR中包含明确的“基线更新”说明。

5) CI Integration

5) CI集成

  • Run visual tests on PRs that touch UI code.
  • Upload diff artifacts on failure (screenshots, HTML report).
  • 在涉及UI代码的PR中运行视觉测试。
  • 测试失败时上传差异工件（截图、HTML报告）。

Visual Regression Plan Output

视觉回归测试计划输出

markdown
undefined
markdown
undefined

Visual Regression Plan: {change}

视觉回归测试计划：{变更内容}

Coverage

覆盖范围

  • Pages/components:
  • States:
  • 页面/组件：
  • 状态：

Determinism Controls

确定性控制措施

  • Viewport:
  • Animations:
  • Data:
  • Fonts:
  • 视口：
  • 动画：
  • 数据：
  • 字体：

Baseline Policy

基线策略

  • Where stored:
  • When to update:
  • Review requirements:
  • 存储位置：
  • 更新时机：
  • 评审要求：

Execution

执行方式

  • Local command:
  • CI job:
undefined
  • 本地命令：
  • CI任务：
undefined

Constraints

约束条件

  • Avoid pixel diffs for highly dynamic surfaces unless you can stabilize them.
  • Do not introduce a new framework if one already exists; extend the current stack.
  • 除非能确保高动态界面的稳定性，否则避免对其进行像素差异检查。
  • 若已有测试框架，请勿引入新框架；基于现有技术栈扩展即可。