尧图网站建设 
Storybook 组件测试覆盖率Vitest 覆盖率支持包安装与配置实战指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook导读Storybook 的 Vitest 插件storybook/addon-vitest把覆盖率Code Coverage能力内建到了组件测试流程中只要启用测试面板里的覆盖率开关就能在你写的每个 Story 运行时自动统计被测代码的语句、分支与函数覆盖情况并在测试面板、/coverage/index.html页面、终端和 CI 中输出可交互的报告。本文以 docs/writing-tests/test-coverage.mdx 为主线重点讲解开启覆盖率前必须完成的覆盖率支持包安装这一步并延伸到 provider 选择、四种使用场景、watermarks 配置以及插件内部的实现原理帮助你一次性把 Storybook 组件测试覆盖率跑起来并看懂结果。一、为什么要给 Storybook 组件测试加覆盖率覆盖率Test coverage衡量的是现有测试是否充分覆盖了你的代码它会标记代码中哪些条件、逻辑分支、函数和变量已经被测试触达哪些还没有。覆盖率测试把被插桩instrumented的代码与一组行业公认的最佳实践进行比对相当于测试套件的最后一道 QA 防线用于持续提升测试质量。每个项目的覆盖率报告形态各不相同但有两类信息最值得关注整体的行/分支覆盖率——作为项目健康度的高层体检指标未被覆盖的具体行/分支——这些是潜在的测试缺口通常意味着对应代码路径从未被执行过。在 Storybook 中当你用 Vitest 插件运行组件测试时它可以顺带生成覆盖率报告并把结果汇总到测试面板testing widget中直观展示被测 Story 覆盖了百分之多少的语句。完整流程请参考 docs/writing-tests/test-coverage.mdx。提示如果你无法使用 Vitest 插件仍可通过 test-runner 生成代码覆盖率参见 test-runner 文档中的 Generate code coverage 一节。二、前置条件Vitest 插件与覆盖率开关覆盖率功能内建于 Vitest 插件之中启用后会在运行项目组件测试时自动计算。启用方式很简单在 Storybook 的测试面板testing widget中勾选coverage复选框即可。从源码看覆盖率开关是插件全局状态的组成部分。constants.ts 中插件初始状态为config: { coverage: false, a11y: false }勾选开关后该状态被置为true并随测试运行请求一同传递。测试面板组件 TestProviderRender.tsx 中对应的复选框事件会把coverage配置写入 store。关键点在覆盖率真正开始计算之前你往往需要先安装一个与所选覆盖率提供器coverage provider对应的支持包——这正是本文要重点讲解的一步安装命令见下文。三、核心步骤安装覆盖率支持包coverage providerVitest 支持两种覆盖率计算引擎provider你需要按需安装其一Provider说明对应 npm 包v8基于 V8 引擎内置的 JavaScript 代码覆盖率能力是默认选项速度快、零额外依赖vitest/coverage-v8Istanbul基于 Istanbul 插桩工具链兼容性更广常用于传统工作流vitest/coverage-istanbul对应原始文档片段 docs/_snippets/vitest-plugin-install-coverage-support-packages.md 给出了三种包管理器的完整安装命令均安装为 devDependenciesnpm# For v8 npm install --save-dev vitest/coverage-v8 # For istanbul npm install --save-dev vitest/coverage-istanbulpnpm# For v8 pnpm add --save-dev vitest/coverage-v8 # For istanbul pnpm add --save-dev vitest/coverage-istanbulyarn# For v8 yarn add --dev vitest/coverage-v8 # For istanbul yarn add --dev vitest/coverage-istanbul安装时可以二选一也可以同时安装以便随时切换 provider。如果你不装支持包就启用覆盖率插件会给出明确提示在 vitest-manager.ts 的启动逻辑中当 Vitest 抛出与 coverage 相关的错误时插件会解析错误信息判断缺少的是vitest/coverage-v8还是vitest/coverage-istanbul并追加提示文案Please install the vitest/coverage-{package} package to collect coverage。此外插件的 postinstall.ts 会在安装后检查这两个支持包是否已安装如果检测到都没有会打印提示并默认尝试加入vitest/coverage-v8以启用覆盖率报告。也就是说装好支持包后覆盖率能力即随 Vitest 插件就绪。四、四种使用场景UI、CLI、编辑器与 CI因为覆盖率内建于 Vitest 插件所以你在任何运行测试的地方都能使用它。1. Storybook UI测试面板在 Storybook UI 中启用覆盖率后运行测试结束测试面板会汇总显示被测 Story 覆盖的语句百分比该百分比是否满足 watermarks 阈值红色/橙色/绿色三档状态。同时完整的覆盖率报告会发布在运行中 Storybook 的/coverage/index.html路由上。报告是可交互的点击任意组件即可查看其源码逐行分辨哪些代码已被测试覆盖、哪些没有。从源码看这条路由由 preset.ts 提供插件把覆盖率报告目录解析到 Storybook 缓存目录resolvePathInStorybookCache(COVERAGE_DIRECTORY)其中 constants.ts 定义COVERAGE_DIRECTORY coverage创建目录后以静态服务方式映射到/coverage端点。测试面板中Open coverage report链接即指向该地址见 TestProviderRender.tsx。⚠️UI 中覆盖率的三点重要限制覆盖率只基于你编写的 Story计算不包含项目中其他 Vitest 测试只能针对项目全部 Story计算不支持单个 Story 或 Story 分组watch 模式监听模式下不计算覆盖率——启用覆盖率时开启 watch 会使其失效。2. CLI命令行与 Storybook Test 的其他能力一样覆盖率构建在 Vitest 之上因此可以直接使用 Vitest CLI 生成报告。假设你的 package.json 中有如下脚本{ scripts: { test-storybook: vitest --projectstorybook } }那么只需追加--coverage参数对应文档片段 docs/_snippets/vitest-plugin-run-with-coverage.mdnpmnpm run test-storybook -- --coveragepnpmpnpm run test-storybook --coverageyarnyarn test-storybook --coverage报告默认保存在项目配置的 coverage 报告目录./coverageVitest 默认值中。提示上述命令只统计你编写的 Story 的覆盖率而非整个代码库。由于覆盖率在纳入项目全部测试时最准确也可以运行npx vitest --coverage对项目所有测试计算覆盖率。3. 编辑器扩展IDE覆盖率同样可通过 Vitest 的 IDE 集成如 VSCode 的 Vitest 扩展使用直接在编辑器内计算并展示覆盖率结果。需要注意的是编辑器中的覆盖率包含项目中所有测试而不只是你编写的 Story。4. CI 流水线在 CI 中生成覆盖率报告直接复用 CLI 方式即可。下面是文档中给出的一个简化版 GitHub Actions 工作流示例name: Storybook Tests on: push jobs: test: steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20.x - name: Install dependencies run: yarn # This will run all Vitest tests, including Storybook tests - name: Run tests run: yarn test --coverage这里刻意运行全部测试yarn test而非仅 Storybook 测试yarn test-storybook原因同上覆盖率报告在纳入项目所有测试时最准确。UI 中查看 Storybook 专属覆盖率很有价值但 CI 输出更应反映项目的整体覆盖情况。五、配置详解Provider 与 WatermarksCoverage provider 选择通过 Vitest 配置中的coverage.provider选项可切换计算引擎v8 为默认值import { defineConfig } from vitest/config; export default defineConfig({ // ... test: { // ... coverage: { // ... provider: istanbul, // v8 is the default }, }, });Watermarks覆盖率阈值两个 provider 都支持 watermarks——即覆盖率阈值low watermark 是通过测试所需的最低覆盖率high watermark 是被认定为良好的最低覆盖率介于两者之间的覆盖率被认为可接受但不理想。测试面板中的覆盖率汇总会展示语句覆盖百分比以及是否达到 watermark 阈值图标颜色三档低于 low watermark红色negative介于 low 与 high 之间橙色warning高于 high watermark绿色positive默认阈值为statements: [50, 80]低 50、高 80可在 Vitest 配置中调整import { defineConfig } from vitest/config; export default defineConfig({ // ... test: { // ... coverage: { // ... watermarks: { // These are the default values statements: [50, 80], }, }, }, });这套三档状态的判定逻辑在插件源码中有直接实现coverage-reporter.ts 的自定义报告器在汇总节点上读取语句覆盖率百分比缺省时回退到 Vitest 默认 watermarks[50, 80]然后按percentage lowWatermark → negative、percentage highWatermark → warning、否则positive三档输出状态再通过testManager.onCoverageCollected写入测试面板状态见 test-manager.ts。其他配置选项更多 coverage 配置项请查阅 Vitest 官方文档的 coverage 章节。需要特别注意的是在 Storybook UI 中计算覆盖率时以下选项始终被忽略enabledcleancleanOnRerunreportOnFailurereporterreportsDirectory这一点从 vitest-manager.ts 可以印证插件从 Storybook UI 启动 Vitest 时会强制覆盖这些选项——例如固定enabled: true、clean: true、cleanOnRerun: true、reportOnFailure: true把 reporter 固定为 HTML 报告器加 Storybook 自定义覆盖率报告器并把reportsDirectory指向 Storybook 缓存目录以便映射到/coverage路由。也就是说UI 场景下这些选项由插件接管你在配置文件中的同名设置不会生效。六、源码级原理覆盖率在插件中如何流动围绕覆盖率支持包安装这一步插件内部有完整闭环理解它有助于排查问题开关与请求UI 勾选 coverage 后状态写入 storeconstants.ts测试运行请求携带coverage: true。启动/重启 Vitest只有当启用了覆盖率、且非 watch 模式、且是全量非聚焦测试时覆盖率才会真正启用vitest-manager.ts。聚焦到单个 Story 运行或 watch 模式下会绕过覆盖率这正是文档中三项限制的实现根源。对应地test-manager.test.ts 中有启用覆盖率时需重启 Vitest以及聚焦测试不重启的用例验证。缺失支持包的兜底若未安装vitest/coverage-v8/vitest/coverage-istanbulVitest 抛错后插件解析错误信息并给出请安装对应包的明确提示vitest-manager.ts。汇总与展示自定义覆盖率报告器coverage-reporter.ts通过storybook/addon-vitest/internal/coverage-reporter入口导出见 package.json在报告汇总节点计算语句百分比与三档状态推送至测试面板HTML 报告则由 preset 映射到/coverage/index.html供交互式查看。排除干扰项插件在configureVitest阶段会把storybook-static目录加入 coverage 排除列表避免构建产物污染覆盖率统计vitest-plugin/index.ts。七、常见问题与最佳实践小结启用覆盖率却报错提示缺少包按上文命令安装vitest/coverage-v8默认 provider或vitest/coverage-istanbul切换 provider 时即可解决无需其他配置。报告一直显示 0% 或不更新检查是否处于 watch 模式watch 下不计算覆盖率以及是否只聚焦运行了单个 Story聚焦运行同样不计覆盖率。UI 报告与实际 CI 数字不一致属正常现象——UI 只统计 Story 覆盖CI 中的npx vitest --coverage统计项目全部测试两者口径不同。想要更完整的覆盖率在 CI 中运行全部测试而非仅 Storybook 测试并在vitest.config.ts中通过watermarks设定可接受的语句/分支/函数/行覆盖率门槛让覆盖率从参考指标升级为质量门禁。按照本文的步骤安装支持包、勾选覆盖率开关并选择合适的 provider你就能在 Storybook 测试面板、/coverage/index.html、终端与 CI 中同时获得组件的覆盖率视图把组件到底测没测全变成一目了然的事实。【免费下载链接】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 组件测试覆盖率：Vitest 覆盖率支持包安装与配置实战指南
Storybook 组件测试覆盖率Vitest 覆盖率支持包安装与配置实战指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook导读Storybook 的 Vitest 插件storybook/addon-vitest把覆盖率Code Coverage能力内建到了组件测试流程中只要启用测试面板里的覆盖率开关就能在你写的每个 Story 运行时自动统计被测代码的语句、分支与函数覆盖情况并在测试面板、/coverage/index.html页面、终端和 CI 中输出可交互的报告。本文以 docs/writing-tests/test-coverage.mdx 为主线重点讲解开启覆盖率前必须完成的覆盖率支持包安装这一步并延伸到 provider 选择、四种使用场景、watermarks 配置以及插件内部的实现原理帮助你一次性把 Storybook 组件测试覆盖率跑起来并看懂结果。一、为什么要给 Storybook 组件测试加覆盖率覆盖率Test coverage衡量的是现有测试是否充分覆盖了你的代码它会标记代码中哪些条件、逻辑分支、函数和变量已经被测试触达哪些还没有。覆盖率测试把被插桩instrumented的代码与一组行业公认的最佳实践进行比对相当于测试套件的最后一道 QA 防线用于持续提升测试质量。每个项目的覆盖率报告形态各不相同但有两类信息最值得关注整体的行/分支覆盖率——作为项目健康度的高层体检指标未被覆盖的具体行/分支——这些是潜在的测试缺口通常意味着对应代码路径从未被执行过。在 Storybook 中当你用 Vitest 插件运行组件测试时它可以顺带生成覆盖率报告并把结果汇总到测试面板testing widget中直观展示被测 Story 覆盖了百分之多少的语句。完整流程请参考 docs/writing-tests/test-coverage.mdx。提示如果你无法使用 Vitest 插件仍可通过 test-runner 生成代码覆盖率参见 test-runner 文档中的 Generate code coverage 一节。二、前置条件Vitest 插件与覆盖率开关覆盖率功能内建于 Vitest 插件之中启用后会在运行项目组件测试时自动计算。启用方式很简单在 Storybook 的测试面板testing widget中勾选coverage复选框即可。从源码看覆盖率开关是插件全局状态的组成部分。constants.ts 中插件初始状态为config: { coverage: false, a11y: false }勾选开关后该状态被置为true并随测试运行请求一同传递。测试面板组件 TestProviderRender.tsx 中对应的复选框事件会把coverage配置写入 store。关键点在覆盖率真正开始计算之前你往往需要先安装一个与所选覆盖率提供器coverage provider对应的支持包——这正是本文要重点讲解的一步安装命令见下文。三、核心步骤安装覆盖率支持包coverage providerVitest 支持两种覆盖率计算引擎provider你需要按需安装其一Provider说明对应 npm 包v8基于 V8 引擎内置的 JavaScript 代码覆盖率能力是默认选项速度快、零额外依赖vitest/coverage-v8Istanbul基于 Istanbul 插桩工具链兼容性更广常用于传统工作流vitest/coverage-istanbul对应原始文档片段 docs/_snippets/vitest-plugin-install-coverage-support-packages.md 给出了三种包管理器的完整安装命令均安装为 devDependenciesnpm# For v8 npm install --save-dev vitest/coverage-v8 # For istanbul npm install --save-dev vitest/coverage-istanbulpnpm# For v8 pnpm add --save-dev vitest/coverage-v8 # For istanbul pnpm add --save-dev vitest/coverage-istanbulyarn# For v8 yarn add --dev vitest/coverage-v8 # For istanbul yarn add --dev vitest/coverage-istanbul安装时可以二选一也可以同时安装以便随时切换 provider。如果你不装支持包就启用覆盖率插件会给出明确提示在 vitest-manager.ts 的启动逻辑中当 Vitest 抛出与 coverage 相关的错误时插件会解析错误信息判断缺少的是vitest/coverage-v8还是vitest/coverage-istanbul并追加提示文案Please install the vitest/coverage-{package} package to collect coverage。此外插件的 postinstall.ts 会在安装后检查这两个支持包是否已安装如果检测到都没有会打印提示并默认尝试加入vitest/coverage-v8以启用覆盖率报告。也就是说装好支持包后覆盖率能力即随 Vitest 插件就绪。四、四种使用场景UI、CLI、编辑器与 CI因为覆盖率内建于 Vitest 插件所以你在任何运行测试的地方都能使用它。1. Storybook UI测试面板在 Storybook UI 中启用覆盖率后运行测试结束测试面板会汇总显示被测 Story 覆盖的语句百分比该百分比是否满足 watermarks 阈值红色/橙色/绿色三档状态。同时完整的覆盖率报告会发布在运行中 Storybook 的/coverage/index.html路由上。报告是可交互的点击任意组件即可查看其源码逐行分辨哪些代码已被测试覆盖、哪些没有。从源码看这条路由由 preset.ts 提供插件把覆盖率报告目录解析到 Storybook 缓存目录resolvePathInStorybookCache(COVERAGE_DIRECTORY)其中 constants.ts 定义COVERAGE_DIRECTORY coverage创建目录后以静态服务方式映射到/coverage端点。测试面板中Open coverage report链接即指向该地址见 TestProviderRender.tsx。⚠️UI 中覆盖率的三点重要限制覆盖率只基于你编写的 Story计算不包含项目中其他 Vitest 测试只能针对项目全部 Story计算不支持单个 Story 或 Story 分组watch 模式监听模式下不计算覆盖率——启用覆盖率时开启 watch 会使其失效。2. CLI命令行与 Storybook Test 的其他能力一样覆盖率构建在 Vitest 之上因此可以直接使用 Vitest CLI 生成报告。假设你的 package.json 中有如下脚本{ scripts: { test-storybook: vitest --projectstorybook } }那么只需追加--coverage参数对应文档片段 docs/_snippets/vitest-plugin-run-with-coverage.mdnpmnpm run test-storybook -- --coveragepnpmpnpm run test-storybook --coverageyarnyarn test-storybook --coverage报告默认保存在项目配置的 coverage 报告目录./coverageVitest 默认值中。提示上述命令只统计你编写的 Story 的覆盖率而非整个代码库。由于覆盖率在纳入项目全部测试时最准确也可以运行npx vitest --coverage对项目所有测试计算覆盖率。3. 编辑器扩展IDE覆盖率同样可通过 Vitest 的 IDE 集成如 VSCode 的 Vitest 扩展使用直接在编辑器内计算并展示覆盖率结果。需要注意的是编辑器中的覆盖率包含项目中所有测试而不只是你编写的 Story。4. CI 流水线在 CI 中生成覆盖率报告直接复用 CLI 方式即可。下面是文档中给出的一个简化版 GitHub Actions 工作流示例name: Storybook Tests on: push jobs: test: steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20.x - name: Install dependencies run: yarn # This will run all Vitest tests, including Storybook tests - name: Run tests run: yarn test --coverage这里刻意运行全部测试yarn test而非仅 Storybook 测试yarn test-storybook原因同上覆盖率报告在纳入项目所有测试时最准确。UI 中查看 Storybook 专属覆盖率很有价值但 CI 输出更应反映项目的整体覆盖情况。五、配置详解Provider 与 WatermarksCoverage provider 选择通过 Vitest 配置中的coverage.provider选项可切换计算引擎v8 为默认值import { defineConfig } from vitest/config; export default defineConfig({ // ... test: { // ... coverage: { // ... provider: istanbul, // v8 is the default }, }, });Watermarks覆盖率阈值两个 provider 都支持 watermarks——即覆盖率阈值low watermark 是通过测试所需的最低覆盖率high watermark 是被认定为良好的最低覆盖率介于两者之间的覆盖率被认为可接受但不理想。测试面板中的覆盖率汇总会展示语句覆盖百分比以及是否达到 watermark 阈值图标颜色三档低于 low watermark红色negative介于 low 与 high 之间橙色warning高于 high watermark绿色positive默认阈值为statements: [50, 80]低 50、高 80可在 Vitest 配置中调整import { defineConfig } from vitest/config; export default defineConfig({ // ... test: { // ... coverage: { // ... watermarks: { // These are the default values statements: [50, 80], }, }, }, });这套三档状态的判定逻辑在插件源码中有直接实现coverage-reporter.ts 的自定义报告器在汇总节点上读取语句覆盖率百分比缺省时回退到 Vitest 默认 watermarks[50, 80]然后按percentage lowWatermark → negative、percentage highWatermark → warning、否则positive三档输出状态再通过testManager.onCoverageCollected写入测试面板状态见 test-manager.ts。其他配置选项更多 coverage 配置项请查阅 Vitest 官方文档的 coverage 章节。需要特别注意的是在 Storybook UI 中计算覆盖率时以下选项始终被忽略enabledcleancleanOnRerunreportOnFailurereporterreportsDirectory这一点从 vitest-manager.ts 可以印证插件从 Storybook UI 启动 Vitest 时会强制覆盖这些选项——例如固定enabled: true、clean: true、cleanOnRerun: true、reportOnFailure: true把 reporter 固定为 HTML 报告器加 Storybook 自定义覆盖率报告器并把reportsDirectory指向 Storybook 缓存目录以便映射到/coverage路由。也就是说UI 场景下这些选项由插件接管你在配置文件中的同名设置不会生效。六、源码级原理覆盖率在插件中如何流动围绕覆盖率支持包安装这一步插件内部有完整闭环理解它有助于排查问题开关与请求UI 勾选 coverage 后状态写入 storeconstants.ts测试运行请求携带coverage: true。启动/重启 Vitest只有当启用了覆盖率、且非 watch 模式、且是全量非聚焦测试时覆盖率才会真正启用vitest-manager.ts。聚焦到单个 Story 运行或 watch 模式下会绕过覆盖率这正是文档中三项限制的实现根源。对应地test-manager.test.ts 中有启用覆盖率时需重启 Vitest以及聚焦测试不重启的用例验证。缺失支持包的兜底若未安装vitest/coverage-v8/vitest/coverage-istanbulVitest 抛错后插件解析错误信息并给出请安装对应包的明确提示vitest-manager.ts。汇总与展示自定义覆盖率报告器coverage-reporter.ts通过storybook/addon-vitest/internal/coverage-reporter入口导出见 package.json在报告汇总节点计算语句百分比与三档状态推送至测试面板HTML 报告则由 preset 映射到/coverage/index.html供交互式查看。排除干扰项插件在configureVitest阶段会把storybook-static目录加入 coverage 排除列表避免构建产物污染覆盖率统计vitest-plugin/index.ts。七、常见问题与最佳实践小结启用覆盖率却报错提示缺少包按上文命令安装vitest/coverage-v8默认 provider或vitest/coverage-istanbul切换 provider 时即可解决无需其他配置。报告一直显示 0% 或不更新检查是否处于 watch 模式watch 下不计算覆盖率以及是否只聚焦运行了单个 Story聚焦运行同样不计覆盖率。UI 报告与实际 CI 数字不一致属正常现象——UI 只统计 Story 覆盖CI 中的npx vitest --coverage统计项目全部测试两者口径不同。想要更完整的覆盖率在 CI 中运行全部测试而非仅 Storybook 测试并在vitest.config.ts中通过watermarks设定可接受的语句/分支/函数/行覆盖率门槛让覆盖率从参考指标升级为质量门禁。按照本文的步骤安装支持包、勾选覆盖率开关并选择合适的 provider你就能在 Storybook 测试面板、/coverage/index.html、终端与 CI 中同时获得组件的覆盖率视图把组件到底测没测全变成一目了然的事实。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考