Parallel & isolated test runs

bun test has three independent knobs for running more than one thing at a time:

They compose: a CI job can run bun test --shard=2/4 --parallel, and files in that shard can still contain test.concurrent tests.

--parallel

$ bun test --parallel        # one worker per CPU core
$ bun test --parallel=4      # exactly 4 workers

The main bun test process becomes a coordinator. It discovers test files as usual, then starts worker processes and hands each one file at a time. Results stream back as each test finishes, so the output looks the same as a serial run — each file's results are printed together under its filename, and console.log output from a test is never interleaved with another file's.

bun test v1.3.14 8x PARALLEL

src/router.test.ts:
✓ matches static routes [0.31ms]
✓ matches params [0.12ms]

src/db.test.ts:
✓ migrates up [41.02ms]
✓ migrates down [38.60ms]
...

Workers start lazily. The first worker starts immediately; the rest are only spawned once every running worker has been busy for a few milliseconds (--parallel-delay=<ms>, default 5). A suite of tiny files therefore runs on a single worker with no process-spawn overhead, while the first slow file triggers full fan-out.

How files are distributed

Files are sorted by path and split into one contiguous chunk per worker, so files in the same directory — which usually import the same modules — mostly land in the same process (a chunk boundary can fall inside a directory, and stolen files move). When a worker drains its chunk it steals the back half of the largest remaining chunk from another worker. With --timings the chunks are cut by recorded duration instead of file count, each worker starts its slowest file first, and an idle worker steals the slowest not-yet-started file from whichever chunk has the most time left.

Every file is isolated (unless you opt out)

--parallel implies --isolate: each file runs in a fresh global object even when two files land on the same worker. Tests that pass with --parallel don't depend on state leaked by an earlier file.

--parallel --no-isolate turns that off: each worker keeps a single global and module registry for all the files it is handed, exactly like a serial bun test does for the whole suite. Imports (and --preload modules) are evaluated once per worker instead of once per file, which is the fastest way to run a large suite of small files — at the price that a file can observe whatever an earlier file on the same worker left behind. Preload-level beforeAll/afterAll hooks still wrap every file, since a worker never knows which file is its last.

Worker environment

Each worker gets BUN_TEST_WORKER_ID and JEST_WORKER_ID set to its 1-based index, so tests can pick a distinct database, port range, or temp directory per worker:

const dbName = `app_test_${process.env.BUN_TEST_WORKER_ID ?? "1"}`;

Flags that affect how tests execute (--timeout, --preload, --define, --coverage, --update-snapshots, -t, --retry, --rerun-each, --concurrent, --randomize/--seed, …) are forwarded to workers. --bail is handled by the coordinator at file granularity: once the failure threshold is reached no new files are started, but files already running finish.

Coverage, JUnit XML and snapshot writes are merged by the coordinator, so --parallel --coverage --reporter=junit --reporter-outfile=junit.xml produces one report.

If a worker crashes (a native addon segfaults, or a test calls process.exit) the file it was running is reported as failed and a replacement worker picks up the remaining files. A crash from a fatal signal aborts the whole run so it can't be masked by later passing files.

When --parallel helps, and when it doesn't

--parallel pays off when the suite is dominated by test execution — I/O waits, real computation, subprocesses, many files. It costs something too: every file re-evaluates its imports in a fresh global (see --isolate), and each worker is a separate process with its own JIT warm-up. For a suite of very fast files that all import the same large module graph, plain bun test (one process, one shared module registry) can be faster. Try both; the numbers are printed at the end of every run.

--isolate

$ bun test --isolate

Runs each test file in a fresh JavaScript global object inside the same process. Between files Bun:

• creates a new globalThis (so properties a file stuck on globalThis, patched built-ins, and module-level state are gone),
• clears the ESM and CommonJS module registries (every file re-evaluates its imports),
• closes servers, sockets, file watchers and subprocesses the file left open, cancels its timers, and restores fake timers,
• re-runs --preload scripts in the new global.

This is how Jest and Vitest behave by default. It makes "passes alone, fails in the full suite" bugs go away at the cost of re-evaluating imports per file.

