jest

Original source / Raw SKILL.md

---
name: jest
description: >
  Jest best practices, patterns, and API guidance for JavaScript/TypeScript testing.
  Covers mock design, async testing, matchers, timer mocks, snapshots, module mocking,
  configuration, and CI optimization. Baseline: jest ^29.0.0 / ^30.0.0.
  Triggers on: jest imports, describe, it, test, expect, jest.fn, jest.mock,
  jest.spyOn, mentions of "jest", "unit test", "test suite", or "mock".
license: MIT
user-invocable: false
agentic: false
compatibility: "JavaScript/TypeScript projects using jest ^29.0.0 or ^30.0.0"
metadata:
  author: Anivar Aravind
  author_url: https://anivar.net
  source_url: https://github.com/anivar/jest-skill
  version: 1.0.0
  tags: jest, testing, unit-test, mock, spy, snapshot, matcher, async, timer, ci
---

# 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 deprecates the `done` callback in favor of async patterns. 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`


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### rules/mock-clear-vs-reset-vs-restore.md

```markdown
---
title: clearAllMocks vs resetAllMocks vs restoreAllMocks
impact: CRITICAL
description: Understand the difference between clearing, resetting, and restoring mocks to avoid stale state leaking between tests.
tags: mock, clearAllMocks, resetAllMocks, restoreAllMocks, isolation
---

# clearAllMocks vs resetAllMocks vs restoreAllMocks

## Problem

Jest provides three mock-cleanup functions that sound similar but do very different things. Using `clearAllMocks` when you need `restoreAllMocks` leaves mock implementations in place, causing later tests to silently use stale fakes. Using `resetAllMocks` destroys custom implementations you intended to keep.

## Incorrect

```javascript
// BUG: clearAllMocks only clears call history — the mock implementation stays
afterEach(() => {
  jest.clearAllMocks();
});

test('first', () => {
  jest.spyOn(Math, 'random').mockReturnValue(0.5);
  expect(Math.random()).toBe(0.5);
});

test('second', () => {
  // Math.random is STILL mocked — returns 0.5, not a real random number
  expect(Math.random()).not.toBe(0.5); // FAILS
});
```

## Correct

```javascript
afterEach(() => {
  jest.restoreAllMocks();
});

test('first', () => {
  jest.spyOn(Math, 'random').mockReturnValue(0.5);
  expect(Math.random()).toBe(0.5);
});

test('second', () => {
  // Math.random is restored to the real implementation
  expect(typeof Math.random()).toBe('number'); // PASSES
});
```

## Decision Table

| Function | Clears calls/instances | Removes mock implementation | Restores original |
|---|---|---|---|
| `clearAllMocks` | Yes | No | No |
| `resetAllMocks` | Yes | Yes (resets to `jest.fn()`) | No |
| `restoreAllMocks` | Yes | Yes | Yes |

## Why

- **clearAllMocks**: Use between tests when you want to keep the mock implementation but reset counters (e.g., checking `toHaveBeenCalledTimes` per test).
- **resetAllMocks**: Use when you want every test to set up its own mock implementation from scratch. Mocks become no-op `jest.fn()`.
- **restoreAllMocks**: Use when you used `jest.spyOn` and want the original implementation back. This is the safest default for `afterEach`.

Prefer setting `restoreMocks: true` in `jest.config` so you never forget:

```javascript
// jest.config.js
module.exports = {
  restoreMocks: true,
};
```

```

### references/matchers.md

```markdown
# Matchers Reference

## Equality Matchers

### `toBe(value)`
Uses `Object.is` (strict reference equality). Use for primitives and reference identity.

```javascript
expect(1 + 1).toBe(2);
expect('hello').toBe('hello');
expect(obj).toBe(sameObjRef);
```

### `toEqual(value)`
Deep value equality. Ignores `undefined` properties and does not check class type.

```javascript
expect({ a: 1, b: undefined }).toEqual({ a: 1 }); // passes
expect(new Cat('Mimi')).toEqual({ name: 'Mimi' }); // passes (ignores class)
```

### `toStrictEqual(value)`
Deep equality with strict checks: `undefined` properties, sparse arrays, and class types must match.

```javascript
expect({ a: 1, b: undefined }).not.toStrictEqual({ a: 1 }); // fails — b is missing
expect(new Cat('Mimi')).not.toStrictEqual({ name: 'Mimi' }); // fails — different class
```

## Truthiness Matchers

| Matcher | Matches |
|---|---|
| `toBeNull()` | `null` only |
| `toBeUndefined()` | `undefined` only |
| `toBeDefined()` | anything except `undefined` |
| `toBeTruthy()` | anything `if()` considers true |
| `toBeFalsy()` | `false`, `0`, `''`, `null`, `undefined`, `NaN` |

## Number Matchers

```javascript
expect(value).toBeGreaterThan(3);
expect(value).toBeGreaterThanOrEqual(3);
expect(value).toBeLessThan(5);
expect(value).toBeLessThanOrEqual(5);
expect(0.1 + 0.2).toBeCloseTo(0.3);          // default precision: 5
expect(0.1 + 0.2).toBeCloseTo(0.3, 10);      // custom precision
expect(NaN).toBeNaN();
```

## String Matchers

```javascript
expect('team').toContain('tea');
expect('hello world').toMatch(/world/);
expect('hello world').toMatch('world');       // substring match
expect(str).toHaveLength(5);
```

## Array/Iterable Matchers

```javascript
expect(['a', 'b', 'c']).toContain('b');
expect([{ a: 1 }, { b: 2 }]).toContainEqual({ a: 1 }); // deep equality
expect(arr).toHaveLength(3);
```

## Object Matchers

```javascript
expect(obj).toHaveProperty('key');
expect(obj).toHaveProperty('key', 'value');
expect(obj).toHaveProperty('nested.key');
expect(obj).toHaveProperty(['nested', 'key']);
expect(obj).toMatchObject({ subset: 'value' }); // partial match
```

## Error Matchers

```javascript
expect(() => fn()).toThrow();                    // any error
expect(() => fn()).toThrow('message');            // message substring
expect(() => fn()).toThrow(/regex/);              // message regex
expect(() => fn()).toThrow(TypeError);            // error class
expect(() => fn()).toThrow(new Error('exact'));   // exact error
```

## Promise Matchers

```javascript
await expect(promise).resolves.toBe('value');
await expect(promise).resolves.toEqual({ key: 'value' });
await expect(promise).rejects.toThrow('error');
await expect(promise).rejects.toBeInstanceOf(Error);
```

## Asymmetric Matchers

Asymmetric matchers can be used inside `toEqual`, `toHaveBeenCalledWith`, `toMatchObject`, and snapshot property matchers.

```javascript
expect.any(Number)                         // any instance of Number
expect.any(String)                         // any instance of String
expect.anything()                          // anything except null/undefined
expect.stringContaining('sub')             // string containing substring
expect.stringMatching(/pattern/)           // string matching regex
expect.arrayContaining([1, 2])             // array containing these items
expect.objectContaining({ key: 'val' })    // object containing these properties
expect.not.arrayContaining([3])            // array NOT containing 3
expect.not.objectContaining({ bad: true }) // object NOT containing bad
expect.closeTo(0.3, 5)                     // number close to 0.3
```

### Usage in assertions

```javascript
expect(fn).toHaveBeenCalledWith(
  expect.any(String),
  expect.objectContaining({ role: 'admin' })
);

