Skip to main content
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"

Build docs developers (and LLMs) love

Get started for freeTalk to us