MSWの使い方｜v3対応のハンドラ一覧とVitest・ブラウザ設定

MSW（Mock Service Worker）は、アプリが送る HTTP リクエストを途中で受け取り、決めたレスポンスを返すライブラリです。 ブラウザでは Service Worker（ページとネットワークの間に入るスクリプト）で、Node（テスト）ではリクエストの横取りで動きます。アプリのコードを書き換えずに、同じハンドラをテストと開発中の画面の両方で使えます。

2026年9月28日に MSW 3.0.0 が出ました。 v2 の書き方の多くはそのまま使えますが、GraphQL と一部のオプション名が変わっています。

import { http, HttpResponse } from 'msw/http'

export const handlers = [
  http.get('https://api.example.com/users/:id', ({ params }) => {
    return HttpResponse.json({ id: Number(params.id), name: 'Taro' })
  }),
]

確認環境：msw 3.0.3・Vitest 5.0.4・Vite 8.3.4・graphql 17.0.2・Node.js 22.22.2（Linux）。Node の setupServer と Vitest のテスト、ブラウザの setupWorker と Vite プラグインは、Vite の開発サーバーを Chromium（playwright-core 1.64.0）で開いて動かしました。v2 からの変更点は公式の移行ガイドで確かめた内容です（確認日 2026年10月13日）。

インストールと版の条件

npm install msw --save-dev

npm の msw 3.0.3 の package.json に書かれた条件です。

Node.js 20 以前では入りません。 v2 の版を続けて使うなら npm install msw@2 で、v2 の最終は 2.15.0（2026年7月8日公開）でした。

ハンドラの書き方：http の一覧

http.メソッド(URL, リゾルバー, オプション) で1つのハンドラを作ります。 リゾルバーは「リクエストを受けてレスポンスを返す関数」です。

3.0.3 の http のキーを出力すると、all, head, get, post, put, delete, patch, options の8つでした。

リゾルバーが受け取るもの

クエリ文字列は params ではなく、new URL(request.url).searchParams から読みます。

レスポンスの作り方：HttpResponse の一覧

動かしたハンドラ一式（コピペ用）

// src/mocks/handlers.js
import { http, HttpResponse } from 'msw/http'
import { graphql } from 'msw/graphql'
import { delay } from 'msw/utils/delay'

const users = [
  { id: 1, name: 'Taro' },
  { id: 2, name: 'Hanako' },
]

const api = graphql.link('https://api.example.com/graphql')

export const handlers = [
  // 一覧（クエリ文字列は url から読む）
  http.get('https://api.example.com/users', ({ request }) => {
    const url = new URL(request.url)
    const q = url.searchParams.get('q') ?? ''
    return HttpResponse.json(users.filter((u) => u.name.includes(q)))
  }),

  // パスパラメータ
  http.get('https://api.example.com/users/:id', ({ params }) => {
    const user = users.find((u) => u.id === Number(params.id))
    if (!user) {
      return HttpResponse.json({ message: 'Not Found' }, { status: 404 })
    }
    return HttpResponse.json(user)
  }),

  // 本文を読む
  http.post('https://api.example.com/users', async ({ request }) => {
    const body = await request.json()
    return HttpResponse.json({ id: 3, ...body }, { status: 201 })
  }),

  // 遅延
  http.get('https://api.example.com/slow', async () => {
    await delay(500)
    return HttpResponse.text('late')
  }),

  // ネットワークエラー
  http.get('https://api.example.com/down', () => HttpResponse.error()),

  // GraphQL
  api.query('GetUser', ({ variables }) => {
    return HttpResponse.json({
      data: { user: { id: variables.id, name: 'Taro' } },
    })
  }),
]

// src/mocks/node.js
import { setupServer } from 'msw/node'
import { handlers } from './handlers.js'

export const server = setupServer(...handlers)

server.listen() のあとに Node の fetch で各 URL を呼んだ結果です。

GraphQL は graphql.link から作る（v3 の変更）

v3 では graphql.query() が無くなり、エンドポイントごとに graphql.link() を作ってから query・mutation を定義します。

