msw

MSW のベストプラクティス

MSW v2 アプリケーション（現行バージョン：MSW 2.15）向けの包括的な API モックガイドです。AI エージェントと LLM 向けに設計されています。影響度に応じて優先順位付けされた、8 つのカテゴリにわたる 48 のルールを収録し、自動リファクタリングとコード生成を支援します。

適用するタイミング

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

• テストや開発用に MSW を設定するとき
• リクエストハンドラーを記述または整理するとき
• MSW を使用するテスト環境を設定するとき
• REST API または GraphQL API をモックするとき
• ハンドラーのマッチングに関する問題をデバッグするとき
• エラー状態やエッジケースをテストするとき

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	セットアップと初期化	重大	setup-
2	ハンドラーの設計	重大	handler-
3	テストとの統合	高	test-
4	レスポンスのパターン	高	response-
5	リクエストのマッチング	中〜高	match-
6	GraphQL のモック	中	graphql-
7	高度なパターン	中	advanced-
8	デバッグとパフォーマンス	低	debug-

クイックリファレンス

1. セットアップと初期化（重大）

• 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. ハンドラーの設計（重大）

• 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. テストとの統合（高）

• 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. レスポンスのパターン（高）

• response-http-response-helpers - HttpResponse の静的メソッドを使用する
• response-delay-realistic - テスト対象がタイミングに関する動作の場合にのみ遅延を追加する
• response-error-simulation - エラーレスポンスを正しくシミュレートする
• response-one-time-handlers - 連続するシナリオには一度限りのハンドラーを使用する
• response-custom-headers - レスポンスヘッダーを正しく設定する
• response-streaming - ReadableStream でストリーミングレスポンスをモックする

5. リクエストのマッチング（中〜高）

• match-url-patterns - URL パスパラメーターを正しく使用する
• match-query-params - リクエスト URL からクエリパラメーターを取得する
• match-custom-predicate - 複雑なマッチングにはカスタム述語を使用する
• match-http-methods - HTTP メソッドを明示的にマッチさせる
• match-handler-order - 具体的なものから一般的なものへとハンドラーを並べる

6. GraphQL のモック（中）

• graphql-operation-handlers - GraphQL のマッチングにはオペレーション名を使用する
• graphql-error-responses - GraphQL エラーを正しい形式で返す
• graphql-batched-queries - バッチ処理された GraphQL クエリを処理する
• graphql-variables-access - GraphQL 変数に正しくアクセスする
• graphql-schema-first - GraphQL スキーマに対してオペレーションを解決する

7. 高度なパターン（MEDIUM）

• advanced-bypass-requests - パススルーリクエストに bypass() を使用する
• advanced-cookies-auth - Cookie と認証を処理する
• advanced-dynamic-scenarios - 動的なモックシナリオを実装する
• advanced-vitest-browser - Vitest のブラウザモード向けに MSW を設定する
• advanced-file-uploads - ファイルアップロードのエンドポイントをモックする
• advanced-websocket-mocking - ws.link を使用して WebSocket 接続をモックする
• advanced-playwright-integration - @msw/playwright の defineNetworkFixture を使用する

8. デバッグとパフォーマンス（LOW）

• debug-lifecycle-events - デバッグにライフサイクルイベントを使用する
• debug-verify-interception - リクエストのインターセプトが機能していることを確認する
• debug-common-issues - MSW のよくある問題と解決方法を把握する
• debug-request-logging - デバッグ用にリクエストの詳細をログに記録する

使用方法

まずプロジェクトのルートで実行します。

npx -y @pymodel/react-frontend-skills detect            # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill msw  # deprecated APIs → rule IDs

タスクに該当する上記の各ルールと、scan で検出された各項目について、references/<rule-id>.md を読み、重要な理由と誤ったコードと正しいコードを確認します。

関連スキル

• モック API の利用については、tanstack-query スキルを参照してください
• テストフレームワークのパターンについては vitest を、手法については tdd を参照してください