UI 视觉设计 / 系统课时

用视觉回归捕获样式漂移

用视觉回归捕获样式漂移

本课用 Playwright 为 Primary 按钮建立浅色、深色及交互状态的截图基线,并在 Token 变更后自动比较差异。完成后,你能定位意外的颜色、尺寸或透明度漂移,且不会把未经审批的变化直接覆盖进基线。

学习目标

  • 设计覆盖主题与组件状态的最小视觉回归矩阵。
  • 使用真实 CSS Token 产物生成、比较并保存截图。
  • 根据差异图判定预期设计变更或意外回归,并正确更新基线。

确定截图范围与判定标准

先固定一个可检查的矩阵:Primary 按钮采用 Light、Dark 两个主题,分别覆盖 Default、Hover、Disabled 三个状态,共 2 × 3 = 6 张基线。每张图截取同样尺寸的组件区域,包含背景,以便检查文字与背景的对比关系。

检查维度 固定条件 主要捕获的问题
主题 Light / Dark 主题覆盖失效、别名落入错误色值
状态 Default / Hover / Disabled 状态色遗漏、禁用透明度错误
运行环境 Chromium、800×600 视口、DPR 1 降低浏览器及尺寸造成的假差异

组件级截图先采用 threshold: 0.1、maxDiffPixels: 0:达到感知色差阈值的不同像素不允许出现。这里的 threshold 是单像素颜色差异判定阈值,不是“允许 10% 像素不同”。只有在固定环境下仍存在已定位的抗锯齿噪声时,才考虑小幅放宽。

让测试直接消费 Token 产物

以下以 Playwright Test 1.41+ 为例。使用 Node.js 与 npm,在项目根目录准备 generated/tokens.css。下面是可用于演练的完整 CSS 文件;接入真实项目时,应改由 Token 构建步骤生成此文件,不要在测试中另写一份与生产无关的色值。

css
:root {
  --color-action-primary: #155eef;
  --color-action-primary-hover: #0046c7;
  --color-on-action: #ffffff;
  --color-surface-default: #ffffff;
  --opacity-disabled: 0.4;
}

[data-theme="dark"] {
  --color-action-primary: #93c5fd;
  --color-action-primary-hover: #bfdbfe;
  --color-on-action: #111827;
  --color-surface-default: #111827;
}

建立 tests/button.visual.spec.ts。测试不比较整个页面,而是给相同宽度的组件演示区域截图;通过真实悬停及 disabled 属性分别进入交互状态。

ts
import { readFileSync } from 'node:fs';
import { test, expect } from '@playwright/test';

const tokens = readFileSync('generated/tokens.css', 'utf8');

// 锁定渲染条件,避免不同视口或 DPR 污染基线。
test.use({
  browserName: 'chromium',
  viewport: { width: 800, height: 600 },
  deviceScaleFactor: 1,
  locale: 'zh-CN',
  colorScheme: 'light',
});

for (const theme of ['light', 'dark'] as const) {
  test(`Primary ${theme}`, async ({ page }) => {
    await page.setContent(`
      <style>
        ${tokens}
        body { margin: 0; }
        main {
          display: inline-block;
          min-width: 240px;
          padding: 24px;
          background: var(--color-surface-default);
        }
        button {
          border: 0;
          border-radius: 8px;
          padding: 12px 20px;
          font: 600 16px Arial, sans-serif;
          background: var(--color-action-primary);
          color: var(--color-on-action);
        }
        button:hover:not(:disabled) {
          background: var(--color-action-primary-hover);
        }
        button:disabled { opacity: var(--opacity-disabled); }
      </style>
      <main data-theme="${theme}"><button>保存</button></main>
    `);
    await page.evaluate(() => document.fonts.ready);
    const panel = page.locator('main');
    const button = page.getByRole('button', { name: '保存' });
    const options = { threshold: 0.1, maxDiffPixels: 0 };

    await expect(panel).toHaveScreenshot(`primary-${theme}-default.png`, options);
    await button.hover();
    await expect(panel).toHaveScreenshot(`primary-${theme}-hover.png`, options);

    // 移开鼠标,避免 Hover 污染 Disabled 截图。
    await button.evaluate((el) => (el as HTMLButtonElement).disabled = true);
    await page.mouse.move(0, 0);
    await expect(panel).toHaveScreenshot(`primary-${theme}-disabled.png`, options);
  });
}

在已保存上述两个文件的项目根目录执行:

bash
npm install -D @playwright/test
npx playwright install chromium
npx playwright test tests/button.visual.spec.ts --update-snapshots --workers=1
npx playwright test tests/button.visual.spec.ts --workers=1

**预期结果:**首次带 --update-snapshots 的执行建立六张 PNG 基线;再次运行比较现有基线,最后一个命令的测试摘要类似:

text
2 passed (<TIME>)

<TIME> 是实际执行耗时,会因机器不同而变化。PNG 默认保存在测试文件旁的 button.visual.spec.ts-snapshots 目录(文件名可能附带平台或项目标识)。将基线纳入版本控制;若首次不带更新参数运行,缺失基线可能被生成但测试仍判失败。

从差异图追踪到具体 Token

一条可复核的审查链是:读取已批准基线、截图当前产物、查看两者差异,再按设计变更单决定修复还是更新。发生失败时,Playwright 的测试结果中通常提供 expected、actual 和 diff 图像;先看差异区域,再查组件计算样式和 Token 别名链。

视觉回归基线对比与差异审批流程

例如设计将 Light 的 --color-action-primary 从 #155eef 改成 #0a60e8,这套样例应主要影响 Light Default 与 Light Disabled 两张图;Hover 使用独立的 Hover Token,Dark 有主题覆盖值,按设计应保持原样。如果 Dark 也出现颜色变化,就要检查主题选择器是否失效,而不是直接重录六张图。

审批更新与排除假阳性

差异现象 判定与处理
已批准的 Light 主色变更 核对变更单及受影响的两张图后,更新对应基线并审查 PNG diff
Dark 颜色意外同步变化 检查 [data-theme="dark"] 覆盖、变量拼写及 CSS 加载顺序,修复后重测
字形边缘每次都闪动 对齐 OS、浏览器版本、字体和渲染环境,不通过放宽阈值掩盖
时间、头像或随机内容变化 在测试数据源固定值;必要时只遮罩无关区域,不能遮住待检查组件

更新截图的命令是 npx playwright test tests/button.visual.spec.ts --update-snapshots --workers=1,但它会更新本次测试中发生变化的快照。因此应先隔离并检查目标改动,随后复查 Git 中变化的 PNG,再在不带更新参数的 CI 流程里运行比较。CI 必须先生成 Token CSS,并保持与基线一致的浏览器、字体和操作系统;有未批准差异时让检查失败。

视觉回归负责发现“像素表现变了”,不能单凭差异图断言设计对错。最终放行依据应同时包含设计变更记录、受影响状态矩阵和可复现的截图比较。接口选项可对照 Playwright 官方视觉比较文档。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用视觉回归捕获样式漂移

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通