jest

Jest

重要提示： 关于 Jest 的训练数据可能已经过时或不准确——Jest 29+ 引入了异步计时器方法、jest.replaceProperty 和通过 jest.unstable_mockModule 进行的 ESM 模拟。Jest 30 移除了已弃用的别名匹配器（toBeCalled、lastCalledWith、toThrowError，等等），将 --testPathPattern 重命名为 --testPathPatterns，并且对象匹配器不再检查对象的不可枚举属性。请始终以此技能的规则文件和项目的实际源代码为准。若记忆中的模式与检索到的参考资料冲突，切勿依赖记忆中的模式。

何时使用 Jest

Jest 是一个用于单元测试、集成测试和快照测试的 JavaScript/TypeScript 测试框架。它包含测试运行器、断言库、模拟系统和覆盖率报告器。

需求	推荐工具
单元测试／集成测试（JS/TS）	Jest
React 组件测试	Jest + React Testing Library
端到端浏览器测试	Playwright、Cypress
API 契约测试	Jest + Supertest
更小、更快的测试运行器	Vitest（兼容 Jest API）
无需配置的原生 ESM	Vitest 或 Node 测试运行器

按优先级划分的规则类别

优先级	类别	影响	前缀
1	模拟设计	严重	mock-（5 条规则）
2	异步测试	严重	async-
3	匹配器用法	高	matcher-
4	计时器模拟	高	timer-
5	测试结构	高	structure-
6	模块模拟	中	module-
7	快照测试	中	snapshot-
8	配置	中	config-
9	性能与 CI	中	perf-

快速参考

1. 模拟设计（严重）

• mock-clear-vs-reset-vs-restore — clearAllMocks、resetAllMocks 与 restoreAllMocks
• mock-spy-restore — 始终恢复 jest.spyOn；优先使用 restoreMocks 配置
• mock-factory-hoisting — jest.mock 工厂不能引用外部变量
• mock-partial-require-actual — 使用 jest.requireActual 进行部分模块模拟
• mock-what-to-mock — 应模拟和不应模拟的内容；模拟边界

2. 异步测试（严重）

• async-always-await — 始终返回／等待 Promise，否则断言会被跳过
• async-expect-assertions — 使用 expect.assertions(n) 验证异步断言确实运行
• async-done-try-catch — 使用 done 回调时，用 try/catch 包裹 expect

3. 匹配器用法（高）

• matcher-equality-choice — toBe 与 toEqual、toStrictEqual 的区别
• matcher-floating-point — 浮点数使用 toBeCloseTo，切勿使用 toBe
• matcher-error-wrapping — 将会抛出异常的代码包裹在箭头函数中，再传给 toThrow

4. 计时器模拟（高）

• timer-recursive-safety — 对递归计时器使用 runOnlyPendingTimers
• timer-async-timers — 涉及 Promise 时使用异步计时器方法
• timer-selective-faking — 使用 doNotFake 保留指定 API 的真实实现

5. 测试结构（高）

• structure-setup-scope — beforeEach／afterEach 的作用范围限于 describe 块
• structure-test-isolation — 每个测试都必须独立；在 beforeEach 中重置状态
• structure-sync-definition — 必须同步定义测试

6. 模块模拟（中）

• module-manual-mock-conventions — mocks 目录约定
• module-esm-unstable-mock — 对 ESM 使用 jest.unstable_mockModule
• module-do-mock-per-test — 使用 jest.doMock + resetModules 创建针对单个测试的模拟

7. 快照测试（中）

• snapshot-keep-small — 保持快照小巧且聚焦
• snapshot-property-matchers — 对动态字段使用属性匹配器
• snapshot-deterministic — 模拟非确定性值，以确保快照稳定

8. 配置（中）

• config-coverage-thresholds — 按目录设置覆盖率阈值
• config-transform-node-modules — 为 ESM 包配置 transformIgnorePatterns
• config-environment-choice — 优先为单个文件使用 @jest-environment 文档块，而非全局 jsdom

9. 性能与 CI（中）

• perf-ci-workers — 在 CI 中使用 --runInBand 或 --maxWorkers
• perf-isolate-modules — 使用 jest.isolateModules 隔离每个测试的模块状态

Jest API 快速参考

API	用途
test(name, fn, timeout?)	定义测试
describe(name, fn)	对测试进行分组
beforeEach(fn) / afterEach(fn)	每个测试的设置／清理
beforeAll(fn) / afterAll(fn)	每个测试套件的设置／清理
expect(value)	开始断言
jest.fn(impl?)	创建模拟函数
jest.spyOn(obj, method)	监视现有方法
jest.mock(module, factory?)	模拟模块
jest.useFakeTimers(config?)	使用模拟计时器 API
jest.useRealTimers()	恢复真实计时器
jest.restoreAllMocks()	恢复所有间谍／模拟
jest.resetModules()	清除模块缓存
jest.isolateModules(fn)	使用沙盒隔离模块缓存
jest.requireActual(module)	导入真实模块（绕过模拟）

使用方法