expect(result).toEqual({
  id: expect.any(Number),
  name: expect.stringContaining('Alice'),
  tags: expect.arrayContaining(['active']),
});
```

## Custom Matchers

```javascript
expect.extend({
  toBeWithinRange(received, floor, ceiling) {
    const pass = received >= floor && received <= ceiling;
    return {
      pass,
      message: () =>
        `expected ${received} to be within range ${floor} - ${ceiling}`,
    };
  },
});

expect(100).toBeWithinRange(90, 110);
```

### TypeScript typing for custom matchers

```typescript
declare module 'expect' {
  interface AsymmetricMatchers {
    toBeWithinRange(floor: number, ceiling: number): void;
  }
  interface Matchers<R> {
    toBeWithinRange(floor: number, ceiling: number): R;
  }
}
```

## Mock Function Matchers

```javascript
expect(fn).toHaveBeenCalled();
expect(fn).toHaveBeenCalledTimes(3);
expect(fn).toHaveBeenCalledWith(arg1, arg2);
expect(fn).toHaveBeenLastCalledWith(arg1, arg2);
expect(fn).toHaveBeenNthCalledWith(1, arg1, arg2);
expect(fn).toHaveReturned();
expect(fn).toHaveReturnedTimes(3);
expect(fn).toHaveReturnedWith(value);
expect(fn).toHaveLastReturnedWith(value);
expect(fn).toHaveNthReturnedWith(1, value);
```

```

### references/mock-functions.md

```markdown
# Mock Functions Reference

## Creating Mocks

### `jest.fn()`

Creates a standalone mock function with no implementation (returns `undefined`).

```javascript
const mock = jest.fn();
mock('arg1', 'arg2');
expect(mock).toHaveBeenCalledWith('arg1', 'arg2');
```

### `jest.fn(implementation)`

Creates a mock with a default implementation.

```javascript
const add = jest.fn((a, b) => a + b);
expect(add(1, 2)).toBe(3);
expect(add).toHaveBeenCalledTimes(1);
```

### `jest.spyOn(object, methodName)`

Wraps an existing method with a mock while preserving the original implementation. The original can be restored with `.mockRestore()`.

```javascript
const spy = jest.spyOn(console, 'log');
console.log('hello');
expect(spy).toHaveBeenCalledWith('hello');
spy.mockRestore(); // restores original console.log
```

### `jest.spyOn(object, methodName, accessType)`

Spy on getters or setters.

```javascript
const spy = jest.spyOn(obj, 'value', 'get').mockReturnValue(42);
expect(obj.value).toBe(42);
```

## Mock Return Values

```javascript
const mock = jest.fn();

// Single return value
mock.mockReturnValue(42);
expect(mock()).toBe(42);

// One-time return value (used once, then falls back to default)
mock.mockReturnValueOnce(1).mockReturnValueOnce(2).mockReturnValue(99);
expect(mock()).toBe(1);  // first call
expect(mock()).toBe(2);  // second call
expect(mock()).toBe(99); // all subsequent calls

// Resolved promise
mock.mockResolvedValue({ data: 'ok' });
await expect(mock()).resolves.toEqual({ data: 'ok' });

// Rejected promise
mock.mockRejectedValue(new Error('fail'));
await expect(mock()).rejects.toThrow('fail');

// One-time resolved/rejected
mock.mockResolvedValueOnce('first').mockRejectedValueOnce(new Error('second'));
```

## Mock Implementations

```javascript
const mock = jest.fn();

// Permanent implementation
mock.mockImplementation((x) => x * 2);
expect(mock(5)).toBe(10);

// One-time implementation
mock.mockImplementationOnce((x) => x + 1).mockImplementationOnce((x) => x + 2);
expect(mock(0)).toBe(1);
expect(mock(0)).toBe(2);
```

## The `.mock` Property

Every mock function has a `.mock` property that records all calls, return values, instances, and contexts.

```javascript
const mock = jest.fn((x) => x + 1);
mock.call(thisArg, 10);
mock(20);

mock.mock.calls;          // [[10], [20]] — arguments of each call
mock.mock.results;         // [{ type: 'return', value: 11 }, { type: 'return', value: 21 }]
mock.mock.instances;       // [thisArg, undefined] — `this` value for each call
mock.mock.contexts;        // same as instances (Jest 29.6+)
mock.mock.lastCall;        // [20] — arguments of last call
```

### Result types

| `type` | Meaning |
|---|---|
| `'return'` | Function returned normally |
| `'throw'` | Function threw an error |
| `'incomplete'` | Function is still executing (recursive calls) |

## Clearing, Resetting, Restoring

| Method | Instance version | Config version | Effect |
|---|---|---|---|
| `mockClear()` | `mock.mockClear()` | `clearMocks: true` | Clears `mock.calls`, `mock.instances`, `mock.results` |
| `mockReset()` | `mock.mockReset()` | `resetMocks: true` | `mockClear()` + removes implementation (returns `undefined`) |
| `mockRestore()` | `mock.mockRestore()` | `restoreMocks: true` | `mockReset()` + restores original implementation (spyOn only) |

```javascript
// Config-level (recommended)
module.exports = { restoreMocks: true };

// Manual
afterEach(() => {
  jest.restoreAllMocks();
});
```

## Mock Matchers

```javascript
const fn = jest.fn();
fn('a', 'b');
fn('c');

expect(fn).toHaveBeenCalled();                  // called at least once
expect(fn).toHaveBeenCalledTimes(2);             // called exactly 2 times
expect(fn).toHaveBeenCalledWith('a', 'b');       // any call had these args
expect(fn).toHaveBeenLastCalledWith('c');         // last call had these args
expect(fn).toHaveBeenNthCalledWith(1, 'a', 'b'); // first call had these args
```

## Mocking Modules

```javascript
// Auto-mock all exports
jest.mock('./module');

// Mock with factory
jest.mock('./module', () => ({
  fn: jest.fn(() => 'mocked'),
}));

// Partial mock — keep some exports real
jest.mock('./module', () => ({
  ...jest.requireActual('./module'),
  fn: jest.fn(),
}));
```

## Replacing Properties

```javascript
// jest.replaceProperty (Jest 29.4+)
const replaced = jest.replaceProperty(process, 'env', { NODE_ENV: 'test' });
expect(process.env.NODE_ENV).toBe('test');
replaced.restore(); // or use restoreMocks config
```

## TypeScript Helpers

```typescript
import { jest, type Mocked } from '@jest/globals';

// Type a mocked module
jest.mock('./api');
const api = jest.mocked(require('./api'));
// api.fetchUser is now typed as jest.Mock<typeof fetchUser>

// Type a single mock function
const fn = jest.fn<(x: number) => string>();
fn.mockReturnValue('hello');
```

```

### references/jest-object.md

```markdown
# Jest Object Reference

The `jest` object is available globally in every test file. It provides methods for mocking, timer control, module manipulation, and test configuration.

## Module Mocking

### `jest.mock(moduleName, factory?, options?)`

Mocks a module. Hoisted to the top of the file automatically.

```javascript
// Auto-mock (all exports become jest.fn())
jest.mock('./api');

// Factory mock
jest.mock('./api', () => ({
  fetchUser: jest.fn(() => ({ id: 1 })),
}));

