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.

Rule Categories by Priority

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 clearMocks + 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-agent-reporter — Inside an AI agent, pass --reporters=default to see passing files and their console output
• perf-isolate-modules — jest.isolateModules for per-test module state

Jest API Quick Reference

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

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:

How They Interact

┌─────────────────────────────────────────────┐
│              Your Test File                 │
│                                             │
│  import { setupServer } from 'msw/node'     │  → msw skill
│  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