> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/oven-sh/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="Before">
    ```bash theme={null}
    npx jest
    yarn test
    npm test
    ```
  </Tab>

  <Tab title="After">
    ```bash theme={null}
    bun test
    ```
  </Tab>
</Tabs>

Update your `package.json` scripts:

```json package.json theme={null}
{
  "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:

```typescript math.test.ts theme={null}
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:

```typescript global.d.ts theme={null}
/// <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:

<CardGroup cols={2}>
  <Card title="Test structure" icon="list">
    `describe`, `test`, `it`, `test.only`, `test.skip`, `test.todo`
  </Card>

  <Card title="Lifecycle hooks" icon="rotate-cw">
    `beforeAll`, `afterAll`, `beforeEach`, `afterEach`
  </Card>

  <Card title="Matchers" icon="check">
    `toBe`, `toEqual`, `toMatch`, `toThrow`, `toHaveBeenCalled`, and most others
  </Card>

  <Card title="Mocks and spies" icon="eye">
    `jest.fn()`, `jest.spyOn()`, `jest.mock()`, `mockReturnValue`, `mockImplementation`
  </Card>

  <Card title="Snapshots" icon="camera">
    `toMatchSnapshot()`, `toMatchInlineSnapshot()`, `bun test --update-snapshots`
  </Card>

  <Card title="Coverage" icon="bar-chart">
    `bun test --coverage` with configurable thresholds
  </Card>
</CardGroup>

## 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`](https://github.com/capricorn86/happy-dom) instead — jsdom depends on V8 internals that are not available in Bun.

Install `happy-dom` and create a preload script:

```bash theme={null}
bun add -d @happy-dom/global-registrator
```

```typescript happy-dom.ts theme={null}
import { GlobalRegistrator } from "@happy-dom/global-registrator";
GlobalRegistrator.register();
```

Configure the preload in `bunfig.toml`:

```toml bunfig.toml theme={null}
[test]
preload = ["./happy-dom.ts"]
```

## Coverage

Run coverage with the `--coverage` flag:

```bash theme={null}
bun test --coverage
```

Set coverage thresholds in `bunfig.toml`:

```toml bunfig.toml theme={null}
[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](/test/writing-tests#matchers) for the full matcher compatibility table.