Jest Manual Mocks 完全指南:用 `__mocks__` 目录搭建稳定、快速的测试替身
Jest Manual Mocks 完全指南:用 __mocks__ 目录搭建稳定、快速的测试替身
导读
手动 Mock(Manual Mocks)是 Jest 提供的"人工定制替身"机制:通过编写一个位于 __mocks__/ 目录下的模块,用假数据替身(stub)替代真实实现,从而让测试不必访问远程资源(如网站、数据库)或真实磁盘,保证测试快速且不会因外部环境波动而 flaky。本文以 Jest 仓库官方文档 docs/ManualMocks.md 为主体,结合仓库内 examples/manual-mocks 完整示例与 jest-runtime、babel-plugin-jest-hoist 源码,系统讲解用户模块、Node 模块与内置模块的手动 Mock 姿势、自动 Mock 与 hoisting 的底层原理、以及 JSDOM 未实现方法(如 window.matchMedia)的补齐方案。读完你将能独立设计并落地一套"零外部依赖"的测试替身体系。
一、什么是 Manual Mocks:动机与适用场景
Manual Mocks 的核心动机写在文档开篇:用 mock 数据去 stub 掉真实功能。例如,与其在测试中真正访问网站或数据库,不如创建一个手动 mock,让测试直接使用假数据,从而获得两个收益:
- 快:不产生真实的网络请求、磁盘 I/O 或数据库连接;
- 稳:结果可预期,不因远端服务宕机、网络抖动、数据变更而偶发失败(flaky)。
从源码实现看,Jest 运行时(runtime)会为 __mocks__ 路径专门建立识别规则,见 packages/jest-runtime/src/index.ts:
mocksPattern: escapePathForRegex(`${path.sep}__mocks__${path.sep}`),
也就是说,__mocks__ 是 Jest 模块解析体系中的"保留目录名",任何位于该目录下的模块都会被纳入手动 Mock 的查找范围。后续所有手动 Mock 行为都建立在这条规则之上。
二、Mocking User Modules:为用户模块创建替身
2.1 目录约定
要 mock 一个用户自己写的模块,规则是:在目标模块的相邻位置创建 __mocks__/ 子目录,并把同名文件放进去。
例如要 mock models 目录下的 user 模块,就在 models/__mocks__ 下创建 user.js:
.
└── models
├── __mocks__
│ └── user.js ← 手动 mock
└── user.js ← 真实实现
2.2 两个必须注意的约束
约束一:__mocks__ 目录名区分大小写。 文档明确警告,命名成 __MOCKS__ 会在某些系统上失效(Windows/macOS 默认文件系统大小写不敏感,但 Linux 及部分 CI 环境会直接破坏匹配)。
约束二:用户模块的手动 mock 不会被自动启用。 当你需要在测试中使用手动 mock 而非真实实现时,必须显式调用 jest.mock('./moduleName')。这是与 Node 模块(见下一节)最大的行为差异。
2.3 仓库中的完整对照示例
仓库 examples/manual-mocks 提供了最直观的对照。真实模块 models/user.js 返回真实用户数据:
// examples/manual-mocks/models/user.js
export default {
getAuthenticated: () => ({
age: 26,
name: 'Real name',
}),
};
相邻的 models/__mocks__/user.js 则基于自动 mock 覆盖 getAuthenticated 返回假数据:
// examples/manual-mocks/models/__mocks__/user.js
const user = jest.createMockFromModule('../user');
user.getAuthenticated = () => ({
age: 622,
name: 'Mock name',
});
export default user;
对应的两个测试文件展示了"同一模块,是否 jest.mock 决定走哪条路":
- user.test.js:直接
import user from '../models/user',不调用jest.mock,断言拿到{age: 26, name: 'Real name'}(真实实现); - userMocked.test.js:先
jest.mock('../models/user')再导入,断言拿到{age: 622, name: 'Mock name'}(手动 mock)。
三、Mocking Node Modules:第三方包与内置模块
3.1 第三方 Node 模块:自动生效
如果 mock 的对象是 Node 模块(如 lodash),mock 文件应放在与 node_modules 平级的 __mocks__ 目录(除非你用 roots 把根目录指到了其他文件夹)。此时 mock 自动生效,无需显式调用 jest.mock('module_name')。
仓库示例 examples/manual-mocks/mocks/lodash.js:
// examples/manual-mocks/__mocks__/lodash.js
const lodash = jest.createMockFromModule('lodash');
lodash.head = arr => 5;
export default lodash;
测试 lodashMocking.test.js 里没有出现任何 jest.mock('lodash'),导入即被替换:
import lodash from 'lodash';
test('if lodash head is mocked', () => {
expect(lodash.head([2, 3])).toBe(5);
});
3.2 Scoped 包:按作用域名建目录
带作用域的模块(scoped packages,如 @scope/project-name)需要按模块全名建立目录结构:在 __mocks__/ 下创建 @scope/ 目录,再放 project-name.js:
__mocks__/
└── @scope/
└── project-name.js
3.3 内置模块(built-in):必须显式 jest.mock
Node 内置模块(如 fs、path)默认不会被 mock,即使你在 __mocks__/ 下写了同名文件,也必须显式调用,例如 jest.mock('path')。内置模块的解析路径与普通第三方模块不同,Jest 无法在未显式声明时判定"你希望替换它"。
判定规则可以这样记忆:用户模块必须显式
jest.mock;第三方 Node 模块自动生效;内置模块又必须显式jest.mock。容易混淆的恰恰是两头。
四、实战示例:用 __mocks__/fs.js 打造内存文件系统
这是文档中篇幅最重的核心示例,仓库内保留了完整可运行版本(examples/manual-mocks),我们逐段拆解。
4.1 被测模块:FileSummarizer.js
被测模块 FileSummarizer.js 使用 Node 内置 fs 同步列出目录下所有文件:
// examples/manual-mocks/FileSummarizer.js
const fs = require('node:fs');
function summarizeFilesInDirectorySync(directory) {
return fs.readdirSync(directory).map(fileName => ({directory, fileName}));
}
exports.summarizeFilesInDirectorySync = summarizeFilesInDirectorySync;
如果直接测试它,每次都会真实命中磁盘——慢且脆弱。所以我们为 fs 写一个手动 mock,让 readdirSync 改从一段内存数据中读取。
4.2 手动 mock:__mocks__/fs.js
核心技巧是基于自动 mock 扩展:先用 jest.createMockFromModule('fs') 生成一份覆盖全部 fs API 的自动 mock,再覆盖我们关心的 readdirSync,并额外导出一个供测试初始化用的 __setMockFiles:
// examples/manual-mocks/__mocks__/fs.js
'use strict';
const path = require('path');
const fs = jest.createMockFromModule('fs');
// 测试可在 setup 阶段调用,用来声明"假文件系统"上的文件布局
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 设置的假文件列表读取
function readdirSync(directoryPath) {
return mockFiles[directoryPath] || [];
}
fs.__setMockFiles = __setMockFiles;
fs.readdirSync = readdirSync;
module.exports = fs;
注意这里的关键设计:__setMockFiles 把 {'/path/to/file1.js': '...', '/path/to/file2.txt': '...'} 这种"路径→内容"的扁平映射,转成"目录→文件名数组"结构,readdirSync 只返回文件名。整个 mock 不碰真实磁盘。
4.3 测试:显式 jest.mock('fs')
因为 fs 是 Node 内置模块,测试必须显式声明 jest.mock('fs'),然后在 beforeEach 中用 __setMockFiles 注入假数据:
// examples/manual-mocks/__tests__/file_summarizer.test.js
'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(() => {
// 在每次测试前设置好 mock 出的文件信息
require('fs').__setMockFiles(MOCK_FILE_INFO);
});
it('includes all files in the directory in the summary', () => {
const FileSummarizer = require('../FileSummarizer');
const fileSummary = FileSummarizer.summarizeFilesInDirectorySync('/path/to');
expect(fileSummary).toHaveLength(2);
});
});
整个测试流程:jest.mock('fs') 让被测模块中的 require('node:fs') 解析到手写 mock → __setMockFiles 填充内存目录 → summarizeFilesInDirectorySync('/path/to') 返回 2 条记录。
4.4 推荐做法与两种退化路径
- 推荐:扩展自动 mock。 用
jest.createMockFromModule(moduleName)(API 详见 Jest 对象 API)先生成自动 mock,再覆盖默认行为。完全可选——你也可以从零手写,自行导出需要的函数。 - 全手写 mock 的缺点:不同步。 手写 mock 意味着每当被 mock 的模块 API 变化,你必须手动同步更新 mock 文件。因此文档建议:只要自动 mock 能满足需求,优先使用或扩展它。
- 保持同步的补救方案。 如果想确保手动 mock 与真实实现保持一致,可以在 mock 文件里用
jest.requireActual(moduleName)(见 Jest 对象 API)引入真实模块,然后用 mock 函数在其基础上做增量修改再导出。
4.5 automock 与 jest.unmock 的交互
当某个模块存在手动 mock 时,Jest 模块系统会在显式调用 jest.mock('moduleName') 时使用它。但如果配置了 automock: true,即使不调用 jest.mock,也会自动使用手动 mock 实现(替代自动生成的 mock)。
此时想在某些测试里用真实实现,就需要显式调用 jest.unmock('moduleName') 来退出该行为。
另外文档强调了一条使用铁律:jest.mock('moduleName') 必须与 require/import 语句处于同一作用域,否则 mock 不会生效。
五、ES Module 导入下的 hoisting 机制
5.1 为什么需要 hoisting
使用 ES Module 语法时,我们习惯把 import 写在文件顶部。但很多场景要求"在模块被使用之前就让 Jest 用上 mock"。为此 Jest 会自动把 jest.mock 调用提升(hoist)到模块顶部(所有 import 之前),从编译层面保证 mock 先于模块加载生效。
这个机制由 babel-plugin-jest-hoist 实现。在 packages/babel-plugin-jest-hoist/src/index.ts 中可以看到其核心工作:识别 jest.mock(...) 调用并标记为可提升(如源码中的 hoistable 判定、hoistedJestGetters.add(jestCallExpr) 等逻辑),同时严格限制 factory 引用的变量必须在提升后依然可见。文档 CodeTransformation 对该插件的整体工作方式也有说明。
5.2 注意 factory 内的变量引用限制
正因为 jest.mock 会被提升到顶部,factory 回调里不能引用外部作用域的变量(此时那些变量尚未初始化)。需要共享数据时,应把依赖注入到 jest.mock 的 factory 参数中,或使用 jest.requireActual 等机制,避免"工厂函数引用了未初始化变量"的经典报错。
5.3 ESM 原生模式下的限制
若你启用了原生 ECMAScript Modules 支持,jest.mock 将无法被提升。 原因是 ESM loader 总是先执行静态 import 再执行代码,hoisting 无从谈起。此时请参照 ECMAScriptModules 文档了解 ESM 场景下 mock 的可行方式与约束。
六、Mocking methods which are not implemented in JSDOM
6.1 问题现象
如果被测代码使用了 JSDOM(Jest 默认 DOM 实现)尚未实现的方法,测试将无法正常执行。典型例子是 window.matchMedia()——直接调用会抛 TypeError: window.matchMedia is not a function,测试直接失败。
6.2 方案一:在测试文件中定义 mock
当 window.matchMedia 是在测试过程中被函数(或方法)内部调用时,在测试文件里用 Object.defineProperty 定义一个完整替身即可:
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 返回值覆盖了 matchMedia 监听器 API 的"新旧两代"接口:addListener/removeListener(已废弃的旧 API)与 addEventListener/removeEventListener/dispatchEvent(新标准 API),保证依赖任意一代接口的代码都能正常工作。
6.3 方案二:被测文件顶层直接调用时,拆出独立 mock 文件并先导入
如果 window.matchMedia() 是在被测文件的顶层直接执行(而非在测试时才调用的函数内部),方案一无效——因为模块加载瞬间就会抛错。此时需要把 mock 挪到独立文件,并在导入被测文件之前先导入它:
import './matchMedia.mock'; // 必须早于被测文件导入
import {myMethod} from './file-to-test';
describe('myMethod()', () => {
// 在这里测试 myMethod...
});
原理很清晰:import 按书写顺序自上而下执行,先导入的 matchMedia.mock 会在被测模块顶层执行 window.matchMedia 之前把该 API 装好。结合第五节可知,如果该 mock 文件里用到了 jest.mock 且你处于 CommonJS 转译模式,hoisting 也会保证其执行顺序。
七、一张图看懂目录布局与文件对照
综合上文,一个典型的完整布局如下(与文档给出的示例结构一致):
.
├── config
├── __mocks__ ← 与 node_modules 平级:第三方/内置模块的手动 mock
│ └── fs.js ← 内置模块:需显式 jest.mock('fs') 才生效
├── models
│ ├── __mocks__
│ │ └── user.js ← 用户模块 mock:需显式 jest.mock('../models/user')
│ └── user.js ← 真实实现
├── node_modules
└── views
仓库 examples/manual-mocks 完整复刻了此布局,并额外包含 utils.test.js(演示 jest.replaceProperty 与 jest.restoreAllMocks 处理 process.env 的用法,与手动 mock 配合可覆盖更多环境类场景)。
八、决策速查表
| Mock 对象 | mock 文件位置 | 是否需要显式 jest.mock |
备注 |
|---|---|---|---|
用户模块(如 models/user) |
模块旁的 __mocks__/ 子目录 |
必须 | 目录名严格区分大小写 |
第三方 Node 模块(如 lodash) |
与 node_modules 平级的 __mocks__/ |
不需要 | 自动生效 |
Scoped 包(如 @scope/project-name) |
__mocks__/@scope/project-name.js |
不需要 | 按包全名建目录 |
内置模块(如 fs、path) |
与 node_modules 平级的 __mocks__/ |
必须 | 内置模块默认不 mock |
任意模块 + automock: true |
同上述规则 | 不需要 | 想用真实实现时需 jest.unmock |
九、最佳实践小结
- 优先扩展自动 mock:用
jest.createMockFromModule生成基底,只覆盖需要定制的 API(如fs.readdirSync),避免全手写导致与真实模块 API 不同步。 - 需要真实实现时用
jest.requireActual:在 mock 文件内部引入真实模块再增量修改,保持长期同步。 - 牢记三档规则:用户模块与内置模块必须显式
jest.mock,第三方模块自动生效。 - ESM 转译模式下信任 hoisting,但 factory 内禁止引用外部变量;原生 ESM 模式下
jest.mock无法提升,需查阅 ECMAScriptModules 适配。 - JSDOM 缺口用
Object.defineProperty补齐,若被测文件顶层直接调用则拆独立 mock 文件并确保先导入。 - 目录名大小写敏感:始终使用全小写
__mocks__,避免在 Linux/CI 上踩坑。
通过以上方式,你可以在不触碰任何真实外部资源的前提下,为磁盘、网络、数据库、浏览器 API 等不可控依赖建立一套快速、稳定、可预期的测试替身体系。