在使用 `jest-mock-extended` 进行单元测试时，未显式实现的模拟函数默认返回 `undefined`，这可能导致难以追踪的测试失败。本文将介绍如何利用 `jest-mock-extended` 的 `fallbackmockimplementation` 选项，为所有未实现的模拟函数设置一个默认的错误抛出行为，从而在测试中更早、更清晰地发现和定位缺失的模拟实现，显著提升测试的健壮性和调试效率。
理解默认模拟行为的挑战
在软件开发中，单元测试是确保代码质量的关键环节。当使用 jest-mock-extended 库创建模拟（mock）对象时，我们通常会为接口中的特定函数提供自定义实现。然而，如果某个函数未被显式地模拟，jest-mock-extended 的默认行为是让该函数返回 undefined。
考虑以下 TypeScript 接口和其模拟对象：
export interface SomeClient {
someFunction(): number;
someOtherFunction(): number;
}
const mockClient = mock<SomeClient>();
mockClient.someFunction.mockImplementation(() => 1);
// 调用结果
mockClient.someFunction(); // 返回 1
mockClient.someOtherFunction(); // 返回 undefined在这种情况下，someOtherFunction 因为没有被模拟而返回 undefined。虽然在理想情况下，测试中的断言应该能够捕获到这种不期望的 undefined 值，但实际情况往往更复杂：
- 隐蔽的错误源： 被测单元中的代码可能不期望接收 undefined。它可能在后续操作中抛出错误，或者导致更深层次的逻辑问题，使得错误根源难以追踪。
- 类型不匹配： 对于使用 TypeScript 的项目，返回 undefined 可能与接口定义的预期类型不符，但在运行时才发现问题，降低了类型系统的保护作用。
- 调试成本高： 当测试失败时，如果错误信息仅仅是某个深层逻辑的异常，而非明确指出“某个模拟函数未实现”，则调试过程会变得漫长且耗时。
为了解决这些问题，我们希望能够强制所有未显式模拟的函数在被调用时立即抛出一个明确的错误，而不是默默地返回 undefined。
优化模拟：强制未实现函数抛出错误
jest-mock-extended 库从 3.0.2 版本开始，引入了一个名为 fallbackMockImplementation 的强大选项，它允许我们为模拟对象设置一个“回退”的默认实现。这意味着，任何没有被显式指定模拟行为的函数，在被调用时都会执行这个回退实现。通过利用这个特性，我们可以轻松地实现强制未实现函数抛出错误的目标。
当一个模拟函数被调用，但它没有自己的 mockImplementation 或 mockReturnValue 等设置时，jest-mock-extended 会检查 fallbackMockImplementation。如果该选项存在，它就会被执行。这为我们提供了一个理想的钩子，用于在模拟函数未被充分配置时发出警告。
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
使用 fallbackMockImplementation
使用 fallbackMockImplementation 非常简单。在创建模拟对象时，将其作为 mock 函数的第二个参数传递即可。
import { mock } from 'jest-mock-extended';
// 定义一个示例接口
interface SomeClient {
someFunction(): number;
someOtherFunction(): number;
anotherFunction(param: string): boolean;
}
describe('Jest Mock Extended 默认错误抛出行为', () => {
test('未实现函数应抛出明确错误', () => {
// 创建 mockClient 实例，并设置 fallbackMockImplementation
const mockClient = mock<SomeClient>(
{}, // 第一个参数通常用于提供部分初始模拟实现，这里我们留空
{
fallbackMockImplementation: (methodName: string) => {
// 抛出带有函数名称的错误，更具诊断性
throw new Error(`Mock function "${methodName}" not implemented.`);
},
},
);
// 显式模拟一个函数
mockClient.someFunction.mockReturnValue(42);
// 验证显式模拟的函数按预期工作
expect(mockClient.someFunction()).toBe(42);
// 验证未显式模拟的函数在调用时抛出错误
expect(() => mockClient.someOtherFunction()).toThrowError('Mock function "someOtherFunction" not implemented.');
expect(() => mockClient.anotherFunction('test')).toThrowError('Mock function "anotherFunction" not implemented.');
});
test('可以为特定函数覆盖默认行为', () => {
const mockClient = mock<SomeClient>(
{},
{
fallbackMockImplementation: (methodName: string) => {
throw new Error(`Mock function "${methodName}" not implemented.`);
},
},
);
// 为 someOtherFunction 提供一个具体的模拟实现
mockClient.someOtherFunction.mockReturnValue(100);
// 验证 someOtherFunction 现在返回其模拟值
expect(mockClient.someOtherFunction()).toBe(100);
// 验证其他未实现函数仍然抛出错误
expect(() => mockClient.anotherFunction('test')).toThrowError('Mock function "anotherFunction" not implemented.');
});
});代码解析：
- 我们通过 mock<SomeClient>({}, { fallbackMockImplementation: ... }) 来创建模拟对象。
- fallbackMockImplementation 接收一个函数，该函数会在任何未显式模拟的方法被调用时执行。
- 这个回退函数可以接收一个参数 methodName，它代表了当前被调用的方法名称，这对于生成更具描述性的错误信息非常有用。
- 在回退函数内部，我们抛出了一个 Error，明确指出哪个模拟函数未被实现。
重要提示：
请确保你的项目使用的 jest-mock-extended 版本是 ^3.0.2 或更高。此功能是在 3.0.2 版本中引入的（参见 PR#110）。
总结与最佳实践
通过配置 jest-mock-extended 的 fallbackMockImplementation 选项，我们可以将模拟函数的默认行为从返回 undefined 更改为抛出明确的错误。这种做法带来了多重优势：
- 早期错误检测： 在测试运行初期就能发现缺失的模拟实现，而不是在代码执行到深层逻辑时才暴露问题。
- 清晰的错误信息： 错误信息直接指出哪个模拟函数未被实现，大大缩短了调试时间。
- 提升测试健壮性： 强制要求所有必要的模拟都必须到位，避免了因疏忽导致的潜在运行时问题。
- 维护性增强： 当接口发生变化（例如添加新方法）时，如果新方法未被模拟，测试将立即失败并给出明确提示，促使开发者及时更新模拟实现。
将 fallbackMockImplementation 应用于你的测试策略，将显著提升单元测试的质量和开发效率，帮助你构建更可靠的应用程序。
