jest-skill AGENTS.md

Jest — Complete Guide

This document is for AI agents and LLMs to follow when writing, reviewing, or debugging Jest tests. It compiles all rules and references into a single executable guide.

Baseline: jest ^30.0.0 with JavaScript or TypeScript (audited against jest 30.4.2)

---

Abstract

Jest is the most widely-used JavaScript testing framework, providing a test runner, assertion library, mock system, and coverage reporter in one package. This guide covers the most impactful patterns and pitfalls: mock lifecycle management (clear vs reset vs restore), async testing traps (floating promises, missing assertion guards), matcher selection (toBe vs toEqual vs toStrictEqual), timer mocking (recursive safety, async timers), module mocking (hoisting, ESM, per-test mocks), snapshot testing (determinism, property matchers), configuration (coverage thresholds, environments, ESM transforms), and CI optimization (workers, sharding). Each rule includes incorrect and correct code examples targeting specific mistakes AI agents commonly make.

---

Table of Contents

1. Mock Design — CRITICAL
2. Async Testing — CRITICAL
3. Matcher Usage — HIGH
4. Timer Mocking — HIGH
5. Test Structure — HIGH
6. Module Mocking — MEDIUM
7. Snapshot Testing — MEDIUM
8. Configuration — MEDIUM
9. Performance & CI — MEDIUM

---

1. Mock Design

Impact: CRITICAL

Rule: clearAllMocks vs resetAllMocks vs restoreAllMocks

Jest provides three mock-cleanup functions with very different behaviors. Using the wrong one leaves stale mocks in place.

// INCORRECT — clearAllMocks only clears call history, not implementations
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
  expect(Math.random()).not.toBe(0.5); // FAILS
});

// CORRECT — restoreAllMocks restores original implementations
afterEach(() => {
  jest.restoreAllMocks();
});