import { graphql } from 'msw/graphql'
import { HttpResponse } from 'msw/http'

const api = graphql.link('https://api.example.com/graphql')

export const handlers = [
  api.query('GetUser', ({ variables }) =>
    HttpResponse.json({ data: { user: { id: variables.id, name: 'Taro' } } }),
  ),
  api.mutation('CreateUser', ({ variables }) =>
    HttpResponse.json({ data: { createUser: { id: '3', ...variables.input } } }),
  ),
]

3.0.3 で graphql のキーは link だけで、v2 の書き方 graphql.query(...) を呼ぶと graphql.query is not a function でした。link() の戻り値には operation・query・mutation・subscription がありました。

Vitest で使う：setupServer の設定

beforeAll で起動、afterEach でテスト中に足したハンドラを戻し、afterAll で止めます。

// vitest.setup.js
import { beforeAll, afterEach, afterAll } from 'vitest'
import { server } from './src/mocks/node.js'

beforeAll(() => server.listen({ onUnhandledFrame: 'error' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

// vitest.config.js
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    setupFiles: ['./vitest.setup.js'],
  },
})

テストするコード（API を呼ぶ関数）です。

// src/userApi.js
const BASE = 'https://api.example.com'

export async function fetchUser(id) {
  const res = await fetch(`${BASE}/users/${id}`)
  if (!res.ok) throw new Error(`HTTP ${res.status}`)
  return res.json()
}

export async function createUser(name) {
  const res = await fetch(`${BASE}/users`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name }),
  })
  return res.json()
}

テストの中だけ応答を変えるときは server.use() を使います。 afterEach の resetHandlers() で元に戻ります。

// src/userApi.test.js
import { describe, it, expect } from 'vitest'
import { http, HttpResponse } from 'msw/http'
import { server } from './mocks/node.js'
import { fetchUser, createUser } from './userApi.js'

describe('userApi', () => {
  it('ユーザーを取得できる', async () => {
    await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: 'Taro' })
  })

  it('404 のときは例外', async () => {
    await expect(fetchUser(9)).rejects.toThrow('HTTP 404')
  })

  it('このテストだけ 500 を返す（server.use）', async () => {
    server.use(
      http.get('https://api.example.com/users/:id', () =>
        new HttpResponse(null, { status: 500 }),
      ),
    )
    await expect(fetchUser(1)).rejects.toThrow('HTTP 500')
  })

  it('resetHandlers で元に戻っている', async () => {
    await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: 'Taro' })
  })

  it('送った本文を確かめる', async () => {
    let sent
    server.use(
      http.post('https://api.example.com/users', async ({ request }) => {
        sent = await request.clone().json()
        return HttpResponse.json({ id: 10, ...sent }, { status: 201 })
      }),
    )
    await createUser('Jiro')
    expect(sent).toEqual({ name: 'Jiro' })
  })

  it('once: 1回目だけ 503', async () => {
    server.use(
      http.get('https://api.example.com/users/:id', () =>
        new HttpResponse(null, { status: 503 }), { once: true }),
    )
    await expect(fetchUser(1)).rejects.toThrow('HTTP 503')
    await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: 'Taro' })
  })

  it('ネットワークエラー', async () => {
    server.use(http.get('https://api.example.com/users/:id', () => HttpResponse.error()))
    await expect(fetchUser(1)).rejects.toThrow('fetch failed')
  })
})

$ npx vitest run --reporter=verbose
 ✓ src/userApi.test.js > userApi > ユーザーを取得できる 51ms
 ✓ src/userApi.test.js > userApi > 404 のときは例外 11ms
 ✓ src/userApi.test.js > userApi > このテストだけ 500 を返す（server.use） 14ms
 ✓ src/userApi.test.js > userApi > resetHandlers で元に戻っている 14ms
 ✓ src/userApi.test.js > userApi > 送った本文を確かめる 23ms
 ✓ src/userApi.test.js > userApi > once: 1回目だけ 503 14ms
 ✓ src/userApi.test.js > userApi > ネットワークエラー 7ms

