立即开始
Docs
Storybook Docs

视觉测试

可视化测试是测试组件最有效的方法。只需点击按钮，你就可以为 Storybook 中的每个故事截取快照，并将这些快照与基线（已知的最新“良好”快照）进行比较。这不仅允许你检查组件的外观，还可以检查 无需编写或维护任何测试代码 的大部分组件功能！

¥Visual tests are the most efficient way to test your components. With the click of a button you can take snapshots of every story in your Storybook and compare those snapshots to baselines — last known “good” snapshots. Not only does this allow you to check the appearance of your components, but they are also able to check a large subset of component functionality without having to write or maintain any test code!

Storybook 使用 Chromatic（Storybook 团队制作的云服务）原生支持跨浏览器视觉测试。当你启用可视化测试时，每个故事都会自动变成一个测试。这会直接在 Storybook 中为你提供有关 UI 错误的即时反馈。

¥Storybook supports cross-browser visual testing natively using Chromatic, a cloud service made by the Storybook team. When you enable visual testing, every story is automatically turned into a test. This gives you instant feedback on UI bugs directly in Storybook.

安装

¥Install the addon

通过安装 @chromatic-com/storybook（Storybook 维护者的官方插件）为你的项目添加视觉测试：

¥Add visual tests to your project by installing @chromatic-com/storybook, the official addon by Storybook maintainers:

npx storybook@latest add @chromatic-com/storybook

启用可视化测试

¥Enable visual tests

当你启动 Storybook 时，你将看到一个新的 Visual Tests 插件面板，你可以在其中运行测试并查看结果。

¥When you start Storybook, you'll see a new addon panel for Visual Tests where you can run tests and view results.

Visual Tests addon enabled

已经在使用 Vitest 插件 了吗？在展开的测试小部件中，你将看到一个可视化测试部分：

¥Already using the Vitest addon? In the expanded testing widget, you’ll now see a Visual tests section:

Expanded testing widget, showing the Visual tests section

点击底部的“运行测试”按钮将运行所有测试，包括组件测试和可视化测试。

¥Clicking the Run tests button at the bottom will run all tests, both component and visual.

首先，登录你的 Chromatic 账户。如果你没有账户，可以在登录过程中创建一个。

¥First, sign in to your Chromatic account. If you do not have an account, you can create one as part of the sign in process.

登录后，你将看到你的 Chromatic 账户及其项目。从列表中选择一个或创建一个新的。

¥Once signed in, you will see your Chromatic account(s) and their projects. Either select one from the list or create a new one.

Visual Tests addon project selection

现在你已将项目链接到插件，你可以点击“捕捉 UI 更改”按钮来运行你的第一个可视化测试版本。

¥Now that you have linked your project to the addon, you can press the “Catch a UI change” button to run your first build of visual tests.

Visual test panel showing the Catch a UI change button

首次构建将为你的故事创建基线快照，当你再次运行可视化测试时，将与这些快照进行比较。

¥That first build will create the baseline snapshots for your stories, which will be compared against when you run visual tests again.

运行可视化测试

¥Run visual tests

更改代码后，有两种方法可以在 Storybook 中运行可视化测试。

¥After you have made a code change, there are two ways to run visual tests in Storybook.

在侧边栏扩展测试小部件中，按下“可视化测试”部分中的“运行”按钮。

¥In the expanded testing widget in the sidebar, press the run button in the Visual tests section.

Test widget showing the Run visual tests button

或者，在 Visual tests 插件面板中，点击面板右上角的运行按钮。

¥Or, in the Visual tests addon panel, press the run button in the top right corner of the panel.

Visual tests addon panel showing the Run visual tests button

两种方法都会将你的故事发送到云端，以便拍摄快照并检测视觉变化。

¥Either method will send your stories to the cloud to take snapshots and detect visual changes.

审查变更

¥Review changes

如果你的故事中有视觉变化，它们将在侧边栏中高亮。单击故事并转到 Visual Tests 插件面板以查看哪些像素发生了变化。

¥If there are visual changes in your stories, they will be 🟡 highlighted in the sidebar. Click the story and go to the Visual Tests addon panel to see which pixels changed.

