Storybook 启用可视化测试用storybook add一键安装 Chromatic 官方插件Storybook 官方在 Visual tests 指南 中提供了一套可视化测试Visual Testing接入方案安装由 Storybook 团队维护的官方插件chromatic-com/storybook即可把每个 story 自动变成基于像素的快照测试并在云端进行跨浏览器对比。本文围绕仓库中嵌入该方案的安装片段 docs/_snippets/chromatic-storybook-add.md讲解它在 npm、pnpm、yarn 三种包管理器下的标准写法并深入 CLI 源码剖析storybook add到底做了什么以及安装后如何启用面板、接入 CI、做基线配置让你能直接在自己的 Storybook 项目中落地可视化测试流程。这个片段在文档体系中扮演的角色该片段本身是 Storybook 文档站点里被多处复用的可执行代码片段CodeSnippets它被正式引用在 docs/writing-tests/visual-testing.mdx 的Install the addon小节中。因此从仓库文档结构看storybook add chromatic-com/storybook就是 Storybook 官方推荐的可视化测试起步命令——它不是一条普通的npm install而是会连同插件注册一起处理的自动安装入口。它的使用场景非常明确你的项目已经初始化了 Storybook无论 Webpack 还是 Vite 构建器、无论 React/Vue/Angular 等哪种渲染器现在希望以最小的手工操作获得可视化回归测试能力。执行这一条命令后插件会被写入 devDependencies并自动登记到 Storybook 的addons配置中随后你在启动的 Storybook 界面里就能看到新增的 Visual Tests 面板。三种包管理器下的安装命令仓库片段 docs/_snippets/chromatic-storybook-add.md 给出了覆盖 npm、pnpm、yarn 的统一写法npmnpx storybooklatest add chromatic-com/storybookpnpmpnpm dlx storybooklatest add chromatic-com/storybookyarnyarn dlx storybooklatest add chromatic-com/storybook三条命令在语义上等价只是借助各自包管理器自带的远程执行工具npx/dlx拉取并运行 CLI包管理器命令说明npmnpx storybooklatest add ...npm 5.2 自带npxpnpmpnpm dlx storybooklatest add ...dlx即 pnpm 的 npx 等价物yarnyarn dlx storybooklatest add ...适用于 Yarn Berry2.x两点值得注意的细节命令中的storybooklatest明确要求从 registry 临时获取最新版 CLI 再执行而非使用本地已安装的storybook二进制这正是dlx/npx的设计初衷——把包拉取到临时环境运行。仓库中 add.ts 的PostinstallOptions注释也印证了dlx/npx这种ephemeral environment取包模式。如果你想同时传入多个插件例如storybook add chromatic-com/storybook another-addon目前只会安装第一个指定的插件。这一限制被明确记录在 自动安装 addon 文档 的警告块中官方称会在未来版本修复。storybook add命令的实际执行流程为什么不直接npm install chromatic-com/storybook因为add子命令要做的远不止装包。以当前仓库中该命令的实现 code/lib/cli-storybook/src/add.ts 为据它按顺序完成以下工作解析插件名与版本号通过getVersionSpecifier把输入拆成包名与可选版本。它同时支持指定版本例如storybook add storybook/addon-docs7.0.1版本号会拼在之后见 add.ts。定位 Storybook 配置读取你的.storybook/main配置文件与 preview 配置如果找不到配置目录会直接报错并提示可用--config-dir标志指定如果找不到main.js|ts则终止。查重与确认如果目标插件已经存在于addons数组中checkInstalledCLI 会提示是否仍然要安装一次由用户确认传入--yes可跳过交互直接执行。决定安装版本源码通过isCoreAddon判断插件包是否在 Storybook 内置的版本清单versions中——若属于 Storybook 核心插件且未指定版本则自动对齐你当前 Storybook 的安装版本否则chromatic-com/storybook属于 Chromatic 生态而非 Storybook 核心包故落入此分支会去 npm registry 查询该包的最新版本。若检测到核心插件版本与当前 Storybook 版本不一致还会打印警告。安装依赖以 devDependencies 的形式安装并依据解析结果自动带上版本范围如^前缀。这正是 CLI 内部对packageManager.addDependencies的调用所完成的工作。自动注册通过setupAddonInConfig把插件写入配置文件里的addons字段等价于手动往.storybook/main.js|ts中追加一条随后即可在 Storybook 中生效。手动方式的完整等价操作示例见 install-addons 文档 与 addons 配置字段说明。触发安装后钩子对 Storybook 核心插件安装完成后还会运行postinstallAddon处理那些需要额外配置的插件的后续动作。也就是说你执行一次storybook add chromatic-com/storybookCLI 在同一轮内替你完成了确定版本、安装为 devDependencies、登记进 addons 配置三步。命令对应的单元测试可参考 code/lib/cli-storybook/src/add.test.ts其中覆盖了版本解析、重复安装询问等分支行为。除可视化测试外同一机制也用于安装其他官方/社区插件如storybook/addon-a11y、storybook/addon-mcp、storybook/addon-vitest等可对比仓库中其他安装片段例如 addon-a11y 安装片段印证。安装完成后启用并连接你的项目插件安装并注册完成后重启 Storybooknpm run storybook或你项目配置的开发脚本侧边栏/工具栏就会出现新的Visual Tests面板。启用流程分三步登录 Chromatic 账户在插件面板中完成登录。如果没有账户可在登录流程中一并创建。选择或创建项目登录后面板会列出你的 Chromatic 账户及关联项目选择一个既有项目或新建一个。首次构建基线点击Catch a UI change按钮执行第一次可视化测试构建。这一次构建会为你的每个 story 生成基线快照baseline后续再次运行测试时云端会将新快照与基线对比从而找出像素级差异。之后每次改动代码可以通过扩展后的测试小组件或插件面板右上角的运行按钮再次把 stories 发送到云端截图并检测视觉变化。如果检测到 高亮的变更可在面板中核对具体差异像素变化符合预期就本地接受为新的基线不符合就修复后重跑。接受的基线会与远程同步供检出新分支的团队成员复用——这就是接受一次CI 不重复审核的设计基础详见 docs/writing-tests/visual-testing.mdx。把可视化测试自动化进 CIGitHub Actions插件面板适合开发期即时检查而合并前的最终把关则推荐放进 CI。仓库提供了配套的 GitHub Actions 工作流模板见 docs/_snippets/chromatic-github-action.md核心内容如下# Workflow name name: Chromatic Publish # Event for the workflow on: push # List of jobs jobs: test: # Operating System runs-on: ubuntu-latest # Job steps steps: - uses: actions/checkoutv6 with: fetch-depth: 0 - uses: actions/setup-nodev6 with: node-version: 24 cache: yarn - run: yarn # Adds Chromatic as a step in the workflow - uses: chromaui/actionlatest # Options required for Chromatics GitHub Action with: # Chromatic projectToken, projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }} token: ${{ secrets.GITHUB_TOKEN }}工作流要点fetch-depth: 0完整克隆历史便于 Chromatic 定位到正确的基线提交做差异比较projectToken通过仓库 SecretCHROMATIC_PROJECT_TOKEN提供用于向 Chromatic 鉴权。如果没有通过storybook add关联过 CLI/CI 项目需先用 chromatic-install 片段 中的方式安装chromatic命令行包并完成 token 配置token传入GITHUB_TOKEN让 Chromatic 能把检查结果UI Tests 徽章回写到你的 PR 上。配置成功后你的 Pull Request / Merge Request 会带上 UI Tests 状态徽章用于提示团队存在未验证的 UI 变更或测试错误。你还可以在 Git 平台把该检查设为 required从流程上阻止意外的 UI 缺陷被合并进主干。可选的精细化配置chromatic.config.json插件与 Chromatic CLI 共用项目根目录下的chromatic.config.json做精细化配置覆盖大多数场景时保持默认即可。Visual tests 文档列出的常用选项如下选项说明与示例projectId自动配置。项目标识符形如projectId: Project:64cbcde96f99841e8b007d75buildScriptName可选。自定义 Storybook 构建脚本名如buildScriptName: deploy-storybookdebug可选。向控制台输出详细调试信息如debug: truezip可选。大项目推荐启用以 zip 压缩包形式把 Storybook 部署到 Chromatic如zip: true组合示例{ buildScriptName: deploy-storybook, debug: true, projectId: Project:64cbcde96f99841e8b007d75, zip: true }需要说明的是storybook add在项目关联后会自动写入并维护projectId通常无需手工编辑buildScriptName、zip等则适合在插件注册完成、接入 CI 时按项目规模调整。与快照测试的差异及更多相关文档Visual tests 与常见的快照测试snapshot tests本质不同快照测试比较每个 story 渲染产物的 HTML 标记与基线改动代码不一定产生可见变化因此容易出现误报而可视化测试比较每个 story 实际渲染出的像素与基线测试的是用户真实看到的东西更贴近真实体验、也更易维护。这也是 Chromatic 方案在组件回归把关上的核心价值所在。围绕可视化测试及与其配合的测试体系可继续查阅仓库内下列文档Visual tests 完整指南安装、启用、运行、评审变更到 CI、PR 检查的端到端流程安装 addon 通用指南storybook add的适用边界与手动安装、移除 addon 的方法CLI 选项参考add子命令及--config-dir、--yes、--skip-install等配套参数main 配置 addons 字段addons 数组支持字符串与对象两种登记形式的语法细节快照测试指南与可视化测试互补的 HTML 级回归手段。按上述步骤完成storybook add chromatic-com/storybook之后你的项目便具备了开发期面板即时检查 合并前 CI 自动巡检的双层可视化回归能力UI 变更在进入主干前都能得到像素级审查。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Storybook 启用可视化测试：用 `storybook add` 一键安装 Chromatic 官方插件
Storybook 启用可视化测试用storybook add一键安装 Chromatic 官方插件Storybook 官方在 Visual tests 指南 中提供了一套可视化测试Visual Testing接入方案安装由 Storybook 团队维护的官方插件chromatic-com/storybook即可把每个 story 自动变成基于像素的快照测试并在云端进行跨浏览器对比。本文围绕仓库中嵌入该方案的安装片段 docs/_snippets/chromatic-storybook-add.md讲解它在 npm、pnpm、yarn 三种包管理器下的标准写法并深入 CLI 源码剖析storybook add到底做了什么以及安装后如何启用面板、接入 CI、做基线配置让你能直接在自己的 Storybook 项目中落地可视化测试流程。这个片段在文档体系中扮演的角色该片段本身是 Storybook 文档站点里被多处复用的可执行代码片段CodeSnippets它被正式引用在 docs/writing-tests/visual-testing.mdx 的Install the addon小节中。因此从仓库文档结构看storybook add chromatic-com/storybook就是 Storybook 官方推荐的可视化测试起步命令——它不是一条普通的npm install而是会连同插件注册一起处理的自动安装入口。它的使用场景非常明确你的项目已经初始化了 Storybook无论 Webpack 还是 Vite 构建器、无论 React/Vue/Angular 等哪种渲染器现在希望以最小的手工操作获得可视化回归测试能力。执行这一条命令后插件会被写入 devDependencies并自动登记到 Storybook 的addons配置中随后你在启动的 Storybook 界面里就能看到新增的 Visual Tests 面板。三种包管理器下的安装命令仓库片段 docs/_snippets/chromatic-storybook-add.md 给出了覆盖 npm、pnpm、yarn 的统一写法npmnpx storybooklatest add chromatic-com/storybookpnpmpnpm dlx storybooklatest add chromatic-com/storybookyarnyarn dlx storybooklatest add chromatic-com/storybook三条命令在语义上等价只是借助各自包管理器自带的远程执行工具npx/dlx拉取并运行 CLI包管理器命令说明npmnpx storybooklatest add ...npm 5.2 自带npxpnpmpnpm dlx storybooklatest add ...dlx即 pnpm 的 npx 等价物yarnyarn dlx storybooklatest add ...适用于 Yarn Berry2.x两点值得注意的细节命令中的storybooklatest明确要求从 registry 临时获取最新版 CLI 再执行而非使用本地已安装的storybook二进制这正是dlx/npx的设计初衷——把包拉取到临时环境运行。仓库中 add.ts 的PostinstallOptions注释也印证了dlx/npx这种ephemeral environment取包模式。如果你想同时传入多个插件例如storybook add chromatic-com/storybook another-addon目前只会安装第一个指定的插件。这一限制被明确记录在 自动安装 addon 文档 的警告块中官方称会在未来版本修复。storybook add命令的实际执行流程为什么不直接npm install chromatic-com/storybook因为add子命令要做的远不止装包。以当前仓库中该命令的实现 code/lib/cli-storybook/src/add.ts 为据它按顺序完成以下工作解析插件名与版本号通过getVersionSpecifier把输入拆成包名与可选版本。它同时支持指定版本例如storybook add storybook/addon-docs7.0.1版本号会拼在之后见 add.ts。定位 Storybook 配置读取你的.storybook/main配置文件与 preview 配置如果找不到配置目录会直接报错并提示可用--config-dir标志指定如果找不到main.js|ts则终止。查重与确认如果目标插件已经存在于addons数组中checkInstalledCLI 会提示是否仍然要安装一次由用户确认传入--yes可跳过交互直接执行。决定安装版本源码通过isCoreAddon判断插件包是否在 Storybook 内置的版本清单versions中——若属于 Storybook 核心插件且未指定版本则自动对齐你当前 Storybook 的安装版本否则chromatic-com/storybook属于 Chromatic 生态而非 Storybook 核心包故落入此分支会去 npm registry 查询该包的最新版本。若检测到核心插件版本与当前 Storybook 版本不一致还会打印警告。安装依赖以 devDependencies 的形式安装并依据解析结果自动带上版本范围如^前缀。这正是 CLI 内部对packageManager.addDependencies的调用所完成的工作。自动注册通过setupAddonInConfig把插件写入配置文件里的addons字段等价于手动往.storybook/main.js|ts中追加一条随后即可在 Storybook 中生效。手动方式的完整等价操作示例见 install-addons 文档 与 addons 配置字段说明。触发安装后钩子对 Storybook 核心插件安装完成后还会运行postinstallAddon处理那些需要额外配置的插件的后续动作。也就是说你执行一次storybook add chromatic-com/storybookCLI 在同一轮内替你完成了确定版本、安装为 devDependencies、登记进 addons 配置三步。命令对应的单元测试可参考 code/lib/cli-storybook/src/add.test.ts其中覆盖了版本解析、重复安装询问等分支行为。除可视化测试外同一机制也用于安装其他官方/社区插件如storybook/addon-a11y、storybook/addon-mcp、storybook/addon-vitest等可对比仓库中其他安装片段例如 addon-a11y 安装片段印证。安装完成后启用并连接你的项目插件安装并注册完成后重启 Storybooknpm run storybook或你项目配置的开发脚本侧边栏/工具栏就会出现新的Visual Tests面板。启用流程分三步登录 Chromatic 账户在插件面板中完成登录。如果没有账户可在登录流程中一并创建。选择或创建项目登录后面板会列出你的 Chromatic 账户及关联项目选择一个既有项目或新建一个。首次构建基线点击Catch a UI change按钮执行第一次可视化测试构建。这一次构建会为你的每个 story 生成基线快照baseline后续再次运行测试时云端会将新快照与基线对比从而找出像素级差异。之后每次改动代码可以通过扩展后的测试小组件或插件面板右上角的运行按钮再次把 stories 发送到云端截图并检测视觉变化。如果检测到 高亮的变更可在面板中核对具体差异像素变化符合预期就本地接受为新的基线不符合就修复后重跑。接受的基线会与远程同步供检出新分支的团队成员复用——这就是接受一次CI 不重复审核的设计基础详见 docs/writing-tests/visual-testing.mdx。把可视化测试自动化进 CIGitHub Actions插件面板适合开发期即时检查而合并前的最终把关则推荐放进 CI。仓库提供了配套的 GitHub Actions 工作流模板见 docs/_snippets/chromatic-github-action.md核心内容如下# Workflow name name: Chromatic Publish # Event for the workflow on: push # List of jobs jobs: test: # Operating System runs-on: ubuntu-latest # Job steps steps: - uses: actions/checkoutv6 with: fetch-depth: 0 - uses: actions/setup-nodev6 with: node-version: 24 cache: yarn - run: yarn # Adds Chromatic as a step in the workflow - uses: chromaui/actionlatest # Options required for Chromatics GitHub Action with: # Chromatic projectToken, projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }} token: ${{ secrets.GITHUB_TOKEN }}工作流要点fetch-depth: 0完整克隆历史便于 Chromatic 定位到正确的基线提交做差异比较projectToken通过仓库 SecretCHROMATIC_PROJECT_TOKEN提供用于向 Chromatic 鉴权。如果没有通过storybook add关联过 CLI/CI 项目需先用 chromatic-install 片段 中的方式安装chromatic命令行包并完成 token 配置token传入GITHUB_TOKEN让 Chromatic 能把检查结果UI Tests 徽章回写到你的 PR 上。配置成功后你的 Pull Request / Merge Request 会带上 UI Tests 状态徽章用于提示团队存在未验证的 UI 变更或测试错误。你还可以在 Git 平台把该检查设为 required从流程上阻止意外的 UI 缺陷被合并进主干。可选的精细化配置chromatic.config.json插件与 Chromatic CLI 共用项目根目录下的chromatic.config.json做精细化配置覆盖大多数场景时保持默认即可。Visual tests 文档列出的常用选项如下选项说明与示例projectId自动配置。项目标识符形如projectId: Project:64cbcde96f99841e8b007d75buildScriptName可选。自定义 Storybook 构建脚本名如buildScriptName: deploy-storybookdebug可选。向控制台输出详细调试信息如debug: truezip可选。大项目推荐启用以 zip 压缩包形式把 Storybook 部署到 Chromatic如zip: true组合示例{ buildScriptName: deploy-storybook, debug: true, projectId: Project:64cbcde96f99841e8b007d75, zip: true }需要说明的是storybook add在项目关联后会自动写入并维护projectId通常无需手工编辑buildScriptName、zip等则适合在插件注册完成、接入 CI 时按项目规模调整。与快照测试的差异及更多相关文档Visual tests 与常见的快照测试snapshot tests本质不同快照测试比较每个 story 渲染产物的 HTML 标记与基线改动代码不一定产生可见变化因此容易出现误报而可视化测试比较每个 story 实际渲染出的像素与基线测试的是用户真实看到的东西更贴近真实体验、也更易维护。这也是 Chromatic 方案在组件回归把关上的核心价值所在。围绕可视化测试及与其配合的测试体系可继续查阅仓库内下列文档Visual tests 完整指南安装、启用、运行、评审变更到 CI、PR 检查的端到端流程安装 addon 通用指南storybook add的适用边界与手动安装、移除 addon 的方法CLI 选项参考add子命令及--config-dir、--yes、--skip-install等配套参数main 配置 addons 字段addons 数组支持字符串与对象两种登记形式的语法细节快照测试指南与可视化测试互补的 HTML 级回归手段。按上述步骤完成storybook add chromatic-com/storybook之后你的项目便具备了开发期面板即时检查 合并前 CI 自动巡检的双层可视化回归能力UI 变更在进入主干前都能得到像素级审查。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考