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 覆蓋行為

條件配置

驗證和故障排除

無效配置

常見配置問題

調試配置