Bun Test Patterns

Bun Test Patterns

Test one coherent behavior with strong assertions, make shared state explicit, and choose concurrency, isolation, or parallel workers deliberately. A passing runtime test does not replace TypeScript type-checking.

Current baseline

Verified against Bun 1.3.14 on 2026-08-03:

bun --version
bun test --help

Bun 1.3.13 added file isolation, worker-process parallelism, deterministic sharding, and Git-aware changed-test selection. Bun 1.3.14 fixed isolation/parallel crashes and a --changed false negative involving tsconfig path aliases. Use 1.3.14 or newer for those features.

Read references/releases.md for the 64-page research ledger and first-party documentation contradictions. Read references/runner-and-configuration.md for discovery, execution, retries, reporters, coverage, lifecycle, snapshots, and timers. Read references/mocks-and-types.md for mock lifecycle, module boundaries, and expectTypeOf. Read references/dom-and-integrations.md for Happy DOM, Testing Library, Prisma, servers, and resource teardown.

Execution dimensions

Isolation changes cross-file leak risk, but it does not excuse missing cleanup inside a test.

Discovery and exact paths

Current canonical discovery includes test, spec, and test-directory conventions across JavaScript, JSX, TypeScript, TSX, MJS, CJS, MTS, and CTS.

Positional arguments are substring filters. Prefix an exact relative path:

bun test ./src/math.test.ts

Do not call a positional value a glob. Use documented config/CLI ignore patterns for path selection.

Selection and flake diagnosis

bun test --changed
bun test --changed=origin/main
bun test --randomize --seed 12345
bun test --rerun-each 20
bun test --retry 1
bun test --bail=1

--changed includes staged, unstaged, and untracked Git changes or compares against a supplied ref. With watch mode, selection is rebuilt each restart.

Retries can mask flakes. Keep zero as the normal gate; use a narrow retry only with captured reporting and remediation. Reproduce randomized failures with the printed seed.

test.only() restricts the run only when bun test --only is used. Do not leave focused tests as an implicit gate.

Configuration

Current coverage threshold shape is plural and fractional:

[test]
coverage = true
coverageThreshold = { lines = 0.80, functions = 0.80, statements = 0.80 }

branch is not a documented threshold field. timeout is a CLI or per-test value, not a documented [test] key.

Other current settings include root and path ignores, concurrentTestGlob, randomization and seed, retry/rerun, coverage reporters, test-file exclusion, and coverage path ignores.

Lifecycle and cleanup

Use async hooks when cleanup returns a promise. onTestFinished runs after afterEach but is unavailable in concurrent tests.

Restore timers, spies, environment, servers, clients, databases, and temporary files in the narrowest owner. The default runner shares process state between files.

Required CI configuration must fail fast. Do not use skipIf(!process.env.DATABASE_URL) to silently remove a suite CI is expected to run. process.env.CI is a string; compare explicit values rather than treating "false" as false.

Assertions

Use as many strong assertions as prove one behavior. Avoid weak truthiness when an exact value, status, state transition, or side effect is available.

Supported Bun-specific matchers include toBePositive, toContainAllKeys, toInclude, and singular toSatisfy. These claimed matchers do not exist: toIncludeAllMembers, toIncludeAnyMembers, and toSatisfyAll.

For arrays:

expect(received).toEqual(expect.arrayContaining(expected));
expect(received).toHaveLength(expected.length);
expect(received.some(predicate)).toBe(true);
expect(received.every(predicate)).toBe(true);