MSW ベストプラクティス

MSW v2 アプリケーション向けの包括的な API モッキングガイドであり、AI エージェントと LLM 向けに設計されています。8 つのカテゴリにわたって 45 のルールを含み、自動リファクタリングとコード生成をガイドするため、影響度でプライオリティ付けされています。

適用時期

以下の場面でこのガイドラインを参照してください:

• テストまたは開発用に MSW をセットアップする場合
• リクエストハンドラーを作成または整理する場合
• MSW でテスト環境を構成する場合
• REST または GraphQL API をモックする場合
• ハンドラーマッチングの問題をデバッグする場合
• エラー状態とエッジケースをテストする場合

ルールカテゴリプライオリティ順

プライオリティ	カテゴリ	インパクト	プレフィックス
1	セットアップ・初期化	CRITICAL	setup-
2	ハンドラーアーキテクチャ	CRITICAL	handler-
3	テスト統合	HIGH	test-
4	レスポンスパターン	HIGH	response-
5	リクエストマッチング	MEDIUM-HIGH	match-
6	GraphQL モッキング	MEDIUM	graphql-
7	高度なパターン	MEDIUM	advanced-
8	デバッグ・パフォーマンス	LOW	debug-

クイックリファレンス

1. セットアップ・初期化 (CRITICAL)

• setup-server-node-entrypoint - Node.js の正しいエントリポイントを使用する (msw/node)
• setup-lifecycle-hooks - テストセットアップでサーバーライフサイクルを構成する
• setup-worker-script-commit - ワーカースクリプトをバージョン管理にコミットする
• setup-node-version - MSW v2 には Node.js 18 以上が必要
• setup-unhandled-requests - 未処理リクエストの動作を構成する
• setup-typescript-config - MSW v2 向けに TypeScript を構成する

2. ハンドラーアーキテクチャ (CRITICAL)

• handler-happy-path-first - ハッピーパスハンドラーをベースラインとして定義する
• handler-domain-grouping - ハンドラーをドメインでグループ化する
• handler-absolute-urls - ハンドラーで絶対 URL を使用する
• handler-shared-resolvers - 共有レスポンスロジックをリゾルバーに抽出する
• handler-v2-response-syntax - MSW v2 レスポンス構文を使用する
• handler-request-body-parsing - リクエストボディを明示的にパースする
• handler-resolver-argument - リゾルバー引数を正しく分割代入する
• handler-reusability-environments - 環境間でハンドラーを共有する

3. テスト統合 (HIGH)

• test-reset-handlers - 各テスト後にハンドラーをリセットする
• test-avoid-request-assertions - リクエストの直接的なアサーションを避ける
• test-concurrent-boundary - 並行テストに server.boundary() を使用する
• test-fake-timers-config - queueMicrotask を保持するようフェイクタイマーを構成する
• test-async-utilities - モックレスポンスに非同期テストユーティリティを使用する
• test-clear-request-cache - テスト間でリクエストライブラリキャッシュをクリアする
• test-jsdom-environment - Jest に正しい JSDOM 環境を使用する

4. レスポンスパターン (HIGH)

• response-http-response-helpers - HttpResponse 静的メソッドを使用する
• response-delay-realistic - 現実的なレスポンス遅延を追加する
• response-error-simulation - エラーレスポンスを正しくシミュレートする
• response-one-time-handlers - 段階的シナリオに一度限りのハンドラーを使用する
• response-custom-headers - レスポンスヘッダーを正しく設定する
• response-streaming - ReadableStream でストリーミングレスポンスをモックする

5. リクエストマッチング (MEDIUM-HIGH)

• match-url-patterns - URL パスパラメーターを正しく使用する
• match-query-params - リクエスト URL からクエリパラメーターにアクセスする
• match-custom-predicate - 複雑なマッチングにカスタムプレディケートを使用する
• match-http-methods - HTTP メソッドを明示的にマッチさせる
• match-handler-order - ハンドラーを具体的なものから一般的なものへと順序付ける

6. GraphQL モッキング (MEDIUM)

• graphql-operation-handlers - GraphQL マッチングに操作名を使用する
• graphql-error-responses - GraphQL エラーを正しい形式で返す
• graphql-batched-queries - バッチ処理された GraphQL クエリを処理する
• graphql-variables-access - GraphQL 変数に正しくアクセスする

7. 高度なパターン (MEDIUM)

• advanced-bypass-requests - パススルーリクエストに bypass() を使用する
• advanced-cookies-auth - クッキーと認証を処理する
• advanced-dynamic-scenarios - 動的モックシナリオを実装する
• advanced-vitest-browser - Vitest ブラウザーモード用に MSW を構成する
• advanced-file-uploads - ファイルアップロードエンドポイントをモックする

8. デバッグ・パフォーマンス (LOW)

• debug-lifecycle-events - デバッグにライフサイクルイベントを使用する
• debug-verify-interception - リクエストインターセプトが機能しているか検証する
• debug-common-issues - MSW の一般的な問題と修正を知る
• debug-request-logging - デバッグ用にリクエスト詳細をログする

使用方法

詳細な説明とコード例については、個別のリファレンスファイルをご覧ください:

• セクション定義 - カテゴリ構造とインパクトレベル
• ルールテンプレート - 新しいルール追加用テンプレート
• 個別ルール: references/{prefix}-{slug}.md

関連スキル

• OpenAPI から MSW モックを生成する場合は、orval スキルを参照
• モック API を利用する場合は、tanstack-query スキルを参照
• テスト方法論については、test-vitest または test-tdd スキルを参照

完全なコンパイルドキュメント

すべてのルール拡張版の完全ガイド: AGENTS.md