name: Bun测试基础 description: 用于bun:test语法、断言、describe/it、test.skip/only/each以及基本模式。 version: 1.0.0

Bun测试基础

Bun内置了一个快速、兼容Jest的测试运行器。测试在Bun运行时中运行，并原生支持TypeScript/JSX。

快速开始

# 运行所有测试
bun test

# 运行特定文件
bun test ./test/math.test.ts

# 运行匹配模式的测试
bun test --test-name-pattern "addition"

编写测试

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

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

describe("math", () => {
  test("addition", () => {
    expect(1 + 1).toBe(2);
  });

  test("subtraction", () => {
    expect(5 - 3).toBe(2);
  });
});

测试文件模式

Bun发现匹配以下模式的测试文件：

*.test.{js|jsx|ts|tsx}
*_test.{js|jsx|ts|tsx}
*.spec.{js|jsx|ts|tsx}
*_spec.{js|jsx|ts|tsx}

测试修饰符

// 跳过测试
test.skip("未就绪", () => {
  // 不会运行
});

// 仅运行此测试
test.only("聚焦于此", () => {
  // 其他测试不会运行
});

// 未来测试占位符
test.todo("稍后实现");

// 预期失败
test.failing("已知错误", () => {
  throw new Error("这是预期的");
});

参数化测试

test.each([
  [1, 1, 2],
  [2, 2, 4],
  [3, 3, 6],
])("add(%i, %i) = %i", (a, b, expected) => {
  expect(a + b).toBe(expected);
});

// 使用对象
test.each([
  { a: 1, b: 2, expected: 3 },
  { a: 5, b: 5, expected: 10 },
])("add($a, $b) = $expected", ({ a, b, expected }) => {
  expect(a + b).toBe(expected);
});

并发测试

// 并行运行测试
test.concurrent("异步测试1", async () => {
  await fetch("/api/1");
});

test.concurrent("异步测试2", async () => {
  await fetch("/api/2");
});

// 使用--concurrent时强制顺序运行
test.serial("必须单独运行", () => {
  // 顺序运行
});

常见匹配器

// 相等性
expect(value).toBe(4);           // 严格相等
expect(obj).toEqual({ a: 1 });   // 深度相等
expect(value).toStrictEqual(4);  // 严格 + 类型

// 真值性
expect(value).toBeTruthy();
expect(value).toBeFalsy();
expect(value).toBeNull();
expect(value).toBeDefined();
expect(value).toBeUndefined();

// 数字
expect(value).toBeGreaterThan(3);
expect(value).toBeGreaterThanOrEqual(3);
expect(value).toBeLessThan(5);
expect(value).toBeCloseTo(0.3, 5);  // 浮点数

// 字符串
expect(str).toMatch(/pattern/);
expect(str).toContain("子字符串");
expect(str).toStartWith("Hello");
expect(str).toEndWith("world");

// 数组
expect(arr).toContain(item);
expect(arr).toContainEqual({ a: 1 });
expect(arr).toHaveLength(3);

// 对象
expect(obj).toHaveProperty("key");
expect(obj).toHaveProperty("key", value);
expect(obj).toMatchObject({ a: 1 });

// 异常
expect(() => fn()).toThrow();
expect(() => fn()).toThrow("消息");
expect(() => fn()).toThrow(CustomError);

// 异步
await expect(promise).resolves.toBe(value);
await expect(promise).rejects.toThrow();

// 否定
expect(value).not.toBe(5);

CLI选项

# 每个测试超时（默认5000毫秒）
bun test --timeout 20

# 在N次失败后停止
bun test --bail
bun test --bail=10

# 监视模式
bun test --watch

# 随机顺序
bun test --randomize
bun test --seed 12345

# 并发执行
bun test --concurrent
bun test --concurrent --max-concurrency 4

# 按名称过滤
bun test -t "pattern"

输出报告器

# 点状（紧凑）
bun test --dots

# JUnit XML（CI/CD）
bun test --reporter=junit --reporter-outfile=./results.xml

常见错误

错误	原因	修复
`测试超时`	测试超过5秒	使用`--timeout`或优化
`未找到测试`	错误的文件模式	检查文件命名
`expect未定义`	缺少导入	从`bun:test`导入
`断言失败`	测试失败	检查预期与实际

何时加载参考

加载references/matchers.md当：

需要完整的匹配器参考
自定义匹配器模式

加载references/cli-options.md当：

完整的CLI标志参考
高级执行选项