Mock · 文档

模拟会使用受控的实现替换依赖项。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: "mock@example.com",
    ...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);
  }
  // ...很多复杂逻辑
});

使用类型安全的模拟

TypeScript

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，以便在运行时覆盖导出值，并递归更新实时绑定。