> ## 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.

# 运行时行为

> 了解 Bun test 的运行时集成、环境变量、超时和错误处理

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

## 环境变量

### NODE\_ENV

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

```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 "bun:test";

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

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

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
NODE_ENV=development bun test
```

### TZ（时区）

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

```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 "bun:test";

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

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

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
TZ=America/New_York bun test
```

## 测试超时

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

### 全局超时

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

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun test --timeout 10000  # 10 秒
```

### 每个测试的超时

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

```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 "bun:test";

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

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

### 无限超时

使用 `0` 或 `Infinity` 禁用超时：

```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"}}
test("无超时测试", async () => {
  // 该测试可以无限运行
  await someVeryLongOperation();
}, 0);
```

## 错误处理

### 未捕获的错误

`bun test` 监控测试间出现的未捕获 Promise 拒绝和错误。如果出现此类错误，最终退出码会是非零的（具体为此类错误的数量），即使所有测试都通过。

这有助于捕获异步代码中的错误，否则可能被忽略：

```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 } from "bun:test";

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

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

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

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

### Promise 拒绝

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

```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 } from "bun:test";

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

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

### 自定义错误处理

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

```ts title="test-setup.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"}}
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` 一起使用以修改其行为：

### 内存使用

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 降低测试运行时 VM 的内存使用
bun test --smol
```

### 调试

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 将调试器附加到测试运行进程
bun test --inspect
bun test --inspect-brk
```

### 模块加载

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 在测试文件之前运行脚本（适用于全局初始化/模拟）
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
```

### 相关安装选项

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
# 影响测试执行期间的网络请求或自动安装
bun test --prefer-offline
bun test --frozen-lockfile
```

## 监视和热重载

### 监视模式

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

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

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

```ts title="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"}}
import { add } from "./math.js";
import { test, expect } from "bun:test";

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

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

### 热重载

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

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

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

## 全局变量

以下全局变量在测试文件中自动可用，无需导入（但也可以从 `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"}}
// 以下变量均全局可用
test("全局 test 函数", () => {
  expect(true).toBe(true);
});

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

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

// Jest 兼容
jest.fn();

// Vitest 兼容
vi.fn();
```

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

```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, it, describe, expect, beforeAll, beforeEach, afterAll, afterEach, jest, vi } from "bun:test";
```

## 进程集成

### 退出码

`bun test` 使用标准退出码：

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

### 信号处理

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

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 优雅地停止测试执行
kill -SIGTERM <测试进程 PID>

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

### 环境检测

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

```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"}}
// GitHub Actions 检测
if (process.env.GITHUB_ACTIONS) {
  // Bun 自动发送 GitHub Actions 注释
}

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

## 性能考虑

### 单进程

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

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

但这意味着：

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

### 内存管理

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 监控内存使用
bun test --smol  # 降低内存占用

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

### 测试隔离

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

```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 { afterEach } from "bun:test";

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

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