> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/oven-sh/bun/llms.txt
> Use this file to discover all available pages before exploring further.

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

```toml bunfig.toml theme={null}
[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.

```toml bunfig.toml theme={null}
[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.

```toml bunfig.toml theme={null}
[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.

```toml bunfig.toml theme={null}
[test]
preload = ["./setup.ts", "./global-mocks.ts"]
```

Equivalent CLI usage:

```bash theme={null}
bun test --preload ./setup.ts --preload ./global-mocks.ts
```

### Example setup file

```typescript setup.ts theme={null}
import { beforeAll, afterAll } from "bun:test";

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

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

### Example global mocks file

```typescript global-mocks.ts theme={null}
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()`.

```toml bunfig.toml theme={null}
[test]
timeout = 10000  # 10 seconds; default is 5000
```

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

```typescript theme={null}
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:

```ini .env.test theme={null}
NODE_ENV=test
DATABASE_URL=postgresql://localhost:5432/test_db
LOG_LEVEL=error
```

```bash theme={null}
bun test --env-file=.env.test
```

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

## TypeScript

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

```bash theme={null}
bun test --tsconfig-override ./tsconfig.test.json
```

## Test execution settings

### randomize and seed

Run tests in random order to detect hidden dependencies:

```toml bunfig.toml theme={null}
[test]
randomize = true
seed = 2444615283  # optional: makes the order reproducible
```

### retry

Set a global retry count for flaky tests:

```toml bunfig.toml theme={null}
[test]
retry = 3
```

### rerunEach

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

```toml bunfig.toml theme={null}
[test]
rerunEach = 3
```

### concurrentTestGlob

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

```toml bunfig.toml theme={null}
[test]
concurrentTestGlob = "**/concurrent-*.test.ts"
```

### smol

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

```toml bunfig.toml theme={null}
[test]
smol = true
```

## Reporters

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

```toml bunfig.toml theme={null}
[test.reporter]
junit = "./reports/junit.xml"
```

Equivalent CLI usage:

```bash theme={null}
bun test --reporter=junit --reporter-outfile=./reports/junit.xml
```

## Coverage

Enable coverage reporting and configure thresholds:

```toml bunfig.toml theme={null}
[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](/test/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.

```toml bunfig.toml theme={null}
[install]
registry = "https://npm.company.com/"
prefer = "offline"

[test]
coverage = true
timeout = 10000
```

## Complete example

```toml bunfig.toml theme={null}
[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"
```