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 放入一个最小按钮;正式项目应改为导入真实组件。

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 可使用相同入口。

ts
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。测试按“变体×视口”运行:先确认按钮真实出现,再等待字体加载完成,最后比较整个视口截图。全视口截图还能检测组件在画布中的位置偏移。

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、批准首批截图,再普通运行一次:

bash
npm install --save-dev @playwright/test http-server
npx playwright install chromium
npx storybook build
npx playwright test --update-snapshots
npx playwright test

预期输出(仅展示最终测试摘要;<TIME> 为实际耗时):

text
4 passed (<TIME>)

基准 PNG 通常保存在 tests/visual/button.spec.ts-snapshots/ 下;把它们提交到版本控制。Playwright 会对比已存基准与本次截图,失败时在 test-results/ 产出实际图、预期图及差异图,便于定位像素变化。

Storybook 视觉回归中的基准、当前与差异对比

审核失败截图而不是盲目更新

现在把按钮背景色由 #2563EB 改为 #1D4ED8,仅运行 npx playwright test:由于同一片按钮区域发生明显像素差异,对应测试应失败。查看失败报告中的基准图、当前图与差异区域,再与 Figma 的颜色 Token 核对。如果变动未经批准,应修复组件;确认是设计升级时,才使用 --update-snapshots 生成新的基准并在代码评审中审查 PNG 变化。

出现随机失败时依次核查:字体或远程图片是否加载完成、动画和光标是否稳定、浏览器及操作系统是否与生成基准时一致。maxDiffPixels: 50 仅容许少量像素差异,不等于忽略任意 50px 的布局移动;阈值过大还会漏掉真实回归。具体截图断言选项可查 Playwright 官方说明。

这条流程的验收标准是:4 组截图均能在同一环境重复通过;故意修改颜色或间距会触发失败;所有更新后的基准都有对应设计变更和人工审查记录。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 Storybook 截图做视觉回归

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

登录哪都通