Back to Details

update-storybook-snapshots

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Update Storybook Snapshots

更新Storybook快照

Overview

概述

Storybook snapshots are baseline images used for visual regression testing. When UI components change intentionally, snapshots must be updated to reflect the new expected appearance.
Storybook快照是用于视觉回归测试的基准图像。当UI组件被有意修改后，必须更新快照以反映新的预期外观。

When to Update Snapshots

何时更新快照

Update snapshots when:
  • You intentionally changed component styling
  • You added new UI components with stories
  • You modified component layout or structure
  • Design system updates affected component appearance
Do NOT update snapshots when:
  • You didn't intentionally change the UI
  • The visual diff shows a bug or regression
  • You're unsure why the appearance changed
在以下情况时更新快照：
  • 你有意修改了组件样式
  • 你添加了带有stories的新UI组件
  • 你修改了组件的布局或结构
  • 设计系统更新影响了组件外观
不要在以下情况更新快照：
  • 你并未有意修改UI
  • 视觉差异图显示存在bug或回归问题
  • 你不确定外观变化的原因

Update Process

更新流程

Step 1: Run Tests to See Failures

步骤1：运行测试查看失败情况

bash
pnpm test:storybook
Review which snapshots failed. Failures generate diff images.
bash
pnpm test:storybook
查看哪些快照测试失败。失败会生成差异图像。

Step 2: Review Diff Images

步骤2：查看差异图像

Diff images are saved to:
packages/keychain/__image_snapshots__/__diff_output__/
Each diff image shows:
  • Left: Expected (baseline)
  • Center: Difference highlighted
  • Right: Actual (current)
Verify the changes are intentional before proceeding.
差异图像会保存到：
packages/keychain/__image_snapshots__/__diff_output__/
每张差异图像展示：
  • 左侧：预期（基准）图像
  • 中间：高亮显示的差异部分
  • 右侧：实际（当前）图像
在继续操作前，确认所有变化都是有意为之的。

Step 3: Update Snapshots

步骤3：更新快照

bash
pnpm test:storybook:update
This regenerates all snapshot images based on current component rendering.
bash
pnpm test:storybook:update
该命令会基于当前组件渲染结果重新生成所有快照图像。

Step 4: Review Updated Snapshots

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

Check the updated images look correct:
bash
undefined
确认更新后的图像显示正确：
bash
undefined

List changed snapshot files

列出已修改的快照文件

git status packages/*/image_snapshots/
git status packages/*/image_snapshots/

View specific changes (if you have an image viewer)

查看具体变化（如果有图片查看器）

ls packages/keychain/image_snapshots/*.png
undefined
ls packages/keychain/image_snapshots/*.png
undefined

Step 5: Commit the Updates

步骤5：提交更新

bash
git add packages/*/__image_snapshots__/
git commit -m "chore: update storybook snapshots"
bash
git add packages/*/__image_snapshots__/
git commit -m "chore: update storybook snapshots"

Snapshot Locations

快照存储位置

packages/keychain/__image_snapshots__/
├── components-*.png           # Component snapshots
├── __diff_output__/           # Diff images (not committed)
│   └── *-diff.png
packages/keychain/__image_snapshots__/
├── components-*.png           # 组件快照
├── __diff_output__/           # 差异图像（不会被提交）
│   └── *-diff.png

Common Scenarios

常见场景

New Component Added

添加新组件

  1. Create the component
  2. Add a Storybook story in 
    packages/keychain/src/components/
  3. Run 
    pnpm test:storybook:update
    to generate initial snapshot
  4. Commit both the component and snapshot
  1. 创建组件
  2. 在
    packages/keychain/src/components/
    中添加Storybook story
  3. 运行
    pnpm test:storybook:update
    生成初始快照
  4. 同时提交组件和快照

Theme/Design System Update

主题/设计系统更新

When design tokens or theme changes affect multiple components:
bash
undefined
当设计令牌或主题变更影响多个组件时：
bash
undefined

Update all snapshots at once

一次性更新所有快照

pnpm test:storybook:update
pnpm test:storybook:update

Review all changes

查看所有变更

git diff --stat packages/*/image_snapshots/
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"
undefined
git add packages/*/image_snapshots/ git commit -m "chore: update snapshots for design system changes"
undefined

CI Auto-Updates

CI自动更新

The CI workflow (
test.yml
) can auto-update snapshots and push:
  • If running on a PR branch
  • If the only failures are visual differences
  • Creates commit "chore: update storybook snapshots"
This means if you push changes that affect visuals, CI may auto-commit updated snapshots to your PR.
CI工作流（
test.yml
）可以自动更新快照并推送：
  • 如果在PR分支上运行
  • 如果仅存在视觉差异导致的失败
  • 会创建提交信息为"chore: update storybook snapshots"的提交
这意味着如果你推送了影响视觉效果的变更，CI可能会自动将更新后的快照提交到你的PR中。

Troubleshooting

故障排除

Tests timeout

测试超时

Storybook must be able to start:
bash
undefined
确保Storybook能够正常启动：
bash
undefined

Kill any existing Storybook process

终止所有已运行的Storybook进程

pkill -f storybook
pkill -f storybook

Ensure port 6006 is free

确保6006端口未被占用

lsof -i :6006
lsof -i :6006

Try running Storybook manually first

先尝试手动运行Storybook

pnpm storybook
undefined
pnpm storybook
undefined

Inconsistent snapshots

快照不一致

If snapshots differ between local and CI:
  • Ensure you're using the same Node version (20.x)
  • Font rendering can differ between platforms
  • CI uses a specific Docker image for consistency
如果本地和CI环境的快照存在差异：
  • 确保使用相同的Node版本（20.x）
  • 不同平台的字体渲染可能存在差异
  • CI使用特定的Docker镜像以保证一致性

Missing dependencies

依赖缺失

bash
pnpm clean && pnpm i && pnpm build:deps
bash
pnpm clean && pnpm i && pnpm build:deps

Script Helper

辅助脚本

There's also a helper script available:
bash
./scripts/update-storybook-snapshot.sh
还有一个辅助脚本可用：
bash
./scripts/update-storybook-snapshot.sh

Best Practices

最佳实践

  1. Review every diff - Don't blindly update snapshots
  2. Small commits - Update snapshots in their own commit
  3. Descriptive messages - Mention what changed if significant
  4. Clean baseline - Don't commit diff images (they're gitignored)
  5. CI consistency - If local passes but CI fails, investigate the difference
  1. 检查每一处差异 - 不要盲目更新快照
  2. 小提交 - 将快照更新单独提交
  3. 描述性提交信息 - 如果变更重大，说明具体变更内容
  4. 干净的基准 - 不要提交差异图像（它们已被git忽略）
  5. CI一致性 - 如果本地测试通过但CI失败，调查差异原因