如果更改是故意的，✅ 在本地接受它们作为基线。如果更改并非有意为之，请修复故事并使用“重新运行”按钮重新运行测试。

¥If the changes are intentional, ✅ accept them as baselines locally. If the changes aren't intentional, fix the story and rerun the tests using the rerun button.

Visual test panel with diff

当你完成接受插件中的更改作为基线时，你就可以将代码推送到远程存储库了。这会将基线同步到云端，以供任何签出你的分支的人使用。

¥When you finish accepting changes as baselines in the addon, you're ready to push the code to your remote repository. This will sync baselines to the cloud for anyone who checks out your branch.

Visual test panel with accepted baselines

使用 CI 自动化

¥Automate with CI

插件设计为与 CI 一起使用。我们建议使用插件在开发过程中检查更改，然后在准备合并时在 CI 中运行可视化测试。

¥The addon is designed to be used in tandem with CI. We recommend using the addon to check for changes during development and then running visual tests in CI as you get ready to merge.

你在插件中接受为基线的更改将自动在 CI 中被接受为基线，因此你无需重复检查。

¥Changes you accept as baselines in the addon will get auto-accepted as baselines in CI so you don’t have to review twice.

  1. 在你的 CI 工作流程中添加一个步骤以运行 Chromatic。

    ¥Add a step to your CI workflow to run Chromatic.

  2. 配置你的 CI 以包含环境变量，以便使用 Chromatic（项目令牌）进行身份验证。

    ¥Configure your CI to include environment variables to authenticate with Chromatic (project token).

PR 检查

¥PR checks

在 CI 中成功设置 Chromatic 后，你的拉取/合并请求将带有 UI 测试检查标记。徽章会通知你需要团队验证的测试错误或 UI 更改。在你的 Git 提供程序中进行必要的检查，以防止意外的 UI 错误被合并。

¥Once you successfully set up Chromatic in CI, your pull/merge requests will be badged with a UI Tests check. The badge notifies you of test errors or UI changes that need to be verified by your team. Make the check required in your Git provider to prevent accidental UI bugs from being merged.

配置

¥Configure

插件默认包含涵盖大多数用例的配置选项。你还可以通过 ./chromatic.config.json 文件微调插件配置以满足项目需求。以下是插件特定选项的简短列表及其使用示例。查看完整的 options 列表。

¥The addon includes configuration options covering most use cases by default. You can also fine-tune the addon configuration to match your project's requirements via the ./chromatic.config.json file. Below is a shortlist of addon-specific options and examples of how to use them. View the full list of options.

选项描述
projectId自动配置。设置项目标识符
"projectId": "Project:64cbcde96f99841e8b007d75" 的值
buildScriptName可选。定义自定义 Storybook 构建脚本
"buildScriptName": "deploy-storybook"
debug可选。将详细的调试信息输出到控制台。
"debug": true
zip可选。推荐用于大型项目。配置插件，以便将 Storybook 以 zip 文件的形式部署到 Chromatic。
"zip": true
./chromatic.config.json
{
  "buildScriptName": "deploy-storybook",
  "debug": true,
  "projectId": "Project:64cbcde96f99841e8b007d75",
  "zip": true
}

FAQs

可视化测试和快照测试有什么区别？

¥What’s the difference between visual tests and snapshot tests?

快照测试 将每个故事的渲染标记与已知基线进行比较。这意味着测试比较 HTML 块，而不是用户实际看到的内容。这反过来会导致误报增加，因为代码更改并不总是会导致组件中的视觉变化。

¥Snapshot tests compare the rendered markup of every story against known baselines. This means the test compares blobs of HTML and not what the user actually sees. Which in turn, can lead to an increase in false positives as code changes don’t always yield visual changes in the component.

Visual Tests 将每个故事的渲染像素与已知基线进行比较。因为你正在测试用户实际体验的相同内容，所以你的测试将更加丰富且易于维护。

¥Visual tests compare the rendered pixels of every story against known baselines. Because you're testing the same thing your users actually experience, your tests will be richer and easier to maintain.

更多测试资源

¥More testing resources