Bun 测试配置

通过 bunfig.toml 文件和命令行选项配置 bun test。本文档介绍了 bun test 的可用配置选项。

配置文件

你可以通过在 bunfig.toml 文件中添加 [test] 部分来配置 bun test 行为：

toml

[test]
# 选项放在这里

测试发现

root

root 选项指定测试发现的根目录，覆盖从项目根目录扫描的默认行为。

toml

[test]
root = "src"  # 仅在 src 目录中扫描测试

这在以下情况下很有用：

将测试发现限制在特定目录
从测试扫描中排除项目的某些部分
在特定的子目录结构中组织测试

示例

toml

[test]
# 仅在 src 目录中运行测试
root = "src"

# 在特定测试目录中运行测试
root = "tests"

# 在多个特定目录中运行测试（当前不支持 - 请使用 patterns）
# root = ["src", "lib"]  # 此语法不受支持

预加载脚本

使用 preload 选项在运行测试之前加载脚本：

toml

[test]
preload = ["./test-setup.ts", "./global-mocks.ts"]

这相当于在命令行上使用 --preload：

bash

bun test --preload ./test-setup.ts --preload ./global-mocks.ts

常见预加载用例

// 全局测试设置
import { beforeAll, afterAll } from "bun:test";

beforeAll(() => {
  // 设置测试数据库
  setupTestDatabase();
});

afterAll(() => {
  // 清理
  cleanupTestDatabase();
});

// 全局模拟
import { mock } from "bun:test";

// 模拟环境变量
process.env.NODE_ENV = "test";
process.env.API_URL = "http://localhost:3001";

// 模拟外部依赖
mock.module("./external-api", () => ({
  fetchData: mock(() => Promise.resolve({ data: "test" })),
}));

超时

默认超时

为所有测试设置默认超时：

toml

[test]
timeout = 10000  # 10 秒（默认为 5000ms）

这适用于所有测试，除非被单个测试超时覆盖：

// 此测试将使用 bunfig.toml 中的默认超时
test("uses default timeout", () => {
  // 测试实现
});

// 此测试覆盖默认超时
test("custom timeout", () => {
  // 测试实现
}, 30000); // 30 秒

报告器

JUnit 报告器

直接在配置文件中配置 JUnit 报告器输出文件路径：

toml

[test.reporter]
junit = "path/to/junit.xml"  # JUnit XML 报告输出路径

这补充了 --reporter=junit 和 --reporter-outfile CLI 标志：

bash

# 等效的命令行用法
bun test --reporter=junit --reporter-outfile=./junit.xml

多个报告器

你可以同时使用多个报告器：

bash

# CLI 方式
bun test --reporter=junit --reporter-outfile=./junit.xml

# 配置文件方式

toml

[test.reporter]
junit = "./reports/junit.xml"

[test]
# 同时启用覆盖率报告
coverage = true
coverageReporter = ["text", "lcov"]

内存使用

smol 模式

专门为测试运行器启用 --smol 内存节省模式：

toml

[test]
smol = true  # 减少测试运行期间的内存使用

这相当于在命令行上使用 --smol 标志：

bash

bun test --smol

smol 模式通过以下方式减少内存使用：

为 JavaScript 堆使用更少的内存
更积极地进行垃圾回收
在可能的情况下减少缓冲区大小

这在以下情况下很有用：

内存有限的 CI 环境
消耗大量内存的大型测试套件
内存受限的开发环境

测试执行

concurrentTestGlob

自动使用并发测试执行运行匹配 glob 模式的测试文件。这对于逐渐将测试套件迁移到并发执行或并发运行特定类型的测试很有用。

toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"  # 并发运行匹配此模式的文件

匹配此模式的测试文件的行为就像传递了 --concurrent 标志一样，并发运行这些文件中的所有测试。这允许你：

逐渐将测试套件迁移到并发执行
并发运行集成测试，同时保持单元测试顺序
将快速并发测试与需要顺序执行的测试分开

指定时，--concurrent CLI 标志将覆盖此设置，强制所有测试并发运行，而不管 glob 模式如何。

randomize

以随机顺序运行测试以识别具有隐藏依赖关系的测试：

toml

[test]
randomize = true

seed

指定种子以重现随机测试顺序。需要 randomize = true：

toml

[test]
randomize = true
seed = 2444615283

rerunEach

多次重新运行每个测试文件以识别不稳定的测试：

toml

[test]
rerunEach = 3

覆盖率选项

基本覆盖率设置

toml

[test]
# 默认启用覆盖率
coverage = true

# 设置覆盖率报告器
coverageReporter = ["text", "lcov"]

# 设置覆盖率输出目录
coverageDir = "./coverage"

从覆盖率中跳过测试文件

从覆盖率报告中排除与测试模式匹配的文件（例如 *.test.ts）：

toml

[test]
coverageSkipTestFiles = true  # 从覆盖率报告中排除测试文件

覆盖率阈值

覆盖率阈值可以指定为数字或具有特定阈值的对象：

toml