To keep that cost low, transpiled source and bytecode are cached at the process level and shared across globals: the second file to import a module skips reading, transpiling and parsing it and goes straight to evaluation. Only the module's top-level code runs again.

Without --isolate (the default), all files share one global and one module registry. That is the fastest mode and is fine for suites whose files don't leak state into each other.

Concurrent tests within a file

--parallel spreads files across cores. Within one file tests still run one at a time unless you opt in to concurrency, which lets async tests overlap while one is waiting on I/O:

import { test, expect } from "bun:test";

test.concurrent("GET /users", async () => {
  const res = await fetch(`${baseUrl}/users`);
  expect(res.status).toBe(200);
});

test.concurrent("GET /posts", async () => {
  const res = await fetch(`${baseUrl}/posts`);
  expect(res.status).toBe(200);
});

// runs after the concurrent group, alone
test.serial("resets the database", async () => {
  await resetDb();
});

• test.concurrent(...) / describe.concurrent(...) mark individual tests or whole groups.
• --concurrent treats every test as concurrent; test.serial opts back out.
• --max-concurrency=N caps how many run at once (default 20).
• concurrentTestGlob in bunfig.toml turns it on for matching files only.

Concurrent tests share a thread and a global; this is cooperative concurrency for I/O-bound tests, not extra CPU cores. expect.assertions() and other per-test global state need care under concurrency — see Concurrent test execution.

Splitting a suite across CI machines with --shard

$ bun test --shard=1/3   # machine 1
$ bun test --shard=2/3   # machine 2
$ bun test --shard=3/3   # machine 3

Every machine sorts the discovered test files by path and takes a deterministic slice, so together the shards cover each file exactly once with no coordination. Without --timings, file i of the sorted list goes to shard (i mod n) + 1 — balanced by file count, not by how long files take.

Balancing with --timings

File count is a poor proxy for duration: one shard can end up with all the slow integration tests. Give bun test a record of how long each file takes and it will cut shards by total time instead, keeping neighbouring files (which share imports) together:

# Record durations (any run can do this; --parallel is fine)
$ bun test --timings=.bun-test-timings.json --update-timings

# Use them
$ bun test --shard=2/8 --parallel --timings=.bun-test-timings.json

The file is plain JSON, slowest first, so it doubles as a "what's slow" report:

{
  "version": 1,
  "files": {
    "test/integration/build.test.ts": 41234,
    "test/db/migrate.test.ts": 9876,
    "src/router.test.ts": 112
  }
}

• Paths are relative to the project root; values are wall-clock milliseconds for the whole file.
• Without --shard, --update-timings merges into what it read, so re-running part of the suite locally refreshes those entries and keeps the rest. Entries for files that no longer exist are left alone; delete the file to start over.
• With --shard, --update-timings writes only the files that shard ran — see below.
• Files with no entry are assumed to take the median time when cutting shards, and are started first under --parallel.
• With --timings, --parallel also uses the durations: worker chunks are cut by time and each worker starts its slowest file first.

One timings file per shard

--timings can be passed more than once; the files are read as one table (paths that don't exist yet are skipped), and --update-timings writes to the first path. Under --shard that output contains just the files the shard ran, so the shards' outputs are disjoint and, read together on the next run, add up to the whole suite — no merge step. Large codebases on the main page has the full CI workflow.

How it compares

2 000 TypeScript test files × 8 small tests each, all importing a small app built on zod, date-fns and lodash, with a shared setup file (custom matcher + beforeEach/afterEach) loaded via each runner's preload mechanism — the shape of a large application's unit-test suite (bench/test/app, bun app/setup.ts 2000 20). 16-core Apple M4 Max:

Where the time goes: with a fresh global per file, every runner re-evaluates the imports and setup file 2 000 times. Bun shares transpiled source and bytecode across those globals so nothing is re-parsed, but module evaluation and JIT warm-up still repeat per file — which is why, on this shape, one shared global (bun test) beats sixteen isolated workers, and sixteen shared globals (--parallel --no-isolate) beat both.