// Virtual module (does not need to exist on disk)
jest.mock('virtual-module', () => ({ key: 'value' }), { virtual: true });
```

### `jest.unmock(moduleName)`

Undoes `jest.mock` — the real module is used. Also hoisted.

### `jest.doMock(moduleName, factory?, options?)`

Same as `jest.mock` but **not hoisted**. Use for per-test mocking with `jest.resetModules()`.

### `jest.dontMock(moduleName)`

Same as `jest.unmock` but not hoisted.

### `jest.resetModules()`

Clears the module registry cache. The next `require()` loads a fresh copy.

```javascript
beforeEach(() => {
  jest.resetModules();
});
```

### `jest.isolateModules(fn)`

Creates a sandboxed module registry for the duration of `fn`. Registry is restored after `fn` completes.

```javascript
jest.isolateModules(() => {
  jest.doMock('./config', () => ({ debug: true }));
  const app = require('./app'); // fresh, isolated instance
});
```

### `jest.requireActual(moduleName)`

Returns the real module, bypassing any mocks. Used inside `jest.mock` factories for partial mocking.

```javascript
jest.mock('./api', () => ({
  ...jest.requireActual('./api'),
  fetchUser: jest.fn(),
}));
```

### `jest.requireMock(moduleName)`

Returns the mock version of a module, even if `jest.mock` was not called (uses auto-mocking).

### `jest.createMockFromModule(moduleName)`

Creates an auto-mocked version of a module. Useful in manual mock files (`__mocks__/`).

```javascript
const utils = jest.createMockFromModule('./utils');
utils.format.mockReturnValue('formatted');
module.exports = utils;
```

## ESM Mocking

### `jest.unstable_mockModule(moduleName, factory, options?)`

Mocks a module for ES module imports. Must be called before `await import()`.

```javascript
jest.unstable_mockModule('./api.mjs', () => ({
  fetchUser: jest.fn(),
}));

const { fetchUser } = await import('./api.mjs');
```

## Timer Mocking

### `jest.useFakeTimers(config?)`

Replaces timer globals with fakes.

```javascript
jest.useFakeTimers();
jest.useFakeTimers({ now: new Date('2024-01-01') }); // fixed Date.now
jest.useFakeTimers({ doNotFake: ['Date', 'performance'] }); // selective
jest.useFakeTimers({ timerLimit: 1000 }); // max timers before error
```

### `jest.useRealTimers()`

Restores real timer implementations.

### Timer Advancement

| Method | Behavior |
|---|---|
| `jest.runAllTimers()` | Runs all pending timers recursively (unsafe for recursive timers) |
| `jest.runOnlyPendingTimers()` | Runs only currently pending timers |
| `jest.advanceTimersByTime(ms)` | Advances clock by `ms`, firing timers along the way |
| `jest.advanceTimersToNextTimer(steps?)` | Advances to the next timer (optionally repeat `steps` times) |

### Async Timer Methods (Jest 29.5+)

Same as above but flush microtask queue between timer executions:

```javascript
await jest.runAllTimersAsync();
await jest.runOnlyPendingTimersAsync();
await jest.advanceTimersByTimeAsync(1000);
await jest.advanceTimersToNextTimerAsync();
```

### Timer Inspection

```javascript
jest.getTimerCount();      // number of pending timers
jest.now();                // current fake clock time (ms)
jest.setSystemTime(date);  // set fake clock to specific time
jest.getRealSystemTime();  // real Date.now() even when faked
```

## Mock Cleanup

```javascript
jest.clearAllMocks();      // clear call history
jest.resetAllMocks();      // clear + remove implementations
jest.restoreAllMocks();    // clear + remove + restore originals
```

## Test Configuration

### `jest.setTimeout(milliseconds)`

Sets the default timeout for all tests and hooks in the file.

```javascript
jest.setTimeout(30000); // 30 seconds
```

### `jest.retryTimes(count, options?)`

Retries failed tests up to `count` times. Useful for flaky integration tests.

```javascript
jest.retryTimes(3);
jest.retryTimes(3, { logErrorsBeforeRetry: true });
```

## Property Replacement

### `jest.replaceProperty(object, propertyKey, value)`

Replaces a property value on an object. Restored by `jest.restoreAllMocks()`.

```javascript
jest.replaceProperty(process.env, 'NODE_ENV', 'test');
// later restored automatically if restoreMocks: true
```

### `jest.spyOn(object, methodName)`

See [Mock Functions Reference](./mock-functions.md).

## Misc

### `jest.mocked(source, options?)`

TypeScript helper — wraps a module or function with mock types.

```javascript
jest.mock('./api');
const api = jest.mocked(require('./api'));
// api.fetchUser is typed as jest.MockedFunction<typeof fetchUser>
```

### `jest.fn(implementation?)`

Creates a mock function. See [Mock Functions Reference](./mock-functions.md).

```

### references/async-patterns.md

```markdown
# Async Testing Patterns Reference

## async/await (Preferred)

The simplest and safest pattern. The test function is `async`, and you `await` async operations.

```javascript
test('fetches user', async () => {
  const user = await fetchUser(1);
  expect(user.name).toBe('Alice');
});
```

Any unhandled rejection inside an `async` test automatically fails the test.

## Returning Promises

If you return a promise, Jest waits for it to resolve. If it rejects, the test fails.

```javascript
test('fetches user', () => {
  return fetchUser(1).then(user => {
    expect(user.name).toBe('Alice');
  });
});
```

**Warning**: If you forget `return`, the promise is floating and assertions may be skipped.

## .resolves / .rejects

Chain `.resolves` or `.rejects` on `expect()` to unwrap promises inline. Must be `await`ed.

```javascript
test('resolves to user', async () => {
  await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: 'Alice' });
});

test('rejects with error', async () => {
  await expect(fetchUser(-1)).rejects.toThrow('not found');
});
```

`.resolves` and `.rejects` return promises — you **must** `await` or `return` them.

## done Callback (Legacy)

For callback-based APIs. The test receives a `done` function and must call `done()` on success or `done(error)` on failure.

```javascript
test('calls callback', (done) => {
  fetchUser(1, (error, user) => {
    try {
      expect(error).toBeNull();
      expect(user.name).toBe('Alice');
      done();
    } catch (e) {
      done(e);
    }
  });
});
```

**Rules for `done`**:
- Always wrap `expect` in try/catch and call `done(error)` in the catch.
- If `done()` is never called, the test times out after `jest.setTimeout` (default: 5s).
- Do not mix `done` with `async` — Jest throws if both are used.

## expect.assertions(n)

Verifies that exactly `n` assertions ran during the test. Catches silently skipped assertions.

```javascript
test('handles errors', async () => {
  expect.assertions(1);
  try {
    await riskyOperation();
  } catch (e) {
    expect(e.message).toMatch('failed');
  }
});
```

## expect.hasAssertions()

Verifies that at least one assertion ran. Weaker than `expect.assertions(n)`.

```javascript
test('all items valid', async () => {
  expect.hasAssertions();
  const items = await getItems();
  items.forEach(item => {
    expect(item.valid).toBe(true);
  });
});
```

## Testing Rejected Promises

### Approach 1: .rejects (preferred)

```javascript
test('rejects on invalid input', async () => {
  await expect(processData(null)).rejects.toThrow('invalid');
});
```

### Approach 2: try/catch with assertions count

```javascript
test('rejects on invalid input', async () => {
  expect.assertions(2);
  try {
    await processData(null);
  } catch (e) {
    expect(e).toBeInstanceOf(ValidationError);
    expect(e.message).toMatch('invalid');
  }
});
```

### Approach 3: .catch handler

```javascript
test('rejects on invalid input', () => {
  expect.assertions(1);
  return processData(null).catch(e => {
    expect(e.message).toMatch('invalid');
  });
});
```

## Testing Async Iteration

```javascript
test('processes stream', async () => {
  const results = [];
  for await (const chunk of createStream()) {
    results.push(chunk);
  }
  expect(results).toEqual(['a', 'b', 'c']);
});
```

## Common Mistakes

### Missing await on .resolves/.rejects

```javascript
// BUG: Missing await — assertion is skipped
test('resolves', () => {
  expect(asyncFn()).resolves.toBe('value'); // no await or return — SKIPPED
});

