本文详解如何使用 jest 高效 mock 被大量组件导入的第三方 sdk（如认证 sdk），规避其内部依赖引发的运行时错误，确保单元测试稳定、快速且专注业务逻辑验证。
本文详解如何使用 jest 高效 mock 被大量组件导入的第三方 sdk（如认证 sdk），规避其内部依赖引发的运行时错误，确保单元测试稳定、快速且专注业务逻辑验证。
在 React 项目中，当一个核心 SDK（例如认证模块 exampleSDK）被广泛导入至多个组件时，直接运行单元测试常因 SDK 内部依赖（如未初始化的 window.x.y 对象）而抛出类似 TypeError: Cannot read properties of undefined (reading 'y') 的错误。这类问题并非组件逻辑缺陷，而是测试环境缺乏真实浏览器上下文或 SDK 初始化条件所致。根本解法不是修补全局对象，而是主动、声明式地隔离 SDK 行为——即对模块进行静态 Mock。
✅ 推荐方案：使用 jest.mock() 进行模块级 Mock
jest.mock() 是 Jest 提供的最可靠、最符合测试意图的方式，它会在模块加载前替换目标模块的导出，确保所有 import 语句均获取到你定义的模拟实现：
// exampleComponent.test.tsx
import { render, screen } from '@testing-library/react';
import { exampleComponent } from './exampleComponent';
// ✅ 在 import 后、test 前立即 mock —— 必须置于顶层作用域
jest.mock('../../path/exampleSDK', () => ({
exampleSDK: jest.fn().mockImplementation(() => ({
onAuthenticate: jest.fn(),
onLogout: jest.fn(),
// 可按需补充其他方法或返回值（如 token、user 等）
getUser: jest.fn().mockReturnValue({ id: 'test-user', name: 'Test User' }),
})),
}));
describe('exampleComponent', () => {
it('renders without crashing and calls SDK methods correctly', () => {
render(<exampleComponent />);
// 验证组件渲染正常
expect(screen.getByText('Example Component')).toBeInTheDocument();
// 验证 SDK 方法是否被创建（非调用）——适用于初始化逻辑
const sdk = require('../../path/exampleSDK').exampleSDK();
expect(sdk.onAuthenticate).toBeDefined();
expect(sdk.onLogout).toBeDefined();
});
});⚠️ 关键注意点：
Orderly Sdk React Hooks下载Orderly React SDK 钩子使用参考指南，包括 useOrderEntry、usePositionStream、useOrderbookStream、useCollateral 等。
- jest.mock() 必须写在 import 语句之后、任何测试代码之前，且通常放在文件顶部（Jest 会自动提升该调用）；
- 不要尝试在 beforeEach 或 test 内部调用 jest.mock()，否则将失效；
- 若 SDK 导出为默认导出（export default ...），则 mock 返回对象应包含 default 属性；若为命名导出（如本例 exampleSDK），则按实际导出名匹配。
? 替代方案：动态控制 Mock 行为（进阶场景）
当需要在不同测试用例中模拟不同响应（如成功登录 vs 登录失败），可结合 jest.fn() 的链式能力：
// 在 test 块内动态配置
const mockOnAuthenticate = jest.fn();
jest.mock('../../path/exampleSDK', () => ({
exampleSDK: jest.fn().mockImplementation(() => ({
onAuthenticate: mockOnAuthenticate,
onLogout: jest.fn(),
})),
}));
it('triggers authentication on button click', async () => {
render(<exampleComponent />);
// 模拟 Promise 成功响应
mockOnAuthenticate.mockResolvedValue({ success: true, token: 'mock-jwt' });
// 触发交互（假设组件内有按钮调用 onAuthenticate）
await userEvent.click(screen.getByRole('button', { name: /login/i }));
await waitFor(() => expect(mockOnAuthenticate).toHaveBeenCalledTimes(1));
});? 不推荐做法及原因
❌ Object.defineProperty(window, 'x', { value: { y: {} } })：
此类“打补丁”方式脆弱、不可靠，且无法覆盖 SDK 内部更深层的依赖（如 window.x.y.z.method()），易因 SDK 版本更新而失效。❌ 在 setupFilesAfterEnv 中全局 mock：
虽可避免重复书写，但会污染所有测试用例，丧失单测的独立性与可预测性，违背“每个测试互不干扰”原则。❌ 使用 jest.spyOn() 对已导入对象 spy：
仅适用于已存在实例的方法劫持，无法解决模块首次加载时的初始化报错（如 Object.create(window.x.y.prototype) 执行阶段）。
✅ 最佳实践总结
| 场景 | 推荐方式 | 说明 |
|---|---|---|
| SDK 被多组件共享 | jest.mock() + 统一 mock 实现 | 保证一致性，避免重复配置 |
| 需验证 SDK 方法调用行为 | jest.fn() + expect(mockFn).toBeCalledTimes(n) | 验证组件是否正确触发 SDK 方法 |
| 需模拟异步结果（成功/失败） | mockResolvedValue() / mockRejectedValue() | 精确控制 Promise 状态 |
| 需复位 mock 状态 | mockClear() 或 mockReset() | 在 beforeEach 中调用，保障测试隔离 |
通过合理运用 jest.mock()，你不仅能彻底规避 SDK 内部依赖导致的测试崩溃，更能将测试焦点精准锚定在组件自身逻辑上——这才是单元测试的核心价值：快速、可靠、可维护地守护业务代码质量。
