Bun 的测试运行器现在支持内置的代码覆盖率报告。这使得查看代码库中有多少被测试覆盖，以及找出当前测试不足的区域变得非常简单。
启用覆盖率
bun:test 支持查看哪些代码行被测试覆盖。要使用此功能，向 CLI 传递 --coverage。它会将覆盖率报告打印到控制台：
bun test --coverage
-------------|---------|---------|-------------------
File | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files | 38.89 | 42.11 |
index-0.ts | 33.33 | 36.84 | 10-15,19-24
index-1.ts | 33.33 | 36.84 | 10-15,19-24
index-10.ts | 33.33 | 36.84 | 10-15,19-24
index-2.ts | 33.33 | 36.84 | 10-15,19-24
index-3.ts | 33.33 | 36.84 | 10-15,19-24
index-4.ts | 33.33 | 36.84 | 10-15,19-24
index-5.ts | 33.33 | 36.84 | 10-15,19-24
index-6.ts | 33.33 | 36.84 | 10-15,19-24
index-7.ts | 33.33 | 36.84 | 10-15,19-24
index-8.ts | 33.33 | 36.84 | 10-15,19-24
index-9.ts | 33.33 | 36.84 | 10-15,19-24
index.ts | 100.00 | 100.00 |
-------------|---------|---------|-------------------
默认启用
要默认启用覆盖率报告，请在你的 bunfig.toml 中添加以下行：
[test]
# 始终启用覆盖率
coverage = true
bunfig.toml 中进行其他配置。
[test]
coverageSkipTestFiles = true # 默认 false
覆盖率阈值
可以在 bunfig.toml 中指定覆盖率阈值。如果测试套件没有达到或超过此阈值，bun test 将以非零退出码退出，表明测试失败。
简单阈值
[test]
# 要求 90% 的行级和函数级覆盖率
coverageThreshold = 0.9
详细阈值
[test]
# 为行和函数设置不同的阈值
coverageThreshold = { lines = 0.9, functions = 0.9, statements = 0.9 }
fail_on_low_coverage，如果覆盖率低于阈值，测试运行将失败。
覆盖率报告器
默认情况下，覆盖率报告会打印到控制台。
对于 CI 环境中的持久化代码覆盖率报告和其他工具，你可以通过 CLI 传递 --coverage-reporter=lcov 选项，或者在 bunfig.toml 中设置 coverageReporter 选项。
[test]
coverageReporter = ["text", "lcov"] # 默认 ["text"]
coverageDir = "path/to/somewhere" # 默认 "coverage"
可用的报告器
| 报告器 | 说明 |
|---|
text | 在控制台打印覆盖率文本摘要 |
lcov | 以 lcov 格式保存覆盖率 |
LCOV 覆盖率报告器
要生成 lcov 报告，可以使用 lcov 报告器。这会在覆盖率目录生成一个 lcov.info 文件。
[test]
coverageReporter = "lcov"
# 或通过 CLI
bun test --coverage --coverage-reporter=lcov
- 代码编辑器：VS Code 扩展可以内联显示覆盖率
- CI/CD 服务：GitHub Actions、GitLab CI、CircleCI
- 覆盖率服务：Codecov、Coveralls
- 集成开发环境（IDE）：WebStorm、IntelliJ IDEA
在 GitHub Actions 中使用 LCOV
.github/workflows/test.yml
name: 带覆盖率的测试
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun test --coverage --coverage-reporter=lcov
- name: 上传覆盖率到 Codecov
uses: codecov/codecov-action@v3
with:
file: ./coverage/lcov.info
从覆盖率中排除文件
跳过测试文件
默认情况下，测试文件本身包含在覆盖率报告中。你可以用以下方式排除它们：
[test]
coverageSkipTestFiles = true # 默认 false
*.test.ts、*.spec.js）从覆盖率报告中排除。
忽略特定路径和模式
你可以使用 coveragePathIgnorePatterns 从覆盖率报告中排除特定文件或文件模式：
[test]
# 单个模式
coveragePathIgnorePatterns = "**/*.spec.ts"
# 多个模式
coveragePathIgnorePatterns = [
"**/*.spec.ts",
"**/*.test.ts",
"src/utils/**",
"*.config.js"
]
collectCoverageFrom 忽略模式。符合任一模式的文件都会被从覆盖率计算和报告中排除，包括文本和 LCOV 输出。
常见用例
[test]
coveragePathIgnorePatterns = [
# 排除工具文件
"src/utils/**",
# 排除配置文件
"*.config.js",
"webpack.config.ts",
"vite.config.ts",
# 排除特定测试模式
"**/*.spec.ts",
"**/*.e2e.ts",
# 排除构建产物
"dist/**",
"build/**",
# 排除生成文件
"src/generated/**",
"**/*.generated.ts",
# 排除第三方/供应商代码
"vendor/**",
"third-party/**"
]
源码映射（Sourcemaps）
内部情况下，Bun 默认转译所有文件，因此 Bun 会自动生成一个内部源码映射，将你原始源码的行映射到 Bun 的内部表示。如果你想禁用此行为，可以设置 test.coverageIgnoreSourcemaps 为 true；除非高级用例，否则很少需要这么做。
[test]
coverageIgnoreSourcemaps = true # 默认 false
使用此选项时，你可能需要在源码文件顶部加上 // @bun 注释，以避免被转译。
覆盖率默认行为
默认情况下，覆盖率报告：
- 排除
node_modules 目录
- 排除 通过非 JS/TS 加载器加载的文件（例如
.css、.txt），除非指定了自定义 JS 加载器
- 包含 测试文件本身（可通过
coverageSkipTestFiles = true 禁用）
- 可以通过
coveragePathIgnorePatterns 进一步排除文件
高级配置
自定义覆盖率目录
[test]
coverageDir = "coverage-reports" # 默认 "coverage"
多个报告器
[test]
coverageReporter = ["text", "lcov"]
针对特定测试模式启用覆盖率
# 仅对特定测试文件运行覆盖率
bun test --coverage src/components/*.test.ts
# 针对名称模式运行覆盖率
bun test --coverage --test-name-pattern="API"
CI/CD 集成
GitHub Actions 示例
.github/workflows/coverage.yml
name: 覆盖率报告
on: [push, pull_request]
jobs:
coverage:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Bun
uses: oven-sh/setup-bun@v2
- name: 安装依赖
run: bun install
- name: 运行带覆盖率的测试
run: bun test --coverage --coverage-reporter=lcov
- name: 上传到 Codecov
uses: codecov/codecov-action@v3
with:
file: ./coverage/lcov.info
fail_ci_if_error: true
GitLab CI 示例
test:coverage:
stage: test
script:
- bun install
- bun test --coverage --coverage-reporter=lcov
coverage: '/Lines\s*:\s*(\d+.\d+)%/'
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage/lcov.info
解析覆盖率报告
文本输出说明
-------------|---------|---------|-------------------
File | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files | 85.71 | 90.48 |
src/ | 85.71 | 90.48 |
utils.ts | 100.00 | 100.00 |
api.ts | 75.00 | 85.71 | 15-18,25
main.ts | 80.00 | 88.89 | 42,50-52
-------------|---------|---------|-------------------
- % Funcs：测试执行过程中调用的函数百分比
- % Lines：测试覆盖的可执行代码行百分比
- 未覆盖的行号：未执行的具体代码行号
目标标准
- 80% 及以上整体覆盖率：通常认为表现良好
- 关键路径 90% 及以上：关键业务逻辑应充分测试
- 工具函数 100%：纯函数和工具函数易于完全覆盖
- UI 组件覆盖率较低：通常可以接受，因多数需要集成测试
最佳实践
注重质量而非数量
test.ts
// 好：测试实际功能
test("calculateTax 应正确处理不同税率", () => {
expect(calculateTax(100, 0.08)).toBe(8);
expect(calculateTax(100, 0.1)).toBe(10);
expect(calculateTax(0, 0.08)).toBe(0);
});
// 不推荐：仅覆盖行数
test("calculateTax 存在", () => {
calculateTax(100, 0.08); // 没有断言！
});
测试边界情况
test.ts
test("用户输入验证", () => {
// 测试正常情况
expect(validateEmail("[email protected]")).toBe(true);
// 测试边界情况以有效提高覆盖率
expect(validateEmail("")).toBe(false);
expect(validateEmail("invalid")).toBe(false);
expect(validateEmail(null)).toBe(false);
});
利用覆盖率发现缺失测试
# 运行覆盖率，找出未测试代码
bun test --coverage
# 关注需要重点关注的文件
bun test --coverage src/critical-module.ts
结合其它质量指标
覆盖率只是一个指标。还应考虑：
- 代码审查质量
- 集成测试覆盖率
- 错误处理测试
- 性能测试
- 类型安全
常见问题排查
某些文件没显示覆盖率
如果某些文件未出现在覆盖率报告中，可能是测试时未导入这些文件。覆盖率只跟踪实际加载的文件。
test.ts
// 确保导入你想测试的模块
import { myFunction } from "../src/my-module";
test("我的函数正常工作", () => {
expect(myFunction()).toBeDefined();
});
覆盖率报告不准确
如果看到的覆盖率报告不符合预期：
- 检查源码映射是否正常工作
- 检查
coveragePathIgnorePatterns 是否配置正确
- 确保测试文件真正导入了要测试的代码
大型代码库性能问题
对于大型项目，收集覆盖率可能会导致测试变慢：
[test]
# 排除不需要覆盖率的大型目录
coveragePathIgnorePatterns = [
"node_modules/**",
"vendor/**",
"generated/**"
]
