ReactとTypeScriptでMock Service Worker (MSW) を活用してAPIをモックする実践ガイド

Development tutorial - IT technology blog
Development tutorial - IT technology blog

実際のインシデント:午前2時にステージングAPIがダウン

深夜2時。4杯目のコーヒーは冷めきっていました。CI/CDの画面は真っ赤に染まり、42件ものテストケースが一斉に失敗を告げています。当日の朝9時は決済機能のリリースデッドライン。しかし、まさにそのタイミングでバックエンドのステージングサーバーがメモリリーク(OOM)により過負荷に陥り、完全にダウンしてしまいました。

フロントエンド開発は完全に麻痺。手動テストも実施できず、Vitestによる自動テストはECONNREFUSEDや504 Gateway Timeoutエラーを吐き出し続けました。バックエンドの稼働状況に100%依存していたため、プロジェクト全体が完全に立ち往生してしまったのです。

納期に間に合わせるため、一部のメンバーはコンポーネント内に直接const fakeUser = {...}をハードコードして急場をしのごうとしました。焦ったコードレビューをすり抜け、この暫定対応が本番環境へあわや混入しかける事態に。UI開発においてステージング環境のインフラに依存することは、あらゆるフロントエンドチームにとって極めて大きなリスクです。

原因の振り返り:APIモックにおける2つの典型的な過ち

上記のトラブルは根本的な弱点を浮き彫りにしました。それは、「モックデータを不適切なレイヤーで注入している」ということです。

  • コンポーネントへの直接ハードコード:ローカルstateやAPI呼び出しカスタムフック内にダミーデータを直接記述する方法です。ビジネスロジックが汚染され、コードをマージする前にテストデータを消し忘れていないか各ファイルを探し回る羽目になります。少しの油断で、モックデータがそのまま本番環境のユーザー画面に表示されてしまいます。
  • HTTPモジュール(AxiosやFetchなど)の上書きモック:vi.mock('axios')などを用いて関数が任意のデータを返すよう強制する手法です。この方法はテスト実行時のNode.js環境でのみ動作し、ローカルのブラウザ開発では機能しません。さらに致命的なのは、HTTPヘッダー、クエリパラメータ、Cookie、ステータスコードの整合性などを一切検証できない点です。

モジュールをモックする場合、検証できているのは「関数がネットワークライブラリを呼び出したかどうか」に過ぎません。実際のネットワークレスポンスをアプリケーションがどう適切に処理するかという本質的な検証が完全に抜け落ちてしまいます。

一般的なモック手法の比較

標準的なアプローチを採用する前に、プロジェクトでは以下の馴染み深い3つの手法を試行しました。

1. コンポーネントへのダミーデータ直接ハードコード

// UIコードにテストデータを混在させる
const UserProfile = () => {
  // const { data } = useFetch('/api/user');
  const data = { id: 'usr-01', name: 'Nguyen Van A', role: 'admin' }; // コミット前に必ず削除すること!
  return <div>{data.name}</div>;
};

UIは即座に確認できますが、本番環境にダミーデータが流出するリスクが非常に高く、自動テストにも再利用できません。

2. JestやVitestによるaxiosのモック化

import axios from 'axios';
vi.mock('axios');

test('ユーザー情報を表示する', async () => {
  vi.mocked(axios.get).mockResolvedValue({
    data: { id: 'usr-01', name: 'Nguyen Van A' }
  });
  // テストロジック...
});

CI上のテストは通りますが、非常に壊れやすいのが難点です。axiosからネイティブのfetchにリプレイスした場合、UIの挙動が変わっていなくても大量のテストケースが失敗します。また、このモックデータはブラウザでの動作確認には使えません。

3. ExpressやJSON-Serverによる専用モックサーバーの構築

localhost:4000などでNode.jsサーバーを立ち上げ、サンプルJSONを返却させる方法です。本番環境に近い挙動を再現できますが、プロキシ設定、サブプロセスの管理、CI/CDパイプラインでのサーバー起動待機など、メンテナンスコストが大幅に増加します。

解決策:Mock Service Worker (MSW) によるネットワーク層でのリクエスト傍受

Mock Service Worker (MSW)は、これらの課題を根本から解決します。アプリケーションのJavaScriptコードを変更したり専用サーバーを立てたりすることなく、MSWはネットワーク層でリクエストを直接キャッチします。

ブラウザ環境では、標準のService Worker APIを利用してリクエストをインターセプトします。一方、テスト環境(Node.js)では、互換性のあるクラスインターセプト機構が機能します。Reactアプリケーション側は通常通りfetchやaxios経由でHTTPリクエストを送信するだけで、MSWがネットワークの境界線上でダミーデータを返却するため、バックエンドサーバーにアクセスする必要がありません。

35,000行以上のReactコードをリファクタリングしたプロジェクトでは、コンポーネントロジックに手を入れる前に、MSWを使ってネットワークエラー、401、500、タイムアウトなど15パターンのシナリオを網羅的に構築しました。その結果、リグレッションを一切発生させることなく安全に移行を完了できました。

ステップ1:プロジェクトにMSW 2.xをインストール

