Storybook Test Runner 本地构建 CI 工作流实战在 GitHub Actions 中构建、服务并运行组件测试【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook Test Runner 能够把项目中的每一个 Story 转化为可执行的测试对于没有 play function 的 Story它验证组件能否无错误渲染对于带有 play function 的 Story它还会执行交互并校验断言结果。本文聚焦官方文档提供的“本地构建工作流”——在 CI以 GitHub Actions 为例中先构建 Storybook 静态产物再用静态服务器托管最后对构建产物运行 Test Runner。读完本文你将掌握这套工作流的完整 YAML 配置、每个步骤的底层原理以及它与“针对已部署 Storybook 测试”方案的取舍。为什么需要“本地构建”式的工作流Storybook 的 Test Runner 是一个独立于 Storybook 框架运行的测试工具它需要在测试执行时访问一个正在运行的 Storybook 实例——无论是本地开发服务器还是已经部署到公网的静态站点。官方文档明确指出Test Runner 要求本地运行中的 Storybook 或已发布的 Storybook 才能执行全部已有测试。在 CI 环境中最常见的两种接入方式针对已部署的 Storybook 测试依赖 Vercel、Netlify 等平台触发 GitHub Actions 的deployment_status事件将部署 URL 通过TARGET_URL环境变量传给 Test Runner针对本地构建产物测试本文主题不依赖任何部署平台在 CI 内完成build-storybook构建 →http-server静态服务 →wait-on端口探测 →test-storybook执行测试的全流程。第二种方式尤其适合以下场景Storybook 需要认证才能访问、团队希望测试与部署解耦或者 CI 中根本没有接部署平台。官方文档也建议当已发布的 Storybook 需要认证时优先采用“非部署式”的本地构建方案。核心工作流完整配置与逐行解析官方在 test-runner-local-build-workflow.md 中给出了推荐配方该片段被主文档 test-runner.mdx 引用。它将构建、服务、测试三个环节用concurrently组织在一个任务中通过-k保证测试结束成功或失败后自动终止静态服务器避免 CI 任务悬挂。完整配置如下name: Storybook Tests on: push jobs: test: timeout-minutes: 60 runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version-file: .nvmrc - name: Install dependencies run: yarn - name: Install Playwright run: npx playwright install --with-deps - name: Build Storybook run: yarn build-storybook --quiet - name: Serve Storybook and run tests run: | npx concurrently -k -s first -n SB,TEST -c magenta,blue \ npx http-server storybook-static --port 6006 --silent \ npx wait-on tcp:127.0.0.1:6006 yarn test-storybook触发器与任务级配置on: push任意分支的推送都会触发测试。如果希望只在主分支或 pull request 上运行可以替换为on: [push, pull_request]或配合branches限定范围。timeout-minutes: 60整个 Job 的硬性超时时间。首次构建依赖、下载 Playwright 浏览器二进制、构建 Storybook 并跑完测试通常需要数分钟到十几分钟60 分钟是文档提供的安全默认值若项目 Storybook 较大或 Story 数量多可适当调大。runs-on: ubuntu-latestTest Runner 底层基于 Playwright需要 Linux 环境来运行浏览器其他 CI 供应商GitLab Pipelines、CircleCI 等可以参照 Playwright 的 CI 文档选择基础镜像。环境准备步骤actions/checkoutv4拉取仓库代码。actions/setup-nodev4node-version-file: .nvmrc从仓库根目录的.nvmrc文件读取 Node.js 版本。如果你的项目没有.nvmrc可以改用node-version: 20这类写法。yarn安装依赖。官方文档给出的配方默认使用 Yarn实际项目中完全可以用npm ci或pnpm install --frozen-lockfile替代保持与本地开发一致的包管理器即可。npx playwright install --with-deps安装 Playwright 浏览器二进制及系统级依赖。--with-deps会在 ubuntu 镜像中额外安装浏览器运行所需的系统库这是 CI 上避免“浏览器启动失败”的关键一步。构建 Storybook 静态产物yarn build-storybook --quietbuild-storybook对应storybook/cli提供的构建命令将项目构建为纯静态 Web 应用。--quiet减少构建日志输出避免 CI 日志过长。官方文档特别提醒默认情况下 Storybook 将构建产物输出到storybook-static目录。如果项目通过main.js/main.ts中的配置改动了输出目录例如自定义outputDir必须同步调整下方http-server的静态目录参数。仓库内 test-storybooks/mcp/package.json 中即可看到真实的脚本示例build-storybook: storybook build其配套的 MCP 测试tests/mcp-endpoint.e2e.test.ts同样遵循“构建 → 服务 → 测试”的模式。并行服务与测试concurrently http-server wait-onnpx concurrently -k -s first -n SB,TEST -c magenta,blue \ npx http-server storybook-static --port 6006 --silent \ npx wait-on tcp:127.0.0.1:6006 yarn test-storybook这是整套工作流中最核心也最容易出问题的一行三个第三方工具各司其职工具作用关键参数说明concurrently同时启动多个命令并统一转发输出-kkill others任一命令退出时终止其余命令-s firstsuccess first以第一个成功退出的命令的结果作为整体退出码-n SB,TEST为两个命令命名-c magenta,blue设置前缀颜色便于区分日志http-server零配置静态文件服务器storybook-static为构建产物目录--port 6006与 Test Runner 默认期望的本地端口一致--silent抑制请求日志wait-on轮询等待某个资源就绪tcp:127.0.0.1:6006表示等待本机 6006 端口可连接避免测试命令在服务器尚未监听时抢先执行而失败整条链路的执行语义是concurrently同时拉起“静态服务器”与“等待端口 运行测试”两条命令wait-on探测到 6006 端口可访问后test-storybook才开始运行测试跑完无论通过与否-k会立刻杀掉仍在监听的http-server配合-s first将测试的退出码传递给 CI从而让 GitHub Actions 正确标记构建的成败状态。关于端口Test Runner 默认假设本地 Storybook 运行在6006端口所以配方中http-server显式指定--port 6006正是为了与默认行为对齐若你通过--url指定了其他端口这里也需保持一致。前置配置安装与本地脚本在把工作流搬上 CI 之前需要先在项目中完成 Test Runner 的安装与脚本配置详见 test-runner.mdx# npm npm install storybook/test-runner --save-dev # 或 pnpm pnpm add --save-dev storybook/test-runner # 或 yarn yarn add --dev storybook/test-runner在package.json中注册脚本{ scripts: { test-storybook: test-storybook } }本地开发时先启动 Storybook 开发服务器默认 6006 端口再开一个新终端执行yarn test-storybook或npm run test-storybook/pnpm run test-storybook即可运行测试。这套本地流程与 CI 工作流是同一套测试逻辑CI 中只是把“开发服务器”替换成了“构建产物 http-server”。备选方案针对已部署 Storybook 的 deployment_status 工作流官方文档在“Run against deployed Storybooks”一节给出了另一份配方test-runner-with-deploy-event-workflow.md与本地构建方案形成互补name: Storybook Tests on: deployment_status jobs: test: timeout-minutes: 60 runs-on: ubuntu-latest if: github.event.deployment_status.state success steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version-file: .nvmrc - name: Install dependencies run: yarn - name: Install Playwright run: npx playwright install --with-deps - name: Run Storybook tests run: yarn test-storybook env: TARGET_URL: ${{ github.event.deployment_status.target_url }}两种方案的关键差异部署方案由 Vercel、Netlify 等平台触发deployment_status事件if: github.event.deployment_status.state success保证只在部署成功后执行测试并通过TARGET_URL环境变量把部署地址传给 Test Runner前提是已发布的 Storybook 必须可公开访问若需要认证则建议改用本地构建方案。本地构建方案不依赖外部部署平台直接在 CI 内构建、服务、测试产物无需公网可达。运行测试时--url参数与TARGET_URL环境变量是等效的两种指定目标地址的方式test-runner-execute-with-url.md# 方式一--url 参数 yarn test-storybook --url https://the-storybook-url-here.com # 方式二TARGET_URL 环境变量 TARGET_URLhttps://the-storybook-url-here.com yarn test-storybook常用 CLI 参数与排查要点Test Runner 基于 Jest 构建接受其部分 CLI 参数。以下是高频使用的选项完整清单见 test-runner.mdx参数用途示例--url指定测试目标 URL默认本地 6006test-storybook --url http://localhost:6007--maxWorkers限制并行 worker 数适合内存受限的 CItest-storybook --maxWorkers2--watch/--watchAll监听模式仅本地开发使用test-storybook --watch--coverage配合storybook/addon-coverage生成覆盖率test-storybook --coverage--failOnConsole浏览器出现 console 错误即判定失败test-storybook --failOnConsole--index-json基于index.json静态索引运行不支持 watchtest-storybook --index-json--eject生成test-runner-jest.config.js便于深度定制test-storybook --eject--ciCI 模式下快照不自动写入失败需-u更新test-storybook --ci--shard 1/8将测试套件拆分到多台机器并行test-storybook --shard1/8官方文档还给出了两个 CI 环境下的高频排查点Troubleshooting测试超时若出现Timeout - Async callback was not invoked within the 15000 ms timeout specified by jest.setTimeout通常是 Story 数量过多或 CI 内存不足可通过--maxWorkers2限制并行度解决错误输出过短CLI 默认截断错误输出为 1000 字符可通过DEBUG_PRINT_LIMIT5000 yarn test-storybook放大限制完整堆栈也可直接在浏览器中打开对应 Story 查看。演进方向Vitest Addon官方文档在 Test Runner 文档开头给出了重要提示Test Runner 正被 Vitest addon 逐步取代——后者基于更快、更现代的 Vitest 浏览器模式提供同样的能力并能在 Storybook 应用中直接运行交互、无障碍与视觉测试。对于使用 Vite 构建的 Storybook 框架官方推荐优先考虑 Vitest addon。对于仍在 Webpack 技术栈或需要零配置 Jest Playwright 组合的团队本文的本地构建工作流依然是经过官方验证的稳定方案。小结本文完整拆解了 Storybook Test Runner 的“本地构建 CI 工作流”在 GitHub Actions 中用build-storybook产出静态产物以http-server托管在 6006 端口通过wait-on探测就绪后由concurrently -k -s first编排执行test-storybook测试结束后自动回收服务器并把退出码正确回传给 CI。这套方案无需公网部署即可在任何 CI 供应商上运行 Storybook 组件测试适合需要认证访问或希望测试与部署解耦的项目若 Storybook 可公开访问也可改用deployment_statusTARGET_URL的部署式工作流。两种方案共享同一套安装、配置与 CLI 参数体系可从 test-runner.mdx 获取全部细节。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Storybook Test Runner 本地构建 CI 工作流实战在 GitHub Actions 中构建、服务并运行组件测试【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook Test Runner 能够把项目中的每一个 Story 转化为可执行的测试对于没有 play function 的 Story它验证组件能否无错误渲染对于带有 play function 的 Story它还会执行交互并校验断言结果。本文聚焦官方文档提供的“本地构建工作流”——在 CI以 GitHub Actions 为例中先构建 Storybook 静态产物再用静态服务器托管最后对构建产物运行 Test Runner。读完本文你将掌握这套工作流的完整 YAML 配置、每个步骤的底层原理以及它与“针对已部署 Storybook 测试”方案的取舍。为什么需要“本地构建”式的工作流Storybook 的 Test Runner 是一个独立于 Storybook 框架运行的测试工具它需要在测试执行时访问一个正在运行的 Storybook 实例——无论是本地开发服务器还是已经部署到公网的静态站点。官方文档明确指出Test Runner 要求本地运行中的 Storybook 或已发布的 Storybook 才能执行全部已有测试。在 CI 环境中最常见的两种接入方式针对已部署的 Storybook 测试依赖 Vercel、Netlify 等平台触发 GitHub Actions 的deployment_status事件将部署 URL 通过TARGET_URL环境变量传给 Test Runner针对本地构建产物测试本文主题不依赖任何部署平台在 CI 内完成build-storybook构建 →http-server静态服务 →wait-on端口探测 →test-storybook执行测试的全流程。第二种方式尤其适合以下场景Storybook 需要认证才能访问、团队希望测试与部署解耦或者 CI 中根本没有接部署平台。官方文档也建议当已发布的 Storybook 需要认证时优先采用“非部署式”的本地构建方案。核心工作流完整配置与逐行解析官方在 test-runner-local-build-workflow.md 中给出了推荐配方该片段被主文档 test-runner.mdx 引用。它将构建、服务、测试三个环节用concurrently组织在一个任务中通过-k保证测试结束成功或失败后自动终止静态服务器避免 CI 任务悬挂。完整配置如下name: Storybook Tests on: push jobs: test: timeout-minutes: 60 runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version-file: .nvmrc - name: Install dependencies run: yarn - name: Install Playwright run: npx playwright install --with-deps - name: Build Storybook run: yarn build-storybook --quiet - name: Serve Storybook and run tests run: | npx concurrently -k -s first -n SB,TEST -c magenta,blue \ npx http-server storybook-static --port 6006 --silent \ npx wait-on tcp:127.0.0.1:6006 yarn test-storybook触发器与任务级配置on: push任意分支的推送都会触发测试。如果希望只在主分支或 pull request 上运行可以替换为on: [push, pull_request]或配合branches限定范围。timeout-minutes: 60整个 Job 的硬性超时时间。首次构建依赖、下载 Playwright 浏览器二进制、构建 Storybook 并跑完测试通常需要数分钟到十几分钟60 分钟是文档提供的安全默认值若项目 Storybook 较大或 Story 数量多可适当调大。runs-on: ubuntu-latestTest Runner 底层基于 Playwright需要 Linux 环境来运行浏览器其他 CI 供应商GitLab Pipelines、CircleCI 等可以参照 Playwright 的 CI 文档选择基础镜像。环境准备步骤actions/checkoutv4拉取仓库代码。actions/setup-nodev4node-version-file: .nvmrc从仓库根目录的.nvmrc文件读取 Node.js 版本。如果你的项目没有.nvmrc可以改用node-version: 20这类写法。yarn安装依赖。官方文档给出的配方默认使用 Yarn实际项目中完全可以用npm ci或pnpm install --frozen-lockfile替代保持与本地开发一致的包管理器即可。npx playwright install --with-deps安装 Playwright 浏览器二进制及系统级依赖。--with-deps会在 ubuntu 镜像中额外安装浏览器运行所需的系统库这是 CI 上避免“浏览器启动失败”的关键一步。构建 Storybook 静态产物yarn build-storybook --quietbuild-storybook对应storybook/cli提供的构建命令将项目构建为纯静态 Web 应用。--quiet减少构建日志输出避免 CI 日志过长。官方文档特别提醒默认情况下 Storybook 将构建产物输出到storybook-static目录。如果项目通过main.js/main.ts中的配置改动了输出目录例如自定义outputDir必须同步调整下方http-server的静态目录参数。仓库内 test-storybooks/mcp/package.json 中即可看到真实的脚本示例build-storybook: storybook build其配套的 MCP 测试tests/mcp-endpoint.e2e.test.ts同样遵循“构建 → 服务 → 测试”的模式。并行服务与测试concurrently http-server wait-onnpx concurrently -k -s first -n SB,TEST -c magenta,blue \ npx http-server storybook-static --port 6006 --silent \ npx wait-on tcp:127.0.0.1:6006 yarn test-storybook这是整套工作流中最核心也最容易出问题的一行三个第三方工具各司其职工具作用关键参数说明concurrently同时启动多个命令并统一转发输出-kkill others任一命令退出时终止其余命令-s firstsuccess first以第一个成功退出的命令的结果作为整体退出码-n SB,TEST为两个命令命名-c magenta,blue设置前缀颜色便于区分日志http-server零配置静态文件服务器storybook-static为构建产物目录--port 6006与 Test Runner 默认期望的本地端口一致--silent抑制请求日志wait-on轮询等待某个资源就绪tcp:127.0.0.1:6006表示等待本机 6006 端口可连接避免测试命令在服务器尚未监听时抢先执行而失败整条链路的执行语义是concurrently同时拉起“静态服务器”与“等待端口 运行测试”两条命令wait-on探测到 6006 端口可访问后test-storybook才开始运行测试跑完无论通过与否-k会立刻杀掉仍在监听的http-server配合-s first将测试的退出码传递给 CI从而让 GitHub Actions 正确标记构建的成败状态。关于端口Test Runner 默认假设本地 Storybook 运行在6006端口所以配方中http-server显式指定--port 6006正是为了与默认行为对齐若你通过--url指定了其他端口这里也需保持一致。前置配置安装与本地脚本在把工作流搬上 CI 之前需要先在项目中完成 Test Runner 的安装与脚本配置详见 test-runner.mdx# npm npm install storybook/test-runner --save-dev # 或 pnpm pnpm add --save-dev storybook/test-runner # 或 yarn yarn add --dev storybook/test-runner在package.json中注册脚本{ scripts: { test-storybook: test-storybook } }本地开发时先启动 Storybook 开发服务器默认 6006 端口再开一个新终端执行yarn test-storybook或npm run test-storybook/pnpm run test-storybook即可运行测试。这套本地流程与 CI 工作流是同一套测试逻辑CI 中只是把“开发服务器”替换成了“构建产物 http-server”。备选方案针对已部署 Storybook 的 deployment_status 工作流官方文档在“Run against deployed Storybooks”一节给出了另一份配方test-runner-with-deploy-event-workflow.md与本地构建方案形成互补name: Storybook Tests on: deployment_status jobs: test: timeout-minutes: 60 runs-on: ubuntu-latest if: github.event.deployment_status.state success steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version-file: .nvmrc - name: Install dependencies run: yarn - name: Install Playwright run: npx playwright install --with-deps - name: Run Storybook tests run: yarn test-storybook env: TARGET_URL: ${{ github.event.deployment_status.target_url }}两种方案的关键差异部署方案由 Vercel、Netlify 等平台触发deployment_status事件if: github.event.deployment_status.state success保证只在部署成功后执行测试并通过TARGET_URL环境变量把部署地址传给 Test Runner前提是已发布的 Storybook 必须可公开访问若需要认证则建议改用本地构建方案。本地构建方案不依赖外部部署平台直接在 CI 内构建、服务、测试产物无需公网可达。运行测试时--url参数与TARGET_URL环境变量是等效的两种指定目标地址的方式test-runner-execute-with-url.md# 方式一--url 参数 yarn test-storybook --url https://the-storybook-url-here.com # 方式二TARGET_URL 环境变量 TARGET_URLhttps://the-storybook-url-here.com yarn test-storybook常用 CLI 参数与排查要点Test Runner 基于 Jest 构建接受其部分 CLI 参数。以下是高频使用的选项完整清单见 test-runner.mdx参数用途示例--url指定测试目标 URL默认本地 6006test-storybook --url http://localhost:6007--maxWorkers限制并行 worker 数适合内存受限的 CItest-storybook --maxWorkers2--watch/--watchAll监听模式仅本地开发使用test-storybook --watch--coverage配合storybook/addon-coverage生成覆盖率test-storybook --coverage--failOnConsole浏览器出现 console 错误即判定失败test-storybook --failOnConsole--index-json基于index.json静态索引运行不支持 watchtest-storybook --index-json--eject生成test-runner-jest.config.js便于深度定制test-storybook --eject--ciCI 模式下快照不自动写入失败需-u更新test-storybook --ci--shard 1/8将测试套件拆分到多台机器并行test-storybook --shard1/8官方文档还给出了两个 CI 环境下的高频排查点Troubleshooting测试超时若出现Timeout - Async callback was not invoked within the 15000 ms timeout specified by jest.setTimeout通常是 Story 数量过多或 CI 内存不足可通过--maxWorkers2限制并行度解决错误输出过短CLI 默认截断错误输出为 1000 字符可通过DEBUG_PRINT_LIMIT5000 yarn test-storybook放大限制完整堆栈也可直接在浏览器中打开对应 Story 查看。演进方向Vitest Addon官方文档在 Test Runner 文档开头给出了重要提示Test Runner 正被 Vitest addon 逐步取代——后者基于更快、更现代的 Vitest 浏览器模式提供同样的能力并能在 Storybook 应用中直接运行交互、无障碍与视觉测试。对于使用 Vite 构建的 Storybook 框架官方推荐优先考虑 Vitest addon。对于仍在 Webpack 技术栈或需要零配置 Jest Playwright 组合的团队本文的本地构建工作流依然是经过官方验证的稳定方案。小结本文完整拆解了 Storybook Test Runner 的“本地构建 CI 工作流”在 GitHub Actions 中用build-storybook产出静态产物以http-server托管在 6006 端口通过wait-on探测就绪后由concurrently -k -s first编排执行test-storybook测试结束后自动回收服务器并把退出码正确回传给 CI。这套方案无需公网部署即可在任何 CI 供应商上运行 Storybook 组件测试适合需要认证访问或希望测试与部署解耦的项目若 Storybook 可公开访问也可改用deployment_statusTARGET_URL的部署式工作流。两种方案共享同一套安装、配置与 CLI 参数体系可从 test-runner.mdx 获取全部细节。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