// FIX
test('resolves', async () => {
  await expect(asyncFn()).resolves.toBe('value');
});
```

### Mixing done and async

```javascript
// BUG: Jest throws "An Async callback was invoked..."
test('bad', async (done) => {
  const data = await fetch('/api');
  done(); // ERROR — cannot use done with async
});

// FIX: Remove done, just use async/await
test('good', async () => {
  const data = await fetch('/api');
  expect(data).toBeDefined();
});
```

### Forgetting to return in .then chains

```javascript
// BUG: No return — floating promise
test('bad', () => {
  fetchData().then(data => { expect(data).toBeDefined(); });
});

// FIX
test('good', () => {
  return fetchData().then(data => { expect(data).toBeDefined(); });
});
```

## Timeouts

```javascript
// Per-test timeout (3rd argument)
test('slow operation', async () => {
  await longRunningTask();
}, 30000);

// Per-file timeout
jest.setTimeout(30000);
```

```

### references/configuration.md

```markdown
# Configuration Reference

Jest configuration can be defined in `jest.config.js`, `jest.config.ts`, `jest.config.mjs`, or in the `"jest"` key of `package.json`.

## Test File Discovery

### `testMatch`

Glob patterns for test files. Default matches `**/__tests__/**/*` and `**/*.{test,spec}.*`.

```javascript
module.exports = {
  testMatch: [
    '<rootDir>/src/**/*.test.{js,ts,tsx}',
    '<rootDir>/tests/**/*.spec.{js,ts,tsx}',
  ],
};
```

### `testPathIgnorePatterns`

Patterns to exclude from test discovery.

```javascript
module.exports = {
  testPathIgnorePatterns: ['/node_modules/', '/dist/', '/fixtures/'],
};
```

### `testRegex`

Alternative to `testMatch` — uses regex instead of globs. Cannot use both.

```javascript
module.exports = {
  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.[jt]sx?$',
};
```

## Transform

### `transform`

Maps file extensions to transformers. Default uses `babel-jest`.

```javascript
module.exports = {
  transform: {
    '^.+\\.tsx?$': 'ts-jest',                // TypeScript
    '^.+\\.jsx?$': 'babel-jest',             // JavaScript
    '^.+\\.css$': 'jest-css-modules-transform', // CSS
  },
};
```

### `transformIgnorePatterns`

Patterns to skip transformation. Default: `['/node_modules/']`.

```javascript
module.exports = {
  transformIgnorePatterns: [
    '/node_modules/(?!(uuid|nanoid|chalk)/)', // transform ESM packages
  ],
};
```

## Module Resolution

### `moduleNameMapper`

Maps module paths for aliasing or mocking static assets.

```javascript
module.exports = {
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',           // @ alias
    '\\.(css|scss)$': 'identity-obj-proxy',   // CSS modules
    '\\.(jpg|png|svg)$': '<rootDir>/test/__mocks__/fileMock.js', // assets
  },
};
```

### `modulePaths`

Additional directories to search for modules.

```javascript
module.exports = {
  modulePaths: ['<rootDir>/src'],
};
```

### `moduleDirectories`

Directories to search when resolving modules. Default: `['node_modules']`.

```javascript
module.exports = {
  moduleDirectories: ['node_modules', 'src'],
};
```

## Test Environment

### `testEnvironment`

The environment for all tests. Default: `'node'`.

```javascript
module.exports = {
  testEnvironment: 'node',   // Node.js globals
  // or
  testEnvironment: 'jsdom',  // Browser-like globals (window, document)
};
```

Per-file override via docblock:

```javascript
/**
 * @jest-environment jsdom
 */
```

### `testEnvironmentOptions`

Options passed to the environment.

```javascript
module.exports = {
  testEnvironmentOptions: {
    url: 'https://example.com',  // jsdom URL
    customExportConditions: ['node', 'node-addons'],
  },
};
```

## Coverage

### `collectCoverage`

Enable coverage collection. Default: `false`.

```javascript
module.exports = {
  collectCoverage: true,
  collectCoverageFrom: [
    'src/**/*.{js,ts,tsx}',
    '!src/**/*.d.ts',
    '!src/**/index.ts',        // barrel files
    '!src/**/*.stories.tsx',   // Storybook
  ],
};
```

### `coverageThreshold`

Enforce minimum coverage. CI fails if thresholds are not met.

```javascript
module.exports = {
  coverageThreshold: {
    global: { branches: 80, functions: 80, lines: 80, statements: 80 },
    './src/critical/': { branches: 95, lines: 95 },
  },
};
```

### `coverageReporters`

Output formats. Default: `['json', 'text', 'lcov', 'clover']`.

```javascript
module.exports = {
  coverageReporters: ['text', 'text-summary', 'lcov', 'html'],
};
```

### `coverageDirectory`

Output directory. Default: `'coverage'`.

### `coverageProvider`

Coverage implementation. `'v8'` (faster, default in Jest 30) or `'babel'`.

## Mock Configuration

```javascript
module.exports = {
  clearMocks: true,    // jest.clearAllMocks() after each test
  resetMocks: true,    // jest.resetAllMocks() after each test
  restoreMocks: true,  // jest.restoreAllMocks() after each test (recommended)
  automock: false,      // auto-mock all imports (default: false)
};
```

## Setup Files

### `setupFiles`

Run before the test framework is installed. Use for polyfills and global setup.

```javascript
module.exports = {
  setupFiles: ['./jest.polyfills.js'],
};
```

### `setupFilesAfterFramework` / `setupFilesAfterFramework` → `setupFilesAfterFramework`

### `setupFilesAfterFramework`

(Jest 30) Replaces `setupFilesAfterFramework`.

### `setupFilesAfterFramework`

Run after test framework is installed. Use for custom matchers and global test setup.

```javascript
module.exports = {
  setupFilesAfterFramework: ['./jest.setup.js'],
};
```

### `globalSetup` / `globalTeardown`

Run once before/after all test suites. Use for starting servers, databases, etc.

```javascript
module.exports = {
  globalSetup: './global-setup.js',
  globalTeardown: './global-teardown.js',
};
```

## Execution

### `maxWorkers`

Number of workers. Default: number of CPUs.

```javascript
module.exports = {
  maxWorkers: '50%',  // or a fixed number: 2
};
```

### `verbose`

Display individual test results. Default: `false`.

### `bail`

Stop after `n` test failures. `true` = 1.

```javascript
module.exports = {
  bail: 1, // stop on first failure
};
```

### `testTimeout`

Default timeout for tests in ms. Default: `5000`.

```javascript
module.exports = {
  testTimeout: 10000,
};
```

### `randomize`

Run tests in random order within each file.

```javascript
module.exports = {
  randomize: true,
};
```

## Projects (Monorepo)

```javascript
module.exports = {
  projects: [
    '<rootDir>/packages/core',
    '<rootDir>/packages/web',
    {
      displayName: 'unit',
      testMatch: ['<rootDir>/src/**/*.test.ts'],
    },
    {
      displayName: 'integration',
      testMatch: ['<rootDir>/tests/**/*.integration.ts'],
      testTimeout: 30000,
    },
  ],
};
```

## Snapshot

```javascript
module.exports = {
  snapshotFormat: {
    printBasicPrototype: false, // cleaner snapshot output
  },
  snapshotSerializers: ['enzyme-to-json/serializer'],
};
```

## Watch Plugins

```javascript
module.exports = {
  watchPlugins: [
    'jest-watch-typeahead/filename',
    'jest-watch-typeahead/testname',
  ],
};
```

```

