UI 视觉设计 / 系统课时
用 Storybook 截图做视觉回归
用 Storybook 截图做视觉回归
本课把 Storybook 中的关键组件状态固定成截图基准,并用 Playwright 在指定视口下自动复拍、比较差异。完成后,颜色、字号、间距或布局的意外变化会让测试失败,审核通过的设计改动则可以更新基准。
学习目标
- 选出需要长期保护的 Story 变体与视口组合。
- 配置可重复的浏览器截图测试,并生成可提交的基准图。
- 区分真实设计回归和环境噪声,正确审核截图更新。
确定变体与视口
先从用户最容易感知的状态入手。以 Button 为例,选定 Primary 和 Disabled,分别在 375×800 与 1280×800 CSS 像素下测试,共产生 4 张基准图。
| 检查维度 | 本例固定值 | 主要发现的问题 |
|---|---|---|
| Story 状态 | Primary、Disabled | 禁用透明度、背景色误改 |
| 视口 | 375×800、1280×800 | 换行、对齐、溢出 |
| 渲染条件 | Chromium、浅色模式、DPR=1 | 避免环境变化干扰 |
| 样式基线 | #2563EB、16px、内边距 10×18px |
色彩、排版和间距漂移 |
截图负责检查“有没有变”,不能独自判断“该不该变”。首次基准应与批准的 Figma 设计核对;长文案、深色主题或 Loading 状态确实属于产品需求时,再增加独立 Story,而不是把所有组合一次性铺满。
编写稳定的 Story
前置条件:项目已初始化 Storybook(此例为 React + Vite、CSF 3),且 .storybook/main.ts 的 stories 配置会扫描 src/**/*.stories.tsx。为使示例可独立复现,先在 src/stories/Button.stories.tsx 放入一个最小按钮;正式项目应改为导入真实组件。
import type { Meta, StoryObj } from '@storybook/react-vite';
function Button({ label, disabled = false }: { label: string; disabled?: boolean }) {
return (
<button
disabled={disabled}
style={{
backgroundColor: '#2563EB',
color: '#FFFFFF',
padding: '10px 18px',
border: 0,
borderRadius: 6,
fontSize: 16,
opacity: disabled ? 0.48 : 1,
}}
>
{label}
</button>
);
}
// 显式标题使 Story ID 不受文件移动影响
const meta = {
title: 'Components/Button',
component: Button,
parameters: { layout: 'centered' },
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Primary: Story = { args: { label: '提交订单' } };
export const Disabled: Story = { args: { label: '提交订单', disabled: true } };生效行为:Storybook 会生成 components-button--primary 和 components-button--disabled 两个 Story ID。截图应打开独立的 iframe.html 故事画面,而不是把 Storybook 侧边栏、工具栏一起截进去。
配置固定的截图环境
在项目根目录创建 playwright.config.ts。它只启用 Chromium,锁定语言、色彩模式与设备像素比,并在测试前自动启动已构建的静态 Storybook。这样本地和 CI 可使用相同入口。
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests/visual',
use: {
baseURL: 'http://127.0.0.1:6006',
browserName: 'chromium',
locale: 'zh-CN',
colorScheme: 'light',
deviceScaleFactor: 1,
},
webServer: {
command: 'npx http-server storybook-static -a 127.0.0.1 -p 6006',
url: 'http://127.0.0.1:6006',
reuseExistingServer: false,
timeout: 60_000,
},
});此配置依赖 @playwright/test 与 http-server。保持本地和 CI 使用同一操作系统镜像、浏览器版本与字体文件;仅固定视口不能消除跨平台字体渲染差异。若端口 6006 已占用,先关闭旧服务再执行。
截图、对比与预期结果
创建 tests/visual/button.spec.ts。测试按“变体×视口”运行:先确认按钮真实出现,再等待字体加载完成,最后比较整个视口截图。全视口截图还能检测组件在画布中的位置偏移。
import { test, expect } from '@playwright/test';
const variants = [
{ id: 'components-button--primary', name: 'primary' },
{ id: 'components-button--disabled', name: 'disabled' },
] as const;
for (const variant of variants) {
for (const width of [375, 1280]) {
test(`${variant.name}-${width}`, async ({ page }) => {
await page.setViewportSize({ width, height: 800 });
await page.goto(`/iframe.html?id=${variant.id}&viewMode=story`);
await expect(page.getByRole('button', { name: '提交订单' })).toBeVisible();
// 截图前等字体稳定,避免首次渲染的字形抖动
await page.evaluate(async () => { await document.fonts.ready; });
await expect(page).toHaveScreenshot(`${variant.name}-${width}.png`, {
animations: 'disabled',
caret: 'hide',
threshold: 0.1,
maxDiffPixels: 50,
});
});
}
}依次安装依赖、构建 Storybook、批准首批截图,再普通运行一次:
npm install --save-dev @playwright/test http-server
npx playwright install chromium
npx storybook build
npx playwright test --update-snapshots
npx playwright test预期输出(仅展示最终测试摘要;<TIME> 为实际耗时):
4 passed (<TIME>)基准 PNG 通常保存在 tests/visual/button.spec.ts-snapshots/ 下;把它们提交到版本控制。Playwright 会对比已存基准与本次截图,失败时在 test-results/ 产出实际图、预期图及差异图,便于定位像素变化。

审核失败截图而不是盲目更新
现在把按钮背景色由 #2563EB 改为 #1D4ED8,仅运行 npx playwright test:由于同一片按钮区域发生明显像素差异,对应测试应失败。查看失败报告中的基准图、当前图与差异区域,再与 Figma 的颜色 Token 核对。如果变动未经批准,应修复组件;确认是设计升级时,才使用 --update-snapshots 生成新的基准并在代码评审中审查 PNG 变化。
出现随机失败时依次核查:字体或远程图片是否加载完成、动画和光标是否稳定、浏览器及操作系统是否与生成基准时一致。maxDiffPixels: 50 仅容许少量像素差异,不等于忽略任意 50px 的布局移动;阈值过大还会漏掉真实回归。具体截图断言选项可查 Playwright 官方说明。
这条流程的验收标准是:4 组截图均能在同一环境重复通过;故意修改颜色或间距会触发失败;所有更新后的基准都有对应设计变更和人工审查记录。