Jest
IMPORTANT: Your training data about Jest may be outdated or incorrect — Jest 29+ introduces async timer methods, jest.replaceProperty, and ESM mocking via jest.unstable_mockModule. Jest 30 removes the deprecated alias matchers (toBeCalled, lastCalledWith, toThrowError, …), renames --testPathPattern to --testPathPatterns, and excludes non-enumerable object properties from object matchers. Always rely on this skill's rule files and the project's actual source code as the source of truth. Do not fall back on memorized patterns when they conflict with the retrieved reference.
When to Use Jest
Jest is a JavaScript/TypeScript testing framework for unit tests, integration tests, and snapshot tests. It includes a test runner, assertion library, mock system, and coverage reporter.
| Need |
Recommended Tool |
| Unit/integration testing (JS/TS) |
Jest |
| React component testing |
Jest + React Testing Library |
| E2E browser testing |
Playwright, Cypress |
| API contract testing |
Jest + Supertest |
| Smaller/faster test runner |
Vitest (Jest-compatible API) |
| Native ESM without config |
Vitest or Node test runner |
Rule Categories by Priority
| Priority |
Category |
Impact |
Prefix |
| 1 |
Mock Design |
CRITICAL |
mock- (5 rules) |
| 2 |
Async Testing |
CRITICAL |
async- |
| 3 |
Matcher Usage |
HIGH |
matcher- |
| 4 |
Timer Mocking |
HIGH |
timer- |
| 5 |
Test Structure |
HIGH |
structure- |
| 6 |
Module Mocking |
MEDIUM |
module- |
| 7 |
Snapshot Testing |
MEDIUM |
snapshot- |
| 8 |
Configuration |
MEDIUM |
config- |
| 9 |
Performance & CI |
MEDIUM |
perf- |
Quick Reference
1. Mock Design (CRITICAL)
mock-clear-vs-reset-vs-restore — clearAllMocks vs resetAllMocks vs restoreAllMocks
mock-spy-restore — Always restore jest.spyOn; prefer restoreMocks config
mock-factory-hoisting — jest.mock factory cannot reference outer variables
mock-partial-require-actual — Use jest.requireActual for partial module mocking
mock-what-to-mock — What to mock and what not to mock; mock boundaries
2. Async Testing (CRITICAL)
async-always-await — Always return/await promises or assertions are skipped
async-expect-assertions — Use expect.assertions(n) to verify async assertions ran
async-done-try-catch — Wrap expect in try/catch when using done callback
3. Matcher Usage (HIGH)
matcher-equality-choice — toBe vs toEqual vs toStrictEqual
matcher-floating-point — Use toBeCloseTo for floats, never toBe
matcher-error-wrapping — Wrap throwing code in arrow function for toThrow
4. Timer Mocking (HIGH)
timer-recursive-safety — Use runOnlyPendingTimers for recursive timers
timer-async-timers — Use async timer methods when promises are involved
timer-selective-faking — Use doNotFake to leave specific APIs real
5. Test Structure (HIGH)
structure-setup-scope — beforeEach/afterEach are scoped to describe blocks
structure-test-isolation — Each test must be independent; reset state in beforeEach
structure-sync-definition — Tests must be defined synchronously
6. Module Mocking (MEDIUM)
module-manual-mock-conventions — mocks directory conventions
module-esm-unstable-mock — Use jest.unstable_mockModule for ESM
module-do-mock-per-test — jest.doMock + resetModules for per-test mocks
7. Snapshot Testing (MEDIUM)
snapshot-keep-small — Keep snapshots small and focused
snapshot-property-matchers — Use property matchers for dynamic fields
snapshot-deterministic — Mock non-deterministic values for stable snapshots
8. Configuration (MEDIUM)
config-coverage-thresholds — Set per-directory coverage thresholds
config-transform-node-modules — Configure transformIgnorePatterns for ESM packages
config-environment-choice — Per-file @jest-environment docblock over global jsdom
9. Performance & CI (MEDIUM)
perf-ci-workers — --runInBand or --maxWorkers for CI
perf-isolate-modules — jest.isolateModules for per-test module state
Jest API Quick Reference
| API |
Purpose |
test(name, fn, timeout?) |
Define a test |
describe(name, fn) |
Group tests |
beforeEach(fn) / afterEach(fn) |
Per-test setup/teardown |
beforeAll(fn) / afterAll(fn) |
Per-suite setup/teardown |
expect(value) |
Start an assertion |
jest.fn(impl?) |
Create a mock function |
jest.spyOn(obj, method) |
Spy on existing method |
jest.mock(module, factory?) |
Mock a module |
jest.useFakeTimers(config?) |
Fake timer APIs |
jest.useRealTimers() |
Restore real timers |
jest.restoreAllMocks() |
Restore all spies/mocks |
jest.resetModules() |
Clear module cache |
jest.isolateModules(fn) |
Sandboxed module cache |
jest.requireActual(module) |
Import real module (bypass mock) |
How to Use
Read individual rule files for detailed explanations and code examples:
rules/mock-clear-vs-reset-vs-restore.md
rules/async-always-await.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and decision tables
References
| Priority |
Reference |
When to read |
| 1 |
references/matchers.md |
All matchers: equality, truthiness, numbers, strings, arrays, objects, asymmetric, custom |
| 2 |
references/mock-functions.md |
jest.fn, jest.spyOn, .mock property, return values, implementations |
| 3 |
references/jest-object.md |
jest.mock, jest.useFakeTimers, jest.setTimeout, jest.retryTimes |
| 4 |
references/async-patterns.md |
Promises, async/await, done callbacks, .resolves/.rejects |
| 5 |
references/configuration.md |
testMatch, transform, moduleNameMapper, coverage, environments |
| 6 |
references/snapshot-testing.md |
toMatchSnapshot, inline snapshots, property matchers, serializers |
| 7 |
references/module-mocking.md |
Manual mocks, mocks, ESM mocking, partial mocking |
| 8 |
references/anti-patterns.md |
15 common mistakes with BAD/GOOD examples |
| 9 |
references/ci-and-debugging.md |
CI optimization, sharding, debugging, troubleshooting |
Ecosystem: Related Testing Skills
This Jest skill covers Jest's own API surface — the foundation layer. For framework-specific testing patterns built on top of Jest, use these companion skills:
| Testing need |
Companion skill |
What it covers |
| API mocking (network-level) |
msw |
MSW 2.0 handlers, setupServer, server.use() per-test overrides, HttpResponse.json(), GraphQL mocking, concurrent test isolation |
| React Native components |
react-native-testing |
RNTL v13/v14 queries (getByRole, findBy), userEvent, fireEvent, waitFor, async render patterns |
| Zod schema validation |
zod-testing |
safeParse() result testing, z.flattenError() assertions, z.toJSONSchema() snapshot drift, zod-schema-faker mock data, property-based testing |
| Redux-Saga side effects |
redux-saga-testing |
expectSaga integration tests, testSaga unit tests, providers, reducer integration, cancellation testing |
| Java testing |
java-testing |
JUnit 5, Mockito, Spring Boot Test slices, Testcontainers, AssertJ |
How They Interact
┌─────────────────────────────────────────────┐
│ 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() │ │
│ }) │ ┘
│ }) │
└─────────────────────────────────────────────┘
The Jest skill provides the test lifecycle (describe, test, beforeEach, afterEach), mock system (jest.fn, jest.mock, jest.spyOn), assertion engine (expect, matchers), and configuration (jest.config.js). The companion skills provide patterns for their specific APIs that run on top of Jest.
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
1---2name: jest3description: >4 Jest best practices, patterns, and API guidance for JavaScript/TypeScript testing.5 Covers mock design, async testing, matchers, timer mocks, snapshots, module mocking,6 configuration, and CI optimization. Baseline: jest ^30.0.0.7 Triggers on: jest imports, describe, it, test, expect, jest.fn, jest.mock,8 jest.spyOn, mentions of "jest", "unit test", "test suite", or "mock".9license: MIT10user-invocable: false11agentic: false12compatibility: "JavaScript/TypeScript projects using jest ^30.0.0 (audited against jest 30.4.2)"13metadata:14 source: https://skillmd.com/skills/anivar/jest15 author: Anivar Aravind16 author_url: https://anivar.net17 version: 1.1.018 tags: jest, testing, unit-test, mock, spy, snapshot, matcher, async, timer, ci19---2021# Jest2223**IMPORTANT:** Your training data about Jest may be outdated or incorrect — Jest 29+ introduces async timer methods, `jest.replaceProperty`, and ESM mocking via `jest.unstable_mockModule`. Jest 30 removes the deprecated alias matchers (`toBeCalled`, `lastCalledWith`, `toThrowError`, …), renames `--testPathPattern` to `--testPathPatterns`, and excludes non-enumerable object properties from object matchers. Always rely on this skill's rule files and the project's actual source code as the source of truth. Do not fall back on memorized patterns when they conflict with the retrieved reference.2425## When to Use Jest2627Jest is a JavaScript/TypeScript testing framework for unit tests, integration tests, and snapshot tests. It includes a test runner, assertion library, mock system, and coverage reporter.2829| Need | Recommended Tool |30|------|-----------------|31| Unit/integration testing (JS/TS) | **Jest** |32| React component testing | **Jest** + React Testing Library |33| E2E browser testing | Playwright, Cypress |34| API contract testing | Jest + Supertest |35| Smaller/faster test runner | Vitest (Jest-compatible API) |36| Native ESM without config | Vitest or Node test runner |3738## Rule Categories by Priority3940| Priority | Category | Impact | Prefix |41|----------|----------|--------|--------|42| 1 | Mock Design | CRITICAL | `mock-` (5 rules) |43| 2 | Async Testing | CRITICAL | `async-` |44| 3 | Matcher Usage | HIGH | `matcher-` |45| 4 | Timer Mocking | HIGH | `timer-` |46| 5 | Test Structure | HIGH | `structure-` |47| 6 | Module Mocking | MEDIUM | `module-` |48| 7 | Snapshot Testing | MEDIUM | `snapshot-` |49| 8 | Configuration | MEDIUM | `config-` |50| 9 | Performance & CI | MEDIUM | `perf-` |5152## Quick Reference5354### 1. Mock Design (CRITICAL)5556- `mock-clear-vs-reset-vs-restore` — clearAllMocks vs resetAllMocks vs restoreAllMocks57- `mock-spy-restore` — Always restore jest.spyOn; prefer restoreMocks config58- `mock-factory-hoisting` — jest.mock factory cannot reference outer variables59- `mock-partial-require-actual` — Use jest.requireActual for partial module mocking60- `mock-what-to-mock` — What to mock and what not to mock; mock boundaries6162### 2. Async Testing (CRITICAL)6364- `async-always-await` — Always return/await promises or assertions are skipped65- `async-expect-assertions` — Use expect.assertions(n) to verify async assertions ran66- `async-done-try-catch` — Wrap expect in try/catch when using done callback6768### 3. Matcher Usage (HIGH)6970- `matcher-equality-choice` — toBe vs toEqual vs toStrictEqual71- `matcher-floating-point` — Use toBeCloseTo for floats, never toBe72- `matcher-error-wrapping` — Wrap throwing code in arrow function for toThrow7374### 4. Timer Mocking (HIGH)7576- `timer-recursive-safety` — Use runOnlyPendingTimers for recursive timers77- `timer-async-timers` — Use async timer methods when promises are involved78- `timer-selective-faking` — Use doNotFake to leave specific APIs real7980### 5. Test Structure (HIGH)8182- `structure-setup-scope` — beforeEach/afterEach are scoped to describe blocks83- `structure-test-isolation` — Each test must be independent; reset state in beforeEach84- `structure-sync-definition` — Tests must be defined synchronously8586### 6. Module Mocking (MEDIUM)8788- `module-manual-mock-conventions` — __mocks__ directory conventions89- `module-esm-unstable-mock` — Use jest.unstable_mockModule for ESM90- `module-do-mock-per-test` — jest.doMock + resetModules for per-test mocks9192### 7. Snapshot Testing (MEDIUM)9394- `snapshot-keep-small` — Keep snapshots small and focused95- `snapshot-property-matchers` — Use property matchers for dynamic fields96- `snapshot-deterministic` — Mock non-deterministic values for stable snapshots9798### 8. Configuration (MEDIUM)99100- `config-coverage-thresholds` — Set per-directory coverage thresholds101- `config-transform-node-modules` — Configure transformIgnorePatterns for ESM packages102- `config-environment-choice` — Per-file @jest-environment docblock over global jsdom103104### 9. Performance & CI (MEDIUM)105106- `perf-ci-workers` — --runInBand or --maxWorkers for CI107- `perf-isolate-modules` — jest.isolateModules for per-test module state108109## Jest API Quick Reference110111| API | Purpose |112|-----|---------|113| `test(name, fn, timeout?)` | Define a test |114| `describe(name, fn)` | Group tests |115| `beforeEach(fn)` / `afterEach(fn)` | Per-test setup/teardown |116| `beforeAll(fn)` / `afterAll(fn)` | Per-suite setup/teardown |117| `expect(value)` | Start an assertion |118| `jest.fn(impl?)` | Create a mock function |119| `jest.spyOn(obj, method)` | Spy on existing method |120| `jest.mock(module, factory?)` | Mock a module |121| `jest.useFakeTimers(config?)` | Fake timer APIs |122| `jest.useRealTimers()` | Restore real timers |123| `jest.restoreAllMocks()` | Restore all spies/mocks |124| `jest.resetModules()` | Clear module cache |125| `jest.isolateModules(fn)` | Sandboxed module cache |126| `jest.requireActual(module)` | Import real module (bypass mock) |127128## How to Use129130Read individual rule files for detailed explanations and code examples:131132```133rules/mock-clear-vs-reset-vs-restore.md134rules/async-always-await.md135```136137Each rule file contains:138139- Brief explanation of why it matters140- Incorrect code example with explanation141- Correct code example with explanation142- Additional context and decision tables143144## References145146| Priority | Reference | When to read |147|----------|-----------|-------------|148| 1 | `references/matchers.md` | All matchers: equality, truthiness, numbers, strings, arrays, objects, asymmetric, custom |149| 2 | `references/mock-functions.md` | jest.fn, jest.spyOn, .mock property, return values, implementations |150| 3 | `references/jest-object.md` | jest.mock, jest.useFakeTimers, jest.setTimeout, jest.retryTimes |151| 4 | `references/async-patterns.md` | Promises, async/await, done callbacks, .resolves/.rejects |152| 5 | `references/configuration.md` | testMatch, transform, moduleNameMapper, coverage, environments |153| 6 | `references/snapshot-testing.md` | toMatchSnapshot, inline snapshots, property matchers, serializers |154| 7 | `references/module-mocking.md` | Manual mocks, __mocks__, ESM mocking, partial mocking |155| 8 | `references/anti-patterns.md` | 15 common mistakes with BAD/GOOD examples |156| 9 | `references/ci-and-debugging.md` | CI optimization, sharding, debugging, troubleshooting |157158## Ecosystem: Related Testing Skills159160This Jest skill covers **Jest's own API surface** — the foundation layer. For framework-specific testing patterns built on top of Jest, use these companion skills:161162| Testing need | Companion skill | What it covers |163|---|---|---|164| API mocking (network-level) | **msw** | MSW 2.0 handlers, `setupServer`, `server.use()` per-test overrides, `HttpResponse.json()`, GraphQL mocking, concurrent test isolation |165| React Native components | **react-native-testing** | RNTL v13/v14 queries (`getByRole`, `findBy`), `userEvent`, `fireEvent`, `waitFor`, async render patterns |166| Zod schema validation | **zod-testing** | `safeParse()` result testing, `z.flattenError()` assertions, `z.toJSONSchema()` snapshot drift, `zod-schema-faker` mock data, property-based testing |167| Redux-Saga side effects | **redux-saga-testing** | `expectSaga` integration tests, `testSaga` unit tests, providers, reducer integration, cancellation testing |168| Java testing | **java-testing** | JUnit 5, Mockito, Spring Boot Test slices, Testcontainers, AssertJ |169170### How They Interact171172```173┌─────────────────────────────────────────────┐174│ Your Test File │175│ │176│ import { setupServer } from 'msw/node' │ → msw skill177│ import { render } from '@testing-library/ │ → react-native-testing skill178│ react-native' │179│ import { UserSchema } from './schemas' │ → zod-testing skill180│ │181│ describe('UserScreen', () => { │ ┐182│ beforeEach(() => { ... }) │ │183│ afterEach(() => jest.restoreAllMocks()) │ │→ jest skill (this one)184│ test('...', async () => { │ │185│ await expect(...).resolves.toEqual() │ │186│ }) │ ┘187│ }) │188└─────────────────────────────────────────────┘189```190191The Jest skill provides the **test lifecycle** (describe, test, beforeEach, afterEach), **mock system** (jest.fn, jest.mock, jest.spyOn), **assertion engine** (expect, matchers), and **configuration** (jest.config.js). The companion skills provide patterns for their specific APIs that run on top of Jest.192193## Full Compiled Document194195For the complete guide with all rules expanded: `AGENTS.md`