Default timezone when running tests with bun test
When running tests with bun test, Bun sets the time zone to UTC to make tests more deterministic.
testing
56 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Code coverage report output format
The code coverage report displays a table with columns for File, % Funcs, % Lines, and Uncovered Line #s. The report includes an 'All files' row showing aggregate coverage and individual rows for each file.
Code coverage threshold configuration in bunfig.toml
Set a minimum code coverage threshold by adding [test] section with coverageThreshold property to bunfig.toml. A threshold of 0.9 requires 90% line coverage and 90% function coverage for every file in the coverage report. Bun checks the threshold against each file individually, not against the 'All files' average.
Non-zero exit code on coverage threshold failure
When the test suite does not meet the coverage threshold, 'bun test' exits with a non-zero exit code (exit code 1) to signal a failure.
Separate line and function coverage thresholds
Set different thresholds for line-level and function-level coverage using the syntax: coverageThreshold = { lines = 0.5, functions = 0.7 } in the [test] section of bunfig.toml, where lines and functions take decimal values between 0 and 1.
Enable code coverage with --coverage flag
Enable code coverage reporting in the Bun test runner by running 'bun test --coverage' command.
Enable coverage reporting by default in bunfig.toml
To enable coverage reporting by default, add [test] section with coverage = true to your bunfig.toml configuration file.
Coverage report output format
The coverage report displays a table with columns for File, % Funcs (percentage of functions), % Lines (percentage of lines), and Uncovered Line #s (line numbers that were not executed). All files are summarized at the top of the table.
Generate code coverage with --coverage flag
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.
bun test command runs test suite
Run `bun test` from your project directory to execute the test runner. The test runner recursively searches for files matching specific patterns and runs the tests they contain.
Test file naming patterns recognized by bun test
The test runner recognizes files matching these patterns: *.test.{js|jsx|ts|tsx|mjs|cjs|mts|cts}, *_test.{js|jsx|ts|tsx|mjs|cjs|mts|cts}, *.spec.{js|jsx|ts|tsx|mjs|cjs|mts|cts}, *_spec.{js|jsx|ts|tsx|mjs|cjs|mts|cts}
Filter tests by file path with positional argument
Pass a positional argument to `bun test` to run only certain test files. The runner executes only files with that argument in their path. For example, `bun test test3` runs only files containing 'test3' in the path.
Import test, expect, and describe from bun:test
Use `import { test, expect, describe } from "bun:test";` to access the test runner API. The `test` function defines individual tests, `expect` provides assertion methods, and `describe` groups tests into suites.
Filter tests by name pattern with -t flag
Use the `-t` or `--test-name-pattern` flag to filter tests by name. The pattern matches test names defined with `test` and suite names defined with `describe`. For example, `bun test -t add` runs only tests with 'add' in the name.
Example: basic test with describe and expect
import { test, expect, describe } from "bun:test"; describe("math", () => { test("add", () => { expect(2 + 2).toEqual(4); }); test("multiply", () => { expect(2 * 2).toEqual(4); }); });
Register happy-dom in a preload file
Create a file (e.g., happydom.ts) that imports GlobalRegistrator from @happy-dom/global-registrator and calls GlobalRegistrator.register() to inject the mocked browser APIs into the global scope.
Write browser DOM tests with happy-dom
After configuring happy-dom with preload, you can write tests using browser APIs like document, document.querySelector, and element properties. Example: document.body.innerHTML = `<button>My button</button>`; const button = document.querySelector("button"); expect(button?.innerText).toEqual("My button");
Configure test preload in bunfig.toml
In bunfig.toml, set the test.preload option to the path of your happy-dom registration file (e.g., ./happydom.ts) under the [test] section. This ensures the registration code runs before any test files execute.
test.skip function skips test execution
The test.skip function is used to skip a test with the Bun test runner. Tests marked with test.skip will not be executed when running 'bun test', and the terminal output marks them as skipped.
Skipped tests show in test output
When a skipped test is present, the test runner output shows the test name and a count of skipped tests. For example, running 'bun test' with one skipped test produces output showing '1 skip' in the summary.
test.skip syntax and example
Use test.skip with a test name string and a test function. Example: test.skip("unimplemented feature", () => { expect(Bun.isAwesome()).toBe(true); }); This test will be skipped when 'bun test' is run.
Jest matcher compatibility with Bun
Bun implements most of Jest's matchers, but compatibility is not 100%. See the compatibility table in the Writing tests documentation for matchers.
Running Bun test runner instead of Jest
Use `bun test` instead of `npx jest` or `yarn test` to run test suites with Bun.
Jest imports rewritten to bun:test automatically
Bun internally rewrites imports from `@jest/globals` to their `bun:test` equivalents, so test files usually work without code changes.
Global test functions injected by Bun
Bun automatically injects global functions like `test` and `expect`, similar to Jest, so explicit imports are optional.
TypeScript support for global test functions since Bun v1.2.19
Add a triple-slash directive `/// <reference types="bun-types/test-globals" />` to one file in your project (such as `global.d.ts` or `preload.ts`) to enable TypeScript support for Jest globals like `test`, `expect`, `describe`, `beforeAll`, and `afterEach` across all test files.
Jest bail option migrated to --bail CLI flag
Replace Jest's `bail` configuration option with the `--bail` CLI flag when running Bun tests. Example: `bun test --bail=3`.
Jest collectCoverage migrated to --coverage CLI flag
Replace Jest's `collectCoverage` configuration option with the `--coverage` CLI flag when running Bun tests. Example: `bun test --coverage`.
Jest testTimeout migrated to --timeout CLI flag
Replace Jest's `testTimeout` configuration option with the `--timeout` CLI flag when running Bun tests. Example: `bun test --timeout 10000`.
Jest configuration mappings to bunfig.toml [test] section
Jest settings map to Bun's `[test]` section in `bunfig.toml` as follows: `setupFiles`/`setupFilesAfterEnv` → `preload`, `testPathIgnorePatterns` → `pathIgnorePatterns`, `rootDir` → `root`, `coverageDirectory` → `coverageDir`, `coverageReporters` → `coverageReporter`, `coverageThreshold` → `coverageThreshold` (as a fraction like `0.9`, not a percentage).
Jest settings not applicable to Bun
The following Jest settings are irrelevant in Bun: `transform` (Bun supports TypeScript & JSX natively), `extensionsToTreatAsEsm`, `haste`, `watchman`, `watchPlugins`, `watchPathIgnorePatterns` (use `--watch` instead), and `verbose` (use `--only-failures` or `--dots` for less output).
DOM testing with jsdom equivalent in Bun
For Jest's `testEnvironment: "jsdom"`, use the happy-dom guide to inject browser APIs into the global scope. Configure this in `bunfig.toml` under `[test]` with `preload = ["./happydom.ts"]`. happy-dom is a leaner and faster alternative to jsdom.
Snapshot file location and naming
Snapshot files are stored in a __snapshots__ directory that is created alongside the test file. The snapshot file is named with the test file name followed by .snap extension (e.g., snap.test.ts.snap).
Snapshot testing example with toMatchSnapshot()
import { test, expect } from "bun:test"; test("snapshot", () => { expect({ foo: "bar" }).toMatchSnapshot(); });
toMatchSnapshot() method for snapshot testing
Bun's test runner supports Jest-style snapshot testing using the toMatchSnapshot() method from the expect() API. On the first test run, Bun evaluates the value passed into expect() and writes it to a __snapshots__ directory alongside the test file. On subsequent runs, Bun reads the snapshot file and compares it to the current value; if they differ, the test fails.
Snapshot file location and format
The __snapshots__ directory is created alongside the test file and contains a .snap file for each test file. The .snap file is a JavaScript file that exports a serialized version of the value using Jest's snapshot format, which is not strict JSON (allows trailing commas). The file header includes a version comment: // Bun Snapshot v1, https://bun.sh/docs/test/snapshots
Snapshot format example
Snapshot files export serialized values in the format: exports[`test name 1`] = `\n{\n "foo": "bar",\n}\n`;
bun test --update-snapshots flag
Use the --update-snapshots flag with the bun test command to regenerate and update snapshot files when the expected behavior changes.
TypeScript matcher type declarations for Testing Library
Create a type declaration file (e.g., matchers.d.ts) for TypeScript to show new matcher types in the editor. Import TestingLibraryMatchers from "@testing-library/jest-dom/matchers" and Matchers, AsymmetricMatchers from "bun:test", then declare module "bun:test" with interface Matchers<T> extends TestingLibraryMatchers<typeof expect.stringContaining, void> and interface AsymmetricMatchers extends TestingLibraryMatchers<any, any>
Install Testing Library packages
For React, install Testing Library packages with: bun add -D @testing-library/react @testing-library/dom @testing-library/jest-dom
Install Happy DOM for Testing Library
To use Testing Library with Bun's test runner, first install Happy DOM using the command: bun add -D @happy-dom/global-registrator
Happy DOM preload script setup
Create a preload script (e.g., happydom.ts) that imports and registers Happy DOM: import { GlobalRegistrator } from "@happy-dom/global-registrator"; GlobalRegistrator.register();
Testing Library preload script setup
Create a preload script (e.g., testing-library.ts) that extends Bun's expect function with Testing Library matchers and optionally runs cleanup after each test. Import { afterEach, expect } from "bun:test", import { cleanup } from "@testing-library/react", import matchers from "@testing-library/jest-dom/matchers", then call expect.extend(matchers) and optionally add afterEach(() => { cleanup(); })
Testing Library preload configuration in bunfig.toml
Add the preload scripts to bunfig.toml under [test] section: preload = ["./happydom.ts", "./testing-library.ts"]. If combining scripts, load @testing-library/* packages with await import() after GlobalRegistrator.register() runs, because Bun evaluates static imports before register() executes and screen queries will throw if called before registration.
Testing Library usage example in Bun tests
Example test using Testing Library with Bun: import { test, expect } from "bun:test"; import { screen, render } from "@testing-library/react"; import { MyComponent } from "./myComponent"; test("Can use Testing Library", () => { render(<MyComponent />); const myComponent = screen.getByTestId("my-component"); expect(myComponent).toBeInTheDocument(); })
Default test timeout is 5000 milliseconds
The default timeout for tests in Bun is 5000 milliseconds, which equals 5 seconds.
bun test --timeout flag sets per-test timeout
Use the --timeout flag with bun test to set a timeout for each test in milliseconds. Bun marks a test that exceeds this timeout as failed.
Example: Set test timeout to 3 seconds
bun test --timeout 3000 sets a per-test timeout of 3000 milliseconds (3 seconds).
bun test --todo runs todo test bodies
The --todo flag causes bun test to execute the bodies of todo tests. Todo tests are expected to fail; when they do fail, Bun prints the error, counts the test as todo, and exits with code 0.
test.todo() signature and usage
test.todo accepts a test name as a string and an optional test body function. Example: test.todo("test name") or test.todo("test name", () => { expect(...).toBe(...) }). It is imported from 'bun:test'.
test.todo() with body does not run without --todo flag
You can write test.todo with a test body (including expect statements) to document intended behavior before implementation. When running bun test normally, the body is not executed. The test is reported as todo without running its code.
Passing todo test signals need to remove .todo
When a todo test body passes (after the implementation is complete), bun test --todo reports it as a failure with the message 'this test is marked as todo but passes. Remove `.todo` if tested behavior now works' and exits with a non-zero code. This signals that the .todo marker should be removed to convert it to a regular test.
test.todo() marks a test to write later
The test.todo function allows you to mark a test that you plan to write later without providing an implementation. It records a placeholder test that the test runner will report.
bun test output reports todo test count
The bun test command outputs a summary that includes the count of todo tests, displayed alongside pass and fail counts.
Bun test command
The `bun test` command runs the test runner. It is Jest-compatible, TypeScript-first with support for snapshots, DOM, and watch mode.
Run tests on Windows
Run the test suite with bun-debug test <path> or with the wrapper script bun run test <path>. The bun run test command runs every test file in a separate instance of bun-debug.exe, so a crash does not stop the entire suite. Examples: bun run test (entire suite), bun-debug test node\fs, or bun-debug test "C:\bun\test\js\bun\resolve\import-meta.test.js"