jest

Jest

重要： Jest に関する学習データは古くなっていたり、誤っていたりする可能性があります。Jest 29 以降では、非同期タイマーメソッド、jest.replaceProperty、および jest.unstable_mockModule による ESM のモックが導入されています。Jest 30 では、非推奨のエイリアスマッチャー（toBeCalled、lastCalledWith、toThrowError、…）が削除され、--testPathPattern が --testPathPatterns に名称変更され、オブジェクトマッチャーで列挙不可のオブジェクトプロパティが除外されます。常に、このスキルのルールファイルとプロジェクトの実際のソースコードを信頼できる情報源として使用してください。取得したリファレンスと矛盾する場合は、記憶しているパターンに頼らないでください。

Jest を使用する場面

Jest は、ユニットテスト、インテグレーションテスト、スナップショットテストに対応する JavaScript／TypeScript テストフレームワークです。テストランナー、アサーションライブラリ、モックシステム、カバレッジレポーターが含まれています。

必要な用途	推奨ツール
ユニットテスト／インテグレーションテスト（JS/TS）	Jest
React コンポーネントのテスト	Jest + React Testing Library
E2E ブラウザーテスト	Playwright、Cypress
API コントラクトテスト	Jest + Supertest
より小規模で高速なテストランナー	Vitest（Jest 互換 API）
設定不要のネイティブ ESM	Vitest または Node テストランナー

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	モック設計	重大	mock-（5 ルール）
2	非同期テスト	重大	async-
3	マッチャーの使い方	高	matcher-
4	タイマーのモック	高	timer-
5	テスト構造	高	structure-
6	モジュールのモック	中	module-
7	スナップショットテスト	中	snapshot-
8	設定	中	config-
9	パフォーマンスと CI	中	perf-

クイックリファレンス

1. モック設計（重大）

• mock-clear-vs-reset-vs-restore — clearAllMocks、resetAllMocks、restoreAllMocks の違い
• mock-spy-restore — jest.spyOn は必ず復元してください。restoreMocks 設定を推奨します
• mock-factory-hoisting — jest.mock のファクトリーから外側の変数を参照することはできません
• mock-partial-require-actual — モジュールの部分的なモックには jest.requireActual を使用してください
• mock-what-to-mock — モックする対象としない対象、およびモックの境界

2. 非同期テスト（重大）

• async-always-await — Promise を必ず return／await してください。そうしないとアサーションがスキップされます
• async-expect-assertions — 非同期アサーションが実行されたことを確認するには expect.assertions(n) を使用してください
• async-done-try-catch — done コールバックを使う場合は、expect を try/catch で囲んでください

3. マッチャーの使い方（高）

• matcher-equality-choice — toBe と toEqual と toStrictEqual の使い分け
• matcher-floating-point — 浮動小数点数には toBeCloseTo を使用し、toBe は使用しないでください
• matcher-error-wrapping — toThrow では、例外を投げるコードをアロー関数で囲んでください

4. タイマーのモック（高）

• timer-recursive-safety — 再帰タイマーには runOnlyPendingTimers を使用してください
• timer-async-timers — Promise が関係する場合は非同期タイマーメソッドを使用してください
• timer-selective-faking — 特定の API を実際のままにするには doNotFake を使用してください

5. テスト構造（高）

• structure-setup-scope — beforeEach／afterEach のスコープは describe ブロック内です
• structure-test-isolation — 各テストは独立させ、beforeEach で状態をリセットしてください
• structure-sync-definition — テストは同期的に定義する必要があります

6. モジュールのモック（中）

• module-manual-mock-conventions — mocks ディレクトリの規約
• module-esm-unstable-mock — ESM には jest.unstable_mockModule を使用してください
• module-do-mock-per-test — テストごとのモックには jest.doMock と resetModules を使用してください

7. スナップショットテスト（中）

• snapshot-keep-small — スナップショットは小さく、焦点を絞ってください
• snapshot-property-matchers — 動的なフィールドにはプロパティマッチャーを使用してください
• snapshot-deterministic — 安定したスナップショットを得るため、非決定的な値をモックしてください

8. 設定（中）

• config-coverage-thresholds — ディレクトリごとにカバレッジしきい値を設定してください
• config-transform-node-modules — ESM パッケージには transformIgnorePatterns を設定してください
• config-environment-choice — グローバルな jsdom より、ファイルごとの @jest-environment docblock を使用してください

9. パフォーマンスと CI（中）

• perf-ci-workers — CI 用の --runInBand または --maxWorkers
• perf-isolate-modules — テストごとのモジュール状態に jest.isolateModules を使用

Jest API クイックリファレンス

API	目的
test(name, fn, timeout?)	テストを定義します
describe(name, fn)	テストをグループ化します
beforeEach(fn) / afterEach(fn)	テストごとのセットアップ／後処理
beforeAll(fn) / afterAll(fn)	テストスイートごとのセットアップ／後処理
expect(value)	アサーションを開始します
jest.fn(impl?)	モック関数を作成します
jest.spyOn(obj, method)	既存のメソッドをスパイします
jest.mock(module, factory?)	モジュールをモックします
jest.useFakeTimers(config?)	タイマー API を偽装します
jest.useRealTimers()	実際のタイマーを復元します
jest.restoreAllMocks()	すべてのスパイ／モックを復元します
jest.resetModules()	モジュールキャッシュをクリアします
jest.isolateModules(fn)	サンドボックス化されたモジュールキャッシュ
jest.requireActual(module)	実際のモジュールをインポートします（モックを迂回）

