bun-test-basics

Bun のテストの基本

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

クイックスタート

# Run all tests
bun test

# Run specific file
bun test ./test/math.test.ts

# Run tests matching pattern
bun test --test-name-pattern "addition"

テストの作成

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

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

describe("math", () => {
  test("addition", () => {
    expect(1 + 1).toBe(2);
  });

  test("subtraction", () => {
    expect(5 - 3).toBe(2);
  });
});

テストファイルのパターン

Bun は、次のパターンに一致するテストファイルを検出します。

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

テスト修飾子

// Skip a test
test.skip("not ready", () => {
  // won't run
});

// Only run this test
test.only("focus on this", () => {
  // other tests won't run
});
// NOTE: in Bun 1.3+ `bun test` exits non-zero in CI when a file uses
// `test.only`. Use it for local debugging only — never commit it.

// Placeholder for future test
test.todo("implement later");

// Expected to fail
test.failing("known bug", () => {
  throw new Error("This is expected");
});

パラメーター化テスト

test.each([
  [1, 1, 2],
  [2, 2, 4],
  [3, 3, 6],
])("add(%i, %i) = %i", (a, b, expected) => {
  expect(a + b).toBe(expected);
});

// With objects
test.each([
  { a: 1, b: 2, expected: 3 },
  { a: 5, b: 5, expected: 10 },
])("add($a, $b) = $expected", ({ a, b, expected }) => {
  expect(a + b).toBe(expected);
});

並行テスト

// Run tests in parallel
test.concurrent("async test 1", async () => {
  await fetch("/api/1");
});

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

// Force sequential when using --concurrent
test.serial("must run alone", () => {
  // runs sequentially
});

一般的なマッチャー

// Equality
expect(value).toBe(4);           // Strict equality
expect(obj).toEqual({ a: 1 });   // Deep equality
expect(value).toStrictEqual(4);  // Strict + type

// Truthiness
expect(value).toBeTruthy();
expect(value).toBeFalsy();
expect(value).toBeNull();
expect(value).toBeDefined();
expect(value).toBeUndefined();

// Numbers
expect(value).toBeGreaterThan(3);
expect(value).toBeGreaterThanOrEqual(3);
expect(value).toBeLessThan(5);
expect(value).toBeCloseTo(0.3, 5);  // Floating point

// Strings
expect(str).toMatch(/pattern/);
expect(str).toContain("substring");
expect(str).toStartWith("Hello");
expect(str).toEndWith("world");

// Arrays
expect(arr).toContain(item);
expect(arr).toContainEqual({ a: 1 });
expect(arr).toHaveLength(3);

// Objects
expect(obj).toHaveProperty("key");
expect(obj).toHaveProperty("key", value);
expect(obj).toMatchObject({ a: 1 });

// Exceptions
expect(() => fn()).toThrow();
expect(() => fn()).toThrow("message");
expect(() => fn()).toThrow(CustomError);

// Async
await expect(promise).resolves.toBe(value);
await expect(promise).rejects.toThrow();

// Negation
expect(value).not.toBe(5);

CLI オプション

# Timeout per test (default 5000ms)
bun test --timeout 20

# Bail after N failures
bun test --bail
bun test --bail=10

# Watch mode
bun test --watch

# Random order
bun test --randomize
bun test --seed 12345

# Concurrent execution
bun test --concurrent
bun test --concurrent --max-concurrency 4

# Filter by name
bun test -t "pattern"

出力レポーター

# Dots (compact)
bun test --dots

# JUnit XML (CI/CD)
bun test --reporter=junit --reporter-outfile=./results.xml

よくあるエラー

エラー	原因	対処方法
Test timeout	テストが 5 秒を超えている	--timeout を使用するか、最適化してください
No tests found	ファイルパターンが正しくない	ファイル名を確認してください
expect is not defined	インポートが不足している	bun:test からインポートしてください
Assertion failed	テストが失敗している	期待値と実際の値を確認してください

参照を読み込むタイミング

次の場合は references/matchers.md を読み込んでください。

• マッチャーの完全なリファレンスが必要な場合
• カスタムマッチャーのパターンを確認する場合

次の場合は references/cli-options.md を読み込んでください。

• CLI フラグの完全なリファレンスを確認する場合
• 高度な実行オプションを確認する場合