Bun ships with a fast, built-in, Jest-compatible test runner. Tests run in the Bun runtime and support the following features.

• TypeScript and JSX
• Lifecycle hooks
• Snapshot testing
• UI & DOM testing
• Watch mode with --watch
• Script pre-loading with --preload

Run testsCopy Anchor Link

bun test

Tests are written in JavaScript or TypeScript with a Jest-like API. See Writing tests.

Copy Text

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

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

The runner recursively searches the working directory for files that match the following patterns:

• *.test.{js|jsx|ts|tsx|mjs|cjs|mts|cts}
• *_test.{js|jsx|ts|tsx|mjs|cjs|mts|cts}
• *.spec.{js|jsx|ts|tsx|mjs|cjs|mts|cts}
• *_spec.{js|jsx|ts|tsx|mjs|cjs|mts|cts}

To filter the set of test files to run, pass additional positional arguments to bun test. Any test file with a path that matches one of the filters runs. Filters are commonly file or directory names; glob patterns are not yet supported.

bun test <filter> <filter> ...

To filter by test name, use the -t/--test-name-pattern flag.

# run all tests or test suites with "addition" in the name
bun test --test-name-pattern addition

To run a specific file in the test runner, make sure the path starts with ./ or / to distinguish it from a filter name.

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

The test runner runs all tests in a single process. It loads all --preload scripts (see Lifecycle), then runs all tests. If a test fails, the test runner exits with a non-zero exit code.

CI/CD integrationCopy Anchor Link

bun test supports a variety of CI/CD integrations.

GitHub ActionsCopy Anchor Link

bun test automatically detects when it’s running inside GitHub Actions and emits GitHub Actions annotations to the console directly.

No configuration is needed, other than installing bun in the workflow and running bun test.

How to install bun in a GitHub Actions workflowCopy Anchor Link

To use bun test in a GitHub Actions workflow, add the following step:

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 # (assuming your project has dependencies)
        run: bun install # You can use npm/yarn/pnpm instead if you prefer
      - name: Run tests
        run: bun test

JUnit XML reports (GitLab, etc.)Copy Anchor Link

To write a JUnit XML report, pass --reporter=junit together with --reporter-outfile.

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

bun test still writes to stdout/stderr as usual, and writes the JUnit XML report to the given path at the end of the run.

JUnit XML is a popular format for reporting test results in CI/CD pipelines.

TimeoutsCopy Anchor Link

Use the --timeout flag to specify a per-test timeout in milliseconds. If a test times out, it is marked as failed. The default value is 5000.

# default value is 5000
bun test --timeout 20

Concurrent test executionCopy Anchor Link

By default, Bun runs all tests sequentially within each test file. Concurrent execution runs async tests in parallel, which speeds up test suites with independent tests.

--concurrent flagCopy Anchor Link

Use the --concurrent flag to run all tests concurrently within their respective files:

bun test --concurrent

When this flag is enabled, all tests run in parallel unless marked with test.serial.

--max-concurrency flagCopy Anchor Link

Control the maximum number of tests running simultaneously with the --max-concurrency flag:

# Limit to 4 concurrent tests
bun test --concurrent --max-concurrency 4

# Default: 20
bun test --concurrent

This helps prevent resource exhaustion when running many concurrent tests. The default value is 20.

test.concurrentCopy Anchor Link

Mark individual tests to run concurrently, even when the --concurrent flag is not used:

Copy Text

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

// These tests run in parallel with each other
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);
});

// This test runs sequentially
test("sequential test", () => {
  expect(1 + 1).toBe(2);
});

test.serialCopy Anchor Link

Force tests to run sequentially, even when the --concurrent flag is enabled:

Copy Text

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

let sharedState = 0;

// These tests must run in order
test.serial("first serial test", () => {
  sharedState = 1;
  expect(sharedState).toBe(1);
});

test.serial("second serial test", () => {
  // Depends on the previous test
  expect(sharedState).toBe(1);
  sharedState = 2;
});

// This test can run concurrently if --concurrent is enabled
test("independent test", () => {
  expect(true).toBe(true);
});

