Jest中Mocked模块方法调用的正确断言姿势

本文详细介绍了在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设计上的一个限制，旨在确保模拟的独立性和可预测性。

AI Sofiya

一款AI驱动的多功能工具

109

查看详情

解决方案：利用模块导入机制

解决这个问题的关键在于，我们应该在定义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<typeof log> 告诉TypeScript编译器，log这个变量现在是一个被Jest模拟过的函数，它拥有jest.fn()提供的所有属性和方法（例如mockClear、mockImplementation等）。这在编写更复杂的模拟行为和断言时非常有用。

注意事项与最佳实践

• 导入顺序： 务必在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”问题，并编写出健壮、可维护的测试代码。遵循这些实践，将大大提升测试的准确性和开发效率。

以上就是Jest中Mocked模块方法调用的正确断言姿势的详细内容，更多请关注php中文网其它相关文章！