使用方法

詳しい説明とコード例については、各ルールファイルを参照してください。

rules/mock-clear-vs-reset-vs-restore.md
rules/async-always-await.md

各ルールファイルには次の内容が含まれています。

• 重要な理由の簡単な説明
• 誤ったコード例とその説明
• 正しいコード例とその説明
• 追加の背景情報と判断表

参考資料

優先度	参考資料	参照するタイミング
1	references/matchers.md	すべてのマッチャー：等価性、真偽値、数値、文字列、配列、オブジェクト、非対称マッチャー、カスタムマッチャー
2	references/mock-functions.md	jest.fn、jest.spyOn、.mock プロパティ、戻り値、実装
3	references/jest-object.md	jest.mock、jest.useFakeTimers、jest.setTimeout、jest.retryTimes
4	references/async-patterns.md	Promise、async/await、done コールバック、.resolves/.rejects
5	references/configuration.md	testMatch、transform、moduleNameMapper、カバレッジ、環境
6	references/snapshot-testing.md	toMatchSnapshot、インラインスナップショット、プロパティマッチャー、シリアライザー
7	references/module-mocking.md	手動モック、mocks、ESM のモック、部分的なモック
8	references/anti-patterns.md	よくある 15 の間違いと BAD/GOOD の例
9	references/ci-and-debugging.md	CI の最適化、シャーディング、デバッグ、トラブルシューティング

エコシステム：関連するテストスキル

この Jest スキルはJest 独自の API サーフェス、つまり基盤レイヤーを扱います。Jest の上に構築された、フレームワーク固有のテストパターンには、次の関連スキルを使用してください。

テストのニーズ	関連スキル	対象範囲
API のモック（ネットワークレベル）	msw	MSW 2.0 のハンドラー、setupServer、テストごとの server.use() によるオーバーライド、HttpResponse.json()、GraphQL のモック、並行テストの分離
React Native コンポーネント	react-native-testing	RNTL v13/v14 のクエリ（getByRole、findBy）、userEvent、fireEvent、waitFor、非同期レンダーのパターン
Zod スキーマの検証	zod-testing	safeParse() の結果テスト、z.flattenError() のアサーション、z.toJSONSchema() のスナップショットの差分、zod-schema-faker のモックデータ、プロパティベーステスト
Redux-Saga の副作用	redux-saga-testing	expectSaga による統合テスト、testSaga による単体テスト、プロバイダー、リデューサーの統合、キャンセルのテスト
Java のテスト	java-testing	JUnit 5、Mockito、Spring Boot Test のスライス、Testcontainers、AssertJ

相互の連携

┌─────────────────────────────────────────────┐
│              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()   │  │
│    })                                       │  ┘
│  })                                         │
└─────────────────────────────────────────────┘

Jest スキルは、テストのライフサイクル（describe、test、beforeEach、afterEach）、モックシステム（jest.fn、jest.mock、jest.spyOn）、アサーションエンジン（expect、マッチャー）、および設定（jest.config.js）を提供します。関連スキルは、Jest 上で動作する各 API 固有のパターンを提供します。

コンパイル済みドキュメント全文

すべてのルールを展開した完全なガイドについては、AGENTS.md を参照してください。

Jest 30.4–30.5 の追加機能

• mockFn.whenCalledWith(...args)（30.5.0）— 引数のリストごとにモックの戻り値を設定でき、非対称マッチャーを標準でサポートします。個別の mockReturnValueOnce の連鎖ではなく、1つのモックで呼び出しごとに異なる結果を返したい場合に使用します。
• describe レベルの再試行（30.5.0）— jest.retryTimes(n, { entireDescribe: true }) を使うと、個々のテストだけでなく describe ブロック全体を再試行します。既存のテスト単位の jest.retryTimes を補完します。
• --collectTests の拡張（30.5.0）— test.each／describe.each のケースを展開し、ステータスごとの件数（スキップされたテストの wouldRun を含む）に加え、実際の実行に対応するサマリー行を報告します。--testNamePattern やフォーカスされた describe の場合も同様です。
• 再試行時のエラー出力の改善（30.5.0）— ネストされた cause と AggregateError のセクションが、再試行ログや未処理の拒否に関するレポートでコードフレーム付きで表示されます。
• defineConfig／mergeConfig ヘルパー（30.3.0）— 型安全な Jest 設定の構築に使えます。
• jest.config.mts（30.4.0）— 他の TypeScript 設定形式と同様に、有効な設定ファイルとして受け付けられます。
• フェイクタイマーでの Temporal（30.4.0）— jest.advanceTimersByTime() は Temporal.Duration を受け付けます。jest.setSystemTime() と useFakeTimers({ now }) は Temporal.Instant と Temporal.ZonedDateTime を受け付けます。また、Temporal.Now.* をフェイクできます。
• Node ネイティブの型削除（30.5.2）— .ts、.mts、.cts ファイルを処理するトランスフォーマーがない場合、Jest は Node 自体を使って TypeScript の型を削除するようになりました。
• toMatchObject／objectContaining の型の拡張（30.5.0）— 引数の型が Record<string, unknown> から object に変更され、クラスのインスタンスも受け付けられるようになりました。