// Chaining test qualifiers
test.failing.each([1, 2, 3])("chained qualifiers %d", input => {
  expect(input).toBe(0); // This test is expected to fail for each input
});

Retry failed testsCopy Anchor Link

Use the --retry flag to automatically retry failed tests up to a given number of times. If a test fails and then passes on a subsequent attempt, it is reported as passing.

bun test --retry 3

Per-test { retry: N } overrides the global --retry value:

// Uses the global --retry value
test("uses global retry", () => {
  /* ... */
});

// Overrides --retry with its own value
test("custom retry", { retry: 1 }, () => {
  /* ... */
});

You can also set this in bunfig.toml:

[test]
retry = 3

Rerun testsCopy Anchor Link

Use the --rerun-each flag to run each test multiple times. This surfaces flaky or non-deterministic test failures.

bun test --rerun-each 100

Randomize test execution orderCopy Anchor Link

Use the --randomize flag to run tests in a random order. This helps detect tests that depend on shared state or execution order.

bun test --randomize

With --randomize, the seed used for randomization is displayed in the test summary:

bun test --randomize

# ... test output ...
 --seed=12345
 2 pass
 8 fail
Ran 10 tests across 2 files. [50.00ms]

Reproducible random order with --seedCopy Anchor Link

Use the --seed flag to specify the randomization seed and reproduce the same test order when debugging order-dependent failures.

# Reproduce a previous randomized run
bun test --seed 123456

The --seed flag implies --randomize, so you don’t need to specify both. The same seed always produces the same test execution order.

Bail out with --bailCopy Anchor Link

Use the --bail flag to abort the test run after a given number of test failures. By default, Bun runs all tests and reports all failures, but in CI it can be preferable to stop early and reduce CPU usage.

# bail after 1 failure
bun test --bail

# bail after 10 failure
bun test --bail=10

Watch modeCopy Anchor Link

Like bun run, bun test accepts the --watch flag to watch for changes and re-run tests.

bun test --watch

Lifecycle hooksCopy Anchor Link

Bun supports the following lifecycle hooks:

Define hooks inside test files, or in a separate file preloaded with the --preload flag.

bun test --preload ./setup.ts

See Lifecycle.

MocksCopy Anchor Link

Create mock functions with the mock function.

Copy Text

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);
});

Alternatively, use jest.fn(); it behaves identically.

Copy Text

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()); 

See Mocks.

Snapshot testingCopy Anchor Link

bun test supports snapshot testing.

Copy Text

// example usage of toMatchSnapshot
import { test, expect } from "bun:test";

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

To update snapshots, use the --update-snapshots flag.

bun test --update-snapshots

See Snapshots.

UI & DOM testingCopy Anchor Link

Bun is compatible with popular UI testing libraries:

• HappyDOM
• DOM Testing Library
• React Testing Library

See DOM testing.

PerformanceCopy Anchor Link

Bun’s test runner is fast.

AI Agent IntegrationCopy Anchor Link

When you use Bun’s test runner with an AI coding assistant, you can enable quieter output that keeps failure details but drops the rest of the noise.

Environment VariablesCopy Anchor Link

Set any of the following environment variables to enable AI-friendly output:

• CLAUDECODE=1 - For Claude Code
• REPL_ID=1 - For Replit
• AGENT=1 - Generic AI agent flag

BehaviorCopy Anchor Link

When an AI agent environment is detected:

• Only test failures are displayed in detail
• Passing, skipped, and todo test indicators are hidden
• Summary statistics remain intact

# Example: Enable quiet output for Claude Code
CLAUDECODE=1 bun test

# Still shows failures and summary, but hides verbose passing test output

CLI UsageCopy Anchor Link

bun test <patterns>

Execution ControlCopy Anchor Link

Test FilteringCopy Anchor Link

ReportingCopy Anchor Link

CoverageCopy Anchor Link

SnapshotsCopy Anchor Link

ExamplesCopy Anchor Link

Run all test files:

bun test

Run all test files with “foo” or “bar” in the file name:

bun test foo bar

Run all test files, only including tests whose name includes “baz”:

bun test --test-name-pattern baz