Webstudio 可视化回归测试:基于 Storybook 与共享视觉引擎的像素级对比实践
Webstudio 可视化回归测试:基于 Storybook 与共享视觉引擎的像素级对比实践
Webstudio 的视觉回归测试(Visual Regression Testing)是一条不依赖任何托管服务的本地/CI 双重测试链路:它自动索引既有 Storybook CSF 故事文件,用 Vite 构建并启动一个轻量浏览器应用,在 Chromium 中分别渲染 merge base(基线)与当前工作区(被测版本),最后借助 Webstudio 共享的视觉引擎(@webstudio-is/vision)逐像素对比截图。读完本文,你将掌握 pnpm visual-regression:ui 系列命令的完整用法、config.ts 中全部阈值与缓存参数的含义、Story 级确定性渲染选项,以及 GitHub Actions 中"缓存基线、标签放行、Fork PR 门禁"的完整工作流。
一、整体架构:从 Storybook 故事到像素级差异报告
Webstudio 的视觉回归运行器(scripts/visual-regression/run.ts)在单次执行中完成如下链路:
- 索引故事:读取 .storybook/story-sources.json 中声明的 8 个故事作用域(Builder、Design system、CSS engine、Image、Icons、SDK components React、SDK components React Radix、SDK components animation),通过
storybook/internal/csf-tools的loadCsf解析每个*.stories.tsx文件,构建出包含id、title、name、exportName、file的故事清单(见 scripts/visual-regression/manifest.ts)。 - 构建与服务:用 Vite 以 Storybook preview 与故事模块为输入,打包一个仅含渲染能力的轻量 harness 应用,并分别在
127.0.0.1:6101(基线)与127.0.0.1:6102(当前)启动两个 preview 服务(见 scripts/visual-regression/story-server.ts 与 scripts/visual-regression/story-build.ts)。 - Chromium 渲染:通过 Playwright 驱动的浏览器会话对每个故事执行
renderVisualStory→ 等待#visual-ready标记 →finishVisualStory冻结最终帧后截图。 - 像素对比:调用共享视觉引擎
@webstudio-is/vision(packages/vision/src)的compareVisualEntries,按pixelThreshold与maxMismatchPercentage判定每个故事的 baseline / current / diff,并输出自包含的 HTML 报告。
整个链路不调用任何云端截图服务,也不需要第三方对比 API——这正是它可以在任意 CI runner 上直接复现的原因。
二、快速开始:三条核心命令
在仓库根目录(需先 pnpm install 完成依赖安装)执行完整对比并自动打开报告:
pnpm visual-regression:ui
该命令等价于 tsx --conditions=webstudio scripts/visual-regression/run.ts --open-report(定义于根目录 package.json),执行时会:
- 用
git merge-base HEAD origin/main计算基线提交,并通过git worktree add --detach检出独立的基线工作树; - 若基线截图缓存缺失,会先对基线工作树执行
pnpm install --frozen-lockfile --ignore-scripts --prod=false安装依赖再渲染; - 最终把报告写入
.visual-regression/report/index.html,并在命令结束时自动打开。
只关注某个区域,用 --grep 过滤故事标题/名称(大小写不敏感的正则匹配):
pnpm visual-regression:ui -- --grep "Design system/Button"
注意:
pnpm会将--之后的参数透传给脚本,因此--grep前需要加--。
与指定分支对比,用 --base <ref>:
pnpm visual-regression:ui -- --base "origin/dev"
只重开最近一次报告,不重新跑对比:
pnpm visual-regression:report
此外仓库还提供 pnpm visual-regression:test(运行 runner 自身的单元测试)与 pnpm visual-regression:typecheck(类型检查)两个开发辅助命令,用于保障 runner 自身的健壮性。
三、命令行参数与运行期行为(源码级解读)
scripts/visual-regression/run.ts 使用 Node 内置 parseArgs 解析参数,支持的选项如下:
| 参数 | 类型 | 默认值 | 作用 |
|---|---|---|---|
--base <ref> |
string | origin/main |
指定基线 git ref,用于计算 merge base |
--grep <regex> |
string | 无 | 按故事 id/title/name 过滤,new RegExp(grep, "i") |
--open-report |
boolean | false |
结束后调用系统浏览器打开报告 |
--approve-visual-changes |
boolean | false |
将"存在视觉差异"的结果视为已批准(CI 放行用) |
运行期还有两个值得注意的细节:
- 退出码语义:
passed(无差异)与approved(已批准)返回 0,visual-differences(有差异未批准)与test-failure(基础设施或故事渲染失败)返回 1,可直接接入 CI 的失败判定。 - 环境变量
VISUAL_CAPTURE_CONCURRENCY:截图并发数默认取min(8, max(5, os.availableParallelism())),即按机器 CPU 数自适应;可通过该环境变量强制覆盖,且必须是正整数,否则 runner 直接抛错:VISUAL_CAPTURE_CONCURRENCY must be a positive integer.。
三级验证流程:并发快照 → 串行复核 → 隔离配对
为了在"快"与"准"之间取得平衡,run.ts 对差异故事执行了三级验证:
- 并发粗筛:以
capture.concurrency(默认 5–8)并发抓取全部故事,执行第一轮像素对比; - 串行复核:对标记为
changed的故事以并发数 1 重新串行截图并再次对比(见verifyChangedCaptures),排除并发渲染时机不一致造成的误报; - 隔离配对:若仍有差异且使用了缓存基线,则只对剩余差异故事重建两个独立 server(基线/当前各一个),用
captureStoryPairs以 1 并发成对重抓,得到最终判定结果。这一步由 scripts/visual-regression/run-utils.ts 的getIsolatedVerificationServers提供配对 server 配置。
四、核心配置:config.ts 全参数解析
所有阈值、端口、缓存规则集中在 scripts/visual-regression/config.ts 的 visualRegressionConfig 常量中,结构如下:
| 分组 | 参数 | 默认值 | 含义 |
|---|---|---|---|
servers |
baselinePort / currentPort |
6101 / 6102 |
基线、当前版本 Vite preview 端口(strictPort: true) |
capture.viewport |
width / height |
1280 / 800 |
截图视口尺寸 |
capture |
timeout |
90000 |
单故事截图超时(毫秒) |
capture |
settleTime |
250 |
React 渲染后、截图前的稳定等待时间(毫秒) |
capture.concurrency |
minimum / maximum |
5 / 8 |
截图并发区间,按 CPU 数在此区间内取值 |
comparison |
pixelThreshold |
0.1 |
像素灵敏度,即单像素差异的最低判定阈值 |
comparison |
maxMismatchPercentage |
0.001 |
容忍的失配比例(即 0.001%),超过即判为 changed |
comparison |
concurrency |
4 |
像素对比阶段的并发数(实际取 min(4, CPU 数)) |
cache.include |
— | 见下 | 参与缓存指纹的文件 glob 列表 |
cache.exclude |
— | 见下 | 从指纹中排除的文件 glob 列表 |
缓存指纹:什么变化会作废截图缓存
cache.include 决定哪些文件的变更会使缓存失效:
cache: {
include: [
".storybook/preview.tsx",
".storybook/story-settings.ts",
".storybook/story-sources.json",
"packages/vision/src/**/*",
"scripts/visual-regression/**/*",
"pnpm-lock.yaml",
],
exclude: [
"**/*.test.*",
"**/*.test-utils.*",
"**/*.d.ts",
"**/*.md",
"**/tsconfig.json",
"**/__snapshots__/**",
],
}
scripts/visual-regression/runtime-hash.ts 会按排序后的文件列表逐个计算 SHA-256,并混入浏览器版本号,最终生成 12 位十六进制指纹。因此:只要视觉 harness、共享视觉引擎源码、Storybook preview/settings、锁文件或浏览器版本任一变化,缓存即自动作废,无需人工清理。截图缓存目录为 .visual-regression-cache/<revision>-<runtimeHash>,本地与 CI 共用同一套读写逻辑(restoreScreenshotCache / writeScreenshotCache,见 packages/vision/src/screenshot-cache.ts)。
五、Story 级确定性渲染:parameters.visualRegression
并发截图最怕"同一故事两次渲染出不同帧"。为此,Webstudio 的视觉 harness(scripts/visual-regression/harness.tsx)默认对所有故事注入确定性环境:
- 禁用 Web Animations:在 React effects 收敛后取消所有
document.getAnimations(),并注入animation-duration: 0s !important、transition: none !important等全局样式; - 禁用 setInterval:
window.setInterval默认替换为空实现(返回 0),防止轮询类逻辑产生时间依赖; - 固定时钟:
Date被代理为固定时间Date.UTC(2020, 0, 1),Date.now()同样被固定; - 确定性随机数:
Math.random替换为固定种子的线性同余生成器; - 隐藏外部 iframe 内容:因为 iframe 内部的渲染不归属于被测修订版本,故通过
visibility: hidden隐藏(对应hideSelectors); - 失焦处理:截图前对
document.activeElement执行blur(),消除焦点样式差异。
只有当一个故事能自行建立确定性状态时,才应在该故事的 parameters.visualRegression 中显式覆盖:
export const MyStory = {
parameters: {
visualRegression: {
disableAnimations: false, // 故事自身负责动画终态
disableIntervals: false, // 故事依赖 setInterval 且结果确定
hideSelectors: [".external-iframe", ".decorative-badge"], // 额外隐藏选择器
settleTime: 500, // 覆盖默认 250ms 稳定等待
},
},
};
可见参数包括 disableAnimations、disableIntervals、hideSelectors、settleTime(类型定义见 harness.tsx 的 VisualRegressionParameters)。渲染侧还会读取 Storybook 的 parameters.backgrounds,在截图前把 body 背景设置为对应值,保证背景一致。
六、故事作用域:.storybook/story-sources.json
对比范围不是硬编码的,而是 .storybook/story-sources.json 中声明的数据:
[
{ "directory": "../apps/builder", "titlePrefix": "Builder", "files": "**/*.stories.tsx" },
{ "directory": "../packages/design-system/src/components", "titlePrefix": "Design system", "files": "**/*.stories.tsx" },
{ "directory": "../packages/css-engine/src", "titlePrefix": "CSS engine", "files": "**/*.stories.tsx" },
{ "directory": "../packages/image/src", "titlePrefix": "Image", "files": "**/*.stories.tsx" },
{ "directory": "../packages/icons", "titlePrefix": "Icons", "files": "**/*.stories.tsx" },
{ "directory": "../packages/sdk-components-react", "titlePrefix": "SDK components React", "files": "**/*.stories.tsx" },
{ "directory": "../packages/sdk-components-react-radix", "titlePrefix": "SDK components React Radix", "files": "**/*.stories.tsx" },
{ "directory": "../packages/sdk-components-animation", "titlePrefix": "SDK components animation", "files": "**/*.stories.tsx" }
]
每个条目包含 directory(相对 .storybook 的扫描根)、files(glob 模式)、titlePrefix(故事标题前缀,最终标题为 titlePrefix/title)。manifest.ts 会做两件事:一是对每个作用域 glob 扫描并解析 CSF;二是检测重复故事 id(Duplicate visual story id)直接报错,从源头杜绝对比歧义。
关键在于:每次被对比的修订版本(基线/当前)各自加载自己工作树下的 story-sources.json 副本。这意味着删除、改名或新增一个故事作用域,对两次对比而言都是可见的——基线用旧的 scope 清单,当前用新的 scope 清单,差异会如实出现在报告中。
七、报告与诊断信息
HTML 报告
对比结束后,scripts/visual-regression/run.ts 调用 writeScreenshotComparisonReport 生成自包含报告(packages/vision/src/report.ts),输出到 .visual-regression/report/index.html。对每个失配故事,报告同时展示 baseline、current、diff 三张图片,并附带 OCR 文本证据(针对发生变化文字,对应 packages/vision/src/screenshot-ocr.ts,CI 环境依赖系统安装的 tesseract-ocr)。报告无需外部服务即可打开浏览,适合直接下载审阅。
CI 日志诊断
当对比失败时,run-utils.ts 的 formatVisualRegressionDiagnostics 会在日志中逐条列出:
- 每个受影响故事的 status、id、title / name 与源文件路径(
file=); - 像素失配度量:
differentPixels(差异像素数)与mismatchPercentage(失配百分比,保留 4 位小数); - 变化区域:每个
regions的x/y/width/height边界与像素计数; - 警告(warnings)与错误(error);
- 报告产物路径:
baseline=、current=、diff=、contextDiff=四类图片的相对路径。
这些信息让开发者在只看 CI 日志的情况下就能定位到具体故事、具体文件和具体像素区域。
八、GitHub Actions 工作流:缓存、标签与 Fork 门禁
完整流程定义在 .github/workflows/visual-regression.yml,核心设计如下:
单 Job 全量执行
整套对比在一个 job 内完成(timeout-minutes: 7,ubuntu-latest),步骤包括:fetch-depth: 0 全量检出 → 安装 submodules → CI 环境准备 → 按 pnpm-lock.yaml 指纹缓存并安装 Playwright Chromium(通过 @webstudio-is/sdk-components-animation 包的 playwright install chromium,WEBSTUDIO_BROWSER_PATH 注入环境变量)→ 安装 tesseract-ocr → 计算基线 merge-base 与运行期指纹 → 恢复/保存截图缓存 → 执行 pnpm visual-regression -- --base ... → 校验报告 JSON 非空 → 上传 visual-regression-report 产物(保留 14 天)。
截图缓存策略
- 缓存键为
visual-baseline-v1-<runner.os>-<base-sha>-<runtime-hash>,其中 runtime hash 混入了浏览器版本,保证同一批截图可在不同 hosted runner 间复用(因为浏览器版本被锁文件钉死); - PR 的基线来自
git merge-base HEAD base.sha,基线截图缓存缺失时由 runner 现场生成基线(自动pnpm install基线工作树); - 步骤末尾
always()保存两份缓存:head 版本(供依赖它的后续修订复用)与base 版本(生成出的基线)。
标签驱动的放行机制
visual-change-approved:默认情况下任何视觉差异都会让 PR 失败;审阅者确认差异是有意为之后,给 PR 打上visual-change-approved标签,CI 以--approve-visual-changes重跑同一次对比,结果被归类为approved而放行;- 新提交撤销批准:approval 仅对当前修订生效,一旦 PR 产生新提交,批准即失效,需要重新审阅——.github/workflows/remove-pr-approvals.yml 会在新提交时自动移除
visual-change-approved(以及safe-to-deploy)标签; - Fork PR 门禁:组织成员的 Fork PR 视为可信直接执行;其他 Fork 修订只有在打上
safe-to-deploy标签后才运行本工作流(对应pull_request_target事件与allow-unsafe-pr-checkout逻辑)。
九、本地缓存与工作树管理
runner 在本地运行时同样会维护截图缓存与基线工作树:
- 截图缓存写入仓库根目录的
.visual-regression-cache/; - 基线工作树创建在系统临时目录
webstudio-visual-regression-<sha1>下(os.tmpdir()),通过git worktree add --detach挂载基线提交,并在运行结束后清理 bundle 目录; - 这两类路径均被本地 git 忽略,不会污染工作区状态;
- 若当前工作区是干净的(
git status --porcelain为空),runner 还会把当前 HEAD 的截图写入缓存,供后续依赖它的修订复用。
十、实践建议与注意事项
- 先本地、后 CI:改动涉及 UI 时先用
pnpm visual-regression:ui -- --grep "<你的故事名>"快速迭代,确认无意外差异后再推送,避免消耗 CI 的 7 分钟配额。 - 谨慎关闭确定性渲染:只有故事自身能保证终态稳定时,才设置
disableAnimations: false/disableIntervals: false;并发截图场景下时序依赖会直接导致误报。 - 利用缓存作废规则:改动
packages/vision/src或视觉 harness 会自动作废所有截图缓存(属于预期行为);而纯文档、类型定义、测试文件的变化不会影响缓存,无需担心无效重建。 - 报告即证据:把
.visual-regression/report产物随 PR 一起下载查看,baseline / current / diff 三图加 OCR 文本足够支撑视觉变更的评审决策。 - 版本一致性:CI 使用 lockfile 钉死的 Playwright Chromium 版本渲染截图,本地也应保持同一浏览器版本,否则 runtime hash 变化会令缓存失效、对比结果也难以互相佐证。
从命令到阈值、从缓存指纹到 CI 标签,Webstudio 的视觉回归体系把"截图对比"这件事做成了完全可复现、可缓存、可审计的工程化流程——无论是本地开发中的快速回归,还是 PR 合并前的最终把关,它都是 Webstudio 组件与 Builder 界面质量的最后一道防线。