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

# 从 Jest 迁移到 Bun 的测试运行器

在很多情况下，Bun 的测试运行器可以在无需更改代码的情况下运行 Jest 测试套件。只需运行 `bun test`，而不是 `npx jest`、`yarn test` 等。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
npx jest # [!code --]
yarn test # [!code --]
bun test # [!code ++]
```

***

通常不需要更改代码。

* Bun 会在内部重写来自 `@jest/globals` 的导入，使用 `bun:test` 的等效项。
* 如果你依赖 Jest 注入 `test`、`expect` 等全局变量，Bun 也会这样做。

但如果你更愿意切换到 `bun:test` 导入，也可以这样做。

```ts title="test.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import { test, expect } from "@jest/globals"; // [!code --]
import { test, expect } from "bun:test"; // [!code ++]
```

***

从 Bun v1.2.19 开始，你可以通过一个三斜线指令启用全局测试函数的 **TypeScript 支持**。这使得从 Jest 迁移更加简单，因为你只需在整个项目中添加一次该指令：

将此指令添加到项目中的 *任意一个文件*，例如：

* 项目根目录下的 `global.d.ts` 文件
* 你的测试 `preload.ts` 设置文件（如果在 bunfig.toml 中使用了 `preload`）
* TypeScript 编译时包含的任意一个 `.ts` 文件

```ts title="global.d.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
/// <reference types="bun-types/test-globals" />
```

***

添加后，项目中的所有测试文件将自动获得 Jest 全局变量的 TypeScript 支持：

```ts math.test.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
describe("my test suite", () => {
  test("should work", () => {
    expect(1 + 1).toBe(2);
  });

  beforeAll(() => {
    // 设置代码
  });

  afterEach(() => {
    // 清理代码
  });
});
```

***

Bun 实现了绝大多数 Jest 的匹配器，但兼容性尚未达到 100%。请参考完整的兼容性表：[文档 > 测试运行器 > 编写测试](/test/writing-tests#matchers)。

一些显著缺失的功能：

* `expect().toHaveReturned()`

***

如果你使用 `testEnvironment: "jsdom"` 在类似浏览器的环境中运行测试，应当遵循 [Bun 和 happy-dom 的 DOM 测试指南](/guides/test/happy-dom)，将浏览器 API 注入全局作用域。该指南依赖 [`happy-dom`](https://github.com/capricorn86/happy-dom)，它是 [`jsdom`](https://github.com/jsdom/jsdom) 的一个更轻量且更快速的替代方案。

目前由于 jsdom 内部使用了 V8 API，无法在 Bun 中运行。其支持进展请追踪这里：[issue](https://github.com/oven-sh/bun/issues/3554)。

```toml bunfig.toml icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
preload = ["./happy-dom.ts"]
```

***

将 Jest 配置中的 `bail` 替换为 `--bail` 命令行参数。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun test --bail=3
```

***

将 `collectCoverage` 替换为 `--coverage` 命令行参数。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun test --coverage
```

***

将 `testTimeout` 替换为 `--test-timeout` 命令行参数。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun test --timeout 10000
```

***

使用 `bun test` 时，许多其他标志变得无关紧要或过时。

* `transform` — Bun 支持 TypeScript 和 JSX。其他文件类型可以通过 [插件](/runtime/plugins) 配置。
* `extensionsToTreatAsEsm`
* `haste` — Bun 使用自有的内部源映射
* `watchman`、`watchPlugins`、`watchPathIgnorePatterns` — 使用 `--watch` 可开启测试的监听模式
* `verbose` — 在 [`bunfig.toml`](/runtime/bunfig#loglevel) 中设置 `logLevel: "debug"`

***

未提及的设置则不被支持或无对应项。如果缺少重要功能，请[提交功能请求](https://github.com/oven-sh/bun)。

***

另见：

* [将测试标记为待办](/guides/test/todo-tests)
* [文档 > 测试运行器 > 编写测试](/test/writing-tests)