### references/snapshot-testing.md

```markdown
# Snapshot Testing Reference

## Basic Usage

### `toMatchSnapshot(propertyMatchers?, hint?)`

Compares the serialized value against a stored snapshot file (`.snap`). On first run, creates the snapshot. On subsequent runs, compares against it.

```javascript
test('renders correctly', () => {
  const tree = renderer.create(<Button label="Click" />).toJSON();
  expect(tree).toMatchSnapshot();
});
```

### `toMatchInlineSnapshot(propertyMatchers?, snapshot?)`

Same as `toMatchSnapshot` but stores the snapshot inline in the test file. Jest auto-updates the inline snapshot string.

```javascript
test('formats greeting', () => {
  expect(formatGreeting('Alice')).toMatchInlineSnapshot(`"Hello, Alice!"`);
});
```

On first run, the snapshot string is auto-inserted:

```javascript
// Before first run:
expect(formatGreeting('Alice')).toMatchInlineSnapshot();

// After first run (auto-filled):
expect(formatGreeting('Alice')).toMatchInlineSnapshot(`"Hello, Alice!"`);
```

## Property Matchers

For objects with dynamic fields (timestamps, IDs), property matchers assert the type while letting the snapshot pin the static fields.

```javascript
test('creates user', () => {
  expect(createUser({ name: 'Alice' })).toMatchSnapshot({
    id: expect.any(String),
    createdAt: expect.any(Date),
  });
});
// Stored snapshot:
// Object {
//   "id": Any<String>,
//   "name": "Alice",
//   "createdAt": Any<Date>,
// }
```

Works with inline snapshots too:

```javascript
expect(createUser({ name: 'Alice' })).toMatchInlineSnapshot(
  { id: expect.any(String), createdAt: expect.any(Date) },
  `
  {
    "id": Any<String>,
    "name": "Alice",
    "createdAt": Any<Date>,
  }
  `
);
```

## Updating Snapshots

```bash
# Update all snapshots
npx jest --updateSnapshot
npx jest -u

# Update snapshots for specific tests
npx jest -u --testPathPattern='Button'

# In watch mode: press 'u' to update failed snapshots
```

## Snapshot Files

- Stored in `__snapshots__/` directory adjacent to the test file.
- File extension: `.snap`.
- Should be committed to version control.
- Review snapshot diffs carefully in PRs — they represent behavioral changes.

## Custom Serializers

Serializers control how objects are rendered in snapshots.

```javascript
// jest.config.js
module.exports = {
  snapshotSerializers: ['enzyme-to-json/serializer'],
};
```

### Writing a custom serializer

```javascript
// my-serializer.js
module.exports = {
  test(val) {
    return val && val.hasOwnProperty('myCustomProp');
  },
  serialize(val, config, indentation, depth, refs, printer) {
    return `MyCustom<${val.myCustomProp}>`;
  },
};
```

```javascript
// Add inline
expect.addSnapshotSerializer({
  test: (val) => typeof val === 'string' && val.startsWith('$$'),
  serialize: (val) => `Token(${val.slice(2)})`,
});
```

## Snapshot Format

```javascript
// jest.config.js
module.exports = {
  snapshotFormat: {
    escapeString: true,
    printBasicPrototype: false, // don't print "Object {" — just "{"
  },
};
```

## Best Practices

### Keep snapshots small

Snapshot large component trees into individual pieces:

```javascript
// Bad: entire page
expect(renderer.create(<Page />).toJSON()).toMatchSnapshot();

// Good: individual components
expect(renderer.create(<Header />).toJSON()).toMatchSnapshot();
expect(renderer.create(<Sidebar />).toJSON()).toMatchSnapshot();
```

### Prefer inline snapshots for small values

```javascript
expect(formatCurrency(1234.5)).toMatchInlineSnapshot(`"$1,234.50"`);
```

### Use descriptive hint parameters

```javascript
expect(tree).toMatchSnapshot('initial render');
expect(tree).toMatchSnapshot('after clicking button');
```

### Mock non-deterministic values

```javascript
jest.useFakeTimers({ now: new Date('2024-01-01') });
jest.spyOn(Math, 'random').mockReturnValue(0.5);
```

## toThrowErrorMatchingSnapshot

```javascript
test('throws formatted error', () => {
  expect(() => validate(null)).toThrowErrorMatchingSnapshot();
});

test('throws formatted error inline', () => {
  expect(() => validate(null)).toThrowErrorMatchingInlineSnapshot(
    `"Validation failed: value must not be null"`
  );
});
```

## Asymmetric Matchers in Snapshots

You can use asymmetric matchers as property matchers:

```javascript
expect(response).toMatchSnapshot({
  body: {
    users: expect.arrayContaining([
      expect.objectContaining({ role: 'admin' }),
    ]),
    total: expect.any(Number),
    timestamp: expect.stringMatching(/^\d{4}-\d{2}-\d{2}/),
  },
});
```

```

### references/module-mocking.md

```markdown
# Module Mocking Reference

## jest.mock — Standard Module Mock

### Auto-mock (no factory)

```javascript
jest.mock('./api');
const { fetchUser } = require('./api');
// fetchUser is now jest.fn() — returns undefined by default
```

Jest auto-generates mocks for all exports: functions become `jest.fn()`, objects are deeply mocked, classes have all methods mocked.

### Factory mock

```javascript
jest.mock('./api', () => ({
  fetchUser: jest.fn(() => ({ id: 1, name: 'Alice' })),
  fetchPosts: jest.fn(() => []),
}));
```

### Partial mock (keep some exports real)

```javascript
jest.mock('./utils', () => ({
  ...jest.requireActual('./utils'),
  formatDate: jest.fn(() => '2024-01-01'),
}));
```

### ES module mock (with default export)

```javascript
jest.mock('./config', () => ({
  __esModule: true,
  default: { apiUrl: 'http://test.local' },
  timeout: 5000,
}));
```

## Manual Mocks — `__mocks__` Directory

### User modules

Place mock file adjacent to the real module. **Must** call `jest.mock()` to activate.

```
src/
├── utils/
│   ├── __mocks__/
│   │   └── api.js        ← manual mock
│   └── api.js             ← real module
└── app.test.js
```

```javascript
// app.test.js — must explicitly mock
jest.mock('./utils/api');
```

### Node modules

Place mock at project root adjacent to `node_modules/`. **Auto-activated** — no `jest.mock()` needed.

```
project/
├── __mocks__/
│   └── axios.js           ← auto-used for all tests
├── node_modules/
│   └── axios/
└── src/
```

### Scoped packages

```
__mocks__/
└── @scope/
    └── package.js