{ once: true } は、1回使ったらそのハンドラを使い終わりにするオプションです。リトライ処理のテストに使えます。vi.fn() で関数を置き換える方法との使い分けは、関連記事「Vitestモックの使い方｜vi.mock・vi.fn・vi.spyOnの使い分け表」で扱っています。

server の主なメソッド

3.0.3 の setupServer() の戻り値にあったものです。

ハンドラの無いリクエスト：onUnhandledFrame

v3 では onUnhandledRequest が onUnhandledFrame に名前が変わりました。 WebSocket なども含めた「対応するハンドラが無かった通信」の扱いを決めます。

既定（警告）のときの出力です。

[MSW] Warning: intercepted a request without a matching request handler:

  • GET https://api.example.com/b

If you still wish to intercept this unhandled request, please create a request handler for it.
Read more: https://mswjs.io/docs/http/intercepting-requests

'error' にした Vitest のテストでは、[MSW] Error: intercepted a request without a matching request handler のあとに、テストが次の内容で失敗しました。

TypeError: fetch failed
Caused by: InternalError: [MSW] Cannot bypass a request when using the "error" strategy for the "onUnhandledFrame" option.

テストでは 'error' にしておくと、ハンドラの書き忘れに気づけます。

v2 の onUnhandledRequest: 'error' を 3.0.3 に渡すと、エラーにならず、既定と同じ「警告して本物へ送る」動きでした。 名前を変え忘れても例外は出ないため、移行のときに見落としやすい点です。

一部だけ本物に送る：passthrough と bypass

import { http, HttpResponse } from 'msw/http'
import { passthrough } from 'msw/utils/passthrough'
import { bypass } from 'msw/utils/bypass'

export const handlers = [
  http.get('http://localhost:18168/health', () => passthrough()),

  // 本物の応答の一部だけを書き換える
  http.get('http://localhost:18168/users/1', async ({ request }) => {
    const original = await fetch(bypass(request)).then((r) => r.json())
    return HttpResponse.json({ ...original, name: 'Taro(mock)' })
  }),
]

手元に立てた本物のサーバー（パスを返すだけ）に対して動かした結果です。

{ from: 'real', path: '/health' }
{ from: 'real', path: '/users/1', name: 'Taro(mock)' }

ブラウザで使う①：msw init と setupWorker

ブラウザでは、Service Worker のスクリプト mockServiceWorker.js を、サイトの公開フォルダに置きます。

npx msw init public --save

--save を付けると、package.json に次の設定が入りました。msw を更新したときに、このフォルダのスクリプトも更新されます。

"msw": {
  "workerDirectory": ["public"]
}

置かれた mockServiceWorker.js は 12,754 バイトで、先頭に const PACKAGE_VERSION = '3.0.3' がありました。--save は、そのフォルダに package.json があるプロジェクトの直下で実行します（package.json が無いと ENOENT で止まりました）。

// src/mocks/browser.js
import { setupWorker } from 'msw/browser'
import { handlers } from './browser-handlers.js'

export const worker = setupWorker(...handlers)

// src/mocks/browser-handlers.js（ブラウザでは相対パスで書ける）
import { http, HttpResponse } from 'msw/http'

export const handlers = [
  http.get('/api/users/:id', ({ params }) => {
    return HttpResponse.json({ id: Number(params.id), name: 'Taro' })
  }),
]

worker.start() の完了を待ってから、アプリの通信を始めます。 待たないと、最初のリクエストが MSW を通らずに本物へ出ることがあります。

// src/main.js
async function enableMocking() {
  if (!import.meta.env.DEV) return
  const { worker } = await import('./mocks/browser.js')
  await worker.start({ onUnhandledFrame: 'bypass' })
}

enableMocking().then(async () => {
  const res = await fetch('/api/users/1')
  document.querySelector('#app').textContent = `${res.status} ${await res.text()}`
})

Vite の開発サーバーを Chromium で開くと、画面に 200 {"id":1,"name":"Taro"} が出て、コンソールに次のログが出ました（抜粋）。

