Migrating from Jest

Replace Jest with Bun’s built-in test runner. Most test suites run without any code changes — just swap the command.

Bun includes a built-in test runner that is largely compatible with Jest. In many projects, you can run your existing Jest test suite with Bun by replacing the test command — no code changes required.

Step 1: Replace the test command

Before

npx jest
yarn test
npm test

After

bun test

Update your package.json scripts:

package.json

{
  "scripts": {
    "test": "bun test"
  }
}

Step 2: Update imports (optional)

Bun internally re-maps imports from @jest/globals to bun:test equivalents, so you often do not need to change your imports. But if you prefer to use Bun’s module explicitly:

math.test.ts

import { test, expect } from "@jest/globals"; // works, but optional to keep
import { test, expect } from "bun:test";       // explicit Bun import

If your tests inject Jest globals implicitly (without any import), those continue to work in Bun as well.

Step 3: Enable global type support (optional)

Since Bun v1.2.19, you can add TypeScript type support for Jest-style globals with a single triple-slash directive. Add it to one file in your project — for example, a global.d.ts in the root:

global.d.ts

/// <reference types="bun-types/test-globals" />

With this in place, all test files get TypeScript type checking for describe, test, expect, beforeAll, etc. without any per-file imports.

What is supported

Bun’s test runner implements the vast majority of Jest’s API:

Test structure

describe, test, it, test.only, test.skip, test.todo

Lifecycle hooks

beforeAll, afterAll, beforeEach, afterEach

Matchers

toBe, toEqual, toMatch, toThrow, toHaveBeenCalled, and most others

Mocks and spies

jest.fn(), jest.spyOn(), jest.mock(), mockReturnValue, mockImplementation

Snapshots

toMatchSnapshot(), toMatchInlineSnapshot(), bun test --update-snapshots

Coverage

bun test --coverage with configurable thresholds

Jest config option equivalents

Replace Jest configuration options with Bun CLI flags or bunfig.toml settings:

Jest config	Bun equivalent
jest --coverage	bun test --coverage
bail: 3	bun test --bail=3
testTimeout: 10000	bun test --timeout 10000
testPathPattern: "src"	bun test src
--watch	bun test --watch
verbose	logLevel = "debug" in bunfig.toml
transform	Not needed — Bun transpiles TS/JSX natively

Most projects can delete jest.config.js entirely once they migrate.

DOM testing (jsdom replacement)

If your tests use testEnvironment: "jsdom", use happy-dom instead — jsdom depends on V8 internals that are not available in Bun.

Install happy-dom and create a preload script:

bun add -d @happy-dom/global-registrator

happy-dom.ts

import { GlobalRegistrator } from "@happy-dom/global-registrator";
GlobalRegistrator.register();

Configure the preload in bunfig.toml:

bunfig.toml

[test]
preload = ["./happy-dom.ts"]

Coverage

Run coverage with the --coverage flag:

bun test --coverage

Set coverage thresholds in bunfig.toml:

bunfig.toml

[test.coverageThreshold]
line = 80
function = 80
statement = 80

Known differences

• expect().toHaveReturned() is not yet implemented.
• jsdom does not work in Bun. Use happy-dom instead.
• Some advanced Jest configuration keys (e.g., haste, watchman) have no equivalent in Bun.

Refer to the Bun test runner documentation for the full matcher compatibility table.