阅读各个规则文件，了解详细说明和代码示例：

rules/mock-clear-vs-reset-vs-restore.md
rules/async-always-await.md

每个规则文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 补充背景和决策表

参考资料

优先级	参考资料	阅读时机
1	references/matchers.md	所有匹配器：相等性、真值、数字、字符串、数组、对象、非对称匹配器、自定义匹配器
2	references/mock-functions.md	jest.fn、jest.spyOn、.mock 属性、返回值、实现
3	references/jest-object.md	jest.mock、jest.useFakeTimers、jest.setTimeout、jest.retryTimes
4	references/async-patterns.md	Promise、async/await、done 回调、.resolves/.rejects
5	references/configuration.md	testMatch、transform、moduleNameMapper、覆盖率、环境
6	references/snapshot-testing.md	toMatchSnapshot、内联快照、属性匹配器、序列化器
7	references/module-mocking.md	手动模拟、mocks、ESM 模拟、部分模拟
8	references/anti-patterns.md	15 个常见错误及 BAD/GOOD 示例
9	references/ci-and-debugging.md	CI 优化、分片、调试、故障排查

生态：相关测试技能

此 Jest 技能涵盖 Jest 自身的 API 范围——基础层。对于构建在 Jest 之上的特定框架测试模式，请使用以下配套技能：

测试需求	配套技能	涵盖内容
API 模拟（网络层）	msw	MSW 2.0 处理程序、setupServer、每个测试的 server.use() 覆盖、HttpResponse.json()、GraphQL 模拟、并发测试隔离
React Native 组件	react-native-testing	RNTL v13/v14 查询（getByRole、findBy）、userEvent、fireEvent、waitFor、异步渲染模式
Zod 模式验证	zod-testing	safeParse() 结果测试、z.flattenError() 断言、z.toJSONSchema() 快照漂移、zod-schema-faker 模拟数据、基于属性的测试
Redux-Saga 副作用	redux-saga-testing	expectSaga 集成测试、testSaga 单元测试、providers、reducer 集成、取消测试
Java 测试	java-testing	JUnit 5、Mockito、Spring Boot Test 切片、Testcontainers、AssertJ

它们如何协同工作

┌─────────────────────────────────────────────┐
│              Your Test File                 │
│                                             │
│  import { setupServer } from 'msw/node'     │  → msw skill
│  import { render } from '@testing-library/  │  → react-native-testing skill
│            react-native'                    │
│  import { UserSchema } from './schemas'     │  → zod-testing skill
│                                             │
│  describe('UserScreen', () => {             │  ┐
│    beforeEach(() => { ... })                │  │
│    afterEach(() => jest.restoreAllMocks())   │  │→ jest skill (this one)
│    test('...', async () => {                │  │
│      await expect(...).resolves.toEqual()   │  │
│    })                                       │  ┘
│  })                                         │
└─────────────────────────────────────────────┘

Jest 技能提供测试生命周期（describe、test、beforeEach、afterEach）、模拟系统（jest.fn、jest.mock、jest.spyOn）、断言引擎（expect、匹配器）和配置（jest.config.js）。配套技能则提供基于 Jest 运行的特定 API 模式。

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md

Jest 30.4–30.5 新增功能

• mockFn.whenCalledWith(...args)（30.5.0）— 按参数列表配置模拟函数的返回值，并原生支持非对称匹配器。当同一个模拟函数需要针对不同调用返回不同结果，而不是使用多条 mockReturnValueOnce 链时，可以使用此功能。
• 描述级重试（30.5.0）— jest.retryTimes(n, { entireDescribe: true }) 会重试整个 describe 块，而不只是单个测试。此功能与现有的按测试设置的 jest.retryTimes 相辅相成。
• 扩展 --collectTests（30.5.0）— 展开 test.each/describe.each 用例并报告各状态的数量（包括跳过测试的 wouldRun），还会输出与实际运行相匹配的摘要行；在 --testNamePattern 和聚焦的 describe 中也同样适用。
• 更丰富的重试错误输出（30.5.0）— 重试日志和未处理的拒绝报告中，嵌套的 cause 和 AggregateError 部分会显示代码框架。
• defineConfig / mergeConfig 助手函数（30.3.0）— 用于以类型安全的方式构建 Jest 配置。
• jest.config.mts（30.4.0）— 现已被接受为有效配置文件，与其他 TS 配置形式并列。
• 虚假计时器中的 Temporal（30.4.0）— jest.advanceTimersByTime() 接受 Temporal.Duration；jest.setSystemTime() 和 useFakeTimers({ now }) 接受 Temporal.Instant 和 Temporal.ZonedDateTime；Temporal.Now.* 可被模拟。
• Node 原生类型剥离（30.5.2）— 当没有转换器处理 .ts、.mts 或 .cts 文件时，Jest 现在会直接使用 Node 剥离 TypeScript 类型。
• 扩大 toMatchObject / objectContaining 的类型范围（30.5.0）— 参数类型从 Record<string, unknown> 改为 object，因此现在接受类实例。