Storybook 测试在 CI 中调试失败storybookUrl 配置与 SB_URL 环境变量实战指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇指南聚焦 Storybook 的 Vitest addon 在 CI 环境下的一处关键配置如何通过storybookUrl插件选项配合SB_URL环境变量让 CI 中失败的测试输出直接指向已发布的 Storybook 实例从而把看到报错升级为一键进入 Storybook 复现问题。读完本文你将掌握 Vitest 3 / Vitest 4 两种配置格式下的完整插件写法、CI 工作流中传递部署 URL 的方式以及从源码层面理解storybookUrl是如何被注入测试运行时并最终拼进失败信息的。问题背景CI 中为什么看不到可点击的调试链接Storybook 的 Vitest addonstorybook/addon-vitest在本地运行测试时每个失败用例的输出都会附带一条指向 Storybook 的调试链接。这个机制依赖一个前提有一个正在运行的 Storybook 可供跳转本地默认就是http://localhost:6006。但在 CI 中情况完全不同——CI 环境里并没有一个活跃运行的 Storybook 服务。如果什么都不配置失败信息里的链接就会指向一个不存在的本地地址调试价值大打折扣。解决方案分三步在 CI 中先构建并发布 Storybook例如发布到 Vercel、GitHub Pages 等平台把发布后的 URL 通过环境变量约定命名为SB_URL传给测试命令在 Vitest 插件配置中用storybookUrl: process.env.SB_URL把这个变量接进插件。下面完整继承官方片段中的两段配置并补充参数说明。配置一Vitest 4 的test.projects写法vitest.config.tsVitest 4 引入了内联projects配置多项目配置统一放在vitest.config.ts中。完整继承自 官方片段文档 的写法如下export default defineConfig({ // ... test: { // ... projects: [ { plugins: [ storybookTest({ // ... // Use the environment variable you passed storybookUrl: process.env.SB_URL, }), ], }, ], }, });要点说明storybookTest()是storybook/addon-vitest提供的 Vitest 插件工厂函数安装 Vitest addon 时生成的配置中已包含它storybookUrl是插件的用户选项类型为string语义是Storybook 的托管地址用于在测试失败时输出中生成 story 链接缺省值为http://localhost:6006见 选项类型定义用process.env.SB_URL而非硬编码 URL是为了让同一份配置在本地变量为空、回退默认值或显式设为本地地址与 CI注入发布地址之间无缝切换。配置二Vitest 3 的defineWorkspace写法vitest.workspace.ts如果你还在 Vitest 3多项目配置放在独立的 workspace 文件里写法如下同样完整继承自 官方片段文档export default defineWorkspace([ // ... { // ... { plugins: [ storybookTest({ // ... // Use the environment variable you passed storybookUrl: process.env.SB_URL, }), ], }, }, ]);两种格式的核心差异只是宿主 APIVitest 3 用defineWorkspace的数组描述项目Vitest 4 用test.projects内联在统一配置中插件选项本身包括storybookUrl完全一致。在 CI 工作流中传递 SB_URL光有插件配置还不够还需要 CI 把Storybook 发布到哪了这件事告诉测试命令。以 GitHub Actions 为例In CI 官方文档 给出的模式是利用部署平台发出的deployment_status事件——其中deployment_status.environment_url就是新生成的 Storybook 地址——在测试步骤中注入环境变量name: Storybook Tests # Update this to only run when a deployment status is emitted on: deployment_status - on: [push] jobs: test: runs-on: ubuntu-latest container: image: mcr.microsoft.com/playwright:v1.58.2-noble # Only run on successful deployments if: github.event_name deployment_status github.event.deployment_status.state success steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 22.12.0 - name: Install dependencies run: npm ci - name: Run tests run: npm run test-storybook # Pass the Storybook URL as an environment variable env: SB_URL: ${{ github.event.deployment_status.environment_url }}配合package.json中的测试脚本vitest --projectstorybook执行npm run test-storybook时SB_URL就已进入进程环境插件的process.env.SB_URL随即生效。其他 CI 平台GitLab、Circle CI、Azure Pipelines 等思路相同在测试步骤的环境变量区把发布 URL 赋给SB_URL具体事件字段名因平台而异。源码原理storybookUrl 如何变成失败信息里的链接从源码看storybookUrl的传播链路非常清晰共三站第一站插件解析选项并写入进程环境变量。在 插件入口 中storybookTest(options)先把用户选项与默认值合并默认值见 defaultOptions其中storybookUrl默认http://localhost:6006随后执行// To be accessed by the global setup file process.env.__STORYBOOK_URL__ finalOptions.storybookUrl; process.env.__STORYBOOK_SCRIPT__ finalOptions.storybookScript;即你传入的process.env.SB_URL在这里被固化成内部变量__STORYBOOK_URL__供后续 global setup 与 setup file 使用。第二站向测试运行时注入 env。插件生成测试项目配置时把该值再次放入test配置的env块相关代码env: { ...(await presets.apply(env, {})), // To be accessed by the setup file __STORYBOOK_URL__: finalOptions.storybookUrl, // ... },这使得浏览器端的测试代码可以通过import.meta.env.__STORYBOOK_URL__读到它。第三站失败信息改写。真正拼出链接的是 setup-file.ts 中的 modifyErrorMessage当某个测试任务状态为fail且带有storyId时它在错误信息最前面注入一行蓝色可点击提示const storybookUrl import.meta.env.__STORYBOOK_URL__; const storyUrl ${storybookUrl}/?path/story/${meta.storyId}addonPanel${COMPONENT_TESTING_PANEL_ID}; currentError.message \n\x1B[34mClick to debug the error directly in Storybook: ${storyUrl}\x1B[39m\n\n${currentError.message};注意链接尾部还带了addonPanel参数——它会把失败 story 直接定位到组件测试面板打开即可看到对应测试的执行结果与报错。这也解释了为什么 URL 必须指向一个已发布的 Storybook链接是真实可访问的 story 路径不是本地临时端口。配置完成后的效果与验证当 CI 测试失败时输出会包含指向已发布 Storybook 的调试链接点击即可在真实部署环境中复现该 story 的失败现场验证要点先确认SB_URL确实注入成功——在 CI 日志中检查测试步骤打印的失败链接域名是否为发布域名若链接仍指向localhost:6006说明环境变量未生效检查env块拼写与deployment_status事件是否触发若发布平台不发deployment_status事件可改为在构建 Storybook 的步骤中解析产物 URL 并export SB_URL...其余步骤不变。实践注意事项本地与 CI 的区分storybookUrl缺省为http://localhost:6006本地开发无需配置只在 CI 需要覆盖时通过SB_URL注入避免把某个环境 URL 硬编码进提交到仓库的配置文件中。配置格式随 Vitest 大版本而变升级 Vitest 4 时vitest.workspace.ts的多项目描述会迁移到vitest.config.ts的test.projects插件选项本身不需要改。与本地运行机制的差异在 watch 模式下插件可通过storybookScript选项自动拉起本地 Storybook见 选项类型定义中的 storybookScript 说明CI 的一次性运行中我们依赖的是已发布的实例因此storybookUrl指向发布地址即可。完整 CI 搭建流程定义test-storybook脚本、为 GitHub Actions / GitLab / Circle CI / Travis / Jenkins / Azure Pipelines 编写工作流、Playwright 镜像选择、代码覆盖率收集等请参阅 In CI 完整文档插件全量选项与 addon 的介绍见 Vitest addon 文档。小结storybookUrl: process.env.SB_URL是一行配置但它打通了CI 测试失败 → 已发布 Storybook 复现的完整调试闭环CI 事件提供发布 URL插件将其写入__STORYBOOK_URL__setup file 在失败时拼出带 story ID 与组件测试面板参数的链接。Vitest 3 用defineWorkspace、Vitest 4 用test.projects插件写法不变。按本文配置后团队成员在 CI 中遇到的每一个 UI 测试失败都能一键跳转进真实环境定位问题。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考