```

### Manual mock using createMockFromModule

```javascript
// __mocks__/fs.js
const fs = jest.createMockFromModule('fs');
fs.readFileSync.mockReturnValue('mock content');
module.exports = fs;
```

## jest.doMock — Non-Hoisted Mock

Not hoisted above imports — use for per-test mocking.

```javascript
beforeEach(() => jest.resetModules());

test('test config', () => {
  jest.doMock('./config', () => ({ env: 'test' }));
  const config = require('./config');
  expect(config.env).toBe('test');
});

test('prod config', () => {
  jest.doMock('./config', () => ({ env: 'production' }));
  const config = require('./config');
  expect(config.env).toBe('production');
});
```

## jest.isolateModules — Sandboxed Registry

Creates an isolated module registry. Modules required inside the callback get fresh instances.

```javascript
test('isolated', () => {
  jest.isolateModules(() => {
    jest.doMock('./config', () => ({ env: 'staging' }));
    const app = require('./app'); // fresh app with staging config
    expect(app.getEnv()).toBe('staging');
  });
  // registry restored — app from other tests unaffected
});
```

## jest.requireActual — Bypass Mocks

Returns the real module even when it's mocked.

```javascript
jest.mock('./utils', () => {
  const actual = jest.requireActual('./utils');
  return {
    ...actual,
    dangerousFunction: jest.fn(), // only mock this one
  };
});
```

## ESM Mocking — jest.unstable_mockModule

For native ES modules (`import`/`export`). Must use `await import()` after registering the mock.

```javascript
jest.unstable_mockModule('./api.mjs', () => ({
  fetchUser: jest.fn(() => ({ id: 1 })),
}));

test('ESM mock', async () => {
  const { fetchUser } = await import('./api.mjs');
  expect(fetchUser()).toEqual({ id: 1 });
});
```

### Async factory

```javascript
jest.unstable_mockModule('./utils.mjs', async () => {
  const actual = await import('./utils.mjs');
  return { ...actual, format: jest.fn() };
});
```

## Hoisting Behavior

| API | Hoisted | Use case |
|---|---|---|
| `jest.mock()` | Yes | Standard mocking (most common) |
| `jest.unmock()` | Yes | Undo a mock |
| `jest.doMock()` | No | Per-test mocking |
| `jest.dontMock()` | No | Per-test unmocking |

### Factory variable restrictions (hoisting)

```javascript
// FAILS: mockData is not initialized when factory runs
const mockData = { id: 1 };
jest.mock('./api', () => ({ getData: () => mockData }));

// WORKS: variables prefixed with `mock` are allowed
const mockData = { id: 1 };
jest.mock('./api', () => ({ getData: () => mockData }));
```

## Mock Verification

```javascript
jest.mock('./api');
const api = require('./api');

test('calls fetchUser', () => {
  myFunction();
  expect(api.fetchUser).toHaveBeenCalledWith(1);
  expect(api.fetchUser).toHaveBeenCalledTimes(1);
});
```

## Clearing Module Mocks

```javascript
jest.resetModules();  // clear module cache — next require loads fresh
jest.restoreAllMocks(); // restore spied/mocked implementations
```

## TypeScript: Typing Mocked Modules

```typescript
jest.mock('./api');
const { fetchUser } = jest.mocked(require('./api'));
// fetchUser is typed as jest.MockedFunction<typeof fetchUser>

// Or import then cast
import { fetchUser } from './api';
jest.mock('./api');
const mockedFetchUser = jest.mocked(fetchUser);
```

```

### references/anti-patterns.md

```markdown
# Anti-Patterns Reference

Common Jest mistakes that cause silent failures, flaky tests, or false positives. Each pattern includes the bug, why it's wrong, and the fix.

## 1. Floating Promise — Assertions Never Run

```javascript
// BAD: Missing await — test passes with 0 assertions
test('fetches data', () => {
  fetchData().then(data => {
    expect(data).toBeDefined(); // never runs
  });
});

// GOOD
test('fetches data', async () => {
  const data = await fetchData();
  expect(data).toBeDefined();
});
```

## 2. Missing expect.assertions — Silent Skip

```javascript
// BAD: If the try branch succeeds, catch never runs, test passes vacuously
test('handles error', async () => {
  try {
    await riskyOp();
  } catch (e) {
    expect(e.message).toMatch('error');
  }
});

// GOOD
test('handles error', async () => {
  expect.assertions(1);
  try {
    await riskyOp();
  } catch (e) {
    expect(e.message).toMatch('error');
  }
});
```

## 3. toBe on Objects — Reference Comparison

```javascript
// BAD: Different object references
expect(getUser()).toBe({ name: 'Alice' }); // FAILS

// GOOD
expect(getUser()).toEqual({ name: 'Alice' });
```

## 4. toThrow Without Wrapper

```javascript
// BAD: Function executes immediately
expect(throwingFn()).toThrow(); // UNCAUGHT ERROR

// GOOD
expect(() => throwingFn()).toThrow();
```

## 5. clearAllMocks Instead of restoreAllMocks

```javascript
// BAD: Implementations persist
afterEach(() => jest.clearAllMocks());

// GOOD
afterEach(() => jest.restoreAllMocks());

// BEST
// jest.config.js: { restoreMocks: true }
```

## 6. Shared Mutable State

```javascript
// BAD: Tests depend on order
const items = [];
test('adds item', () => { items.push('a'); expect(items).toHaveLength(1); });
test('adds another', () => { items.push('b'); expect(items).toHaveLength(2); }); // order-dependent

// GOOD
let items;
beforeEach(() => { items = []; });
test('adds item', () => { items.push('a'); expect(items).toHaveLength(1); });
test('adds another', () => { items.push('b'); expect(items).toHaveLength(1); });
```

## 7. runAllTimers With Recursive Timers

```javascript
// BAD: Infinite loop
jest.useFakeTimers();
startPolling();
jest.runAllTimers(); // hangs

// GOOD
jest.runOnlyPendingTimers();
// or
jest.advanceTimersByTime(5000);
```

## 8. Mock Factory Referencing Outer Variables

```javascript
// BAD: Variable not initialized when factory runs (hoisting)
const mockData = loadFixtures();
jest.mock('./api', () => ({ getData: () => mockData }));

// GOOD: Inline or use `mock` prefix
jest.mock('./api', () => ({ getData: () => ({ id: 1 }) }));
```

## 9. Forgetting jest.requireActual in Partial Mocks

```javascript
// BAD: All exports except mocked ones are undefined
jest.mock('./utils', () => ({ format: jest.fn() }));

// GOOD
jest.mock('./utils', () => ({
  ...jest.requireActual('./utils'),
  format: jest.fn(),
}));
```

## 10. Test Defined in Async Context

```javascript
// BAD: Tests are never registered
(async () => {
  const cases = await loadCases();
  cases.forEach(c => test(c.name, () => { /* ... */ }));
})();

