本文详细介绍了如何在 jest 中正确地对模拟模块的方法进行断言。针对常见的“out-of-scope”变量引用错误，教程提供了解决方案：通过在 `jest.mock()` 之前导入目标方法，从而使其可被访问和断言。文章涵盖了 javascript 和 typescript 两种实现方式，并强调了类型断言在 typescript 中的必要性，旨在帮助开发者高效地测试模块交互。
在 Jest 中进行单元测试时，我们经常需要模拟外部模块以隔离测试目标。然而，当尝试对这些模拟模块中的方法进行断言（例如，检查它们是否被调用或以特定参数调用）时，可能会遇到作用域问题。本教程将深入探讨如何有效地实现这一目标，并解决常见的“out-of-scope variables”错误。
理解问题：模拟模块方法的访问挑战
假设我们有一个 logs.service.js 服务，其中包含一个 log 方法：
// services/logs.service.js
export function log(level, message) {
console.log(`[${level}] ${message}`);
}在测试文件中，我们希望模拟这个 log 方法，并断言它是否被正确调用。一个常见的尝试是直接在 jest.mock() 内部定义一个 jest.fn()：
// test.spec.js
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn()
}));
// 假设某个被测试函数调用了 log
// someFunctionThatCallsLog();
// 尝试断言
// expect(log).toHaveBeenCalledWith(2, "foo"); // 错误：log 未定义在这种情况下，log 变量在 jest.mock() 的回调函数外部是无法访问的。为了解决这个问题，一些开发者可能会尝试将 log 函数的 jest.fn() 定义移到 jest.mock() 外部：
// test.spec.js
const log = jest.fn(); // 尝试将 log 定义在外部
jest.mock('../../../../services/logs.service.js', () => ({
log // 引用外部的 log
}));
// 此时会遇到错误：
// > The module factory of `jest.mock()` is not allowed to reference any out-of-scope variables.这个错误表明 jest.mock() 的模块工厂函数不允许引用其作用域之外的变量。这是 Jest 的一个设计选择，旨在确保模拟的隔离性和可预测性。那么，如何在满足 Jest 限制的同时，又能访问到模拟的方法进行断言呢？
解决方案：先导入，再模拟
解决这个问题的关键在于，在 jest.mock() 调用之前，先通过 import 语句导入你想要模拟和断言的方法。这样，当 jest.mock() 执行时，它会“劫持”这个导入的引用，使其指向你定义的模拟函数。
1. JavaScript 实现
对于 JavaScript 项目，你可以按照以下步骤操作：
- 导入目标方法： 在测试文件的顶部，使用 ES6 import 语法导入你想要模拟的方法。即使你最终会模拟它，这个导入也是必要的，因为它创建了一个在当前作用域内可访问的引用。
- 使用 jest.mock() 进行模拟： 正常调用 jest.mock()，并在其工厂函数中为导入的方法提供一个 jest.fn() 实现。
- 执行断言： 现在，你可以使用之前导入的 log 变量来执行断言了。
// test.spec.js
// 1. 导入目标方法
import { log } from '../../../../services/logs.service.js';
// 2. 使用 jest.mock() 进行模拟
// Jest 会拦截对 'logs.service.js' 的导入，并用这里的模拟实现替换它。
// 重要的是，上面导入的 'log' 变量现在指向了这个模拟函数。
jest.mock('../../../../services/logs.service.js', () => ({
log: jest.fn() // 提供一个 jest.fn() 作为模拟实现
}));
describe('Some module that uses logs.service', () => {
it('should call log method with correct arguments', () => {
// 假设这里调用了某个会触发 log 方法的函数
// 例如：someFunctionThatCallsLog();
// 模拟一个调用场景
(log as jest.Mock).mock.calls = [[2, "foo"], [3, "bar"]]; // 模拟两次调用
// 3. 执行断言
expect(log).toHaveBeenCalledWith(2, "foo"); // 断言 log 方法被调用了两次，其中一次参数是 (2, "foo")
expect(log).toHaveBeenCalledTimes(2); // 断言 log 方法被调用了两次
});
});在这个例子中，import { log } from ... 创建了一个对 log 函数的引用。当 jest.mock() 执行时，它会确保所有对 logs.service.js 模块的引用（包括我们刚刚导入的 log）都指向新的模拟实现。因此，我们可以在测试代码中直接使用 log 变量来访问和断言这个模拟函数。
2. TypeScript 实现
在 TypeScript 项目中，基本原理与 JavaScript 相同，但为了获得更好的类型安全性和开发体验，我们通常需要进行一个额外的类型断言。
- 导入目标方法： 与 JavaScript 相同，导入你想要模拟的方法。
- 使用 jest.mock() 进行模拟： 与 JavaScript 相同，提供 jest.fn() 实现。
- 类型断言： 将导入的方法断言为 jest.MockedFunction<typeof yourMethod> 或 jest.Mock 类型，以便 TypeScript 编译器知道它是一个 Jest 模拟函数，从而允许你访问 toHaveBeenCalledWith 等模拟器特定的方法。
- 执行断言： 使用类型断言后的变量执行断言。
// test.spec.ts
// 1. 导入目标方法
import { log } from '../../../../services/logs.service'; // 注意：TypeScript 通常不需要 .js 后缀
// 2. 使用 jest.mock() 进行模拟
jest.mock('../../../../services/logs.service', () => ({
log: jest.fn() // 提供一个 jest.fn() 作为模拟实现
}));
describe('Some module that uses logs.service', () => {
it('should call log method with correct arguments', () => {
// 3. 类型断言
// 将导入的 log 变量断言为 Jest 模拟函数类型，以便访问其模拟器方法
const mockedLog = log as jest.MockedFunction<typeof log>;
// 模拟一个调用场景
mockedLog.mock.calls = [[2, "foo"], [3, "bar"]]; // 模拟两次调用
// 4. 执行断言
expect(mockedLog).toHaveBeenCalledWith(2, "foo");
expect(mockedLog).toHaveBeenCalledTimes(2);
});
});通过将 log 断言为 jest.MockedFunction<typeof log>，我们明确告诉 TypeScript 编译器 mockedLog 是一个 Jest 模拟函数，从而可以安全地调用 toHaveBeenCalledWith 等方法，并享受类型检查的好处。
总结与最佳实践
- 导入先行： 无论是在 JavaScript 还是 TypeScript 中，核心原则都是在 jest.mock() 调用之前，通过 import 语句引入你希望模拟和断言的模块方法。
- Jest 的作用域隔离： 理解 jest.mock() 的模块工厂函数不能引用外部变量的限制。import 语句提供了一个绕过此限制的合法途径，因为它创建了一个 Jest 可以拦截的模块引用。
- TypeScript 类型安全： 在 TypeScript 项目中，使用 as jest.MockedFunction<typeof yourMethod> 或 as jest.Mock 进行类型断言是良好的实践，它能提升代码的可读性和健壮性。
- 清晰的测试结构： 始终保持测试代码的清晰和简洁。将模拟设置放在测试文件的顶部，并在 describe 或 it 块中执行具体的断言。
通过遵循这些指导原则，你将能够有效地在 Jest 中对模拟模块的方法进行断言，从而编写出更健壮、更可靠的单元测试。
