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/

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

添加新组件

Create the component
Add a Storybook story in
```
packages/keychain/src/components/
```
Run
```
pnpm test:storybook:update
```
to generate initial snapshot
Commit both the component and snapshot

创建组件
在
```
packages/keychain/src/components/
```
中添加Storybook story
运行
```
pnpm test:storybook:update
```
生成初始快照
同时提交组件和快照

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

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"

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

Ensure port 6006 is free

确保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

最佳实践

Review every diff - Don't blindly update snapshots
Small commits - Update snapshots in their own commit
Descriptive messages - Mention what changed if significant
Clean baseline - Don't commit diff images (they're gitignored)
CI consistency - If local passes but CI fails, investigate the difference

检查每一处差异 - 不要盲目更新快照
小提交 - 将快照更新单独提交
描述性提交信息 - 如果变更重大，说明具体变更内容
干净的基准 - 不要提交差异图像（它们已被git忽略）
CI一致性 - 如果本地测试通过但CI失败，调查差异原因