// GOOD: Use test.each with synchronous data
const cases = require('./cases.json');
test.each(cases)('$name', ({ input, expected }) => {
  expect(process(input)).toBe(expected);
});
```

## 11. Not Awaiting .resolves/.rejects

```javascript
// BAD: Floating assertion
test('resolves', () => {
  expect(asyncFn()).resolves.toBe('value'); // no await
});

// GOOD
test('resolves', async () => {
  await expect(asyncFn()).resolves.toBe('value');
});
```

## 12. done With try but No catch

```javascript
// BAD: Assertion failure causes timeout instead of real error
test('callback test', (done) => {
  asyncOp((err, data) => {
    expect(data).toBe('value'); // throws, done never called → timeout
    done();
  });
});

// GOOD
test('callback test', (done) => {
  asyncOp((err, data) => {
    try {
      expect(data).toBe('value');
      done();
    } catch (e) {
      done(e);
    }
  });
});
```

## 13. Forgetting useRealTimers in afterEach

```javascript
// BAD: Fake timers leak to next test file (in same worker)
test('timer test', () => {
  jest.useFakeTimers();
  // ... test code
  // forgot to restore
});

// GOOD
afterEach(() => {
  jest.useRealTimers();
});
```

## 14. Large Snapshots That Get Rubber-Stamp Updated

```javascript
// BAD: 500-line snapshot nobody reviews
expect(renderer.create(<EntirePage />).toJSON()).toMatchSnapshot();

// GOOD: Small, focused snapshots
expect(renderer.create(<Header />).toJSON()).toMatchSnapshot();
expect(formatOutput(data)).toMatchInlineSnapshot(`"expected output"`);
```

## 15. Sync Timer Methods With Async Code

```javascript
// BAD: Promises not flushed
jest.useFakeTimers();
startAsyncPoller();
jest.advanceTimersByTime(5000); // timers fire but promises don't resolve

// GOOD: Use async timer methods
await jest.advanceTimersByTimeAsync(5000);
```

```

### references/ci-and-debugging.md

```markdown
# CI & Debugging Reference

## CI Optimization

### Worker Configuration

```bash
# Serial execution — best for small suites or memory-constrained CI
npx jest --runInBand

# Fixed workers
npx jest --maxWorkers=2

# Percentage of CPUs
npx jest --maxWorkers=50%
```

### Sharding (Jest 28+)

Split tests across parallel CI jobs:

```bash
# 4 parallel CI jobs
npx jest --shard=1/4  # Job 1
npx jest --shard=2/4  # Job 2
npx jest --shard=3/4  # Job 3
npx jest --shard=4/4  # Job 4
```

Jest distributes test files deterministically so each shard runs a different subset.

### CI-Specific Config

```javascript
// jest.config.js
module.exports = {
  ...(process.env.CI && {
    maxWorkers: 2,
    bail: 1,
    verbose: false,
    coverageReporters: ['text-summary', 'lcov'],
  }),
};
```

### Cache

Jest caches transformed files and dependency graphs. In CI:

```bash
# Cache directory (default: /tmp/jest_*)
npx jest --cacheDirectory=.jest-cache

# Clear cache
npx jest --clearCache

# Disable cache (for debugging)
npx jest --no-cache
```

Cache the `.jest-cache` directory in CI for faster subsequent runs:

```yaml
# GitHub Actions
- uses: actions/cache@v4
  with:
    path: .jest-cache
    key: jest-${{ runner.os }}-${{ hashFiles('**/jest.config.*') }}
```

### Bail on First Failure

```bash
npx jest --bail          # stop after first failed test suite
npx jest --bail=3        # stop after 3 failed test suites
```

### Detect Open Handles

```bash
npx jest --detectOpenHandles
```

Warns about handles (timers, connections, listeners) that prevent Jest from exiting cleanly.

### Force Exit

```bash
npx jest --forceExit
```

Forcefully exits after tests complete. Use as a last resort — `--detectOpenHandles` is preferred to find the root cause.

## Debugging

### Node Inspector

```bash
# Debug in Chrome DevTools
node --inspect-brk node_modules/.bin/jest --runInBand

# Then open chrome://inspect in Chrome
```

`--runInBand` is required — debugging multiple workers is not practical.

### VS Code Launch Config

```json
{
  "type": "node",
  "request": "launch",
  "name": "Jest Debug",
  "program": "${workspaceFolder}/node_modules/.bin/jest",
  "args": [
    "--runInBand",
    "--no-cache",
    "${relativeFile}"
  ],
  "console": "integratedTerminal",
  "internalConsoleOptions": "neverOpen"
}
```

### Debug Specific Test

```json
{
  "type": "node",
  "request": "launch",
  "name": "Jest Debug Current Test",
  "program": "${workspaceFolder}/node_modules/.bin/jest",
  "args": [
    "--runInBand",
    "--no-cache",
    "--testPathPattern",
    "${relativeFile}",
    "--testNamePattern",
    "test name pattern"
  ]
}
```

### console.log in Tests

Jest buffers console output by default. To see it immediately:

```bash
npx jest --verbose
```

Or suppress console output for cleaner test output:

```javascript
beforeEach(() => {
  jest.spyOn(console, 'log').mockImplementation(() => {});
  jest.spyOn(console, 'error').mockImplementation(() => {});
});
```

## Troubleshooting

### "Your test suite must contain at least one test"

- Tests defined inside async callbacks are not registered.
- Check for `(async () => { test(...) })()` pattern.
- Ensure `test()` calls are at the top level or inside synchronous `describe()`.

### "Cannot use import statement outside a module"

- A `node_modules` package ships ESM but Jest expects CJS.
- Fix: add the package to `transformIgnorePatterns` negative lookahead.

```javascript
transformIgnorePatterns: ['/node_modules/(?!(esm-package)/)']
```

### "Async callback was not invoked within the 5000 ms timeout"

- `done()` callback was never called.
- Wrap `expect` in try/catch and call `done(error)` in catch.
- Or switch to async/await.

### "ReferenceError: X is not defined" in jest.mock factory

- Variable is not initialized when the hoisted factory runs.
- Prefix variable with `mock` or define values inline.

### Tests pass individually but fail together

- Shared mutable state between tests.
- Missing mock restoration.
- Fix: use `beforeEach` to reset state, `restoreMocks: true` in config.

### Tests pass locally but fail in CI

- Worker count mismatch (too many workers for CI container).
- Use `--maxWorkers=2` or `--runInBand` in CI.
- Race conditions exposed by different execution order.
- Missing `--forceExit` for open handles.

### Jest hangs after tests complete

```bash
npx jest --detectOpenHandles --forceExit
```

Common causes:
- Open database connections
- Running HTTP servers
- Uncleared intervals/timers
- Unclosed event listeners

### Slow test startup

```bash
# Profile Jest startup
npx jest --showConfig  # check for expensive transforms
npx jest --listTests   # verify test discovery isn't scanning too much
```

Common fixes:
- Use `@swc/jest` or `esbuild-jest` instead of `ts-jest` for faster TypeScript transform.
- Exclude unnecessary directories with `testPathIgnorePatterns`.
- Use `--shard` to split across CI jobs.

## Watch Mode

```bash
npx jest --watch          # re-run on file changes (git-aware)
npx jest --watchAll       # re-run on any file change

