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

Jest 30.4–30.5 Additions

• mockFn.whenCalledWith(...args) (30.5.0) — configure a mock's return value per argument list, with first-class asymmetric-matcher support. Use it when one mock needs different results for different calls instead of separate mockReturnValueOnce chains.
• Describe-level retries (30.5.0) — jest.retryTimes(n, { entireDescribe: true }) retries the whole describe block, not just individual tests. Complements the existing per-test jest.retryTimes.
• --collectTests expansion (30.5.0) — expands test.each/describe.each cases and reports per-status counts (including wouldRun for skipped tests) plus a summary line matching a real run, also under --testNamePattern and focused describes.
• Richer retry error output (30.5.0) — nested cause and AggregateError sections render with code frames in retry logs and unhandled-rejection reports.
• defineConfig / mergeConfig helpers (30.3.0) — type-safe Jest config construction.
• jest.config.mts (30.4.0) — accepted as a valid configuration file, alongside the other TS config forms.
• Temporal in fake timers (30.4.0) — jest.advanceTimersByTime() accepts Temporal.Duration; jest.setSystemTime() and useFakeTimers({ now }) accept Temporal.Instant and Temporal.ZonedDateTime; Temporal.Now.* can be faked.
• Node-native type stripping (30.5.2) — when no transformer claims a .ts, .mts or .cts file, Jest now strips TypeScript types with Node itself.
• toMatchObject / objectContaining widened (30.5.0) — parameter type is object instead of Record<string, unknown>, so class instances are accepted.