本文详细介绍了在jest测试框架中，如何正确地对被mock的模块方法进行调用断言。针对常见的因`jest.mock()`作用域限制导致的“out-of-scope”变量引用错误，文章提供了基于`import`机制的解决方案，并分别展示了javascript和typescript环境下的实现方法，确保测试能够有效验证mocked方法的调用情况。
在Jest中进行单元测试时，我们经常需要模拟（mock）外部依赖模块的方法，以便隔离被测试代码，专注于其自身的逻辑。然而，在尝试断言这些被模拟方法是否被正确调用时，开发者可能会遇到一些作用域问题。
理解问题根源
考虑以下常见的模拟场景，我们希望模拟一个日志服务模块中的log方法：
// services/logs.service.js
export const log = (level, message) => {
console.log(`[${level}] ${message}`);
};
// .spec.js
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn()
}));当尝试直接在测试文件中断言这个log方法时，例如：
// 期望log方法被调用两次，参数为2和"foo" expect(log).toHaveBeenCalledWith(2, "foo");
会发现log变量是未定义的，因为jest.fn()创建的模拟函数只存在于jest.mock()的回调函数内部。
一些开发者可能会尝试将log函数的初始化移到jest.mock()外部，以便在测试文件中直接访问：
const log = jest.fn(); // 尝试将log定义在外部
jest.mock('../../../../services/logs.service.js', () => ({
log // 引用外部的log
}));然而，这种做法会导致Jest抛出错误：The module factory of jest.mock() is not allowed to reference any out-of-scope variables.（jest.mock()的模块工厂不允许引用任何超出作用域的变量）。这是Jest设计上的一个限制，旨在确保模拟的独立性和可预测性。
解决方案：利用模块导入机制
解决这个问题的关键在于，我们应该在定义jest.mock()之前，先将原始模块中的方法导入到当前测试文件中。Jest的模块系统会智能地识别这个导入，并在jest.mock()定义后，将导入的引用指向我们定义的模拟函数。
1. JavaScript 环境下的实现
在JavaScript环境中，只需在测试文件顶部导入你想要模拟的方法，然后正常定义jest.mock()。Jest会自动将该导入指向你的模拟实现。
// .spec.js
// 1. 从原始模块中导入log方法。
// 即使它将被模拟，这个导入操作是必要的，它为Jest提供了一个“钩子”。
import { log } from '../../../../services/logs.service.js';
// 2. 定义模块的模拟实现。
// 这里的log: jest.fn() 会覆盖上面导入的log引用。
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn() // 定义一个jest的模拟函数
}));
describe('My Module Test', () => {
beforeEach(() => {
// 在每个测试前重置mock的调用状态，确保测试独立性
(log as jest.Mock).mockClear();
});
test('should call log method with correct arguments', () => {
// 假设这里调用了某个会触发log方法的函数
// yourFunctionThatCallsLog();
// 3. 现在可以直接断言导入的log方法
expect(log).toHaveBeenCalledWith(2, "foo");
expect(log).toHaveBeenCalledTimes(1); // 示例：验证调用次数
});
test('another scenario', () => {
// anotherFunctionThatCallsLog();
expect(log).not.toHaveBeenCalled();
});
});解释： 当你在jest.mock()之前使用import { log } from ...时，你实际上是在告诉Jest：“我需要这个模块的log导出”。然后，当jest.mock()被执行时，Jest会拦截对'../../../../services/logs.service.js'模块的任何引用，并用你提供的模拟工厂函数替换它。因此，你通过import语句获得的log变量，实际上会指向jest.mock()中定义的jest.fn()实例。
2. TypeScript 环境下的实现
在TypeScript中，除了上述JavaScript的导入和模拟步骤外，为了获得更好的类型推断和避免潜在的类型错误，我们通常会将导入的模拟函数进行类型断言，明确它是一个jest.MockedFunction。
// .spec.ts
// 1. 从原始模块中导入log方法
import { log } from '../../../../services/logs.service.js';
// 2. 定义模块的模拟实现
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn() // 定义一个jest的模拟函数
}));
describe('My Module Test', () => {
// 3. (可选但推荐) 对导入的log进行类型断言，明确它是一个Jest Mock函数
// 这样可以获得更好的类型提示，并确保你可以访问jest.Mock特有的方法（如.mockClear()）
const mockedLog = log as jest.MockedFunction<typeof log>;
beforeEach(() => {
// 在每个测试前重置mock的调用状态
mockedLog.mockClear();
});
test('should call log method with correct arguments in TypeScript', () => {
// 假设这里调用了某个会触发log方法的函数
// yourFunctionThatCallsLog();
// 4. 使用类型断言后的mockedLog进行断言
expect(mockedLog).toHaveBeenCalledWith(2, "foo");
expect(mockedLog).toHaveBeenCalledTimes(1);
});
});解释：as jest.MockedFunction
注意事项与最佳实践
- 导入顺序： 务必在jest.mock()调用之前导入你需要模拟的模块成员。
- mockClear() 或 mockReset()： 在每个测试用例（或测试套件）开始前，使用mockClear()或mockReset()来清除模拟函数的调用历史和状态。这有助于确保测试用例之间的隔离性，避免前一个测试的副作用影响到后续测试。通常放在beforeEach钩子中。
-
断言匹配器： Jest提供了丰富的模拟函数匹配器，例如：
- toHaveBeenCalled()：验证函数是否被调用过。
- toHaveBeenCalledTimes(number)：验证函数被调用的次数。
- toHaveBeenCalledWith(...args)：验证函数被调用时传递的参数。
- lastCalledWith(...args)：验证函数最后一次被调用时传递的参数。
- nthCalledWith(nthCall, ...args)：验证函数第n次被调用时传递的参数。
- 命名导出 vs 默认导出： 上述示例针对的是命名导出。如果模块是默认导出，则导入方式会有所不同，例如 import MyModule from './my-module';，然后模拟时通常是 jest.mock('./my-module', () => ({ default: jest.fn() }));。
总结
在Jest中正确地断言被模拟的模块方法调用，关键在于理解Jest的模块模拟机制和作用域规则。通过在jest.mock()之前明确导入目标方法，并结合TypeScript中的类型断言，可以有效地解决常见的“out-of-scope”问题，并编写出健壮、可维护的测试代码。遵循这些实践，将大大提升测试的准确性和开发效率。