[test]
# 简单阈值 - 适用于行、函数和语句
coverageThreshold = 0.8

# 详细阈值
coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }

设置任何这些将启用 fail_on_low_coverage，如果覆盖率低于阈值，测试运行将失败。

阈值示例

toml

[test]
# 要求 90% 的整体覆盖率
coverageThreshold = 0.9

# 对不同指标的不同要求
coverageThreshold = {
  lines = 0.85,      # 85% 行覆盖率
  functions = 0.90,  # 90% 函数覆盖率
  statements = 0.80  # 80% 语句覆盖率
}

覆盖率路径忽略模式

使用 glob 模式从覆盖率报告中排除特定文件或文件模式：

toml

[test]
# 单个模式
coveragePathIgnorePatterns = "**/*.spec.ts"

# 多个模式
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**",
  "vendor/**"
]

与任何这些模式匹配的文件将从覆盖率计算和报告中排除。有关更多详细信息和示例，请参阅覆盖率文档。

常见忽略模式

toml

[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/**"
]

Sourcemap 处理

在内部，Bun 转译每个文件。这意味着代码覆盖率在报告之前也必须经过 sourcemap。我们将其公开为标志，允许你选择退出此行为，但这可能会令人困惑，因为在转译过程中，Bun 可能会移动代码并更改变量名。此选项主要用于调试覆盖率问题。

toml

[test]
coverageIgnoreSourcemaps = true  # 在覆盖率分析中不使用 sourcemaps

安装设置继承

bun test 命令从 bunfig.toml 的 [install] 部分继承相关的网络和安装配置（registry、cafile、prefer、exact 等）。如果测试需要在测试运行期间与私有注册表交互或需要特定的安装行为，这很重要。

toml

[install]
# 这些设置被测试继承
registry = "https://npm.company.com/"
exact = true
prefer = "offline"

[test]
# 特定于测试的配置
coverage = true
timeout = 10000

环境变量

你也可以在配置中设置影响测试行为的环境变量：

toml

[env]
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
LOG_LEVEL = "error"

[test]
coverage = true

完整配置示例

这是一个综合示例，显示了所有可用的测试配置选项：

toml

[install]
# 测试继承的安装设置
registry = "https://registry.npmjs.org/"
exact = true

[env]
# 测试的环境变量
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
API_URL = "http://localhost:3001"
LOG_LEVEL = "error"

[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"

CLI 覆盖行为

命令行选项始终覆盖配置文件设置：

toml

[test]
timeout = 5000
coverage = false

bash

# 这些 CLI 标志覆盖配置文件
bun test --timeout 10000 --coverage
# timeout 将为 10000ms 并且将启用覆盖率

条件配置

你可以为不同环境使用不同的配置：

toml

[test]
# 默认测试配置
coverage = false
timeout = 5000

# CI 环境的覆盖
[test.ci]
coverage = true
coverageThreshold = 0.8
timeout = 30000

然后在 CI 中：

bash

# 使用特定于 CI 的设置
bun test --config=ci

验证和故障排除

无效配置

Bun 将警告无效配置选项：

toml

[test]
invalidOption = true  # 这将生成警告

常见配置问题

路径解析：配置中的相对路径是相对于配置文件位置解析的
模式匹配：Glob 模式使用标准 glob 语法
类型不匹配：确保数值未加引号，除非它们应该是字符串

toml

[test]
# 正确
timeout = 10000

# 不正确 - 将被视为字符串
timeout = "10000"

调试配置

要查看正在使用的配置：

bash

# 显示有效配置
bun test --dry-run

# 查看配置加载的详细输出
bun test --verbose

配置文件 ​

测试发现 ​

root ​

示例 ​

预加载脚本 ​

常见预加载用例 ​

超时 ​

默认超时 ​

报告器 ​

JUnit 报告器 ​

多个报告器 ​

内存使用 ​

smol 模式 ​

测试执行 ​

concurrentTestGlob ​

randomize ​

seed ​

rerunEach ​

覆盖率选项 ​

基本覆盖率设置 ​

从覆盖率中跳过测试文件 ​

覆盖率阈值 ​

阈值示例 ​

覆盖率路径忽略模式 ​

常见忽略模式 ​

Sourcemap 处理 ​

安装设置继承 ​

环境变量 ​

完整配置示例 ​

CLI 覆盖行为 ​

条件配置 ​

验证和故障排除 ​

无效配置 ​

常见配置问题 ​

调试配置 ​

配置文件

测试发现

root

示例

预加载脚本

常见预加载用例

超时

默认超时

报告器

JUnit 报告器

多个报告器

内存使用

smol 模式

测试执行

concurrentTestGlob

randomize

seed

rerunEach

覆盖率选项

基本覆盖率设置

从覆盖率中跳过测试文件

覆盖率阈值

阈值示例

覆盖率路径忽略模式

常见忽略模式

Sourcemap 处理

安装设置继承

环境变量

完整配置示例

CLI 覆盖行为

条件配置

验证和故障排除

无效配置

常见配置问题

调试配置