mcpField
U
update-storybook-snapshots

update-storybook-snapshots

github.com/cartridge-gg测试与质量8036 次安装7 周前更新
代码仓库

关于 update-storybook-snapshots

update-storybook-snapshots 是用于维护 Storybook 视觉回归测试基线的技能，面向 UI 组件开发者。它说明如何查看差异、更新快照并检查结果，也涵盖常见故障处理。

主要功能

  1. 01运行 Storybook 快照测试
  2. 02查看预期与实际图像差异
  3. 03重新生成快照基线
  4. 04检查改动并提交快照
  5. 05处理超时和环境差异

适用场景

  1. 01有意修改组件样式后更新基线
  2. 02为新增组件生成快照
  3. 03设计系统更新后核验视觉变化

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cartridge-gg/controller --skill update-storybook-snapshots

安装后在 Claude Code 中输入/update-storybook-snapshots确认已加载。

详细介绍

更新 Storybook 快照

概述

Storybook 快照是用于视觉回归测试的基准图像。当有意更改 UI 组件时，必须更新快照，以反映新的预期外观。

何时更新快照

在以下情况下更新快照：

  • 有意更改了组件样式
  • 添加了带有 story 的新 UI 组件
  • 修改了组件布局或结构
  • 设计系统更新影响了组件外观

在以下情况下不要更新快照：

  • 没有有意更改 UI
  • 视觉差异显示存在 Bug 或回归
  • 不确定外观为何发生变化

更新流程

步骤 1：运行测试以查看失败项
pnpm test:storybook

查看哪些快照测试失败。失败时会生成差异图像。

步骤 2：查看差异图像

差异图像保存在：

packages/keychain/__image_snapshots__/__diff_output__/

每张差异图像都显示：

  • 左侧：预期结果（基准）
  • 中间：突出显示的差异
  • 右侧：实际结果（当前）

继续之前，请确认这些更改是有意的。

步骤 3：更新快照
pnpm test:storybook:update

这会根据当前组件渲染结果重新生成所有快照图像。

步骤 4：检查更新后的快照

检查更新后的图像是否正确：

# List changed snapshot files
git status packages/*/__image_snapshots__/

# View specific changes (if you have an image viewer)
ls packages/keychain/__image_snapshots__/*.png
步骤 5：提交更新
git add packages/*/__image_snapshots__/
git commit -m "chore: update storybook snapshots"

快照位置

packages/keychain/__image_snapshots__/
├── components-*.png           # Component snapshots
├── __diff_output__/           # Diff images (not committed)
│   └── *-diff.png

常见场景

添加新组件
  1. 创建组件
  2. 在 packages/keychain/src/components/ 中添加 Storybook story
  3. 运行 pnpm test:storybook:update 以生成初始快照
  4. 提交组件和快照
主题／设计系统更新

当设计令牌或主题更改影响多个组件时：

# Update all snapshots at once
pnpm test:storybook:update

# Review all changes
git diff --stat packages/*/__image_snapshots__/

# Commit with descriptive message
git add packages/*/__image_snapshots__/
git commit -m "chore: update snapshots for design system changes"
CI 自动更新

CI 工作流（test.yml）可以自动更新快照并推送：

  • 在 PR 分支上运行时
  • 只有视觉差异导致测试失败时
  • 创建提交 "chore: update storybook snapshots"

这意味着，如果你推送了影响视觉效果的更改，CI 可能会自动将更新后的快照提交到你的 PR。

故障排除

测试超时

Storybook 必须能够启动：

# Kill any existing Storybook process
pkill -f storybook

# Ensure port 6006 is free
lsof -i :6006

# Try running Storybook manually first
pnpm storybook
快照不一致

如果本地和 CI 的快照不同：

  • 确保使用相同的 Node 版本（20.x）
  • 不同平台的字体渲染可能不同
  • CI 使用特定的 Docker 镜像来确保一致性
缺少依赖项
pnpm clean && pnpm i && pnpm build:deps

脚本辅助工具

此外还提供了一个辅助脚本：

./scripts/update-storybook-snapshot.sh

最佳实践

  1. 检查每处差异 — 不要盲目更新快照
  2. 小步提交 — 将快照更新单独放在一个提交中
  3. 提供描述性提交信息 — 如有重大更改，请说明更改内容
  4. 保持基准干净 — 不要提交差异图像（它们已被 gitignore 忽略）
  5. 确保 CI 一致性 — 如果本地通过但 CI 失败，请调查差异

评论

支持 Markdown