# Test configuration (/docs/test/configuration)

<!-- agent-signals: reading_time_min: 7 · est_tokens: 2984 · updated: 2026-07-28 -->
Related: [Writing tests](/docs/test/writing-tests.md), [Runtime behavior](/docs/test/runtime-behavior.md), [Finding tests](/docs/test/discovery.md), [Lifecycle hooks](/docs/test/lifecycle.md), [Mocks](/docs/test/mocks.md), [Snapshots](/docs/test/snapshots.md)

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

## Configuration File [#configuration-file]

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

```toml title="bunfig.toml" icon="settings"
[test]
# Options go here
```

## Test Discovery [#test-discovery]

### root [#root]

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

```toml title="bunfig.toml" icon="settings"
[test]
root = "src"  # Only scan for tests in the src directory
```

#### Examples [#examples]

```toml title="bunfig.toml" icon="settings"
[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 [#preload-scripts]

The `preload` option loads scripts before the tests run:

```toml title="bunfig.toml" icon="settings"
[test]
preload = ["./test-setup.ts", "./global-mocks.ts"]
```

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

```bash terminal icon="terminal"
bun test --preload ./test-setup.ts --preload ./global-mocks.ts
```

#### Common Preload Use Cases [#common-preload-use-cases]

```ts title="test-setup.ts" icon="/icons/typescript.svg"
// Global test setup
import { beforeAll, afterAll } from "bun:test";

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

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

```ts title="global-mocks.ts" icon="/icons/typescript.svg"
// 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 [#path-ignore-patterns]

`pathIgnorePatterns` excludes files and directories from test discovery entirely, using glob patterns. Unlike `coveragePathIgnorePatterns`, which only affects coverage reports, `pathIgnorePatterns` prevents matching paths from being discovered and run 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.

```toml title="bunfig.toml" icon="settings"
[test]
# Single pattern
pathIgnorePatterns = "vendor/**"

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

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

```bash terminal icon="terminal"
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 [#common-use-cases]

```toml title="bunfig.toml" icon="settings"
[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/**"
]
```

<Note>
  Command-line `--path-ignore-patterns` flags override the `bunfig.toml` value entirely -- the two are not merged.
</Note>

## Reporters [#reporters]

### JUnit Reporter [#junit-reporter]

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

```toml title="bunfig.toml" icon="settings"
[test.reporter]
junit = "path/to/junit.xml"  # Output path for JUnit XML report
```

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

```bash terminal icon="terminal"
# Equivalent command line usage
bun test --reporter=junit --reporter-outfile=./junit.xml
```

#### Multiple Reporters [#multiple-reporters]

You can use multiple reporters simultaneously:

```bash terminal icon="terminal"
# CLI approach
bun test --reporter=junit --reporter-outfile=./junit.xml

# Config file approach
```

```toml title="bunfig.toml" icon="settings"
[test.reporter]
junit = "./reports/junit.xml"

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

## Memory Usage [#memory-usage]

### smol Mode [#smol-mode]

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

```toml title="bunfig.toml" icon="settings"
[test]
smol = true  # Reduce memory usage during test runs
```

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

```bash terminal icon="terminal"
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 [#test-execution]

### concurrentTestGlob [#concurrenttestglob]

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

```toml title="bunfig.toml" icon="settings"
[test]
concurrentTestGlob = "**/concurrent-*.test.ts"  # Run files matching this pattern concurrently
```

Test files matching the pattern behave as if the `--concurrent` flag was passed: 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 [#randomize]

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

```toml title="bunfig.toml" icon="settings"
[test]
randomize = true
```

#### seed [#seed]

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

```toml title="bunfig.toml" icon="settings"
[test]
randomize = true
seed = 2444615283
```

#### retry [#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).

```toml title="bunfig.toml" icon="settings"
[test]
retry = 3
```

The `--retry` CLI flag overrides this setting.

#### rerunEach [#reruneach]

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

```toml title="bunfig.toml" icon="settings"
[test]
rerunEach = 3
```

## Coverage Options [#coverage-options]

### Basic Coverage Settings [#basic-coverage-settings]

```toml title="bunfig.toml" icon="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 [#skip-test-files-from-coverage]

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

```toml title="bunfig.toml" icon="settings"
[test]
coverageSkipTestFiles = true  # Exclude test files from coverage reports
```

### Coverage Thresholds [#coverage-thresholds]

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

```toml title="bunfig.toml" icon="settings"
[test]
# Simple threshold - applies to lines, functions, and statements
coverageThreshold = 0.8

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

Setting any of these enables `fail_on_low_coverage`, causing the test run to fail if coverage is below the threshold.

#### Threshold Examples [#threshold-examples]

```toml title="bunfig.toml" icon="settings"
[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
  statements = 0.80  # 80% statement coverage
}
```

### Coverage Path Ignore Patterns [#coverage-path-ignore-patterns]

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

```toml title="bunfig.toml" icon="settings"
[test]
# Single pattern
coveragePathIgnorePatterns = "**/*.spec.ts"

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

Files matching any of these patterns are excluded from coverage calculation and reporting. See [Code coverage](/test/code-coverage).

#### Common Ignore Patterns [#common-ignore-patterns]

```toml title="bunfig.toml" icon="settings"
[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 [#sourcemap-handling]

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

```toml title="bunfig.toml" icon="settings"
[test]
coverageIgnoreSourcemaps = true  # Don't use sourcemaps for coverage analysis
```

<Warning>
  When using this option, you probably want to stick a `// @bun` comment at the top of the source file to opt out of the
  transpilation process.
</Warning>

## Install Settings Inheritance [#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.

```toml title="bunfig.toml" icon="settings"
[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 [#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:

```ini title=".env.test" icon="settings"
NODE_ENV=test
DATABASE_URL=postgresql://localhost:5432/test_db
LOG_LEVEL=error
```

## Complete Configuration Example [#complete-configuration-example]

An example showing the available test configuration options:

```toml title="bunfig.toml" icon="settings"
[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, statements = 0.80 }
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 [#cli-override-behavior]

Command-line options always override configuration file settings:

```toml title="bunfig.toml" icon="settings"
[test]
coverage = false
```

```bash terminal icon="terminal"
# This CLI flag overrides the config file
bun test --coverage
# coverage will be enabled
```