运行时行为

bun test 与 Bun 的运行时深度集成。此集成是 bun test 能够快速运行的原因之一。

环境变量

NODE_ENV

bun test 会将 $NODE_ENV 设置为 "test"，除非它已经在环境或 .env 文件中设置。大多数测试运行器也会这样做。

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（时区）

除非 TZ 环境变量对其进行覆盖，否则 bun test 会使用 UTC（Etc/UTC）作为时区。这可以确保日期和时间行为在不同机器上保持一致。

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 选项集成

Several Bun CLI flags also work with 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 .svg:text

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

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

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

监视和热重载

监视模式

使用 --watch 标志时，测试运行器会监视文件更改并重新运行测试。

terminal

bun test --watch

热重载

--hot 标志与之类似，但会更积极地在运行之间保留状态：

terminal

bun test --hot

对于大多数测试，请使用 --watch：它能在运行之间提供更好的隔离。

全局变量

以下全局变量在测试文件中无需导入即可使用：

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: 发生测试失败或未处理的错误

信号处理

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

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.restoreAllMocks();
});

入门

测试执行

测试特性

专门测试

报告

环境变量

NODE_ENV

TZ（时区）

测试超时

全局超时

每个测试的超时

无限超时

错误处理

未捕获的错误

Promise 拒绝

自定义错误处理

CLI 选项集成

内存使用

调试

模块加载

相关安装选项

监视和热重载

监视模式

热重载

全局变量

进程集成

退出码

信号处理

环境检测

性能考虑

单进程

内存管理

测试隔离

​环境变量

​NODE_ENV

​TZ（时区）

​测试超时

​全局超时

​每个测试的超时

​无限超时

​错误处理

​未捕获的错误

​Promise 拒绝

​自定义错误处理

​CLI 选项集成

​内存使用

​调试

​模块加载

​相关安装选项

​监视和热重载

​监视模式

​热重载

​全局变量

​进程集成

​退出码

​信号处理

​环境检测

​性能考虑

​单进程

​内存管理

​测试隔离

环境变量

NODE_ENV

TZ（时区）

测试超时

全局超时

每个测试的超时

无限超时

错误处理

未捕获的错误

Promise 拒绝

自定义错误处理

CLI 选项集成

内存使用

调试

模块加载

相关安装选项

监视和热重载

监视模式

热重载

全局变量

进程集成

退出码

信号处理

环境检测

性能考虑

单进程

内存管理

测试隔离