Mock - Bun 中文文档

模拟会使用受控的实现替换依赖项。Bun 支持函数模拟、间谍以及模块模拟。

基础函数模拟

使用 mock 函数创建模拟。

test.ts

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

const random = mock(() => Math.random());

test("random", () => {
  const val = random();
  expect(val).toBeGreaterThan(0);
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

Jest 兼容性

你也可以像在 Jest 中一样使用 jest.fn()。它的行为完全相同。

test.ts

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

const random = jest.fn(() => Math.random());

test("random", () => {
  const val = random();
  expect(val).toBeGreaterThan(0);
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

模拟函数属性

mock() 返回一个带有附加属性的新函数。

test.ts

import { mock } from "bun:test";

const random = mock((multiplier: number) => multiplier * Math.random());

random(2);
random(10);

random.mock.calls;
// [[ 2 ], [ 10 ]]

random.mock.results;
//  [
//    { type: "return", value: 0.6533907460954099 },
//    { type: "return", value: 0.6452713933037312 }
//  ]

可用属性和方法

模拟函数实现了以下属性和方法：

属性/方法	描述
`mockFn.getMockName()`	返回模拟函数名称
`mockFn.mock.calls`	每次调用的参数数组
`mockFn.mock.results`	每次调用的返回值数组
`mockFn.mock.instances`	使用 `new` 创建的实例数组
`mockFn.mock.contexts`	每次调用的 `this` 上下文数组
`mockFn.mock.lastCall`	最近一次调用的参数
`mockFn.mockClear()`	清除调用历史
`mockFn.mockReset()`	清除调用历史并移除实现
`mockFn.mockRestore()`	恢复原始实现
`mockFn.mockImplementation(fn)`	设置新的实现
`mockFn.mockImplementationOnce(fn)`	仅为下一次调用设置实现
`mockFn.mockName(name)`	设置模拟函数名称
`mockFn.mockReturnThis()`	将返回值设置为 `this`
`mockFn.mockReturnValue(value)`	设置返回值
`mockFn.mockReturnValueOnce(value)`	仅为下一次调用设置返回值
`mockFn.mockResolvedValue(value)`	设置已解决的 Promise 值
`mockFn.mockResolvedValueOnce(value)`	仅为下一次调用设置已解决的 Promise
`mockFn.mockRejectedValue(value)`	设置已拒绝的 Promise 值
`mockFn.mockRejectedValueOnce(value)`	仅为下一次调用设置已拒绝的 Promise
`mockFn.withImplementation(fn, callback)`	临时更改实现

实际示例

基础模拟用法

test.ts

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

test("mock function behavior", () => {
  const mockFn = mock((x: number) => x * 2);

  // 调用模拟函数
  const result1 = mockFn(5);
  const result2 = mockFn(10);

  // 验证调用情况
  expect(mockFn).toHaveBeenCalledTimes(2);
  expect(mockFn).toHaveBeenCalledWith(5);
  expect(mockFn).toHaveBeenLastCalledWith(10);

  // 检查返回结果
  expect(result1).toBe(10);
  expect(result2).toBe(20);

  // 检视调用历史
  expect(mockFn.mock.calls).toEqual([[5], [10]]);
  expect(mockFn.mock.results).toEqual([
    { type: "return", value: 10 },
    { type: "return", value: 20 },
  ]);
});

动态模拟实现

test.ts

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

test("dynamic mock implementations", () => {
  const mockFn = mock();

  // 设置不同实现
  mockFn.mockImplementationOnce(() => "first");
  mockFn.mockImplementationOnce(() => "second");
  mockFn.mockImplementation(() => "default");

  expect(mockFn()).toBe("first");
  expect(mockFn()).toBe("second");
  expect(mockFn()).toBe("default");
  expect(mockFn()).toBe("default"); // 使用默认实现
});

异步模拟

test.ts

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

test("async mock functions", async () => {
  const asyncMock = mock();

  // 模拟解析的值
  asyncMock.mockResolvedValueOnce("first result");
  asyncMock.mockResolvedValue("default result");

  expect(await asyncMock()).toBe("first result");
  expect(await asyncMock()).toBe("default result");

  // 模拟拒绝的值
  const rejectMock = mock();
  rejectMock.mockRejectedValue(new Error("Mock error"));

  await expect(rejectMock()).rejects.toThrow("Mock error");
});

使用 spyOn() 创建间谍

使用 spyOn() 跟踪函数调用，而不将其替换为模拟函数。你可以将间谍传给 .toHaveBeenCalled() 和 .toHaveBeenCalledTimes()。

test.ts

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

const ringo = {
  name: "Ringo",
  sayHi() {
    console.log(`Hello I'm ${this.name}`);
  },
};

const spy = spyOn(ringo, "sayHi");

test("spyon", () => {
  expect(spy).toHaveBeenCalledTimes(0);
  ringo.sayHi();
  expect(spy).toHaveBeenCalledTimes(1);
});

高级间谍用法

test.ts

import { test, expect, spyOn, afterEach, jest } from "bun:test";

class UserService {
  async getUser(id: string) {
    // 原始实现
    return { id, name: `User ${id}` };
  }

  async saveUser(user: any) {
    // 原始实现
    return { ...user, saved: true };
  }
}

const userService = new UserService();

afterEach(() => {
  // 每个测试后恢复所有间谍
  jest.restoreAllMocks();
});

test("spy on service methods", async () => {
  // 监听但不改变实现
  const getUserSpy = spyOn(userService, "getUser");
  const saveUserSpy = spyOn(userService, "saveUser");

  // 正常使用服务
  const user = await userService.getUser("123");
  await userService.saveUser(user);

  // 验证调用
  expect(getUserSpy).toHaveBeenCalledWith("123");
  expect(saveUserSpy).toHaveBeenCalledWith(user);
});

test("spy with mock implementation", async () => {
  // 监听并覆盖实现
  const getUserSpy = spyOn(userService, "getUser").mockResolvedValue({
    id: "123",
    name: "Mocked User",
  });

  const result = await userService.getUser("123");

  expect(result.name).toBe("Mocked User");
  expect(getUserSpy).toHaveBeenCalledWith("123");
});

使用 mock.module() 进行模块模拟

使用 mock.module(path: string, callback: () => Object) 覆盖模块的行为。

test.ts

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

mock.module("./module", () => {
  return {
    foo: "bar",
  };
});

test("mock.module", async () => {
  const esm = await import("./module");
  expect(esm.foo).toBe("bar");

  const cjs = require("./module");
  expect(cjs.foo).toBe("bar");
});

与 Bun 其他部分一样，模块模拟同时支持 import 和 require。

重写已导入模块

调用 mock.module() 会覆盖模块，即使该模块已经被导入。

test.ts

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

// 我们将模拟的模块：
import { foo } from "./module";

test("mock.module", async () => {
  const cjs = require("./module");
  expect(foo).toBe("bar");
  expect(cjs.foo).toBe("bar");

  // 这里更新模拟：
  mock.module("./module", () => {
    return {
      foo: "baz",
    };
  });

  // 实时绑定会自动更新。
  expect(foo).toBe("baz");

  // 该模块对 CJS 也会更新。
  expect(cjs.foo).toBe("baz");
});

当工厂函数返回一个仍处于待定状态的 Promise 时，Bun 会在该 Promise 完成后更新已导入的模块。在这种情况下，mock.module() 会返回一个在更新完成后解析的 Promise；否则，它会返回 undefined。在测试或钩子中使用 await mock.module(...) 可以同时处理这两种情况。在测试文件的顶层，Bun 会等待待定的模块模拟完成后再运行文件中的测试。

test.ts

import { test, expect, mock } from "bun:test";
import { foo } from "./module";

mock.module("./module", async () => {
  const { default: fixture } = await import("./fixture.json");
  return { foo: fixture.foo };
});

test("async factory", () => {
  expect(foo).toBe("baz");
});

fixture.json

{ "foo": "baz" }

提升与预加载

为了确保模块在导入之前已被模拟，请使用 --preload 在测试运行前加载模拟模块。

my-preload.ts

import { mock } from "bun:test";

mock.module("./module", () => {
  return {
    foo: "bar",
  };
});

terminal

bun test --preload ./my-preload

为了避免每次运行测试时都输入 --preload，请将其添加到 bunfig.toml 中：

bunfig.toml

[test]
# 在运行测试前加载这些模块。
preload = ["./my-preload"]

模块模拟最佳实践

何时使用预加载

模拟已导入的模块会更新模块缓存，因此任何导入该模块的内容都会获取模拟版本。不过，Bun 已经执行了原始模块，因此其副作用也已经发生。若要完全避免执行原始模块，请使用 --preload 在测试运行前加载模拟模块。

实际模块模拟示例

api-client.test.ts

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

// 模拟 API 客户端模块
mock.module("./api-client", () => ({
  fetchUser: mock(async (id: string) => ({ id, name: `User ${id}` })),
  createUser: mock(async (user: any) => ({ ...user, id: "new-id" })),
  updateUser: mock(async (id: string, user: any) => ({ ...user, id })),
}));

test("user service with mocked API", async () => {
  const { fetchUser } = await import("./api-client");
  const { UserService } = await import("./user-service");

  const userService = new UserService();
  const user = await userService.getUser("123");

  expect(fetchUser).toHaveBeenCalledWith("123");
  expect(user.name).toBe("User 123");
});

模拟外部依赖

database.test.ts

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

// 模拟外部数据库库
mock.module("pg", () => ({
  Client: mock(function () {
    return {
      connect: mock(async () => {}),
      query: mock(async (sql: string) => ({
        rows: [{ id: 1, name: "Test User" }],
      })),
      end: mock(async () => {}),
    };
  }),
}));

test("database operations", async () => {
  const { Database } = await import("./database");
  const db = new Database();

  const users = await db.getUsers();
  expect(users).toHaveLength(1);
  expect(users[0].name).toBe("Test User");
});

全局模拟函数

清除所有模拟

mock.clearAllMocks() 会重置每个模拟的 .mock.calls、.mock.instances、.mock.contexts 和 .mock.results 属性。与 mock.restore() 不同，它不会恢复原始实现：

test.ts

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

const random1 = mock(() => Math.random());
const random2 = mock(() => Math.random());

test("clearing all mocks", () => {
  random1();
  random2();

  expect(random1).toHaveBeenCalledTimes(1);
  expect(random2).toHaveBeenCalledTimes(1);

  mock.clearAllMocks();

  expect(random1).toHaveBeenCalledTimes(0);
  expect(random2).toHaveBeenCalledTimes(0);

  // 注意：实现依然存在
  expect(typeof random1()).toBe("number");
  expect(typeof random2()).toBe("number");
});

重置所有模拟

jest.resetAllMocks()（及其别名 vi.resetAllMocks()）会对每个模拟调用 mockFn.mockReset()。除了 clearAllMocks() 的操作外，它还会丢弃通过 mockImplementation()、mockReturnValue() 等方法设置的实现。它不会恢复间谍的原始实现：

test.ts

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

const random = jest.fn(() => Math.random());

test("resetting all mocks", () => {
  random();
  expect(random).toHaveBeenCalledTimes(1);

  jest.resetAllMocks();

  expect(random).toHaveBeenCalledTimes(0);
  // 与 clearAllMocks() 不同，实现已被删除
  expect(random()).toBeUndefined();
});

恢复所有模拟

mock.restore() 一次性恢复所有模拟，而不必分别对每个模拟调用 mockFn.mockRestore()。它不会重置通过 mock.module() 覆盖的模块。

test.ts

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

import * as fooModule from "./foo.ts";
import * as barModule from "./bar.ts";
import * as bazModule from "./baz.ts";

test("foo, bar, baz", () => {
  const fooSpy = spyOn(fooModule, "foo");
  const barSpy = spyOn(barModule, "bar");
  const bazSpy = spyOn(bazModule, "baz");

  // 原始实现仍可用
  expect(fooModule.foo()).toBe("foo");
  expect(barModule.bar()).toBe("bar");
  expect(bazModule.baz()).toBe("baz");

  // 模拟实现
  fooSpy.mockImplementation(() => 42);
  barSpy.mockImplementation(() => 43);
  bazSpy.mockImplementation(() => 44);

  expect(fooModule.foo()).toBe(42);
  expect(barModule.bar()).toBe(43);
  expect(bazModule.baz()).toBe(44);

  // 恢复所有
  mock.restore();

  expect(fooModule.foo()).toBe("foo");
  expect(barModule.bar()).toBe("bar");
  expect(bazModule.baz()).toBe("baz");
});

在 afterEach 块或测试预加载脚本中调用 mock.restore()，这样就不必在每个测试中重复清理操作。

Vitest 兼容性

为方便移植 Vitest 编写的测试，Bun 提供了 vi 对象作为 Jest 模拟 API 部分的别名：

test.ts

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

// 使用 'vi' 别名，类似 Vitest
test("vitest compatibility", () => {
  const mockFn = vi.fn(() => 42);

  mockFn();
  expect(mockFn).toHaveBeenCalled();

  // vi 对象支持以下函数：
  // vi.fn
  // vi.spyOn
  // vi.mock
  // vi.restoreAllMocks
  // vi.resetAllMocks
  // vi.clearAllMocks
});

你可以直接移植 Vitest 测试，无需重写模拟函数。

实现细节

缓存交互

模块模拟会与 ESM 和 CommonJS 模块缓存交互。

惰性求值

Bun 仅在导入或 require 模块时才会执行模拟工厂回调。

路径解析

Bun 以解析 import 的相同方式解析模块说明符，支持：

相对路径（'./module'）
绝对路径（'/path/to/module'）
包名（'lodash'）

导入时机影响

在首次导入前模拟：原模块不会执行副作用
在导入后模拟：原模块副作用已经发生

因此，对于需要阻止副作用的模拟，请使用 --preload。

实时绑定

被模拟的 ESM 模块会维护实时绑定，因此更改模拟内容会更新所有现有导入。

高级模式

工厂函数

test.ts

import { mock } from "bun:test";

function createMockUser(overrides = {}) {
  return {
    id: "mock-id",
    name: "Mock User",
    email: "[email protected]",
    ...overrides,
  };
}

const mockUserService = {
  getUser: mock(async (id: string) => createMockUser({ id })),
  createUser: mock(async (data: any) => createMockUser(data)),
  updateUser: mock(async (id: string, data: any) => createMockUser({ id, ...data })),
};

条件式模拟

test.ts

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

const shouldUseMockApi = process.env.NODE_ENV === "test";

if (shouldUseMockApi) {
  mock.module("./api", () => ({
    fetchData: mock(async () => ({ data: "mocked" })),
  }));
}

test("conditional API usage", async () => {
  const { fetchData } = await import("./api");
  const result = await fetchData();

  if (shouldUseMockApi) {
    expect(result.data).toBe("mocked");
  }
});

模拟清理模式

test.ts

import { afterEach, beforeEach, mock } from "bun:test";

beforeEach(() => {
  // 设定通用模拟
  mock.module("./logger", () => ({
    log: mock(() => {}),
    error: mock(() => {}),
    warn: mock(() => {}),
  }));
});

afterEach(() => {
  // Restore spies and clear call history; neither call resets the mock.module() override
  mock.restore();
  mock.clearAllMocks();
});

最佳实践

保持模拟简单

test.ts

// 好：简单、聚焦的模拟
const mockUserApi = {
  getUser: mock(async id => ({ id, name: "Test User" })),
};

// 避免：过于复杂的模拟行为
const complexMock = mock(input => {
  if (input.type === "A") {
    return processTypeA(input);
  } else if (input.type === "B") {
    return processTypeB(input);
  }
  // ...很多复杂逻辑
});

使用类型安全的模拟

interface UserService {
  getUser(id: string): Promise<User>;
  createUser(data: CreateUserData): Promise<User>;
}

const mockUserService: UserService = {
  getUser: mock(async (id: string) => ({ id, name: "Test User" })),
  createUser: mock(async data => ({ id: "new-id", ...data })),
};

测试模拟行为

test.ts

test("service calls API correctly", async () => {
  const mockApi = { fetchUser: mock(async () => ({ id: "1" })) };

  const service = new UserService(mockApi);
  await service.getUser("123");

  // 验证模拟被正确调用
  expect(mockApi.fetchUser).toHaveBeenCalledWith("123");
  expect(mockApi.fetchUser).toHaveBeenCalledTimes(1);
});

备注

自动模拟

Bun 不支持 __mocks__ 目录或自动模拟。如果这阻碍了你迁移到 Bun，请提交 issue。

ESM 与 CommonJS

ESM 和 CommonJS 模块的模块模拟实现方式不同。对于 ES 模块，Bun 会修补 JavaScriptCore，以便在运行时覆盖导出值，并递归更新实时绑定。

​基础函数模拟

​Jest 兼容性

​模拟函数属性

​可用属性和方法

​实际示例

​基础模拟用法

​动态模拟实现

​异步模拟

​使用 spyOn() 创建间谍

​高级间谍用法

​使用 mock.module() 进行模块模拟

​重写已导入模块

​提升与预加载

​模块模拟最佳实践

​何时使用预加载

​实际模块模拟示例

​模拟外部依赖

​全局模拟函数

​清除所有模拟

​重置所有模拟

​恢复所有模拟

​Vitest 兼容性

​实现细节

​缓存交互

​惰性求值

​路径解析

​导入时机影响

​实时绑定

​高级模式

​工厂函数

​条件式模拟

​模拟清理模式

​最佳实践

​保持模拟简单

​使用类型安全的模拟

​测试模拟行为

​备注

​自动模拟

​ESM 与 CommonJS

基础函数模拟

Jest 兼容性

模拟函数属性

可用属性和方法

实际示例

基础模拟用法

动态模拟实现

异步模拟

使用 spyOn() 创建间谍

高级间谍用法

使用 mock.module() 进行模块模拟

重写已导入模块

提升与预加载

模块模拟最佳实践

何时使用预加载

实际模块模拟示例

模拟外部依赖

全局模拟函数

清除所有模拟

重置所有模拟

恢复所有模拟

Vitest 兼容性

实现细节

缓存交互

惰性求值

路径解析

导入时机影响

实时绑定

高级模式

工厂函数

条件式模拟

模拟清理模式

最佳实践

保持模拟简单

使用类型安全的模拟

测试模拟行为

备注

自动模拟

ESM 与 CommonJS