# Watch mode commands:
# f — run only failed tests
# o — run only changed tests (default)
# p — filter by filename pattern
# t — filter by test name pattern
# a — run all tests
# u — update failing snapshots
# q — quit
```

## Reporters

```javascript
// jest.config.js
module.exports = {
  reporters: [
    'default',
    ['jest-junit', {
      outputDirectory: './reports',
      outputName: 'jest-junit.xml',
    }],
    ['jest-html-reporter', {
      outputPath: './reports/test-report.html',
    }],
  ],
};
```

### GitHub Actions Reporter

```yaml
- name: Run tests
  run: npx jest --ci --reporters=default --reporters=jest-junit
  env:
    JEST_JUNIT_OUTPUT_DIR: ./reports
```

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Jest Skill

An AI agent skill for writing, debugging, and reviewing Jest tests with modern best practices.

Created by **[Anivar Aravind](https://anivar.net)**

## The Problem

AI agents frequently generate outdated or incorrect Jest patterns — wrong mock cleanup semantics (`clearAllMocks` vs `restoreAllMocks`), missing `await` on async assertions, incorrect timer mock usage, factory hoisting bugs, and anti-patterns that cause tests to silently pass without actually asserting anything. These produce test suites that compile and pass but don't test what they claim to test.

## This Solution

28 rules with incorrect→correct code examples that teach agents Jest's actual API behavior, mock lifecycle, async patterns, timer control, module mocking, snapshot testing, configuration, and CI optimization. Each rule targets a specific mistake and shows exactly how to fix it.

## Install

```bash
npx skills add anivar/jest-skill -g
```

Or with full URL:

```bash
npx skills add https://github.com/anivar/jest-skill
```

## Baseline

- jest ^29.0.0 / ^30.0.0
- JavaScript / TypeScript

## What's Inside

### 28 Rules Across 9 Categories

| Priority | Category | Rules | Impact |
|----------|----------|-------|--------|
| 1 | Mock Design | 5 | CRITICAL |
| 2 | Async Testing | 3 | CRITICAL |
| 3 | Matcher Usage | 3 | HIGH |
| 4 | Timer Mocking | 3 | HIGH |
| 5 | Test Structure | 3 | HIGH |
| 6 | Module Mocking | 3 | MEDIUM |
| 7 | Snapshot Testing | 3 | MEDIUM |
| 8 | Configuration | 3 | MEDIUM |
| 9 | Performance & CI | 2 | MEDIUM |

Each rule file contains:
- Why it matters
- Incorrect code with explanation
- Correct code with explanation
- Decision tables and additional context

### 9 Deep-Dive References

| Reference | Covers |
|-----------|--------|
| `matchers.md` | All matchers: equality, truthiness, numbers, strings, arrays, objects, asymmetric, custom |
| `mock-functions.md` | jest.fn, jest.spyOn, .mock property, return values, implementations, mock matchers |
| `jest-object.md` | jest.mock, jest.useFakeTimers, jest.setTimeout, jest.retryTimes, jest.replaceProperty |
| `async-patterns.md` | Promises, async/await, done callbacks, .resolves/.rejects, expect.assertions |
| `configuration.md` | Key config options: testMatch, transform, moduleNameMapper, coverage, environments |
| `snapshot-testing.md` | toMatchSnapshot, inline snapshots, property matchers, serializers, updating |
| `module-mocking.md` | Manual mocks, __mocks__ directory, ESM mocking, partial mocking, jest.requireActual |
| `anti-patterns.md` | 15 common mistakes with BAD/GOOD examples |
| `ci-and-debugging.md` | CI optimization, --runInBand, --shard, debugging with inspector, troubleshooting |

## Structure

```
├── SKILL.md                          # Entry point for AI agents
├── AGENTS.md                         # Compiled guide with all rules expanded
├── rules/                            # Individual rules (Incorrect→Correct)
│   ├── mock-*                        # Mock design (CRITICAL)
│   ├── async-*                       # Async testing (CRITICAL)
│   ├── matcher-*                     # Matcher usage (HIGH)
│   ├── timer-*                       # Timer mocking (HIGH)
│   ├── structure-*                   # Test structure (HIGH)
│   ├── module-*                      # Module mocking (MEDIUM)
│   ├── snapshot-*                    # Snapshot testing (MEDIUM)
│   ├── config-*                      # Configuration (MEDIUM)
│   └── perf-*                        # Performance & CI (MEDIUM)
└── references/                       # Deep-dive reference docs
    ├── matchers.md
    ├── mock-functions.md
    ├── jest-object.md
    ├── async-patterns.md
    ├── configuration.md
    ├── snapshot-testing.md
    ├── module-mocking.md
    ├── anti-patterns.md
    └── ci-and-debugging.md
```

## Ecosystem — Skills by [Anivar Aravind](https://anivar.net)

This Jest skill covers Jest's own API surface — the foundation layer. For framework-specific testing patterns built on top of Jest, use companion skills:

### Testing Skills (Jest Foundation)

| Need | Skill | Install |
|------|-------|---------|
| **API mocking** (network-level) | [msw-skill](https://github.com/anivar/msw-skill) — MSW 2.0 handlers, server lifecycle, per-test overrides | `npx skills add anivar/msw-skill -g` |
| **React Native components** | [react-native-testing](https://github.com/anivar/react-native-testing) — RNTL v13/v14 queries, userEvent, async render | `npx skills add anivar/react-native-testing -g` |
| **Zod schema validation** | [zod-testing](https://github.com/anivar/zod-testing) — safeParse testing, mock data, property-based testing | `npx skills add anivar/zod-testing -g` |
| **Redux-Saga side effects** | [redux-saga-testing](https://github.com/anivar/redux-saga-testing) — expectSaga, testSaga, providers | `npx skills add anivar/redux-saga-testing -g` |

### Library & Framework Skills

| Skill | What it covers | Install |
|-------|---------------|---------|
| [zod-skill](https://github.com/anivar/zod-skill) | Zod v4 schema validation, parsing, error handling, type inference | `npx skills add anivar/zod-skill -g` |
| [redux-saga-skill](https://github.com/anivar/redux-saga-skill) | Redux-Saga effects, fork model, channels, RTK integration | `npx skills add anivar/redux-saga-skill -g` |
| [msw-skill](https://github.com/anivar/msw-skill) | MSW 2.0 API mocking — handlers, responses, GraphQL, v1→v2 migration | `npx skills add anivar/msw-skill -g` |

### Engineering Analysis Skills

| Skill | What it covers | Install |
|-------|---------------|---------|
| [contributor-codebase-analyzer](https://github.com/anivar/contributor-codebase-analyzer) | Deep-dive code analysis, annual reviews, promotion readiness | `npx skills add anivar/contributor-codebase-analyzer -g` |

## Author

**[Anivar Aravind](https://anivar.net)** — Building AI agent skills for modern JavaScript/TypeScript development.

## License

MIT

```

### _meta.json

```json
{
  "owner": "anivar",
  "slug": "jest-skill",
  "displayName": "Jest",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1772687965799,
    "commit": "https://github.com/openclaw/skills/commit/a49745918d0b572c16d445460bed60775937f0ec"
  },
  "history": []
}

```