测试覆盖率

测试覆盖率是测量现有测试是否完全覆盖代码的做法。它标记了代码中哪些条件、逻辑分支、函数和变量正在被测试，哪些没有被测试。

¥Test coverage is the practice of measuring whether existing tests fully cover your code. It marks which conditions, logic branches, functions and variables in your code are and are not being tested.

覆盖率测试根据一组行业认可的最佳实践检查已检测的代码。它们充当 QA 的最后一行，以提高测试套件的质量。

¥Coverage tests examine the instrumented code against a set of industry-accepted best practices. They act as the last line of QA to improve the quality of your test suite.

每个项目的覆盖率报告看起来会有所不同，但需要注意以下几点：

¥Each project’s coverage report will look different, but the important things to note are:

整体行/分支覆盖率，可作为高级健康检查。

¥The overall line/branch coverage, which serves as a high-level health check.
未涵盖的特定行/分支，这些是潜在的测试缺口。

¥Specific lines/branches that are not covered, which are potential test gaps.

使用 Vitest 插件运行组件测试时，它可以生成覆盖率报告。结果汇总在测试小部件中，显示测试故事覆盖的语句百分比。

¥When you run component tests with the Vitest addon, it can generate a coverage report. The result is summarized in the testing widget, showing the percentage of statements covered by your tested stories.

如果你无法在项目中使用 Vitest 插件，你仍然可以使用测试运行器生成代码覆盖率。按照测试运行器文档中的说明，在你的项目中设置带有代码覆盖率的测试运行器。

¥If you cannot use the Vitest addon in your project, you can still generate code coverage using the test-runner. Follow the instructions in the test-runner documentation to set up the test-runner with code coverage in your project.

设置

¥Set up

覆盖率包含在 Vitest 插件中，启用后，将在运行项目的组件测试时进行计算。要启用覆盖率，请选中测试小部件中的覆盖率复选框。

¥Coverage is included in the Vitest addon and, when enabled, will be calculated when running component tests for your project. To enable coverage, check the coverage checkbox in the testing widget.

在计算覆盖率之前，你可能需要安装与你的覆盖率提供程序对应的支持包：

¥Before coverage can be calculated, you may need to install a support package corresponding to your coverage provider:

# For v8
npm install --save-dev @vitest/coverage-v8
 
# For istanbul
npm install --save-dev @vitest/coverage-istanbul

用法

¥Usage

由于覆盖率内置于 Vitest 插件中，因此你可以在运行测试的任何地方使用它。

¥Because coverage is built into the Vitest addon, you can use it everywhere you run your tests.

Storybook UI

在 Storybook UI 中启用覆盖率后，运行测试后，将生成覆盖率报告并将其汇总在测试小部件中。你可以查看测试故事覆盖的语句百分比，以及覆盖率是否符合 watermarks 的要求。

¥When you enable coverage in the Storybook UI, the coverage report will be generated and summarized in the testing widget after you run your tests. You can see the percentage of statements covered by your tested stories, as well as whether the coverage meets the watermarks.

此外，完整的覆盖率报告将通过你正在运行的 Storybook 的 /coverage/index.html 路由提供。

¥Additionally, the full coverage report will be served at the /coverage/index.html route of your running Storybook.

Two browser windows. The frontmost one shows the interactive coverage report generated by the Vitest addon. The background one shows the Storybook sidebar with the coverage summary visible in the testing widget.

报告是交互式的。你可以点击某个组件来查看其源代码，并查看代码的哪些部分已被测试覆盖或未被覆盖：

¥The report is interactive. You can click through to a component to view its source and see which parts of your code are covered by tests or not:

Interactive coverage report generated by the Vitest addon, showing the Calendar component's reported source

请务必了解 Storybook UI 中报告的覆盖率有三个重要限制：

¥It's important to understand that the coverage reported in the Storybook UI has three important limitations:

覆盖率是使用你编写的故事计算的，而不是整个代码库。换句话说，它不会包含任何其他 Vitest 测试。

¥Coverage is calculated using the stories you've written, not the entire codebase. In other words, it will not include any other Vitest tests.
覆盖率只能针对项目中的所有故事进行计算，而不能针对单个故事或一组故事进行计算。

¥Coverage can only be calculated for all stories in your project, not for an individual story or a group of stories.
激活监视模式时不会计算覆盖率。启用覆盖率后，启用监视模式将禁用覆盖率。

¥Coverage is not calculated while watch mode is activated. When coverage is enabled, enabling watch mode will disable coverage.

CLI

与 Storybook Test 的其他功能一样，覆盖率测试基于 Vitest 构建。这意味着你可以使用 Vitest CLI 生成覆盖率报告。

¥Like the rest of Storybook Test, coverage is built on top of Vitest. Which means you can generate a coverage report using the Vitest CLI.

假设你使用如下包脚本运行测试：

¥Assuming you run your tests with a package script like this:

package.json

{
  "scripts": {
    "test-storybook": "vitest --project=storybook"
  }
}

然后，你可以使用以下命令生成覆盖率报告：

¥Then you can generate a coverage report with:

npm run test-storybook -- --coverage

Generated coverage report in terminal

覆盖率报告将保存到项目中的已配置覆盖率报告目录（默认为 ./coverage）。

¥The coverage report will be saved to the configured coverage reports directory (./coverage, by default) in your project.

