Coverage threshold failure behavior
When test coverage falls below the configured threshold, `bun test --coverage` exits with a non-zero exit code (exit code 1) to signal failure.
test runner
85 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Set different coverage thresholds for lines and functions
Use `coverageThreshold = { lines = 0.5, functions = 0.7 }` in the `[test]` section of `bunfig.toml` to specify different coverage thresholds for line-level and function-level coverage separately.
coverageThreshold configuration in bunfig.toml
Add a `[test]` section to `bunfig.toml` with `coverageThreshold` to set a minimum code coverage requirement. A value of `0.9` requires 90% coverage. When the test suite does not meet the threshold, `bun test` exits with a non-zero exit code.
Enable code coverage with --coverage flag
Use `bun test --coverage` to enable built-in code coverage reporting in Bun's test runner.
Simple coverage threshold configuration example
To require 90% line-level and function-level coverage, add to `bunfig.toml`: `[test]` section with `coverageThreshold = 0.9`.
bun test --concurrent flag behavior
The `--concurrent` flag overrides `bunfig.toml` settings and forces all tests to run concurrently, regardless of the `concurrentTestGlob` pattern or individual test markers.
concurrentTestGlob example configuration
Example `bunfig.toml` configuration: `[test]` section with `concurrentTestGlob = "**/concurrent-*.test.ts"` runs all test files with "concurrent-" prefix concurrently.
Using test.concurrent() in concurrent files
In files matched by `concurrentTestGlob`, using plain `test()` is equivalent to `test.concurrent()` - both run concurrently. You can still use `test.concurrent()` explicitly for clarity, and `test.serial()` to override and run a specific test sequentially.
concurrentTestGlob option in bunfig.toml
The `concurrentTestGlob` option in the `[test]` section of `bunfig.toml` runs tests concurrently in files whose names match the specified glob pattern. By default, tests run sequentially unless their file matches this pattern. The option accepts a single pattern string or an array of multiple patterns.
Default test execution mode
Tests run sequentially by default. Tests only run concurrently if their file name matches a pattern in `concurrentTestGlob`, or if explicitly marked with `test.concurrent()`, or if the `--concurrent` flag is passed to `bun test`.
test.concurrent() explicitly marks test as concurrent
The `test.concurrent()` function explicitly marks an individual test to run concurrently. This works regardless of whether the file matches `concurrentTestGlob`. In files matched by `concurrentTestGlob`, using plain `test()` already runs concurrently, so `test.concurrent()` is redundant in those files.
test.serial() explicitly marks test as sequential
The `test.serial()` function explicitly marks an individual test to run sequentially. This works regardless of the `concurrentTestGlob` setting, allowing fine-grained control over test execution order even in files matched by the concurrent pattern.
concurrentTestGlob accepts array of patterns
The `concurrentTestGlob` option accepts multiple patterns as an array in `bunfig.toml`. Tests in files matching any of the patterns run concurrently. Example: `concurrentTestGlob = ["**/integration/*.test.ts", "**/e2e/*.test.ts", "**/concurrent-*.test.ts"]`
Enable coverage reporting by default in bunfig.toml
To enable coverage reporting by default, add [test] section with coverage = true to your bunfig.toml file. This makes the test runner always generate coverage reports without needing to pass the --coverage flag each time.
bun test --coverage flag generates code coverage reports
Pass the --coverage flag to bun test to print a coverage report after the test run. The report lists the source files the tests executed, the percentage of functions and lines that ran, and the line ranges that never ran.
Coverage report output format
The coverage report displays a table with columns: File, % Funcs (percentage of functions covered), % Lines (percentage of lines covered), and Uncovered Line #s (line number ranges that were not executed). The report shows both individual file coverage and an overall 'All files' summary row.
Example: Testing DOM with Happy DOM and Bun test
import { test, expect } from "bun:test"; test("set button text", () => { document.body.innerHTML = `<button>My button</button>`; const button = document.querySelector("button"); expect(button?.innerText).toEqual("My button"); });
Use preload option in bunfig.toml to run setup before tests
In bunfig.toml, the [test] section accepts a preload option that specifies a file to execute before any test files run. Set `preload = "./happydom.ts"` to run Happy DOM registration before tests.
Install @happy-dom/global-registrator for browser DOM tests
To use Happy DOM with Bun's test runner, install the @happy-dom/global-registrator package as a dev dependency using `bun add -d @happy-dom/global-registrator`.
GlobalRegistrator.register() injects mocked browser APIs
The GlobalRegistrator class from @happy-dom/global-registrator exports a register() method that injects mocked versions of browser APIs like document and location into the global scope.
Example: Happy DOM registration setup file
Create a file (e.g., happydom.ts) with the following content to register mocked browser APIs: import { GlobalRegistrator } from "@happy-dom/global-registrator"; GlobalRegistrator.register();
Happy DOM implements mocked browser APIs
Happy DOM provides mocked versions of browser APIs such as document and location that can be used in Bun's test runner for writing browser DOM tests.
Replace Jest testTimeout with --timeout CLI flag
Replace `testTimeout` in your Jest config with the `--timeout` CLI flag. Example: `bun test --timeout 10000`.
Basic migration: run bun test instead of jest
To migrate from Jest to Bun's test runner, replace the command. Instead of running `npx jest` or `yarn test`, run `bun test`.
Jest test files work in Bun without code changes
In many cases, Bun's test runner can run Jest test suites with no code changes.
Bun rewrites @jest/globals imports to bun:test
Bun internally rewrites imports from `@jest/globals` to their `bun:test` equivalents. Test files do not need to be modified to use this; however, you can optionally update imports to `bun:test` directly.
Bun injects global test functions like Jest
If you rely on Jest to inject globals like `test` and `expect`, Bun does that too.
TypeScript support for global test functions via triple-slash directive
Since Bun v1.2.19, add the triple-slash directive `/// <reference types="bun-types/test-globals" />` to one file in your project, such as a `global.d.ts` file in the project root, your test `preload.ts` setup file, or any single `.ts` file that TypeScript includes in your compilation. Once added, every test file in the project gets TypeScript support for the Jest globals.
Bun does not have 100% Jest matcher compatibility
Bun implements most of Jest's matchers, but compatibility is not 100%. The compatibility table is available in the Writing tests documentation under matchers.
Use happy-dom for DOM testing instead of jsdom
If you use `testEnvironment: "jsdom"` to run tests in a browser-like environment, follow the DOM testing with Bun and happy-dom guide to inject browser APIs into the global scope. The guide uses `happy-dom`, a leaner and faster alternative to `jsdom`. Configure it using the preload option in `bunfig.toml`: `[test] preload = ["./happy-dom.ts"]`.
Replace Jest bail config with --bail CLI flag
Replace `bail` in your Jest config with the `--bail` CLI flag. Example: `bun test --bail=3`.
Replace Jest collectCoverage with --coverage CLI flag
Replace `collectCoverage` in your Jest config with the `--coverage` CLI flag. Example: `bun test --coverage`.
Jest settings that are irrelevant in bun test
The following Jest settings are irrelevant in `bun test`: `transform` (Bun supports TypeScript & JSX natively; configure other file types with plugins), `extensionsToTreatAsEsm`, `haste` (Bun uses its own internal source maps), `watchman`, `watchPlugins`, `watchPathIgnorePatterns` (use `--watch` to run tests in watch mode instead), and `verbose` (set `logLevel: "debug"` in `bunfig.toml` instead).
setSystemTime complete code example
```ts import { test, expect, setSystemTime } from "bun:test"; test("party like it's 1999", () => { const date = new Date("1999-01-01T00:00:00.000Z"); setSystemTime(date); // it's now January 1, 1999 const now = new Date(); expect(now.getFullYear()).toBe(1999); expect(now.getMonth()).toBe(0); expect(now.getDate()).toBe(1); }); ``` This example demonstrates mocking the system time to January 1, 1999 in a test and verifying that Date operations reflect the mocked time.
Mock system time with setSystemTime in beforeAll lifecycle hook
Call setSystemTime in a beforeAll lifecycle hook to give all tests in a suite a deterministic fake clock. This sets the system time once for all tests in that lifecycle scope.
Reset system clock with setSystemTime no arguments
Call setSystemTime() with no arguments to reset the system clock to the actual current time.
Using setSystemTime to set a specific time in a test
Call setSystemTime with a Date object to set the system time. For example, setSystemTime(new Date('1999-01-01T00:00:00.000Z')) sets the time to January 1, 1999. Subsequent new Date() calls within the test will use the mocked time.
setSystemTime in beforeAll example
```ts import { test, expect, beforeAll, setSystemTime } from "bun:test"; beforeAll(() => { const date = new Date("1999-01-01T00:00:00.000Z"); setSystemTime(date); // it's now January 1, 1999 }); // tests... ``` This example shows how to set a deterministic fake clock for all tests in a suite by calling setSystemTime in a beforeAll hook.
setSystemTime function signature and import
The setSystemTime function is imported from 'bun:test'. It takes an optional Date argument to set the system time in tests. When called with no arguments, it resets the system clock to the actual time.
bun test --rerun-each flag
The --rerun-each flag runs every test multiple times. It is used to find flaky or non-deterministic tests. The flag takes a number argument specifying how many times to run each test. For example, 'bun test --rerun-each 10' runs each test 10 times.
toHaveBeenCalledTimes matcher
The toHaveBeenCalledTimes matcher checks if a mock function was called exactly N times. Example: expect(random).toHaveBeenCalledTimes(3);
mock function from bun:test
The mock function is imported from 'bun:test' and creates a mock function for testing. It wraps a function implementation and decorates the result with extra properties for inspection.
mock function basic usage
Call mock() with a function as an argument to create a mock. The mock function can be called immediately and will execute the wrapped function. Example: const random = mock(() => Math.random());
mock function with arguments
The function passed to mock() can accept arguments. Example: const random = mock((multiplier: number) => multiplier * Math.random()); The mock function will pass arguments to the wrapped function when called.
mock.calls property
A mock function has a mock.calls property that is an array of arrays, where each inner array contains the arguments passed to each call. For example, after calling random(2) then random(10), random.mock.calls is [[2], [10]].
mock.results property
A mock function has a mock.results property that is an array of objects describing each call's result. Each result object has a type property (e.g. 'return') and a value property containing the returned value. Example: [{type: 'return', value: 0.6533907460954099}, {type: 'return', value: 0.6452713933037312}]
mock.calls assertion example
You can assert on the mock.calls array directly using toEqual. Example: expect(random.mock.calls).toEqual([[1], [2], [3]]);
mock.results assertion example
You can assert on individual elements of mock.results. Example: expect(random.mock.results[0]).toEqual({type: 'return', value: a});
test.skip function signature and usage
The Bun test runner provides the test.skip function to skip tests. It takes a test name string and a test function as parameters. When a test is skipped using test.skip, it is not executed when running bun test, and the terminal output marks it as skipped with a » symbol.
Skipped test output format in bun test
When bun test runs and encounters skipped tests, the terminal output displays a summary showing the count of passed tests, skipped tests, and failed tests. Skipped tests are marked with a » symbol in the output and are included in the total test count but not in the pass count.
test.skip example
import { test } from "bun:test"; test.skip("unimplemented feature", () => { expect(Bun.isAwesome()).toBe(true); });
bun test command basic usage
Run `bun test` from your project directory to execute the built-in test runner. The test runner recursively searches for test files and runs all tests they contain.
Test and describe usage example
Example showing test organization: ```ts import { test, expect, describe } from "bun:test"; describe("math", () => { test("add", () => { expect(2 + 2).toEqual(4); }); test("multiply", () => { expect(2 * 2).toEqual(4); }); }); ``` Each test has a name (first argument to `test`), tests can be grouped into suites with `describe`, and assertions use the `expect` API.
Filter tests by name with -t flag
Use the `-t` or `--test-name-pattern` flag to filter tests by name. For example, `bun test -t add` runs only tests with 'add' in the name. The pattern matches both test names defined with `test` and suite names defined with `describe`.
Filter tests by file path with positional argument
Pass a positional argument to `bun test` to only run certain test files. For example, `bun test test3` only executes files with 'test3' in their path.
Test file patterns recognized by bun test
The test runner searches for files matching these patterns: *.test.{js|jsx|ts|tsx}, *_test.{js|jsx|ts|tsx}, *.spec.{js|jsx|ts|tsx}, *_spec.{js|jsx|ts|tsx}.
import test, expect, describe from bun:test
Import the test runner API using: `import { test, expect, describe } from "bun:test";`. The `test` function defines individual tests, `describe` groups tests into suites, and `expect` provides Jest-like assertions.
spyOn example with object method
import { test, expect, spyOn } from 'bun:test'; const leo = { name: 'Leonardo', sayHi(thing: string) { console.log(`Sup I'm ${this.name} and I like ${thing}`); }, }; const spy = spyOn(leo, 'sayHi'); test('turtles', () => { expect(spy).toHaveBeenCalledTimes(0); leo.sayHi('pizza'); expect(spy).toHaveBeenCalledTimes(1); expect(spy.mock.calls).toEqual([['pizza']]); });
spyOn import from bun:test
The spyOn utility is imported from 'bun:test' along with test and expect.
spyOn creates a spy on an object method
spyOn is called with two arguments: an object and a method name (as a string). It returns a spy object that tracks calls to that method. Example: const spy = spyOn(leo, 'sayHi');