Bun テスト設定

bun test は bunfig.toml ファイルとコマンドラインオプションを介して設定できます。このページでは、bun test の利用可能な設定オプションを文書化しています。

設定ファイル

bunfig.toml ファイルに [test] セクションを追加することで、bun test の動作を設定できます。

toml

[test]
# オプションはここに記載

テスト発見

root

root オプションは、プロジェクトルートからスキャンするデフォルトの動作を上書きして、テスト発見用のルートディレクトリを指定します。

toml

[test]
root = "src"  # src ディレクトリでのみテストをスキャン

これは以下の場合に役立ちます。

テスト発見を特定のディレクトリに制限する
プロジェクトの特定の部分をテストスキャンから除外する
テストを特定のサブディレクトリ構造に整理する

例

toml

[test]
# src ディレクトリでのみテストを実行
root = "src"

# 特定のテストディレクトリでテストを実行
root = "tests"

# 複数の特定のディレクトリでテストを実行（現在はサポートされていません - 代わりにパターンを使用）
# 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("デフォルトタイムアウトを使用", () => {
  // テスト実装
});

// このテストはデフォルトタイムアウトを上書き
test("カスタムタイムアウト", () => {
  // テスト実装
}, 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

再現可能なランダムなテスト順序のために 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/**"
]

ソースマップ処理

内部的には、Bun はすべてのファイルをトランスパイルします。つまり、コードカバレッジもレポートされる前にソースマップを通過する必要があります。この動作をオプトアウトできるようにフラグとして公開していますが、トランスパイルプロセス中に Bun がコードを移動して変数名を変更する可能性があるため、混乱を招く可能性があります。このオプションは、カバレッジの問題をデバッグする場合に最も役立ちます。

toml

[test]
coverageIgnoreSourcemaps = true  # カバレッジ分析にソースマップを使用しない

インストール設定の継承

bun test コマンドは、bunfig.toml の [install] セクションから関連するネットワークおよびインストール設定（レジストリ、cafile、prefer、exact など）を継承します。これは、テストがプライベートレジストリと対話する必要がある場合や、テスト実行中にトリガーされるインストール動作が必要な場合に重要です。

toml

[install]
# これらの設定は bun test によって継承されます
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 になり、coverage は有効になります

条件付き設定

異なる環境に対して異なる設定を使用できます。

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 ​

カバレッジオプション ​

基本的なカバレッジ設定 ​

カバレッジからテストファイルをスキップ ​

カバレッジしきい値 ​

しきい値の例 ​

カバレッジパス無視パターン ​

一般的な無視パターン ​

ソースマップ処理 ​

インストール設定の継承 ​

環境変数 ​

設定の完全な例 ​

CLI 上書き動作 ​

条件付き設定 ​

検証とトラブルシューティング ​

無効な設定 ​

一般的な設定の問題 ​

設定のデバッグ ​

設定ファイル

テスト発見

root

例

プリロードスクリプト

一般的なプリロードの使用例

タイムアウト

デフォルトタイムアウト

レポーター

JUnit レポーター

複数のレポーター

メモリ使用量

smol モード

テスト実行

concurrentTestGlob

randomize

seed

rerunEach

カバレッジオプション

基本的なカバレッジ設定

カバレッジからテストファイルをスキップ

カバレッジしきい値

しきい値の例

カバレッジパス無視パターン

一般的な無視パターン

ソースマップ処理

インストール設定の継承

環境変数

設定の完全な例

CLI 上書き動作

条件付き設定

検証とトラブルシューティング

無効な設定

一般的な設定の問題

設定のデバッグ