上述命令将仅计算你编写的故事的覆盖率，而不是整个代码库。

¥The above command will only calculate coverage for the stories you've written, not the entire codebase.

由于覆盖率在涵盖项目所有测试时最为准确，因此你也可以使用以下命令对项目中的所有测试进行覆盖率计算：

¥Because coverage is most accurate when accounting for all tests in your project, you can also run coverage for all tests in your project with:

npx vitest --coverage

编辑器扩展

¥Editor extension

Vitest 的 IDE 集成也提供覆盖率计算功能。你可以直接在编辑器中计算并显示覆盖率结果。

¥Coverage is also available through Vitest's IDE integrations. You can calculate and display coverage results directly in your editor.

Screenshot of test coverage in VSCode

请注意，此覆盖范围将涵盖你项目中的所有测试，而不仅仅是你编写的故事。

¥Note that this coverage will include all tests in your project, not just the stories you've written.

CI

要在 CI 管道中生成覆盖率报告，你可以使用 CLI。

¥To generate coverage reports in your CI pipeline, you can use the CLI.

例如，这是一个简化的 GitHub Actions 工作流程，用于运行测试并生成覆盖率报告：

¥For example, here's a simplified GitHub Actions workflow that runs your tests and generates a coverage report:

.github/workflows/test-storybook.yml

name: Storybook Tests
on: push
jobs:
  test:
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        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）？因为覆盖率报告在涵盖项目中的所有测试（而不仅仅是你编写的故事）时最为准确。

¥Why are we running all tests (yarn test) instead of just the Storybook tests (yarn test-storybook)? Because a coverage report is most accurate when accounting for all tests in your project, not just the stories you've written.

查看 Storybook 特定覆盖范围可能会有所帮助，但在 CI 输出中，你希望看到项目的全面覆盖率。

¥Seeing Storybook-specific coverage can be helpful, but in CI output, you want to see the comprehensive coverage of your project.

有关在 CI 中进行测试的更多信息，请参阅专用指南。

¥For more on testing in CI, see the dedicated guide.

配置

¥Configuration

覆盖率提供程序

¥Coverage provider

你可以通过在 Vitest 配置中设置 coverage.provider 选项来选择使用哪个提供程序（v8（默认）或伊斯坦布尔）进行覆盖率计算：

¥You can choose which provider, v8 (default) or Istanbul, to use for coverage calculation by setting the coverage.provider option in your Vitest config:

vitest.config.ts

import { defineConfig } from 'vitest/config';
 
export default defineConfig({
  // ...
  test: {
    // ...
    coverage: {
      // ...
      provider: 'istanbul', // 'v8' is the default
    },
  },
});

水印

¥Watermarks

两种覆盖率提供程序都支持 watermarks，这是覆盖率的阈值。低水位线是通过测试所需的最低覆盖率，高水位线是被视为良好所需的最低覆盖率。介于低水位线和高水位线之间的覆盖率百分比被认为是可接受的，但并非理想值。

¥Both coverage providers support watermarks, which are threshold values for coverage. The low watermark is the minimum coverage required to pass the test, and the high watermark is the minimum coverage required to be considered good. A coverage percentage between the low and high watermarks will be considered acceptable but not ideal.

在测试小部件中，覆盖率摘要将显示已测试故事所覆盖语句的百分比，以及覆盖率是否符合水印。低于低水位线时，图标为红色；介于低水位线和高水位线之间时，图标为橙色；高于高水位线时，图标为绿色。

¥In the testing widget, the coverage summary will show the percentage of statements covered by your tested stories, as well as whether the coverage meets the watermarks. Below the low watermark, the icon will be red, between the low and high watermarks, it will be orange, and above the high watermark, it will be green.

要配置水印，你可以调整 Vitest 配置：

¥To configure the watermarks, you can adjust the Vitest config:

vitest.config.ts

import { defineConfig } from 'vitest/config';
 
export default defineConfig({
  // ...
  test: {
    // ...
    coverage: {
      // ...
      watermarks: {
        // These are the default values
        statements: [50, 80],
      },
    },
  },
});

附加配置

¥Additional configuration

你可以在 Vitest 文档中找到更多覆盖范围的配置选项。

¥You can find more configuration options for coverage in the Vitest documentation.

在 Storybook UI 中计算覆盖率时，以下选项始终会被忽略：

¥When calculating coverage in the Storybook UI, the following options are always ignored:

enabled
clean
cleanOnRerun
reportOnFailure
reporter
reportsDirectory

更多测试资源

¥More testing resources

Vitest 插件用于在 Storybook 中运行测试

¥Vitest addon for running tests in Storybook
交互测试提供有关用户行为模拟

¥Interaction testing for user behavior simulation
无障碍测试用于可访问性

¥Accessibility testing for accessibility
可视化测试用于外观

¥Visual testing for appearance
快照测试提供有关渲染错误和警告

¥Snapshot testing for rendering errors and warnings
CI 用于在你的 CI/CD 流水线中运行测试

¥CI for running tests in your CI/CD pipeline
端到端测试提供有关模拟真实用户场景

¥End-to-end testing for simulating real user scenarios
单元测试用于功能性

¥Unit testing for functionality
测试运行器用于自动化测试执行

¥Test runner to automate test execution