bun.sh/docs/cli/test.md

Bun ships with a fast, built-in, Jest-compatible test runner. Tests are executed with 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

{% callout %} Bun aims for compatibility with Jest, but not everything is implemented. To track compatibility, see this tracking issue. {% /callout %}

Run tests

$ bun test

Tests are written in JavaScript or TypeScript with a Jest-like API. Refer to Writing tests for full documentation.

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}
• *_test.{js|jsx|ts|tsx}
• *.spec.{js|jsx|ts|tsx}
• *_spec.{js|jsx|ts|tsx}

You can filter the set of test files to run by passing additional positional arguments to bun test. Any test file with a path that matches one of the filters will run. Commonly, these filters will be 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 for details), then runs all tests. If a test fails, the test runner will exit with a non-zero exit code.

Timeouts

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

# default value is 5000
$ bun test --timeout 20

Rerun tests

Use the --rerun-each flag to run each test multiple times. This is useful for detecting flaky or non-deterministic test failures.

$ bun test --rerun-each 100

Bail out with --bail

Use the --bail flag to abort the test run early after a pre-determined number of test failures. By default Bun will run all tests and report all failures, but sometimes in CI environments it's preferable to terminate earlier to reduce CPU usage.

# bail after 1 failure
$ bun test --bail

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

Watch mode

Similar to bun run, you can pass the --watch flag to bun test to watch for changes and re-run tests.

$ bun test --watch

Lifecycle hooks

Bun supports the following lifecycle hooks:

Hook	Description
beforeAll	Runs once before all tests.
beforeEach	Runs before each test.
afterEach	Runs after each test.
afterAll	Runs once after all tests.

These hooks can be define inside test files, or in a separate file that is preloaded with the --preload flag.

$ bun test --preload ./setup.ts

See Test > Lifecycle for complete documentation.

Mocks

{% callout %} Module mocking (jest.mock()) is not yet supported. Track support for it here. {% /callout %}

Create mock functions with the mock function. Mocks are automatically reset between tests.

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

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

Alternatively, you can use jest.fn(), it behaves identically.

- 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 Test > Mocks for complete documentation.

Snapshot testing

Snapshots are supported by bun test.

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

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

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

$ bun test --update-snapshots

See Test > Snapshots for complete documentation.

UI & DOM testing

Bun is compatible with popular UI testing libraries:

• HappyDOM
• DOM Testing Library
• React Testing Library

See Test > DOM Testing for complete documentation.

Performance

Bun's test runner is fast.

{% image src="/images/buntest.jpeg" caption="Running 266 React SSR tests faster than Jest can print its version number." /%}