msw

MSW のベストプラクティス

MSW v2 アプリケーション向けの包括的な API モックガイドです。AI エージェントと LLM を対象に設計されています。8 つのカテゴリにわたる 45 のルールが含まれており、影響度に基づいて優先順位を付け、リファクタリングやコード生成の自動化を支援します。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• テストや開発のために MSW をセットアップするとき
• リクエストハンドラーを記述または整理するとき
• MSW を使用するテスト環境を設定するとき
• REST API または 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 - passthrough リクエストに bypass() を使用する
• advanced-cookies-auth - Cookie と認証を処理する
• 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