Test configuration

Configure bun test with bunfig.toml and command-line options.

Configuration File#

To configure bun test in bunfig.toml, add a [test] section:

[test]
# Options go here

Test Discovery#

root#

The root option sets the directory Bun scans for tests, instead of the project root.

[test]
root = "src"  # Only scan for tests in the src directory

Examples#

[test]
# Only run tests in the src directory
root = "src"

# Run tests in a specific test directory
root = "tests"

# Run tests in multiple specific directories (not currently supported - use patterns instead)
# root = ["src", "lib"]  # This syntax is not supported

Preload Scripts#

The preload option loads scripts before the tests run:

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

This is equivalent to using --preload on the command line:

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

Common Preload Use Cases#

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

beforeAll(() => {
  // Set up test database
  setupTestDatabase();
});

afterAll(() => {
  // Clean up
  cleanupTestDatabase();
});

// Global mocks
import { mock } from "bun:test";

// Mock environment variables
process.env.NODE_ENV = "test";
process.env.API_URL = "http://localhost:3001";

// Mock external dependencies
mock.module("./external-api", () => ({
  fetchData: mock(() => Promise.resolve({ data: "test" })),
}));

Path Ignore Patterns#

pathIgnorePatterns excludes files and directories from test discovery entirely, using glob patterns. Unlike coveragePathIgnorePatterns, which only affects coverage reports, pathIgnorePatterns prevents Bun from discovering matching paths and running them as tests.

Use it when your project contains submodules, vendored code, or other directories with *.test.ts files that you don't want bun test to pick up.

[test]
# Single pattern
pathIgnorePatterns = "vendor/**"

# Multiple patterns
pathIgnorePatterns = [
  "vendor/**",
  "submodules/**",
  "fixtures/**"
]

This is equivalent to using --path-ignore-patterns on the command line:

bun test --path-ignore-patterns 'vendor/**' --path-ignore-patterns 'fixtures/**'

Bun prunes directories matching a pattern during scanning and never traverses their contents, so ignoring a large directory tree is cheap.

Common Use Cases#

[test]
pathIgnorePatterns = [
  # Git submodules with their own test suites
  "submodules/**",

  # Vendored dependencies
  "vendor/**",
  "third-party/**",

  # Test fixtures that look like tests but aren't
  "fixtures/**",
  "**/test-data/**",

  # Integration / E2E tests you want to run separately
  "**/integration/**",
  "e2e/**"
]

Reporters#

JUnit Reporter#

Configure the JUnit reporter output file path directly in the config file:

[test.reporter]
junit = "path/to/junit.xml"  # Output path for JUnit XML report

This complements the --reporter=junit and --reporter-outfile CLI flags:

# Equivalent command line usage
bun test --reporter=junit --reporter-outfile=./junit.xml

Multiple Reporters#

You can use multiple reporters simultaneously:

# CLI approach
bun test --reporter=junit --reporter-outfile=./junit.xml

# Config file approach

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

[test]
# Also enable coverage reporting
coverage = true
coverageReporter = ["text", "lcov"]

Memory Usage#

smol Mode#

Enable the --smol memory-saving mode specifically for the test runner:

[test]
smol = true  # Reduce memory usage during test runs

This is equivalent to using the --smol flag on the command line:

bun test --smol

The smol mode reduces memory usage by:

• Using less memory for the JavaScript heap
• Being more aggressive about garbage collection
• Reducing buffer sizes where possible

Use it in memory-constrained environments, such as CI runners, or for large test suites.

Test execution#

concurrentTestGlob#

Run test files matching a glob pattern with concurrent test execution enabled.

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"  # Run files matching this pattern concurrently

Test files matching the pattern behave as if you passed the --concurrent flag: every test in those files runs concurrently. Use this to migrate a test suite to concurrent execution gradually, or to run one kind of test (say, integration tests) concurrently while the rest stay sequential.

The --concurrent CLI flag overrides this setting, forcing all tests to run concurrently regardless of the glob pattern.

randomize#