[MSW] Mocking enabled.
Worker script URL: http://localhost:18167/mockServiceWorker.js
Worker scope: http://localhost:18167/
[MSW] 15:55:41 GET /api/users/1 (200 OK)

import.meta.env.DEV で囲むと、本番ビルドには MSW が入りません。

ブラウザで使う②：Vite プラグイン（v3 の新機能）

v3 の msw/vite プラグインを使うと、mockServiceWorker.js を public に置かなくても、開発サーバーがスクリプトを配ります。

// vite.config.js
import { defineConfig } from 'vite'
import { msw } from 'msw/vite'

export default defineConfig({
  plugins: [msw()],
})

// src/main.js
async function enableMocking() {
  if (!import.meta.env.DEV) return
  const { network } = await import('virtual:msw')
  const { handlers } = await import('./mocks/handlers.js')
  network.configure({ handlers })
  await network.enable()
}

enableMocking().then(async () => {
  const res = await fetch('/api/users/7')
  document.querySelector('#app').textContent = `${res.status} ${await res.text()}`
})

public フォルダの無いプロジェクトで開発サーバーを起動すると、/mockServiceWorker.js が 200・application/javascript で返り、画面に 200 {"id":7,"name":"Taro"} が出ました。

v2・v1 からの書き換え早見表

3.0.3 では、import { http, HttpResponse, delay } from 'msw' のようにルートから読み込む書き方も動きました。移行ガイドではサブパス（msw/http など）が案内されています。graphql だけはルートから読み込めませんでした。

よくあるエラーと原因

最後の Service Worker の登録エラーは、mockServiceWorker.js を消して開いたときに出たメッセージです。Vite の開発サーバーは、無いファイルにも index.html を返すため、MIME type のエラーになりました。

よくある質問

Q. Jest でも使えますか。 A. 使えます。v2 の移行ガイドには、jest-environment-jsdom で Request・Response・TextEncoder が「is not defined」になる問題と、jest-fixed-jsdom を使う解決策が書かれています。

Q. 本番のビルドに入りませんか。 A. import.meta.env.DEV の条件の中で動的に import() すると、本番では読み込まれません。public/mockServiceWorker.js はファイルとして残るので、気になる場合は本番の配信から外します。

Q. Angular の HttpClient のテストでも使えますか。 A. MSW は fetch や XMLHttpRequest の層で横取りします。Angular の標準のやり方は関連記事「Angular HTTPテスト｜HttpTestingControllerの使い方」で扱っています。

Q. E2E テストと組み合わせられますか。 A. ブラウザで worker.start() した画面を Playwright で開けば、MSW の応答で E2E テストを流せます。この記事のブラウザの確認も、その形で行いました。Playwright は関連記事「Playwright入門｜E2Eテストの書き方とCI実行まで実行結果つきで解説」で扱っています。

まとめ

• MSW は HTTP リクエストを横取りして決めた応答を返す。ハンドラはテストとブラウザで共通
• ハンドラは http.get(url, ({ request, params }) => HttpResponse.json(...))
• 3.0.0（2026年9月28日）で Node.js 22.12 以上。GraphQL は graphql.link()、オプションは onUnhandledFrame
• Vitest は listen・resetHandlers・close の3行。テスト中の上書きは server.use()
• ブラウザは npx msw init public --save か Vite プラグイン msw/vite

参考・出典

確認日はいずれも 2026年10月13日です。

• MSW ドキュメント「Quick start」：https://mswjs.io/docs/quick-start
• MSW ドキュメント「http」：https://mswjs.io/docs/api/http
• MSW ドキュメント「HttpResponse」：https://mswjs.io/docs/api/http-response
• MSW ドキュメント「setupServer」：https://mswjs.io/docs/api/setup-server
• MSW ドキュメント「Migrating from 2.x to 3.x」：https://mswjs.io/docs/migrations/2.x-to-3.x
• MSW ドキュメント「Migrating from 1.x to 2.x」：https://mswjs.io/docs/migrations/1.x-to-2.x
• npm「msw」：https://www.npmjs.com/package/msw

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。