Jest Manual Mocks 完全指南:用 `__mocks__` 目录手工 Mock 用户模块与 Node 模块
Jest Manual Mocks 完全指南:用 __mocks__ 目录手工 Mock 用户模块与 Node 模块
本文基于 Jest 官方文档 docs/ManualMocks.md(及同内容的 website/versioned_docs/version-29.7/ManualMocks.md)编写,结合当前仓库的 examples/manual-mocks 示例工程与
jest-runtime、babel-plugin-jest-hoist源码进行印证。读完本文,你将掌握:在__mocks__/目录下为用户模块、Node 第三方包、Node 内置模块与 scoped 包编写手动 mock 的完整规则,理解jest.mock/jest.unmock/jest.createMockFromModule/jest.requireActual的协作方式,并能解决 ES Module 下jest.mock提升(hoisting)以及 JSDOM 未实现 API(如window.matchMedia)等实战问题。
Manual mocks(手动 mock)用于使用模拟数据(mock data)来替代真实功能。例如,与其真实访问网站或数据库这类远程资源,不如创建一个手动 mock 来提供假数据,从而确保测试快速且不脆弱(fast and not flaky)——不依赖网络、不依赖磁盘、不依赖外部服务状态。
一、Manual Mock 的核心目录约定:__mocks__
Jest 通过一个约定俗成的目录名 __mocks__ 来识别手动 mock。规则非常简单:在紧邻被 mock 模块的目录下创建一个 __mocks__/ 子目录,并在其中放置与模块同名的文件。
例如,要 mock models 目录下的 user 模块,就在 models/__mocks__/ 目录下创建 user.js:
models/
├── __mocks__/
│ └── user.js # 手动 mock 实现
└── user.js # 真实实现
:::caution 大小写敏感
__mocks__ 目录名是大小写敏感的。如果写成 __MOCKS__,在某些系统(尤其是大小写敏感的文件系统)上会导致 mock 无法生效、测试失败。
:::
1. Mock 用户模块(User Modules):必须显式调用 jest.mock
当你在测试中 require/import 一个用户模块(即你自己项目中的模块),并希望使用手动 mock 而不是真实实现时,显式调用 jest.mock('./moduleName') 是必需的:
jest.mock('./models/user'); // 必须显式声明使用手动 mock
const user = require('./models/user'); // 此时拿到的是 __mocks__/user.js
:::note 作用域要求
为了正确完成 mock,jest.mock('moduleName') 必须与 require/import 语句处于同一个作用域(same scope)。这也是后续讲解 ES Module 时 jest.mock 自动提升(hoist)的重要原因。
:::
2. Mock Node 模块(第三方 npm 包):自动生效,无需显式调用
如果被 mock 的是 Node 模块(例如 lodash),mock 文件应放在与 node_modules 同级的 __mocks__ 目录中,且该 mock 会自动生效——无需显式调用 jest.mock('module_name'):
项目根目录/
├── node_modules/ # 真实安装的依赖
├── __mocks__/
│ └── lodash.js # lodash 的手动 mock,自动生效
:::tip 关于 roots
上述“与 node_modules 同级”的默认位置,仅在 roots 配置指向项目根目录时成立。若你在 Configuration.md 中将 roots 配置为其他目录,则 __mocks__ 需要放置到对应的 roots 目录下。
:::
3. Mock scoped 包(@scope/pkg 形式)
Scoped 包(即 npm 的 scoped packages)的 mock 文件需要放在与包名层级对应的目录结构中。例如要 mock @scope/project-name,需要创建文件:
__mocks__/
└── @scope/
└── project-name.js # 注意需按需创建 @scope/ 目录
4. Mock Node 内置模块(如 fs、path):必须显式调用 jest.mock
对于 Node 内置模块(built-in modules,例如 fs、path),情况又与第三方包不同:内置模块默认不会被自动 mock,因此必须显式调用 jest.mock('path') / jest.mock('fs'),手动 mock 才会生效。
三种模块的规则可总结为下表:
| 被 mock 的对象 | __mocks__ 放置位置 |
是否需显式 jest.mock() |
|---|---|---|
| 用户模块(项目内模块) | 紧邻模块的 __mocks__/ 子目录 |
必需 |
Node 第三方包(如 lodash) |
与 node_modules 同级的 __mocks__/ |
自动生效,无需调用 |
scoped 包(如 @scope/pkg) |
__mocks__/@scope/pkg.js |
与第三方包一致,自动生效 |
Node 内置模块(如 fs、path) |
与 node_modules 同级的 __mocks__/ |
必需(默认不 mock 内置模块) |
5. automock 配置下的行为差异
当某个模块存在手动 mock 时,Jest 的模块系统会在显式调用 jest.mock('moduleName') 时使用该 mock。但有一个例外场景:当配置项 automock 设为 true 时,即使不调用 jest.mock('moduleName'),手动 mock 实现也会替代自动生成的 mock 被使用。
如果你希望某些测试使用真实模块实现,则需要显式调用 jest.unmock('moduleName') 来退出该行为:
jest.unmock('fs'); // automock 开启时,用真实 fs 实现
一个典型目录布局(来自官方文档)如下:
.
├── config
├── __mocks__
│ └── fs.js # 内置模块 fs 的手动 mock(与 node_modules 同级)
├── models
│ ├── __mocks__
│ │ └── user.js # 用户模块 user 的手动 mock(紧邻 models/user.js)
│ └── user.js
├── node_modules
└── views
二、实战示例:Mock Node 内置模块 fs
官方文档给出的经典案例是:编写一个遍历目录并汇总文件名的模块 FileSummarizer,它依赖核心内置模块 fs。测试时我们希望完全避免真实读写磁盘(慢且脆弱),因此为 fs 创建手动 mock。
1. 被测模块
'use strict';
const fs = require('fs');
function summarizeFilesInDirectorySync(directory) {
return fs.readdirSync(directory).map(fileName => ({
directory,
fileName,
}));
}
exports.summarizeFilesInDirectorySync = summarizeFilesInDirectorySync;
当前仓库中的实际实现见 examples/manual-mocks/FileSummarizer.js,使用了
require('node:fs')写法,逻辑一致。
2. 手动 mock:在自动 mock 之上扩展
在项目根目录的 __mocks__/fs.js 中创建 fs 的手动 mock。这里采用官方推荐做法:先用 jest.createMockFromModule('fs') 生成自动 mock,再覆盖其默认行为:
'use strict';
const path = require('path');
const fs = jest.createMockFromModule('fs');
// 这是供测试在 setup 阶段调用的自定义函数:
// 指定"模拟文件系统"在任何 fs API 被调用时应呈现的文件结构。
let mockFiles = Object.create(null);
function __setMockFiles(newMockFiles) {
mockFiles = Object.create(null);
for (const file in newMockFiles) {
const dir = path.dirname(file);
if (!mockFiles[dir]) {
mockFiles[dir] = [];
}
mockFiles[dir].push(path.basename(file));
}
}
// 自定义的 readdirSync:从通过 __setMockFiles 设置的专用 mock 文件列表中读取
function readdirSync(directoryPath) {
return mockFiles[directoryPath] || [];
}
fs.__setMockFiles = __setMockFiles;
fs.readdirSync = readdirSync;
module.exports = fs;
这段代码的关键设计:
jest.createMockFromModule('fs')生成一个保留fs全部 API 形状的自动 mock,因此其他测试代码中使用到的fs方法仍存在;__setMockFiles(newMockFiles)是一个暴露给测试的辅助安装函数:把形如{'/path/to/file1.js': '内容'}的扁平对象,转化为目录 -> [文件名]的映射;- 自定义的
readdirSync(directoryPath)直接从这份模拟清单中取数据,永不触碰真实磁盘。
3. 编写测试
由于 fs 是 Node 内置模块,必须显式调用 jest.mock('fs'):
'use strict';
jest.mock('fs');
describe('listFilesInDirectorySync', () => {
const MOCK_FILE_INFO = {
'/path/to/file1.js': 'console.log("file1 contents");',
'/path/to/file2.txt': 'file2 contents',
};
beforeEach(() => {
// 在每个测试前设置好模拟的文件信息
require('fs').__setMockFiles(MOCK_FILE_INFO);
});
test('includes all files in the directory in the summary', () => {
const FileSummarizer = require('../FileSummarizer');
const fileSummary =
FileSummarizer.summarizeFilesInDirectorySync('/path/to');
expect(fileSummary.length).toBe(2);
});
});
测试流程清晰可验证:beforeEach 中通过 require('fs').__setMockFiles(...) 注入两文件,随后 FileSummarizer.summarizeFilesInDirectorySync('/path/to') 从 mock 清单返回 ['file1.js', 'file2.txt'],断言长度为 2。由于手动 mock 覆盖了 readdirSync,整个测试不产生任何真实 I/O。
上述文件与真实仓库中的 examples/manual-mocks/tests/file_summarizer.test.js 一一对应。
三、jest.createMockFromModule 与 jest.requireActual:让 mock 与真实实现保持同步
文档明确指出:上例中使用 jest.createMockFromModule 生成自动 mock 再覆盖其默认行为,是推荐做法,但完全可选。如果你完全不想用自动 mock,也可以从 mock 文件直接导出自定义函数。
但纯手工 mock(fully manual mocks)有一个明显缺点:它们终究是"手动的"——每当被 mock 的模块发生变化,你必须手动同步更新 mock 文件。因此官方建议:在自动 mock 能满足需求时,优先使用或扩展自动 mock。
jest.createMockFromModule(moduleName)
该 API 以模块名为参数,自动生成一个与该模块形状一致的 mock:所有函数属性自动变为 mock 函数,非函数属性保留原值。其正式说明见 JestObjectAPI.md,底层由 jest-runtime 中的 mock 工厂实现(仓库中的相关测试见 runtime_create_mock_from_module.test.js)。
仓库示例 examples/manual-mocks/models/mocks/user.js 展示了用户模块的完整 mock 写法:
const user = jest.createMockFromModule('../user');
user.getAuthenticated = () => ({
age: 622,
name: 'Mock name',
});
export default user;
对照真实实现 examples/manual-mocks/models/user.js(getAuthenticated 返回 age: 26, name: 'Real name'),mock 仅覆盖了 getAuthenticated 一个方法,其余结构沿用自动 mock。
对应测试 examples/manual-mocks/tests/userMocked.test.js:
import user from '../models/user';
jest.mock('../models/user');
test('if user model is mocked', () => {
expect(user.getAuthenticated()).toEqual({age: 622, name: 'Mock name'});
});
注意这里用户模块必须显式 jest.mock('../models/user'),且 jest.mock 虽然写在 import 之后,但由于 Jest 的提升机制(见第四节),mock 依然在模块加载前生效——这正是该示例验证的行为。
jest.requireActual(moduleName)
为了确保手动 mock 与真实实现保持同步,另一个常用技巧是:在手动 mock 文件中调用 jest.requireActual(moduleName) 拿到真实模块,用 mock 函数对其进行修改后再导出。这样真实模块新增的 API 会自然保留在 mock 中,降低"mock 与实现脱节"的风险。API 说明见 JestObjectAPI.md,仓库中 jest-runtime 的 runtime_require_actual.test.js 覆盖了该行为的测试。
四、ES Module 导入下的 jest.mock:自动提升(Hoisting)与 ESM 限制
使用 ES Module import 语法时,你通常习惯把 import 语句放在测试文件顶部。但很多时候你需要在模块使用 mock 之前就告诉 Jest 使用 mock。为此,Jest 会自动将 jest.mock 调用提升(hoist)到模块顶部(所有 import 之前)。
这一行为由 babel-plugin-jest-hoist 实现,仓库源码 packages/babel-plugin-jest-hoist/src/index.ts 中通过 hoistedJestGetters、hoistedJestExpressions 等集合跟踪并重排可提升的 jest.mock 表达式,其配套快照测试位于 packages/babel-plugin-jest-hoist/src/tests。正是因为有这一步,上例中写在 import 之后的 jest.mock('../models/user') 才能正确生效。
:::caution ESM 原生模块支持下的限制
如果你启用了 ECMAScript modules(原生 ESM)支持,jest.mock 调用无法被提升到模块顶部——因为 ESM 加载器总是先执行静态导入、再执行代码。详细机制与注意事项见 ECMAScriptModules.md。在原生 ESM 场景下,需要自行保证 mock 注册先于被测模块的加载(例如借助单独的 mock 入口文件)。
:::
五、源码视角:手动 mock 是如何被解析的
手动 mock 的查找与缓存发生在 jest-runtime 的模块解析层。仓库源码 packages/jest-runtime/src/internals/Resolution.ts 中:
- 维护了一个
manualMockCache(Map<string, string | null>)用于缓存每个模块对应手动 mock 文件的解析结果(第 27 行定义,第 188-191 行写入,第 263 行在重置时清空),避免重复扫描文件系统; - 解析过程会根据前文所述规则定位
__mocks__目录:用户模块就近查找,Node 模块在根级__mocks__查找,从而决定最终加载哪个文件。
从源码结构可以推断,jest.mock 注册的 mock 状态(MockState.ts)与解析层(Resolution.ts)共同协作:jest.mock 将模块标记为"使用 mock",解析层再按手动 mock 优先级取文件。这也解释了文档中"同作用域"要求的本质——jest.mock 必须先于模块的实际加载被执行。
六、Mock JSDOM 未实现的方法:window.matchMedia 案例
Jest 的 DOM 环境基于 JSDOM 实现。当被测代码使用了 JSDOM 尚未实现的方法时,测试无法顺利进行。典型例子是 window.matchMedia()——直接调用会抛出 TypeError: window.matchMedia is not a function 导致测试失败。
方案一:在测试文件中直接 mock
如果 window.matchMedia() 是在测试执行期间被调用的函数(或方法)内部使用,可在测试文件顶部用 Object.defineProperty 注入 mock 实现:
Object.defineProperty(window, 'matchMedia', {
writable: true,
value: jest.fn().mockImplementation(query => ({
matches: false,
media: query,
onchange: null,
addListener: jest.fn(), // deprecated
removeListener: jest.fn(), // deprecated
addEventListener: jest.fn(),
removeEventListener: jest.fn(),
dispatchEvent: jest.fn(),
})),
});
方案二:拆分为独立 mock 文件并在被测文件之前导入
如果 window.matchMedia() 是在被测文件加载时直接执行(而不是在测试中调用的函数内部),Jest 会报同样的错误。此时解决方案是:把上面的手动 mock 移到单独的文件中,并在测试中先于被测文件导入它:
import './matchMedia.mock'; // 必须在该被测文件之前导入
import {myMethod} from './file-to-test';
describe('myMethod()', () => {
// 在这里测试该方法...
});
利用 ES Module 静态导入的顺序性(以及 Babel 转译后 require 的执行顺序),确保 matchMedia 在被测模块评估前就绪。
七、仓库示例速览与最佳实践小结
当前仓库在 examples/manual-mocks 提供了完整的可运行示例,目录结构如下:
examples/manual-mocks/
├── __mocks__/
│ ├── fs.js # 内置模块 fs 的手动 mock(扩展自动 mock)
│ └── lodash.js # 第三方包 lodash 的手动 mock(自动生效)
├── __tests__/
│ ├── file_summarizer.test.js # fs mock 端到端测试
│ ├── lodashMocking.test.js # lodash mock 自动生效验证
│ ├── user.test.js # 使用真实 user 实现
│ ├── userMocked.test.js # 显式 jest.mock 使用手动 mock
│ └── utils.test.js
├── models/
│ ├── __mocks__/user.js # 用户模块的手动 mock
│ └── user.js # 真实实现
├── FileSummarizer.js # 被测模块(依赖 fs)
└── utils.js
其中 examples/manual-mocks/tests/lodashMocking.test.js 是最能体现"Node 模块自动 mock"规则的例子——测试文件里没有任何 jest.mock('lodash') 调用:
import lodash from 'lodash';
test('if lodash head is mocked', () => {
expect(lodash.head([2, 3])).toBe(5);
});
真实 lodash.head(<a href="https://link.gitcode.com/i/a0749bb4d79c660f7bf56b81b576cd30" target="_blank">2, 3]) 返回 2,而 [examples/manual-mocks/mocks/lodash.js 将其改写为返回 5,断言成功即证明自动 mock 生效。
关键决策清单
- 能用自动 mock 就别纯手写:优先
jest.createMockFromModule扩展,或jest.requireActual+ mock 函数修补,降低与真实实现脱节的风险; - 区分三类模块的 mock 规则:用户模块要
jest.mock,第三方包自动生效,内置模块必须jest.mock; - 保持
jest.mock与require/import同作用域,并充分利用 Babel 插件对jest.mock的自动提升; - 留意
automock: true的全局影响:此时手动 mock 默认启用,需要真实实现时显式jest.unmock; - JSDOM 缺口:对
matchMedia等未实现 API,按调用时机选择"测试内 mock"或"前置 mock 文件"两种方案。
以上内容完全继承并扩展了 docs/ManualMocks.md 的全部要点,所有示例均可在 examples/manual-mocks 目录中直接运行验证,相关行为可由 packages/jest-runtime/src/internals/Resolution.ts 与 packages/babel-plugin-jest-hoist/src/index.ts 等源码印证。