Run tests in random order to identify tests with hidden dependencies:

[test]
randomize = true

seed#

Specify a seed for reproducible random test order. Requires randomize = true:

[test]
randomize = true
seed = 2444615283

retry#

Default retry count for all tests. Bun retries a failed test up to this many times. Per-test { retry: N } overrides this value. Default 0 (no retries).

[test]
retry = 3

The --retry CLI flag overrides this setting.

rerunEach#

Re-run each test file multiple times to identify flaky tests:

[test]
rerunEach = 3

Coverage Options#

Basic Coverage Settings#

[test]
# Enable coverage by default
coverage = true

# Set coverage reporter
coverageReporter = ["text", "lcov"]

# Set coverage output directory
coverageDir = "./coverage"

Skip Test Files from Coverage#

Exclude files matching test patterns (for example *.test.ts) from the coverage report:

[test]
coverageSkipTestFiles = true  # Exclude test files from coverage reports

Coverage Thresholds#

Specify the coverage threshold as a single number or as an object with per-metric thresholds:

[test]
# Simple threshold - applies to lines and functions
coverageThreshold = 0.8

# Detailed thresholds
coverageThreshold = { lines = 0.9, functions = 0.8 }

Setting a threshold makes bun test exit with code 1 when coverage is enabled and any file's line or function coverage is below it. Bun accepts the statements key but does not currently enforce it. Outside --parallel, the check only runs when the text reporter is enabled (the default); a run with only the lcov reporter currently exits 0 regardless of the threshold.

Threshold Examples#

[test]
# Require 90% coverage across the board
coverageThreshold = 0.9

# Different requirements for different metrics
coverageThreshold = {
  lines = 0.85,      # 85% line coverage
  functions = 0.90   # 90% function coverage
}

Coverage Path Ignore Patterns#

Exclude specific files or file patterns from coverage reports using glob patterns:

[test]
# Single pattern
coveragePathIgnorePatterns = "**/*.spec.ts"

# Multiple patterns
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**",
  "vendor/**"
]

Bun excludes files matching any of these patterns from coverage calculation and reporting. See Code coverage.

Common Ignore Patterns#

[test]
coveragePathIgnorePatterns = [
  # Test files
  "**/*.test.ts",
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # Configuration files
  "*.config.js",
  "*.config.ts",
  "webpack.config.*",
  "vite.config.*",

  # Build output
  "dist/**",
  "build/**",
  ".next/**",

  # Generated code
  "generated/**",
  "**/*.generated.ts",

  # Vendor/third-party
  "vendor/**",
  "third-party/**",

  # Utilities that don't need testing
  "src/utils/constants.ts",
  "src/types/**"
]

Sourcemap Handling#

Bun transpiles every file, so coverage results pass through sourcemaps before they're reported. coverageIgnoreSourcemaps opts out of this, but the results are confusing: during transpilation, Bun may move code around and rename variables. The option is mostly useful for debugging coverage issues.

[test]
coverageIgnoreSourcemaps = true  # Don't use sourcemaps for coverage analysis

Install Settings Inheritance#

bun test inherits network and installation configuration (such as registry, cafile, prefer, and exact) from the [install] section of bunfig.toml. This matters if your tests reach a private registry or trigger installs during the run.

[install]
# These settings are inherited by bun test
registry = "https://npm.company.com/"
exact = true
prefer = "offline"

[test]
# Test-specific configuration
coverage = true

Environment Variables#

Set environment variables for tests with .env files, which Bun loads from your project root automatically. For test-specific variables, create a .env.test file, which bun test loads automatically:

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

Complete Configuration Example#

An example showing the available test configuration options:

[install]
# Install settings inherited by tests
registry = "https://registry.npmjs.org/"
exact = true

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

# Execution settings
smol = true

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

# Advanced coverage settings
coverageIgnoreSourcemaps = false

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

CLI Override Behavior#

Command-line options always override configuration file settings:

[test]
coverage = false

# This CLI flag overrides the config file
bun test --coverage
# coverage will be enabled