运行时行为

bun test 与 Bun 的运行时深度集成。这也是 bun test 快速且易于使用的原因之一。

环境变量

NODE_ENV

bun test 会自动将 $NODE_ENV 设置为 "test"，除非它已经在环境变量或 .env 文件中被设置。这是大多数测试运行器的标准行为，有助于确保测试行为的一致性。

https://mintcdn.com/ikxin/RzFFGbzo0-4huILA/icons/typescript.svg?fit=max&auto=format&n=RzFFGbzo0-4huILA&q=85&s=a3dffd2241f05776d3bd25171d0c5a79

test.ts

import { test, expect } from "bun:test";

test("NODE_ENV 被设置为 test", () => {
  expect(process.env.NODE_ENV).toBe("test");
});

你可以通过显式设置 NODE_ENV 来覆盖默认值：

terminal

NODE_ENV=development bun test

TZ（时区）

默认情况下，所有 bun test 运行都使用 UTC（Etc/UTC）作为时区，除非通过 TZ 环境变量覆盖。这确保了不同开发环境中的日期和时间行为一致。

test.ts

import { test, expect } from "bun:test";

test("默认时区为 UTC", () => {
  const date = new Date();
  expect(date.getTimezoneOffset()).toBe(0);
});

要使用特定时区进行测试：

terminal

TZ=America/New_York bun test

测试超时

每个测试默认超时为 5000 毫秒（5 秒），除非显式覆盖。超过超时时间的测试将失败。

全局超时

通过 --timeout 选项修改全局超时：

terminal

bun test --timeout 10000  # 10 秒

每个测试的超时

在测试函数的第三个参数中设置超时：

test.ts

import { test, expect } from "bun:test";

test("快速测试", () => {
  expect(1 + 1).toBe(2);
}, 1000); // 1 秒超时

test("慢速测试", async () => {
  await new Promise(resolve => setTimeout(resolve, 8000));
}, 10000); // 10 秒超时

无限超时

使用 0 或 Infinity 禁用超时：

test.ts

test("无超时测试", async () => {
  // 该测试可以无限运行
  await someVeryLongOperation();
}, 0);

错误处理

未捕获的错误

bun test 监控测试间出现的未捕获 Promise 拒绝和错误。如果出现此类错误，最终退出码会是非零的（具体为此类错误的数量），即使所有测试都通过。这有助于捕获异步代码中的错误，否则可能被忽略：

test.ts

import { test } from "bun:test";

test("测试 1", () => {
  // 测试通过
  expect(true).toBe(true);
});

// 该错误发生在任何测试外部
setTimeout(() => {
  throw new Error("未捕获的错误");
}, 0);

test("测试 2", () => {
  // 此测试也通过
  expect(true).toBe(true);
});

// 因未捕获的错误，测试运行仍会以非零码失败

Promise 拒绝

未处理的 Promise 拒绝也会被捕获：

test.ts

import { test } from "bun:test";

test("通过测试", () => {
  expect(1).toBe(1);
});

// 这将导致测试运行失败
Promise.reject(new Error("未处理的拒绝"));

自定义错误处理

你可以在测试设置中配置自定义错误处理器：

test-setup.ts

process.on("uncaughtException", error => {
  console.error("未捕获异常:", error);
  process.exit(1);
});

process.on("unhandledRejection", (reason, promise) => {
  console.error("未处理的拒绝发生于:", promise, "原因:", reason);
  process.exit(1);
});

CLI 选项集成

多个 Bun CLI 选项可与 bun test 一起使用以修改其行为：

内存使用

terminal

# 降低测试运行时 VM 的内存使用
bun test --smol

调试

terminal

# 将调试器附加到测试运行进程
bun test --inspect
bun test --inspect-brk

模块加载

terminal

# 在测试文件之前运行脚本（适用于全局初始化/模拟）
bun test --preload ./setup.ts

# 设置编译时常量
bun test --define "process.env.API_URL='http://localhost:3000'"

# 配置自定义加载器
bun test --loader .special:special-loader

# 使用不同的 tsconfig
bun test --tsconfig-override ./test-tsconfig.json

# 设置 package.json 中的条件以控制模块解析
bun test --conditions development

# 为测试加载环境变量
bun test --env-file .env.test

监视和热重载

监视模式

