import Test from "/snippets/cli/test.mdx";

Bun には、高速な組み込みの Jest 互換テストランナーが付属しています。テストは Bun ランタイムで実行され、次の機能をサポートします。

• TypeScript と JSX
• ライフサイクルフック
• スナップショットテスト
• UI と DOM テスト
• --watch を使用したウォッチモード
• --preload を使用したスクリプト事前読み込み

NOTE

Bun は Jest との互換性を目指していますが、すべてが実装されているわけではありません。互換性を追跡するには、[このトラッキングイシュー](https://github.com/oven-sh/bun/issues/1825) を参照してください。

テストの実行

bun test

テストは Jest ライクな API を使用して JavaScript または TypeScript で記述されます。完全なドキュメントについては、テストの記述 を参照してください。

import { expect, test } from "bun:test";

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

ランナーは、次のパターンに一致するファイルを検索するために、作業ディレクトリを再帰的に検索します。

• *.test.{js|jsx|ts|tsx}
• *_test.{js|jsx|ts|tsx}
• *.spec.{js|jsx|ts|tsx}
• *_spec.{js|jsx|ts|tsx}

bun test に追加の位置引数を渡すことで、実行する テストファイル のセットをフィルタリングできます。パスがフィルターの 1 つに一致するテストファイルは実行されます。一般的に、これらのフィルターはファイルまたはディレクトリ名です。glob パターンはまだサポートされていません。

bun test <filter> <filter> ...

テスト名 でフィルタリングするには、-t/--test-name-pattern フラグを使用します。

# 名前に "addition" を含むすべてのテストを実行
bun test --test-name-pattern addition

テストランナーで特定のファイルを実行するには、フィルター名と区別するためにパスが ./ または / で始まることを確認してください。

bun test ./test/specific-file.test.ts

テストランナーは、すべてのテストを単一のプロセスで実行します。すべての --preload スクリプトを読み込み（詳細は ライフサイクル を参照）、次にすべてのテストを実行します。テストが失敗した場合、テストランナーは 0 以外の終了コードで終了します。

CI/CD 統合

bun test は、さまざまな CI/CD 統合をサポートします。

GitHub Actions

bun test は、GitHub Actions 内で実行されているかどうかを自動的に検出し、GitHub Actions アノテーションをコンソールに直接出力します。

ワークフローで bun をインストールし、bun test を実行する以外に設定は必要ありません。

GitHub Actions ワークフローでの bun のインストール方法

GitHub Actions ワークフローで bun test を使用するには、次のステップを追加します。

jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies # (プロジェクトに依存関係がある場合)
        run: bun install # 必要に応じて npm/yarn/pnpm を使用できます
      - name: Run tests
        run: bun test

これで、GitHub Actions アノテーションが取得できます。

JUnit XML レポート（GitLab など）

bun test を JUnit XML レポーターで使用するには、--reporter=junit を --reporter-outfile と組み合わせて使用できます。

bun test --reporter=junit --reporter-outfile=./bun.xml

これは通常どおり stdout/stderr に出力し続け、テスト実行の最後に JUnit XML レポートを指定されたパスに書き込みます。

JUnit XML は、CI/CD パイプラインでテスト結果をレポートするための人気のある形式です。

タイムアウト

--timeout フラグを使用して、テストごと のタイムアウトをミリ秒単位で指定します。テストがタイムアウトすると、失敗としてマークされます。デフォルト値は 5000 です。

# デフォルト値は 5000
bun test --timeout 20

並行テスト実行

デフォルトでは、Bun は各テストファイル内のすべてのテストを順次実行します。非同期テストを並列で実行するために並行実行を有効にすると、独立したテストを持つテストスイートを大幅に高速化できます。

--concurrent フラグ

--concurrent フラグを使用して、それぞれのファイル内のすべてのテストを並行して実行します。

bun test --concurrent

このフラグが有効な場合、test.serial で明示的にマークされていない限り、すべてのテストは並列で実行されます。

--max-concurrency フラグ

--max-concurrency フラグを使用して、同時に実行されるテストの最大数を制御します。

# 並行テストを 4 つに制限
bun test --concurrent --max-concurrency 4

# デフォルト：20
bun test --concurrent

これにより、多くの並行テストを実行する際のリソース枯渇を防ぎます。デフォルト値は 20 です。

test.concurrent

--concurrent フラグが使用されていない場合でも、個々のテストを並行して実行するようにマークします。

import { test, expect } from "bun:test";

// これらのテストは互いに並列で実行されます
test.concurrent("concurrent test 1", async () => {
  await fetch("/api/endpoint1");
  expect(true).toBe(true);
});

test.concurrent("concurrent test 2", async () => {
  await fetch("/api/endpoint2");
  expect(true).toBe(true);
});

// このテストは順次に実行されます
test("sequential test", () => {
  expect(1 + 1).toBe(2);
});

test.serial

--concurrent フラグが有効な場合でも、テストを順次に実行するように強制します。

import { test, expect } from "bun:test";

let sharedState = 0;

// これらのテストは順序通りに実行する必要があります
test.serial("first serial test", () => {
  sharedState = 1;
  expect(sharedState).toBe(1);
});

test.serial("second serial test", () => {
  // 前のテストに依存
  expect(sharedState).toBe(1);
  sharedState = 2;
});

// --concurrent が有効な場合、このテストは並行して実行できます
test("independent test", () => {
  expect(true).toBe(true);
});

// テスト修飾子のチェーン
test.failing.each([1, 2, 3])("chained qualifiers %d", input => {
  expect(input).toBe(0); // このテストは各入力に対して失敗すると予想されます
});

テストの再実行

--rerun-each フラグを使用して、各テストを複数回実行します。これは、不安定または非決定的なテストの失敗を検出するのに役立ちます。

bun test --rerun-each 100

テスト実行順序のランダム化

--randomize フラグを使用して、テストをランダムな順序で実行します。これは、共有状態または実行順序に依存するテストを検出するのに役立ちます。

bun test --randomize

--randomize を使用すると、ランダム化に使用されたシードがテストサマリーに表示されます。

bun test --randomize

# ... テスト出力 ...
 --seed=12345
 2 pass
 8 fail
Ran 10 tests across 2 files. [50.00ms]

--seed を使用した再現可能なランダム順序

--seed フラグを使用して、ランダム化のシードを指定します。これにより、順序依存の失敗をデバッグするときに、同じテスト順序を再現できます。

# 以前のランダム化実行を再現
bun test --seed 123456

--seed フラグは --randomize を意味するため、両方を指定する必要はありません。同じシード値を使用すると、常に同じテスト実行順序が生成され、テストの相互依存関係によって引き起こされる間欠的な失敗をデバッグしやすくなります。

--bail による早期終了

--bail フラグを使用して、事前に決定された数のテスト失敗後にテスト実行を早期に中止します。デフォルトでは、Bun はすべてのテストを実行し、すべての失敗をレポートしますが、CI 環境では CPU 使用量を削減するために早期に終了する方が望ましい場合があります。

# 1 回の失敗後に中止
bun test --bail

# 10 回の失敗後に中止
bun test --bail=10

ウォッチモード

bun run と同様に、--watch フラグを bun test に渡して、変更を監視し、テストを再実行できます。

bun test --watch

ライフサイクルフック

Bun は、次のライフサイクルフックをサポートしています。

フック	説明
beforeAll	すべてのテストの前に 1 回実行
beforeEach	各テストの前に実行
afterEach	各テストの後に実行
afterAll	すべてのテストの後に 1 回実行

これらのフックは、テストファイル内で定義するか、--preload フラグで事前読み込みされる別のファイルで定義できます。

bun test --preload ./setup.ts

完全なドキュメントについては、テスト > ライフサイクル を参照してください。

モック

mock 関数を使用してモック関数を作成します。

import { test, expect, mock } from "bun:test";
const random = mock(() => Math.random());

test("random", () => {
  const val = random();
  expect(val).toBeGreaterThan(0);
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

または、jest.fn() を使用することもできます。これは同じように動作します。

import { test, expect, mock } from "bun:test"; 
import { test, expect, jest } from "bun:test"; 

const random = mock(() => Math.random()); 
const random = jest.fn(() => Math.random()); 

完全なドキュメントについては、テスト > モック を参照してください。

スナップショットテスト

bun test はスナップショットをサポートしています。

// toMatchSnapshot の使用例
import { test, expect } from "bun:test";

test("snapshot", () => {
  expect({ a: 1 }).toMatchSnapshot();
});

スナップショットを更新するには、--update-snapshots フラグを使用します。

bun test --update-snapshots

完全なドキュメントについては、テスト > スナップショット を参照してください。

UI と DOM テスト

Bun は、人気のある UI テストライブラリと互換性があります。

• HappyDOM
• DOM Testing Library
• React Testing Library

完全なドキュメントについては、テスト > DOM テスト を参照してください。

パフォーマンス

Bun のテストランナーは高速です。

AI エージェント統合

AI コーディングアシスタントで Bun のテストランナーを使用する場合、より静かな出力を有効にして、可読性を向上させ、コンテキストノイズを削減できます。この機能は、重要な失敗情報を保持しながら、テスト出力の詳細を最小限に抑えます。

環境変数

次の環境変数のいずれかを設定して、AI フレンドリーな出力を有効にします。

• CLAUDECODE=1 - Claude Code 用
• REPL_ID=1 - Replit 用
• AGENT=1 - 汎用 AI エージェントフラグ

動作

AI エージェント環境が検出されると。

• テストの失敗のみが詳細に表示されます
• 合格、スキップ、todo テストのインジケーターは非表示になります
• サマリー統計はそのまま残ります

# 例：Claude Code のために静かな出力を有効にする
CLAUDECODE=1 bun test

# 失敗とサマリーは表示されますが、詳細な合格テスト出力は非表示になります

この機能は、テストの失敗の可視性を維持しながら、出力の詳細を削減してコンテキストの効率を向上させる AI 支援開発ワークフローで特に役立ちます。

---