Storybook Test Runner 按 Tags 过滤测试include、exclude、skip 配置与 CLI 实战指南【免费下载链接】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 生成并执行测试但真实项目中常常存在尚未就绪的组件仅用于展示的布局页与测试无关的 token 样式等场景。本指南基于 Storybook 仓库中的官方文档 test-runner-tags-config.md 与其宿主章节 test-runner.mdx系统讲解如何利用 Storybook 的 tags 机制通过配置文件或--includeTags、--excludeTags、--skipTags三个 CLI 参数精准控制哪些 story 被测、哪些被跳过、哪些被彻底排除并结合仓库源码说明其底层实现原理。一、为什么需要按 Tags 过滤测试Test Runner 将你的每一个 story 都转化为可执行的测试对没有 play function的 story验证其能否无错误地渲染对带有 play function的 story还会检查 play function 中的断言是否全部通过。这些测试运行在真实浏览器中可通过命令行或 CI 执行。默认情况下每次运行都会测试所有story。当组件库规模变大后全量测试会带来几个痛点某些 story 处于草稿状态尚未准备好被测试某些 story 只服务于文档演示如布局、token 展示测试它们没有意义某些 story 依赖外部服务或环境变量不适合在常规测试中执行。Storybook 原本引入 tags 特性是为了生成自动文档但它可以被进一步扩展test-runner 使用与 Storybook 相同的 tags 配置体系或等价的 CLI 标志来按需运行测试。该 CLI 过滤能力仅在 test-runner 最新稳定版0.15 及以上中可用。二、在 test-runner 配置文件中启用 tags 过滤在项目根目录的.storybook/test-runner.js或 TypeScript 版本的test-runner.ts中增加tags字段即可声明三组过滤规则。以下是官方配置的完整示例module.exports { tags: { include: [test-only, pages], exclude: [no-tests, tokens], skip: [skip-test, layout], }, };如果你使用 TypeScript 编写配置文件可以引入官方类型TestRunnerConfig获得完整的类型提示import type { TestRunnerConfig } from storybook/test-runner; const config: TestRunnerConfig { tags: { include: [test-only, pages], exclude: [no-tests, tokens], skip: [skip-test, layout], }, }; export default config;三个选项的含义选项说明exclude匹配到所提供 tags 的 story不会被测试彻底排除include只有匹配到所提供 tags 的 story子集才会被测试skip匹配到所提供 tags 的 story 会被跳过并在测试结果中被标记出来三、通过 CLI 标志覆盖配置0.15除了配置文件test-runner 还暴露了三个对应的 CLI 标志它们适用于不想改动配置文件、或希望在 CI 流水线的不同阶段动态切换过滤规则的场景CLI 选项说明示例命令--includeTags定义仅测试匹配这些 tags 的 story 子集实验性test-storybook --includeTagstest-only, pages--excludeTags阻止匹配这些 tags 的 story 被测试实验性test-storybook --excludeTagsno-tests, tokens--skipTags配置 test-runner 跳过匹配这些 tags 的 story实验性test-storybook --skipTagsskip-test, layout重要规则CLI 标志的优先级高于配置文件。当同时提供 CLI 标志与配置文件中的选项时CLI 标志会生效并覆盖配置文件中的对应选项。这为默认配置 按需覆盖的 CI 工作流提供了灵活性。CLI 执行示例# 仅测试带有 test-only 或 pages 标签的 story test-storybook --includeTagstest-only, pages # 排除带有 no-tests 或 tokens 标签的 story test-storybook --excludeTagsno-tests, tokens # 跳过带有 skip-test 或 layout 标签的 story test-storybook --skipTagsskip-test, layout四、在 CSF 中为 story 打标签过滤规则生效的前提是 story 本身带有匹配的 tags。Tags 可以在组件级meta或story 级声明官方文档明确指出为组件的 story 应用 tags 应在组件级meta或 story 级完成跨 story 导入 tags 在 Storybook 中不受支持也不会按预期工作。场景一禁用排除某些 story 的测试当你想让 test-runner 完全跳过某些尚未就绪或不相关的 story 时为其打上自定义 tag并在配置文件的exclude中声明或运行时使用--excludeTags。以下为 ReactCSF 3示例import type { Meta, StoryObj } from storybook/react; import { MyComponent } from ./MyComponent; const meta { component: MyComponent, // 为文件内所有 story 提供 no-tests 标签 tags: [no-tests], } satisfies Metatypeof MyComponent; export default meta; type Story StoryObjtypeof meta; export const ExcludeStory: Story { // 为单个 story 添加 no-tests 标签以便在 test-runner 配置启用后将其排除出测试 tags: [no-tests], };场景二只运行特定子集的测试当你想让 test-runner只对某一部分 story 执行测试时为其打上自定义 tag并在配置文件的include中声明或使用--includeTagsimport type { Meta, StoryObj } from storybook/react; import { MyComponent } from ./MyComponent; const meta { component: MyComponent, // 为文件内所有 story 提供 test-only 标签 tags: [test-only], } satisfies Metatypeof MyComponent; export default meta; type Story StoryObjtypeof meta; export const IncludeStory: Story { // 为单个 story 添加 test-only 标签使其在 test-runner 配置启用后被纳入测试 tags: [test-only], };场景三跳过标记为临时禁用某些 story当你想让 test-runner 忽略某些 story但又希望它们在测试结果中明确显示为被跳过而不是彻底消失时为其打上自定义 tag并在配置文件的skip中声明或使用--skipTagsimport type { Meta, StoryObj } from storybook/react; import { MyComponent } from ./MyComponent; const meta { component: MyComponent, // 为文件内所有 story 提供 skip-test 标签 tags: [skip-test], } satisfies Metatypeof MyComponent; export default meta; type Story StoryObjtypeof meta; export const SkipStory: Story { // 为单个 story 添加 skip-test 标签使其在 test-runner 配置启用后被跳过 tags: [skip-test], };官方文档还提供了Angular、Vue、Web Components等多个框架以及CSF Next 实验性写法通过preview.meta()/meta.story()声明的完整代码示例分别见 my-component-exclude-tags.md、my-component-include-tags.md 与 my-component-skip-tags.md。三者的核心逻辑一致tag 加在meta上作用于整组 story加在单个 story 上仅作用于该 story。五、include、exclude、skip 三者的区别三个选项的语义容易混淆总结如下exclude排除匹配的 story 不会出现在测试执行列表中相当于不测这个。include包含只有匹配的 story 才会被测试相当于只测这些不匹配的 story 全部被排除在外。skip跳过匹配的 story 会被 test-runner 忽略并在测试结果中被标记出来表明这些测试被临时禁用——这是它和exclude的关键差异。实践建议组件开发中常用include例如仅对带有test-only标签的 story 跑交互测试加快本地反馈循环发布前可用exclude将文档型、占位型 story 排除出回归测试skip适合临时屏蔽如某条故事依赖的接口暂时不可用跳过并保留可见的标记方便后续恢复。六、源码级原理tags 过滤在 Storybook 中如何生效本仓库Storybook 源码中tags 过滤在多个层面都有对应实现可以作为理解其工作机制的依据。1. 默认值与配置合并在 code/addons/vitest/src/vitest-plugin/index.ts 中Vitest 插件会合并用户传入的 tags 选项并为include设置了默认值Tag.TEST即test标签tags: { include: options?.tags?.include ?? [Tag.TEST], exclude: options?.tags?.exclude ?? [], skip: options?.tags?.skip ?? [], },也就是说即使你不做任何配置Storybook 默认也会只测试带有test标签或满足其他默认规则的的 story一旦你在 test-runner 配置中提供了include/exclude/skip则会覆盖这些默认值。2. 运行时传递tags 注入测试环境同一文件的 L379-L381 显示最终合并后的 tags 会通过环境变量注入测试运行环境供 setup 文件消费__VITEST_INCLUDE_TAGS__: finalOptions.tags.include.join(,), __VITEST_EXCLUDE_TAGS__: finalOptions.tags.exclude.join(,), __VITEST_SKIP_TAGS__: finalOptions.tags.skip.join(,),从源码结构可以推断include/exclude主要用于在测试生成阶段决定哪些 story 被纳入测试文件而skip则在单条 story 执行阶段生效。3. skip 的执行逻辑context.skip()在 code/addons/vitest/src/vitest-plugin/test-utils.ts 中可以看到skip的具体落地实现——当组合出的 story 的 tags 命中skipTags中的任意一个时直接调用context.skip()跳过该条测试if (composedStory undefined || skipTags?.some((tag) composedStory.tags.includes(tag))) { context.skip(); }这解释了skip与exclude的行为差异skip仍会创建测试用例只是在执行时被标记为跳过测试报告中可见而exclude则是在更早的阶段测试收集/生成阶段就把匹配的 story 过滤掉。七、常见陷阱与排查官方文档在 test-runner.mdx 中记录了该功能最典型的一个坑按 tags 过滤后测试仍被错误执行如果你在include和exclude列表中提供了相同的 tagtest-runner 会以exclude列表为准执行测试并忽略include列表。因此务必保证include与exclude中的 tags 互不相同。另一个需要留意的是版本前提--includeTags、--excludeTags、--skipTags属于实验性功能仅在 test-runner0.15 及以上的稳定版本中可用在旧版本中请使用配置文件方式并确认你安装的 test-runner 版本支持 tags 过滤。八、完整工作流示例综合以上内容一个典型的按 tags 管理测试工作流如下在 CSF 中打标签为组件meta或单个 story 添加自定义 tags如test-only、no-tests、skip-test在 test-runner 配置中声明规则在.storybook/test-runner.js中配置tags.include/tags.exclude/tags.skip按需用 CLI 覆盖在 CI 的不同阶段使用--includeTags、--excludeTags、--skipTags动态调整过滤范围检查测试结果被skip的 story 会在结果中被标记便于追踪临时禁用的测试及时恢复。# 本地开发只测关键路径 test-storybook --includeTagstest-only, pages # 发布前排除文档型与 token 展示 story 后全量回归 test-storybook --excludeTagsno-tests, tokens # 临时跳过某个 story 并保留可见标记 test-storybook --skipTagsskip-test, layout通过将 tags 过滤与 CI 结合你可以把全量测试、关键子集测试、发布前回归等不同粒度的测试策略落到同一条测试管线上既保证测试覆盖面又避免无关 story 拖慢流水线。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考