使用 --watch 标志运行 bun test 时，测试运行器会监听文件更改并重新运行受影响的测试。

terminal

bun test --watch

测试运行器会智能地确定需要重新运行的测试：

math.test.ts

import { add } from "./math.js";
import { test, expect } from "bun:test";

test("加法", () => {
  expect(add(2, 3)).toBe(5);
});

如果你修改了 math.js，只有 math.test.ts 会重新执行，而不会运行所有测试。

热重载

--hot 标志提供类似的功能，但更积极地尝试在测试运行之间保留状态：

terminal

bun test --hot

对于大多数测试场景，推荐使用 --watch，因为它提供了更好的测试隔离。

全局变量

以下全局变量在测试文件中自动可用，无需导入（但也可以从 bun:test 里导入，如果你愿意）：

test.ts

// 以下变量均全局可用
test("全局 test 函数", () => {
  expect(true).toBe(true);
});

describe("全局 describe", () => {
  beforeAll(() => {
    // 全局 beforeAll
  });

  it("全局 it 函数", () => {
    // it 是 test 的别名
  });
});

// Jest 兼容
jest.fn();

// Vitest 兼容
vi.fn();

如果喜欢，你也可以显式导入它们：

test.ts

import { test, it, describe, expect, beforeAll, beforeEach, afterAll, afterEach, jest, vi } from "bun:test";

进程集成

退出码

bun test 使用标准退出码：

0：所有测试通过，且无未捕获错误
1：出现测试失败
>1：未捕获错误的数量（即使测试通过）

信号处理

测试运行器正确处理常见信号：

terminal

# 优雅地停止测试执行
kill -SIGTERM <测试进程 PID>

# 立即停止测试执行
kill -SIGKILL <测试进程 PID>

环境检测

Bun 会自动检测某些环境并调整行为：

test.ts

// GitHub Actions 检测
if (process.env.GITHUB_ACTIONS) {
  // Bun 自动发送 GitHub Actions 注释
}

// CI 检测
if (process.env.CI) {
  // 可能针对 CI 环境调整某些行为
}

性能考虑

单进程

测试运行器默认在单个进程中运行所有测试。这带来了：

更快的启动时间 — 无需生成多个进程
共享内存 — 资源使用更高效
简单的调试 — 所有测试都在一个进程中

但这意味着：

测试共享全局状态（使用生命周期钩子进行清理）
一个测试崩溃可能影响其他测试
不支持真正的单个测试并行

内存管理

terminal

# 监控内存使用
bun test --smol  # 降低内存占用

# 对于大型测试套件，考虑按文件拆分
bun test src/unit/
bun test src/integration/

测试隔离

由于测试运行在同一进程，需确保适当清理：

test.ts

import { afterEach } from "bun:test";

afterEach(() => {
  // 清理全局状态
  global.myGlobalVar = undefined;
  delete process.env.TEST_VAR;

  // 如有需要，重置模块
  jest.resetModules();
});

入门

测试执行

测试特性

专门测试

报告

环境变量

NODE_ENV

TZ（时区）

测试超时

全局超时

每个测试的超时

无限超时

错误处理

未捕获的错误

Promise 拒绝

自定义错误处理

CLI 选项集成

内存使用

调试

模块加载

相关安装选项

监视和热重载

监视模式

热重载

全局变量

进程集成

退出码

信号处理

环境检测

性能考虑

单进程

内存管理

测试隔离

入门

测试执行

测试特性

专门测试

报告

​环境变量

​NODE_ENV

​TZ（时区）

​测试超时

​全局超时

​每个测试的超时

​无限超时

​错误处理

​未捕获的错误

​Promise 拒绝

​自定义错误处理

​CLI 选项集成

​内存使用

​调试

​模块加载

​相关安装选项

​监视和热重载

​监视模式

​热重载

​全局变量

​进程集成

​退出码

​信号处理

​环境检测

​性能考虑

​单进程

​内存管理

​测试隔离

环境变量

NODE_ENV

TZ（时区）

测试超时

全局超时

每个测试的超时

无限超时

错误处理

未捕获的错误

Promise 拒绝

自定义错误处理

CLI 选项集成

内存使用

调试

模块加载

相关安装选项

监视和热重载

监视模式

热重载

全局变量

进程集成

退出码

信号处理

环境检测

性能考虑

单进程

内存管理

测试隔离