Test Configuration

Configure bun test behavior using bunfig.toml and command-line flags, including timeouts, preload scripts, coverage, and reporters.

Configure bun test via bunfig.toml and command-line flags. CLI flags always take precedence over configuration file values.

bunfig.toml

Add a [test] section to your bunfig.toml file to configure the test runner:

bunfig.toml

[test]
timeout = 5000
preload = ["./setup.ts"]

Test discovery

root

Set the root directory for test file scanning. By default, Bun scans from the current working directory.

bunfig.toml

[test]
root = "src"

pathIgnorePatterns

Exclude files and directories from test discovery using glob patterns. Matched directories are pruned during scanning — their contents are never traversed.

bunfig.toml

[test]
pathIgnorePatterns = [
  "vendor/**",
  "submodules/**",
  "fixtures/**",
  "e2e/**"
]

This is equivalent to the --path-ignore-patterns CLI flag. Note that CLI flags override the config file value entirely — they are not merged.

Preload scripts

Run setup scripts before any test files with preload. This is the recommended way to configure global state, mocks, or DOM environments.

bunfig.toml

[test]
preload = ["./setup.ts", "./global-mocks.ts"]

Equivalent CLI usage:

bun test --preload ./setup.ts --preload ./global-mocks.ts

Example setup file

setup.ts

import { beforeAll, afterAll } from "bun:test";

beforeAll(async () => {
  await connectTestDatabase();
});

afterAll(async () => {
  await disconnectTestDatabase();
});

Example global mocks file

global-mocks.ts

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: "mocked" })),
}));

Timeouts

Default timeout

Set the default timeout (in milliseconds) for all tests. Individual tests can override this with a third argument to test().

bunfig.toml

[test]
timeout = 10000  # 10 seconds; default is 5000

Use 0 or Infinity in test() to disable timeout for a specific test:

test("no timeout", async () => {
  await longRunningOperation();
}, 0);

Environment variables

Bun automatically loads .env files from the project root. For test-specific variables, create a .env.test file and load it explicitly:

.env.test

NODE_ENV=test
DATABASE_URL=postgresql://localhost:5432/test_db
LOG_LEVEL=error

bun test --env-file=.env.test

bun test automatically sets NODE_ENV to "test" unless it is already defined in the environment or an .env file.

TypeScript

Bun compiles TypeScript natively — no extra configuration is needed. To use a custom tsconfig.json for tests:

bun test --tsconfig-override ./tsconfig.test.json

Test execution settings

randomize and seed

Run tests in random order to detect hidden dependencies:

bunfig.toml

[test]
randomize = true
seed = 2444615283  # optional: makes the order reproducible

retry

Set a global retry count for flaky tests:

bunfig.toml

[test]
retry = 3

rerunEach

Re-run each test file multiple times to detect non-deterministic failures:

bunfig.toml

[test]
rerunEach = 3

concurrentTestGlob

Run test files matching a glob pattern with concurrent execution enabled automatically:

bunfig.toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"

smol

Reduce memory usage during test runs (useful in memory-constrained CI environments):

bunfig.toml

[test]
smol = true

Reporters

Configure the JUnit XML reporter output path in bunfig.toml:

bunfig.toml

[test.reporter]
junit = "./reports/junit.xml"

Equivalent CLI usage:

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

Coverage

Enable coverage reporting and configure thresholds:

bunfig.toml

[test]
coverage = true
coverageReporter = ["text", "lcov"]
coverageDir = "./coverage"
coverageThreshold = { lines = 0.85, functions = 0.90, statements = 0.80 }
coverageSkipTestFiles = true
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "generated/**",
  "vendor/**"
]

See Code Coverage for full documentation.

Install settings inheritance

bun test inherits relevant settings from the [install] section of bunfig.toml, including registry, prefer, and exact. This matters when tests trigger auto-installs or interact with a private registry.

bunfig.toml

[install]
registry = "https://npm.company.com/"
prefer = "offline"

[test]
coverage = true
timeout = 10000

Complete example

bunfig.toml

[install]
registry = "https://registry.npmjs.org/"
exact = true

[test]
# Discovery
root = "src"
preload = ["./setup.ts", "./global-mocks.ts"]
pathIgnorePatterns = ["vendor/**", "submodules/**"]

# Execution
timeout = 10000
smol = true
randomize = true
retry = 3

# Coverage
coverage = true
coverageReporter = ["text", "lcov"]
coverageDir = "./coverage"
coverageThreshold = { lines = 0.85, functions = 0.90, statements = 0.80 }
coverageSkipTestFiles = true
coveragePathIgnorePatterns = ["**/*.spec.ts", "generated/**"]

# Reporter
[test.reporter]
junit = "./reports/junit.xml"