在 jest 中断言模拟模块方法的调用时，常见的挑战是无法直接访问 `jest.mock()` 工厂函数内部定义的模拟函数。本文将详细介绍如何通过正确导入模块并结合 jest 的模拟机制，在 javascript 和 typescript 环境下，有效地获取并断言模拟模块方法的调用，解决“不允许引用作用域外变量”的错误。
理解 Jest 模拟中的作用域问题
在使用 Jest 进行模块模拟时，我们经常会遇到需要模拟一个模块的特定方法，并在测试中验证该方法是否被调用以及调用参数。一个常见的错误尝试如下：
// 错误的尝试：尝试在 jest.mock 外部定义并引用
const log = jest.fn(); // 声明在外部
jest.mock('../../../../services/logs.service.js', () => ({
log // 在 jest.mock 工厂函数中引用外部变量
}));
// 此时，直接使用 expect(log).toHaveBeenCalledWith(...) 会导致错误
// 因为 jest.mock 的工厂函数不允许引用其作用域之外的变量。上述代码会导致 Jest 抛出错误：“The module factory of jest.mock() is not allowed to reference any out-of-scope variables.” 这是因为 Jest 的模拟机制在内部实现上，要求 jest.mock() 的第二个参数（模块工厂函数）是自包含的，不能依赖外部作用域的变量来定义模拟。
正确断言模拟模块方法调用的方法
要正确地断言一个被模拟的模块方法，关键在于在测试文件中先导入原始模块的引用，然后 Jest 会在内部将这个引用指向模拟后的函数。
1. JavaScript 环境下的解决方案
在 JavaScript 中，解决方案非常直接：首先从目标模块中导入你需要模拟并断言的方法，然后在 jest.mock() 中定义该方法的模拟实现。Jest 会确保你导入的变量最终指向模拟后的函数。
免费 盛世企业网站管理系统(SnSee)系统完全免费使用，无任何功能模块使用限制，在使用过程中如遇到相关问题可以去官方论坛参与讨论。开源 系统Web代码完全开源，在您使用过程中可以根据自已实际情况加以调整或修改，完全可以满足您的需求。强大且灵活 独创的多语言功能，可以直接在后台自由设定语言版本，其语言版本不限数量，可根据自已需要进行任意设置；系统各模块可在后台自由设置及开启；强大且适用的后台管理支
// 1. 从目标模块导入 'log' 方法
import { log } from '../../../../services/logs.service.js';
// 2. 使用 jest.mock 模拟整个模块，并定义 'log' 的模拟实现
// 此时，导入的 'log' 变量将指向这个 jest.fn()
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn() // 定义模拟函数
}));
// 3. 现在可以安全地对导入的 'log' 进行断言
describe('Log Service', () => {
test('log method should be called with correct arguments', () => {
// 假设这里执行了某个操作，该操作会调用 logs.service.js 中的 log 方法
// 例如：someFunctionThatCallsLogService();
// 模拟调用 log 方法两次
log(2, "foo");
log(1, "bar");
// 断言 log 方法被调用
expect(log).toHaveBeenCalled();
// 断言 log 方法被调用了两次
expect(log).toHaveBeenCalledTimes(2);
// 断言 log 方法被调用时带有特定参数
expect(log).toHaveBeenCalledWith(2, "foo");
expect(log).toHaveBeenCalledWith(1, "bar");
});
});解释： 当你在测试文件的顶部使用 import { log } from '...' 时，你获取了一个对 logs.service.js 模块中 log 导出成员的引用。当 jest.mock() 执行时（Jest 会将 jest.mock 调用提升到文件顶部），它会替换 logs.service.js 模块的 log 导出为 jest.fn()。由于你的 import 语句已经引用了那个导出成员，因此你现在通过 log 变量访问到的就是那个被模拟的 jest.fn() 实例。
2. TypeScript 环境下的解决方案
在 TypeScript 中，除了上述 JavaScript 的步骤外，我们还需要进行一步类型断言，以确保 TypeScript 编译器正确识别 log 变量现在是一个 Jest 模拟函数，从而能够访问 jest.fn() 提供的匹配器（如 toHaveBeenCalledWith）。
// 1. 从目标模块导入 'log' 方法
import { log } from '../../../../services/logs.service.js';
// 2. 使用 jest.mock 模拟整个模块，并定义 'log' 的模拟实现
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn() // 定义模拟函数
}));
describe('Log Service (TypeScript)', () => {
test('log method should be called with correct arguments in TS', () => {
// 3. 对导入的 'log' 进行类型断言，明确它是一个 Jest 模拟函数
const mockedLog = log as jest.MockedFunction<typeof log>;
// 模拟调用 log 方法
mockedLog(2, "foo");
// 4. 现在可以安全地对 mockedLog 进行断言
expect(mockedLog).toHaveBeenCalledWith(2, "foo");
expect(mockedLog).toHaveBeenCalledTimes(1);
});
});解释：jest.MockedFunction
注意事项与最佳实践
- 导入顺序： 始终在 jest.mock() 调用之前导入你需要断言的模块成员。Jest 会提升 jest.mock 调用，但 import 语句确保你的测试文件能够获取到对模块导出的引用。
- 命名导出 vs. 默认导出： 本文示例使用的是命名导出 (export const log = ...)。如果是默认导出 (export default class LogService { ... })，导入方式会略有不同，但核心原理一致：import LogService from '...'。
- 重置模拟： 在每个测试用例（或测试套件）之间，你可能需要重置模拟函数的状态，以确保测试的独立性。可以使用 mockedLog.mockClear() 或 jest.clearAllMocks()。
- 清晰的模拟： jest.fn() 是创建模拟函数的基础。你可以进一步使用 mockImplementation(), mockReturnValue(), mockResolvedValue() 等方法来定义模拟函数的行为。
总结
在 Jest 中断言模拟模块方法的调用，关键在于理解 jest.mock() 的作用域限制以及 Jest 如何处理模块导入。通过在测试文件中先行导入目标模块的成员，然后利用 jest.mock() 来替换这些成员的实现，我们便能获得一个指向模拟函数的引用，进而对其进行精确的调用断言。对于 TypeScript 用户，额外的类型断言步骤能够确保类型安全，并提供更好的开发体验。遵循这些实践，可以使你的 Jest 测试更加健壮和可靠。
