jest-skill

# 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