jest

# 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...

# 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-objec...