在React组件测试中，依赖注入通常并不是通过构造函数或注解完成的，更多时候表现为组件内部直接import一个服务模块。当测试需要隔离网络请求、随机数生成或本地存储等副作用时，直接修改组件源码加入注入点并不总是可行。Jest提供的手动模拟（Manual Mocks）能力允许我们在不触碰业务代码的情况下，用测试专用的模块实现替换真实的依赖模块。理解这一机制需要先搞清楚Jest的模块解析流程：当测试文件中出现import语句时，Jest会优先查找模块所在目录下是否存在__mocks__文件夹以及对应的模拟文件；如果存在，且测试中调用了jest.mock，该模拟文件就会替代真实模块被加载。这种解析优先级为依赖注入测试提供了一条低侵入的通道。
手动模拟与常见的jest.mock内联工厂函数不同。内联工厂函数直接写在测试文件里，优点是简单直观，但每个测试文件都要重复定义模拟逻辑；而手动模拟则把模拟实现抽离到独立的__mocks__文件中，可以跨多个测试文件复用，并且模拟代码与测试代码分离，维护性更好。对于React组件依赖的API服务、浏览器API封装等模块，推荐优先采用手动模拟，尤其是当多个测试套件都需要同一份模拟数据时。
手动模拟的解析规则与创建方式
Jest对手动模拟文件的查找位置有明确约定：如果被模拟的模块是通过node_modules解析的第三方库，则需要在项目根目录下创建__mocks__文件夹，模拟文件的名称必须与模块名完全一致。例如要模拟axios，就创建根目录__mocks__/axios.js。如果被模拟的是项目内的相对路径模块，比如src/utils/api.js，则可以在src/utils目录下创建__mocks__文件夹，里面放api.js。这种就近放置的方式让模拟文件与真实模块处于同一层级，阅读代码时可以快速对应。
手动模拟文件本身导出的内容就是测试中实际拿到的接口。对于ES模块，通常使用export default或命名导出；对于CommonJS模块则使用module.exports。如果被模拟的模块既有默认导出又有命名导出，模拟文件需要同时模拟这两类导出，否则测试中import { namedExport }可能得到undefined。创建时务必将模拟文件的导出签名与真实模块保持一致，避免测试代码在运行时报错。下面是一个模拟src/utils/api.js的示例，该真实模块负责调用后端接口获取用户列表。
// 真实模块 src/utils/api.js
export async function fetchUsers() {
const res = await fetch('/api/users');
return res.json();
}
export async function fetchPosts() {
const res = await fetch('/api/posts');
return res.json();
}
// 手动模拟 src/utils/__mocks__/api.js
export const fetchUsers = jest.fn(async () => [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' },
]);
export const fetchPosts = jest.fn(async () => [
{ id: 101, title: 'First Post' },
]);
注意模拟文件中的函数通常需要包装为jest.fn()，这样可以方便在测试中断言调用次数和参数。如果某些测试需要访问真实实现，可以在模拟文件内部通过jest.requireActual获取原始模块，然后在模拟导出中按需调用真实函数。这种混合策略可以避免完全替换导致的测试盲区。
在React组件测试中启用手动模拟
要让手动模拟生效，必须在测试文件顶层调用jest.mock，并传入模块路径。即使模块路径与真实模块相同，Jest也需要这个显式调用来告诉模块系统去查找对应的手动模拟文件。例如组件UserList在useEffect中调用fetchUsers，测试文件可以这样编写：
// UserList.test.js
import React from 'react';
import { render, screen, waitFor } from '@testing-library/react';
import UserList from './UserList';
import { fetchUsers } from './utils/api';
jest.mock('./utils/api');
test('renders user names after fetch', async () => {
fetchUsers.mockResolvedValue([
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' },
]);
render(<UserList />);
await waitFor(() => {
expect(screen.getByText('Alice')).toBeInTheDocument();
});
});
上面代码中，jest.mock('./utils/api')会告诉Jest使用src/utils/__mocks__/api.js中的模拟实现，而不是真实的网络请求模块。测试里通过fetchUsers.mockResolvedValue可以针对当前测试覆盖返回值，因为手动模拟中的fetchUsers是jest.fn()。如果手动模拟中没有使用jest.fn()而是一个普通函数，则无法在测试中动态调整返回值。因此建议手动模拟导出可配置的mock函数。
如果组件内部同时使用了多个依赖，也可以对它们分别调用jest.mock。Jest支持在单个测试文件中模拟任意数量的模块。只需要确保每个被模拟模块都有对应的手动模拟文件，或者在调用jest.mock时提供内联工厂函数作为后备。当两种方式同时存在时，内联工厂函数优先于手动模拟文件，这个优先级关系在处理特殊情况时很有用。
手动模拟的隔离性问题与解决思路
手动模拟文件在模块加载后只会被实例化一次，这意味着跨测试用例共享同一个模块实例和状态。如果多个测试用例对同一个模拟函数设置了不同的返回值或调用断言，前一个测试遗留的状态可能污染后一个测试。解决这个问题需要在每个测试用例开始前重置模拟状态。常见做法是在afterEach钩子中调用jest.resetAllMocks()或针对特定模拟调用mockReset。如果模拟模块内部还维护了非函数状态，比如一个数组缓存，则需要手动清空或使用jest.isolateModules配合require重新加载模块。
另一种隔离性问题是模拟模块与真实模块的类型定义不一致。在TypeScript项目中，手动模拟文件因为是JavaScript文件，无法提供完整的类型信息。如果测试代码引用了模拟模块导出的函数并调用mockResolvedValue，TypeScript编译器可能因为类型缺失而报错。此时可以使用jest.MockedFunction类型显式声明，或者将模拟文件的扩展名改为.ts并在其中导入真实模块的类型。推荐做法是在手动模拟文件中使用import type从真实模块导入类型，这样模拟实现的签名就能与真实模块保持一致，同时保留jest.fn()的动态能力。
手动模拟还有一个常见陷阱：当模块路径使用了目录索引（例如import utils from './utils'）时，对应的手动模拟文件应该放在__mocks__/utils.js，但Jest对目录模块的模拟解析有时会与预期不同。如果utils是一个目录，真实模块解析到utils/index.js，那么手动模拟文件需要命名为utils.js还是utils/index.js？实践表明，需要模拟确切的解析路径，通常创建__mocks__/utils.js即可，但为了防止解析歧义，建议在jest.mock中传入与实际导入完全一致的字符串，并在__mocks__中创建相同层级的文件。
最后，手动模拟并非万能。如果依赖注入的目标是一个React Context或者通过props传入的服务实例，使用Jest的手动模拟模块反而可能掩盖组件与依赖之间的交互逻辑。此时更合适的是使用Testing Library的render方法传入自定义的上下文值或依赖对象。判断标准是：当依赖是模块级导入且不通过组件props或context注入时，手动模拟是最直接的手段；而当依赖是显式注入的对象时，直接在测试中构造假的依赖对象会是更清晰的做法。理解这两类依赖注入形式的差异，能帮助开发者针对不同场景选择最合适的测试策略，避免过度使用模块模拟导致测试与实现细节过度耦合。
React依赖注入测试Jest手动模拟Manual Mocks修改时间：2026-10-06 22:23:15