Migrate from Jest to Bun's test runner

In many cases, Bun's test runner can run Jest test suites with no code changes. Run bun test instead of npx jest or yarn test.

terminal
npx jest 
yarn test 
bun test

Your test files usually work as-is.

  • Bun internally rewrites imports from @jest/globals to their bun:test equivalents.
  • If you rely on Jest to inject globals like test and expect, Bun does that too.

If you'd rather import from bun:test directly, update the imports.

test.ts
import { test, expect } from "@jest/globals"; 
import { test, expect } from "bun:test";

Since Bun v1.2.19, a triple-slash directive enables TypeScript support for global test functions. Add it to one file in your project, such as:

  • A global.d.ts file in your project root
  • Your test preload.ts setup file (if using preload in bunfig.toml)
  • Any single .ts file that TypeScript includes in your compilation
global.d.ts
/// <reference types="bun-types/test-globals" />

Once added, every test file in your project gets TypeScript support for the Jest globals:

math.test.ts
describe("my test suite", () => {
  test("should work", () => {
    expect(1 + 1).toBe(2);
  });

  beforeAll(() => {
    // setup code
  });

  afterEach(() => {
    // cleanup code
  });
});

Bun implements most of Jest's matchers, but compatibility isn't 100%. See the compatibility table in Writing tests.

If you use testEnvironment: "jsdom" to run your tests in a browser-like environment, follow the DOM testing with Bun and happy-dom guide to inject browser APIs into the global scope. That guide uses happy-dom, a leaner and faster alternative to jsdom.

bunfig.toml
[test]
preload = ["./happydom.ts"]

Replace bail in your Jest config with the --bail CLI flag.

terminal
bun test --bail=3

Replace collectCoverage with the --coverage CLI flag.

terminal
bun test --coverage

Replace testTimeout with the --timeout CLI flag.

terminal
bun test --timeout 10000

Many other Jest settings are irrelevant in bun test.

  • transform — Bun supports TypeScript & JSX. Configure other file types with plugins.
  • extensionsToTreatAsEsm
  • haste — Bun uses its own module resolver
  • watchman, watchPlugins, watchPathIgnorePatterns — use --watch to run tests in watch mode
  • verbose — bun test reports each test by default. Use --only-failures or --dots for less output (see Test reporters).

Many other settings have an equivalent in the [test] section of bunfig.toml. For example:

  • setupFiles/setupFilesAfterEnv → preload
  • testPathIgnorePatterns → pathIgnorePatterns
  • rootDir → root
  • coverageDirectory → coverageDir
  • coverageReporters → coverageReporter
  • coverageThreshold → coverageThreshold (as a fraction like 0.9, not a percentage)

See Test configuration. Settings without an equivalent are not supported. File a feature request if something you need is missing.

See also: