Storybook Test Runner 认证配置指南：使用 getHttpHeaders 为受保护的 Storybook 实例添加 HTTP 请求头

Storybook Test Runner 认证配置指南使用 getHttpHeaders 为受保护的 Storybook 实例添加 HTTP 请求头【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文聚焦 Storybook 官方测试工具Test Runner在部署场景下的认证配置当 Storybook 托管在需要鉴权的安全服务上时如何通过.storybook/test-runner.js或.storybook/test-runner.ts配置文件中的getHttpHeaders函数注入 HTTP 请求头让基于 Jest 与 Playwright 的测试能够成功访问并测试受保护的 Storybook 实例。读完本文你将掌握getHttpHeaders的完整配置方法、动态按 URL 选择 Token 的实战写法以及配套的--url参数与TARGET_URL环境变量用法。背景为什么部署后的 Storybook 需要认证配置Storybook Test Runner 会把项目中所有 story 转化为可执行的测试底层由 Jest 的说明。测试运行流程包含两类网络请求通过fetch请求检查 Storybook 实例的可用状态通过 Playwright 打开 story 页面并访问其索引index。如果你使用需要登录鉴权的安全托管服务secure hosting provider来部署 Storybook上述请求默认不带任何凭证会被服务端拒绝导致测试无法进行。解决方式就是在 test-runner 配置文件中加入getHttpHeaders函数。核心配置getHttpHeaders 函数getHttpHeaders是TestRunnerConfig类型中的一个可选配置项。它接收一个参数url——即 fetch 请求与页面访问所对应的 URL并返回一个对象对象中的键值对就是要附加到请求上的 HTTP 请求头。JavaScript 写法.storybook/test-runner.js使用 CommonJS 语法导出配置对象内容来自仓库中的原始代码片段 test-runner-auth.mdmodule.exports { getHttpHeaders: async (url) { const token url.includes(prod) ? XYZ : ABC; return { Authorization: Bearer ${token}, }; }, };TypeScript 写法.storybook/test-runner.tsTS 版本从storybook/test-runner导入TestRunnerConfig类型做类型标注并使用export default导出import type { TestRunnerConfig } from storybook/test-runner; const config: TestRunnerConfig { getHttpHeaders: async (url) { const token url.includes(prod) ? prod-token : dev-token; return { Authorization: Bearer ${token}, }; }, }; export default config;配置要点说明异步函数官方示例使用async便于在函数内执行异步的 Token 获取逻辑如调用认证服务、读取密钥等。按 URL 动态选择凭证url参数是区分环境的关键。示例中通过url.includes(prod)判断当前访问的是生产还是开发环境从而返回不同的 Bearer Token同理也可以按url.includes(staging)、url.includes(localhost)等条件扩展实现一套配置覆盖多个环境。返回请求头对象函数返回值会直接作为 HTTP 请求头附加到请求上因此你可以返回任意合法请求头如Authorization、Cookie、X-Api-Key等需与目标托管服务的鉴权方式匹配。注意保护敏感信息若 Token 属于机密信息不建议硬编码在配置文件中可改为从环境变量读取如process.env.TOKEN再在 CI 或部署平台中注入。配套操作指定目标 Storybook URLgetHttpHeaders只有在针对远程部署的 Storybook 运行时才有意义。默认情况下 test-runner 假设你测试的是本地6006端口上运行的 Storybook相关文档见 test-runner.mdx因此需要显式指定目标地址有两种方式。方式一--url 命令行参数在package.json中定义脚本后通过--url传入部署地址对应仓库片段 test-runner-execute-with-url.md{ scripts: { test-storybook: test-storybook } }npm run test-storybook -- --url https://the-storybook-url-here.compnpm run test-storybook --url https://the-storybook-url-here.comyarn test-storybook --url https://the-storybook-url-here.com方式二TARGET_URL 环境变量不修改命令直接通过环境变量注入目标地址TARGET_URLhttps://the-storybook-url-here.com yarn test-storybook在 CI 场景中TARGET_URL 常常来自部署平台触发的回调事件例如 Vercel、Netlify 在 GitHub Actions 中触发的deployment_status事件的target_url字段从而实现在部署完成后自动对该次部署的 Storybook 执行测试。补充Test Runner 相关 CLI 选项速查以下是与远程部署测试相关的常用 CLI 选项完整清单见 test-runner.mdx 中的 CLI Options 小节选项说明示例--url指定运行测试的 URL适用于自定义或远程 Storybook 地址test-storybook --url http://the-storybook-url-here.com-s,--index-json以 index.json 模式运行针对远程 Storybook依据静态索引文件执行测试test-storybook --index-json--no-index-json禁用 index.json 模式test-storybook --no-index-json--maxWorkers [amount]限制并行 worker 数量适用于大项目或低配 CItest-storybook --maxWorkers2--browsers指定运行浏览器chromium / firefox / webkit 之一或多个test-storybook --browsers firefox chromium--testTimeout [amount]定义单个测试的超时毫秒数test-storybook --testTimeout60000--failOnConsole浏览器控制台出现错误时使测试失败test-storybook --failOnConsole深入理解为什么认证会影响两种请求路径从文档对 test-runner 工作机制的描述test-runner.mdx可以推断出认证生效的两个层面实例状态检查与索引获取test-runner 需要通过fetch请求验证 Storybook 实例状态并获取 story 索引远程实例使用index.json即原stories.json的静态索引文件其内容以v: 3开头并包含stories映射。若托管服务要求鉴权这些 fetch 请求必须携带getHttpHeaders返回的请求头否则无法获取测试清单。Playwright 页面访问测试执行时 Playwright 会真实打开每个 story 页面getHttpHeaders返回的请求头也会附加到这些页面访问请求上保证页面在受保护环境下能够正常渲染。需要特别注意的是index.json模式与 watch 模式不兼容详见原文档说明此外在 CI 中如果采用部署事件触发测试原文档也明确指出已部署的 Storybook 必须可公开访问若托管服务需要认证则推荐改用本地构建后测试的方案。常见问题与排障建议结合 test-runner.mdx 的 Troubleshooting 小节使用认证配置时可能遇到以下问题测试超时若出现Timeout - Async callback was not invoked within the 15000 ms timeout specified by jest.setTimeout通常是并发 worker 过多所致可通过--maxWorkers2降低并发。认证配置未生效检查配置文件是否放在正确的路径.storybook/test-runner.js或.storybook/test-runner.ts以及是否通过--url或TARGET_URL指定了目标地址同时确认返回的请求头与托管服务的鉴权协议如 Bearer Token 前缀完全一致。Token 过期若托管服务使用短期有效 Token可在getHttpHeaders的异步逻辑中动态获取最新 Token而不是使用写死的常量。小结针对需要认证的远程 Storybook 部署在 test-runner-auth.md 所示的配置文件中定义getHttpHeaders函数即可让 Storybook Test Runner 的 fetch 请求与 Playwright 页面访问自动携带所需请求头。配合--url参数或TARGET_URL环境变量指定目标地址再结合url入参按环境动态切换 Token即可让测试在受保护的生产、预发等多环境部署下稳定运行。相关完整说明可继续阅读 test-runner.mdx其中还包含快照测试、覆盖率、CI 集成、Test Hook API 等进阶内容。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考