bun-src/docs/test/configuration.mdx

---
title: "Test configuration"
description: "Configure bun test behavior with bunfig.toml and command-line options"
---

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

## 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

### 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

```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

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

```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

`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.

```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

```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. Bun does not merge the two.
</Note>

## Reporters

### 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

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

### 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

### 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 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:

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

#### seed

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

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

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

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

#### rerunEach

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

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

## Coverage Options

### 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

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

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 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

```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
}
```

### 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/**"
]
```

Bun excludes files matching any of these patterns from coverage calculation and reporting. See [Code coverage](/test/code-coverage).

#### 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

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.

```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

`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

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

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 }
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:

```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
```