本文将详细介绍在 jest 单元测试中，如何有效断言被 jest.mock() 模拟的模块方法是否被调用及其调用参数。核心策略是在 jest.mock() 调用之前导入目标模块方法，从而避免“out-of-scope variable”错误，并确保能够通过导入的引用直接对模拟函数进行断言，适用于 javascript 和 typescript 环境。
在进行单元测试时，我们经常需要模拟（mock）外部依赖，以隔离被测试模块。Jest 提供了强大的 jest.mock() 功能来完成这项任务。然而，当我们需要断言一个被模拟模块的特定方法是否被调用，以及调用参数是否正确时，可能会遇到一些挑战，特别是当 jest.mock() 的工厂函数试图引用其外部作用域的变量时，Jest 会抛出“The module factory of jest.mock() is not allowed to reference any out-of-scope variables”的错误。本教程将深入探讨如何优雅地解决这一问题。
核心策略：在 jest.mock() 之前导入目标方法
解决上述问题的关键在于，在调用 jest.mock() 模拟整个模块之前，先通过 import 语句引入你希望断言的那个特定方法。Jest 的模块解析和模拟机制会确保你导入的变量最终指向你为该模块定义的模拟函数。
JavaScript 示例
假设我们有一个服务模块 services/logs.service.js，其中导出了一个 log 方法：
// services/logs.service.js
export const log = (level, message) => {
console.log(`[${level}] ${message}`);
};在测试文件中，如果你想模拟 log 方法并断言它的调用，可以这样做：
// __tests__/my.spec.js
// 关键步骤：在 jest.mock() 调用之前导入 log 方法
import { log } from '../../../../services/logs.service.js';
// 使用 jest.mock() 模拟整个模块
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn() // 在模拟工厂函数中定义一个 jest mock 函数
}));
describe('我的模块功能测试', () => {
// 假设这里有一个被测试的函数或类
// 例如：const myModule = require('../path/to/myModule');
it('应该正确调用日志服务', () => {
// 调用会触发 log 服务的方法
// 例如：myModule.doSomething();
// 现在，我们可以直接对导入的 log 变量进行断言
// 它已经被 Jest 替换为我们定义的 jest.fn()
expect(log).toHaveBeenCalledWith(2, "foo"); // 断言调用参数
expect(log).toHaveBeenCalledTimes(1); // 断言调用次数
});
// 注意事项：为了测试独立性，通常在每个测试用例前清除 mock 状态
beforeEach(() => {
log.mockClear(); // 清除特定模拟函数的调用记录
// 或者 jest.clearAllMocks(); // 清除所有模拟函数的记录
});
});在这个例子中，尽管 log 方法是在 jest.mock() 的工厂函数内部被定义为 jest.fn()，但由于我们事先通过 import { log } from ... 引入了它，Jest 会在运行时确保这个 log 变量指向我们定义的模拟函数。这样，我们就能在测试代码中直接通过 log 变量对模拟函数进行断言。
TypeScript 示例
对于 TypeScript 项目，处理方式基本相同，但为了获得更好的类型提示和避免潜在的类型错误，通常会进行类型断言：
// services/logs.service.ts
export const log = (level: number, message: string): void => {
console.log(`[${level}] ${message}`);
};在 TypeScript 测试文件中：
// __tests__/my.spec.ts
// 同样在 jest.mock() 调用之前导入 log 方法
import { log } from '../../../../services/logs.service.js';
// 使用 jest.mock() 模拟整个模块
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn() // 定义一个 jest mock 函数
}));
describe('我的模块功能测试 (TypeScript)', () => {
it('应该正确调用日志服务', () => {
// 假设这里有一个被测试的函数或类
// 例如：myModule.doSomething();
// TypeScript 中，为了获得 Jest mock 函数的完整类型提示，通常会进行类型断言
const mockedLog = log as jest.MockedFunction<typeof log>;
expect(mockedLog).toHaveBeenCalledWith(2, "foo");
expect(mockedLog).toHaveBeenCalledTimes(1);
});
beforeEach(() => {
(log as jest.MockedFunction<typeof log>).mockClear();
// 或者 jest.clearAllMocks();
});
});通过 const mockedLog = log as jest.MockedFunction
原理阐释
Jest 在运行测试时，会对模块导入和 jest.mock() 调用进行特殊的“提升”（hoisting）和模块解析处理。当 jest.mock() 被调用时，它会在目标模块实际加载之前“劫持”该模块的导入。这意味着，即使你在 jest.mock() 之前写下了 import { log } from ...，当测试代码执行到需要 log 变量时，Jest 会确保这个变量指向的是你在 jest.mock() 的工厂函数中提供的模拟实现（即 jest.fn()），而不是原始的 log 函数。因此，在你的测试代码中，你通过 import 语句获取到的 log 实际上就是 jest.fn() 的实例，你可以对其进行所有的 Jest 断言操作。
注意事项
- 导入顺序至关重要： 务必确保 import 语句位于 jest.mock() 调用之前。如果顺序颠倒，你可能会断言到原始函数（如果未被完全模拟）或遇到其他意料之外的问题。
- jest.mock() 的作用域： jest.mock() 调用本身通常会被 Jest 提升到文件顶部，但其内部的工厂函数是在模块加载时才执行的。通过直接在 jest.mock() 的工厂函数中返回 jest.fn()，可以确保模拟函数是在正确的上下文中创建的，并避免“out-of-scope variable”错误。
- 测试间状态清理： 模拟函数的调用记录是会累积的。为了确保每个测试用例的独立性和可重复性，强烈建议在 beforeEach 钩子中使用 mockFn.mockClear() 来清除特定模拟函数的调用记录，或使用 jest.clearAllMocks() 来清除所有模拟函数的记录。这可以避免一个测试用例的调用记录影响到后续的测试用例。
- 命名导出与默认导出： 本文示例针对命名导出。对于默认导出，原理类似，只是导入语法会有所不同（例如 import MyModule from './my-module'）。
总结
在 Jest 单元测试中，要有效断言被 jest.mock() 模拟的模块方法，关键在于在 jest.mock() 调用之前使用 import 语句引入目标方法。这一策略不仅解决了“out-of-scope variable”的常见错误，还使得在 JavaScript 和 TypeScript 环境下都能清晰、准确地对模拟函数的调用行为进行断言。结合适当的测试状态清理（如 beforeEach 中的 mockClear()），你可以构建出健壮且易于维护的单元测试。
