通过 bunfig.toml 文件和命令行选项配置 bun test。本页记录了 bun test 可用的配置选项。
配置文件
你可以通过在 bunfig.toml 文件中添加 [test] 部分来配置 bun test 的行为：
测试发现
root
root 选项指定测试发现的根目录，覆盖默认从项目根目录开始扫描的行为。
[test]
root = "src" # 只在 src 目录内扫描测试
- 限制测试扫描特定目录
- 排除项目中某些部分的测试扫描
- 按特定子目录结构组织测试
时非常有用。
[test]
# 只运行 src 目录中的测试
root = "src"
# 在特定测试目录中运行测试
root = "tests"
# 同时运行多个特定目录中的测试（当前不支持 - 请改用 patterns）
# root = ["src", "lib"] # 此语法不被支持
预加载脚本
使用 preload 选项在运行测试前加载脚本：
[test]
preload = ["./test-setup.ts", "./global-mocks.ts"]
--preload：
bun test --preload ./test-setup.ts --preload ./global-mocks.ts
常见预加载用例
test-setup.ts
// 全局测试设置
import { beforeAll, afterAll } from "bun:test";
beforeAll(() => {
// 设置测试数据库
setupTestDatabase();
});
afterAll(() => {
// 清理
cleanupTestDatabase();
});
global-mocks.ts
// 全局 Mock
import { mock } from "bun:test";
// Mock 环境变量
process.env.NODE_ENV = "test";
process.env.API_URL = "http://localhost:3001";
// Mock 外部依赖
mock.module("./external-api", () => ({
fetchData: mock(() => Promise.resolve({ data: "test" })),
}));
超时时间
默认超时
设置所有测试的默认超时时间：
[test]
timeout = 10000 # 10 秒（默认是 5000 毫秒）
test.ts
// 使用 bunfig.toml 中的默认超时
test("使用默认超时", () => {
// 测试实现
});
// 重写默认超时
test("自定义超时", () => {
// 测试实现
}, 30000); // 30 秒
报告器
JUnit 报告器
在配置文件中直接配置 JUnit 报告器的输出文件路径：
[test.reporter]
junit = "path/to/junit.xml" # JUnit XML 报告的输出路径
--reporter=junit 和 --reporter-outfile 相辅相成：
# 等效的命令行用法
bun test --reporter=junit --reporter-outfile=./junit.xml
多重报告器
你可以同时使用多个报告器：
# 命令行方式
bun test --reporter=junit --reporter-outfile=./junit.xml
# 配置文件方式
[test.reporter]
junit = "./reports/junit.xml"
[test]
# 同时启用覆盖率报告
coverage = true
coverageReporter = ["text", "lcov"]
内存使用
smol 模式
为测试运行器开启 --smol 的节省内存模式：
[test]
smol = true # 在测试运行时减少内存使用
--smol：
smol 模式通过以下方式降低内存占用：
- 使用更小的 JavaScript 堆内存
- 更积极地进行垃圾回收
- 尽可能减少缓冲区大小
适用于：
- 内存有限的 CI 环境
- 占用大量内存的大型测试套件
- 内存受限的开发环境
测试执行
concurrentTestGlob
自动对匹配 glob 模式的测试文件启用并发测试执行。这对逐步迁移测试套件到并发执行或仅让特定测试类型并发运行很有用。
[test]
concurrentTestGlob = "**/concurrent-*.test.ts" # 对匹配此模式的文件并发运行
--concurrent 标志，所有文件中的测试都将并发执行。该特性允许你：
- 逐渐迁移测试套件到并发执行
- 并发执行集成测试，同时保持单元测试顺序执行
- 将快速并发测试与需要顺序执行的测试分开
当命令行指定了 --concurrent 标志时，会覆盖该设置，强制所有测试均并发执行，忽略 glob 模式。
randomize
随机执行测试，用于发现存在隐式依赖的测试：
seed
指定用于可复现随机顺序的种子。需要 randomize = true：
[test]
randomize = true
seed = 2444615283
rerunEach
多次重新运行每个测试文件，用于发现不稳定测试：
覆盖率选项
基础覆盖率设置
[test]
# 默认启用覆盖率
coverage = true
# 设置覆盖率报告类型
coverageReporter = ["text", "lcov"]
# 覆盖率输出目录
coverageDir = "./coverage"
避免测试文件计入覆盖率
排除匹配测试文件模式（如 *.test.ts）的文件不计入覆盖率报告：
[test]
coverageSkipTestFiles = true # 从覆盖率报告中排除测试文件
覆盖率阈值
覆盖率阈值可以用数字或对象形式指定具体阈值：
[test]
# 简单阈值 - 适用于行、函数和语句
coverageThreshold = 0.8
# 详细阈值
coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }
fail_on_low_coverage，即当实际覆盖率低于阈值时，测试运行会失败。
阈值示例
[test]
# 要求全面达到 90% 覆盖率
coverageThreshold = 0.9
# 不同指标不同要求
coverageThreshold = {
lines = 0.85, # 85% 行覆盖率
functions = 0.90, # 90% 函数覆盖率
statements = 0.80 # 80% 语句覆盖率
}
忽略路径模式
使用 glob 模式排除特定文件或文件模式不计入覆盖率报告：
[test]
# 单个模式
coveragePathIgnorePatterns = "**/*.spec.ts"
# 多个模式
coveragePathIgnorePatterns = [
"**/*.spec.ts",
"**/*.test.ts",
"src/utils/**",
"*.config.js",
"generated/**",
"vendor/**"
]
常见忽略模式
[test]
coveragePathIgnorePatterns = [
# 测试文件
"**/*.test.ts",
"**/*.spec.ts",
"**/*.e2e.ts",
# 配置文件
"*.config.js",
"*.config.ts",
"webpack.config.*",
"vite.config.*",
# 构建产物
"dist/**",
"build/**",
".next/**",
# 生成代码
"generated/**",
"**/*.generated.ts",
# 第三方库
"vendor/**",
"third-party/**",
# 不需要测试的工具文件
"src/utils/constants.ts",
"src/types/**"
]
Source Map 处理
Bun 会内部转译所有文件，代码覆盖率也必须经过 source map 映射后才能正确报告。我们暴露了一个开关允许关闭此行为，但部分情况下会比较混乱，因为转译过程中 Bun 可能会移动代码或更改变量名。此选项主要用于调试覆盖率问题。
[test]
coverageIgnoreSourcemaps = true # 不使用 source map 进行覆盖率分析
使用此选项时，建议在源代码文件顶部添加 // @bun 注释，来避免转译过程。
安装设置继承
bun test 会从 bunfig.toml 的 [install] 部分继承相关的网络和安装配置（registry、cafile、prefer、exact 等），这对于测试需要访问私有注册表或在测试运行时需要特定安装行为时非常重要。
[install]
# 这些设置会被 bun test 继承
registry = "https://npm.company.com/"
exact = true
prefer = "offline"
[test]
# 测试专用配置
coverage = true
timeout = 10000
环境变量
测试的环境变量应通过 .env 文件设置。Bun 会自动加载项目根目录下的 .env 文件。对于特定测试环境变量，可以创建 .env.test 文件：
NODE_ENV=test
DATABASE_URL=postgresql://localhost:5432/test_db
LOG_LEVEL=error
--env-file 加载：
bun test --env-file=.env.test
完整配置示例
下面是一个包含所有可用测试配置选项的完整示例：
[install]
# 测试继承的安装设置
registry = "https://registry.npmjs.org/"
exact = true
[test]
# 测试发现
root = "src"
preload = ["./test-setup.ts", "./global-mocks.ts"]
# 执行设置
timeout = 10000
smol = true
# 覆盖率配置
coverage = true
coverageReporter = ["text", "lcov"]
coverageDir = "./coverage"
coverageThreshold = { lines = 0.85, functions = 0.90, statements = 0.80 }
coverageSkipTestFiles = true
coveragePathIgnorePatterns = [
"**/*.spec.ts",
"src/utils/**",
"*.config.js",
"generated/**"
]
# 高级覆盖率设置
coverageIgnoreSourcemaps = false
# 报告器配置
[test.reporter]
junit = "./reports/junit.xml"
命令行覆盖行为
命令行选项总是会覆盖配置文件设置：
[test]
timeout = 5000
coverage = false
# 这些命令行参数会覆盖配置文件
bun test --timeout 10000 --coverage
# timeout 将是 10000 毫秒，覆盖率将被启用
条件配置
你可以针对不同环境使用不同配置：
[test]
# 默认测试配置
coverage = false
timeout = 5000
# CI 环境覆盖
[test.ci]
coverage = true
coverageThreshold = 0.8
timeout = 30000
# 使用 CI 专用配置
bun test --config=ci
验证和故障排除
无效配置
Bun 会对无效配置选项发出警告：
[test]
invalidOption = true # 这将产生警告
常见配置问题
- 路径解析：配置中相对路径是相对于配置文件所在位置解析的
- 模式匹配：Glob 模式使用标准 glob 语法
- 类型不匹配：确保数字值未被引号包裹，除非它们应被视为字符串
[test]
# 正确写法
timeout = 10000
# 错误写法 - 会被当成字符串处理
timeout = "10000"
配置调试
查看实际使用的配置：
# 显示生效配置
bun test --dry-run
# 详细日志显示配置加载过程
bun test --verbose