mswパッケージを開発依存(dev dependencies)としてインストールします。

npm install msw@latest --save-dev
# またはpnpmを使用する場合
pnpm add -D msw@latest

ブラウザ用のワーカーファイルを生成します(ViteまたはCreate React Appのpublic/ディレクトリに配置)。

npx msw init public/ --save

このコマンドによりmockServiceWorker.jsが生成され、ライブラリのアップデート時に自動同期されるようpackage.jsonに設定が保存されます。

ステップ2:TypeScriptでネットワークハンドラーを構築

モック対象のエンドポイントを一元管理するため、src/mocks/ディレクトリを作成します。

// src/mocks/handlers.ts
import { http, HttpResponse, delay } from 'msw';

interface UserProfileResponse {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';
}

export const handlers = [
  // ユーザープロフィールを取得するGETエンドポイント
  http.get('/api/user/profile', async () => {
    // 150msのネットワーク遅延をシミュレート
    await delay(150);

    return HttpResponse.json<UserProfileResponse>({
      id: 'usr-9821',
      name: 'Le Quoc Bao',
      email: '[email protected]',
      role: 'admin',
    }, { status: 200 });
  }),

  // 注文決済を処理するPOSTエンドポイント
  http.post('/api/checkout', async ({ request }) => {
    const payload = (await request.json()) as { amount: number };

    // 決済上限額超過のケースをシミュレート
    if (payload.amount > 50_000_000) {
      return HttpResponse.json(
        { error: '決済金額が上限の5,000万VNDを超えています' },
        { status: 400 }
      );
    }

    return HttpResponse.json({
      success: true,
      transactionId: 'txn-883921'
    }, { status: 201 });
  }),
];

ステップ3:ローカル開発時のブラウザでMSWを有効化

ChromeやFirefoxでリクエストを直接インターセプトできるよう、ブラウザ用ワーカーを初期化します。

// src/mocks/browser.ts
import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';

export const worker = setupWorker(...handlers);

開発環境での実行時にワーカーを起動するよう、src/main.tsxに設定を追加します。

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

async function prepareEnvironment() {
  // Viteの開発環境を判定(CRA/Webpackの場合はprocess.env.NODE_ENVを使用)
  if (import.meta.env.DEV) {
    const { worker } = await import('./mocks/browser');
    return worker.start({
      onUnhandledRequest: 'bypass',
    });
  }
}

prepareEnvironment().then(() => {
  ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
      <App />
    </React.StrictMode>
  );
});

DevToolsのコンソールを開くと、[MSW] Mocking enabled.というログが表示されます。Networkタブでは、ハンドラーにマッチしたリクエストにService Worker特有の歯車アイコンが表示され、ステータスコード200が返却されていることを確認できます。

ステップ4:テスト環境の設定(Vitest / Jest)

自動テストを実行するNode.js環境向けに、MSWはsetupServer関数を提供しています。

// src/mocks/server.ts
import { setupServer } from 'msw/node';
import { handlers } from './handlers';

export const server = setupServer(...handlers);

テスト設定ファイルsrc/setupTests.tsでサーバーのライフサイクルを定義します。

// src/setupTests.ts
import { beforeAll, afterEach, afterAll } from 'vitest';
import '@testing-library/jest-dom';
import { server } from './mocks/server';

// テストスイートの実行前にサーバーを起動
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));

// テスト間のデータ干渉を防ぐため、各テスト後に一時的なハンドラーをリセット
afterEach(() => server.resetHandlers());

// すべてのテスト完了後にサーバーを停止
afterAll(() => server.close());

ステップ5:バックエンド非依存のインテグレーションテスト作成

これにより、データ取得の成功パターンだけでなく、サーバーエラー時のシナリオも容易にテストできます。

// src/components/UserProfile.test.tsx
import { render, screen } from '@testing-library/react';
import { expect, test } from 'vitest';
import { http, HttpResponse } from 'msw';
import { server } from '../mocks/server';
import UserProfile from './UserProfile';

test('APIから取得したユーザー名を正しく表示する', async () => {
  render(<UserProfile />);
  
  // コンポーネントがデータをフェッチしてDOMに描画されるのを待機
  expect(await screen.findByText('Le Quoc Bao')).toBeInTheDocument();
});

test('サーバーが500エラーを返した際にエラーメッセージを表示する', async () => {
  // このテストケース専用にハンドラーをオーバーライド
  server.use(
    http.get('/api/user/profile', () => {
      return new HttpResponse(null, { status: 500 });
    })
  );

  render(<UserProfile />);
  
  expect(await screen.findByText(/ユーザーデータの読み込みに失敗しました/i)).toBeInTheDocument();
});

すべてのリクエストはテストプロセスのメモリ内で完結して処理されます。インターネット接続やステージングサーバーへの依存は一切ありません。

CI上でnpm run testを実行したところ、全42件のテストケースがわずか2.8秒で滞りなく完了しました。MSWを活用してネットワーク層を完全に分離することで、フロントエンド開発チームは開発スピードとコード品質の両面で完全な自律性を手に入れることができます。

Share: