Storybook Test Runner 的 Index.json 模式：用 --index-json 精确测试已部署的 Storybook

Storybook 的 Test Runner 可以将你项目中的每一个 story 自动转化为可执行测试，并借助 Jest 与 Playwright 在真实浏览器中运行。本指南聚焦 Test Runner 的 Index.json 模式：通过 --index-json 标志，让测试直接基于 Storybook 生成的 index.json 静态索引文件执行，从而在本地与远程 Storybook 不同步、甚至完全没有代码访问权限时，也能以最准确的方式测试目标 Storybook 实例。阅读本文后，你将掌握 --index-json / --no-index-json 两个核心标志的用法、适用场景、验证 index.json 是否可用的方法，以及该模式背后的索引生成原理。

Index.json 模式是什么

Storybook Test Runner 在测试时有两种数据来源：

• 本地 Storybook：Test Runner 直接读取并转换你项目中的 story 源文件，把它们变成测试用例；
• 远程 Storybook：Test Runner 无法访问源码，转而使用 Storybook 暴露的 index.json（旧版称为 stories.json）文件来运行测试。这个文件是全部 story 的静态索引，记录了每个 story 的 id、title、name 等元数据。

Index.json 模式指的就是后者：以 index.json 为准来驱动测试执行。在 Test Runner 官方文档 中，该模式被描述为"当本地和远程 Storybook 看似不同步，或者你甚至无法访问代码时，index.json 文件保证是你要测试的已部署 Storybook 最准确的表示"。

如何使用 --index-json 标志

使用 --index-json（短选项为 -s）即可让 Test Runner 以 Index.json 模式运行，针对本地 Storybook 测试该功能。针对不同的包管理器，命令写法略有差异，以下是 官方代码片段 中的三种标准形式：

npm（通过 package.json scripts 调用）

npm run test-storybook -- --index-json

注意：使用 npm run 时，传给脚本的参数必须放在 -- 之后，否则会被 npm 自身拦截。

pnpm

pnpm run test-storybook --index-json

yarn

yarn test-storybook --index-json

前置条件与常规 Test Runner 一致：需要先在本地启动 Storybook（storybook dev），再打开一个新的终端窗口运行上述命令。同时，启用 Index.json 模式的前提是目标 Storybook 支持生成 index.json（要求兼容的 Storybook 版本），该标志在满足条件时也会被自动检测启用。

为什么需要 Index.json 模式

默认情况下，Test Runner 假定你在本地通过 6006 端口运行 Storybook 并直接转换 story 源文件。但在以下场景中，这种默认行为会出现偏差：

• 本地与远程不同步：你手头的代码版本与已部署的 Storybook 构建不一致，直接跑本地文件得出的结果并不能反映线上真实状况；
• 没有代码访问权限：你只拥有一个线上 Storybook 的访问地址，无法读取源码来生成测试；
• 需要精确验证部署产物：index.json 由 Storybook 构建时生成，与部署内容一一对应，是"已部署 Storybook 最准确的表示"。

在这些情况下，使用 --index-json 让测试以线上 index.json 为准，能保证测试目标与线上实例完全一致。配合 --url 标志指向部署地址（或设置 TARGET_URL 环境变量），即可对已发布的 Storybook 执行测试。

如何检查 Storybook 是否支持 index.json

Index.json 模式要求目标实例提供 index.json 文件。验证方法很简单：在浏览器中打开你的 Storybook 实例地址并追加 /index.json 路径，例如 https://your-storybook-url-here.com/index.json。如果返回的 JSON 文件以 "v": 3 键开头，紧随其后是名为 stories 的键，且其值为"story ID 到 JSON 对象"的映射，则说明该 Storybook 支持 Index.json 模式（参见 test-runner.mdx 中的检查说明）。

index.json 并非凭空产生，而是由 Storybook 的 Story Indexers 构建：索引器依据 glob 规则爬取文件系统，找出符合 *.stories.@(js|jsx|mjs|ts|tsx) 模式的 story 文件，生成包含 id、title、tags 等元数据的完整索引，该索引可在 Storybook 的 /index.json 路由读取（参见 sidebar-and-urls.mdx）。换句话说，只要你的 Storybook 构建流程正常产出该索引文件，Test Runner 的 Index.json 模式即可生效。

配套与相关 CLI 选项

--index-json 是 Test Runner 众多 CLI 选项之一，与之直接相关和常配合使用的选项包括（完整列表见 test-runner.mdx 的 CLI Options 章节）：

选项	说明
-s, --index-json	以 Index.json 模式运行。兼容的 Storybook 会自动检测启用，示例：test-storybook --index-json
--no-index-json	禁用 Index.json 模式，示例：test-storybook --no-index-json
--url	指定测试运行的 URL，适用于自定义 Storybook 地址，示例：test-storybook --url http://the-storybook-url-here.com
--browsers	指定运行浏览器，可传多个：chromium、firefox、webkit，示例：test-storybook --browsers firefox chromium
--maxWorkers [amount]	限制并行 worker 数量，示例：test-storybook --maxWorkers=2

如果需要显式关闭自动检测到的 Index.json 模式，使用 --no-index-json 标志即可，对应写法同样按包管理器区分（test-runner-no-index-json.md）：

npm run test-storybook -- --no-index-json

pnpm run test-storybook --no-index-json

yarn test-storybook --no-index-json

已知限制：与 watch 模式不兼容

需要特别留意的是，Index.json 模式不兼容 watch 模式。因为 watch 模式依赖监听本地文件变化并重新转换 story 源文件，而 Index.json 模式以静态索引文件为数据源，两者工作机制冲突。若你在使用 --index-json 时发现测试无法进入监听状态或行为异常，请移除 --watch / --watchAll 相关标志。

底层原理与索引文件格式

从实现角度看，Test Runner 对本地 Storybook 使用"转换 story 文件为测试"的策略，而远程 Storybook 则直接消费 index.json。index.json 本质上是 Storybook 构建流程产出的静态元数据清单，其顶层结构以版本号 "v": 3 标识当前格式，stories 键下以 story ID 为键、以描述该 story 的对象为值（包含 id、title、name 等信息）。测试执行时，Test Runner 依据这份清单逐条访问并渲染对应的 story 页面：

• 没有 play function 的 story：验证其能否无错误地渲染；
• 带 play function 的 story：额外检查 play function 是否报错、内部断言是否全部通过。

这种基于索引的测试方式与 storybook-composition.mdx 中介绍的组合场景 一脉相承：/index.json 端点（旧称 /stories.json）返回 story 列表及其元数据，无论用于组合其他 Storybook 还是驱动 Test Runner，都保证了数据的一致性和可校验性。

延伸阅读

• 完整的 CLI 选项与用法：Test Runner 官方文档
• 禁用 Index.json 模式的代码片段：test-runner-no-index-json.md
• 索引生成机制：Story Indexers 配置
• index.json 与侧边栏填充：Sidebar and URLs
• 发布与 /index.json 端点：Publish Storybook