api-testing

API テスト

概要

API テストでは、リクエストを送信してレスポンスを検証し、HTTP エンドポイントのステータスコード、ヘッダー、本文の内容、エラー処理を確認します。Supertest は、実際のサーバーを起動せずに Express、Fastify、Hono アプリを対象とした統合テストを実行できる、流暢なチェーン可能 API を提供します。MSW（Mock Service Worker）v2 は、ネットワークレベルで送信 HTTP リクエストをインターセプトし、Node.js のテストとブラウザー環境の両方で外部サービスを現実的にモックできます。

使用する場面： REST API の統合テスト、ミドルウェアパイプラインのテスト、リクエスト／レスポンスの契約の検証、テストでのサードパーティ API のモック、エラー処理やエッジケースのテスト。

使用しない場面： 純粋関数の単体テスト（直接アサーションを使用）、E2E ブラウザーテスト（Playwright/Cypress を使用）、負荷／パフォーマンステスト（k6/Artillery を使用）、静的ファイル配信のテスト。

クイックリファレンス

パターン	API	主なポイント
GET リクエスト	request(app).get('/path')	supertest の Test オブジェクトを返します
本文付き POST	request(app).post('/path').send(body)	Content-Type を自動的に設定します
認証ヘッダー	.set('Authorization', 'Bearer token')	.expect() の前にチェーンします
ステータスのアサーション	.expect(200)	本文のアサーションとチェーンできます
本文のアサーション	.expect({ key: 'value' })	深い等価性をチェックします
ヘッダーのアサーション	.expect('Content-Type', /json/)	文字列または正規表現を受け付けます
MSW HTTP ハンドラー	http.get('/api/users', resolver)	一致するリクエストをインターセプトします
MSW GraphQL ハンドラー	graphql.query('GetUser', resolver)	オペレーション名でインターセプトします
MSW レスポンス	HttpResponse.json(data, { status })	v2 のレスポンス形式
MSW エラーのシミュレーション	HttpResponse.error()	ネットワーク障害をシミュレートします
MSW の一度限りのハンドラー	http.get(path, resolver, { once: true })	最初の一致後に自動的に削除されます
テストごとの MSW 上書き	server.use(handler)	特定のテストでデフォルトのハンドラーを上書きします
スキーマ検証	schema.parse(response.body)	Zod でレスポンスの構造を検証します
Cookie の保持	const agent = request.agent(app)	リクエスト間で Cookie を保持します
Fastify の inject	app.inject({ method, url })	supertest を使わない組み込みのテスト機能
Hono テストクライアント	testClient(app)	型安全なリクエストビルダー

よくある間違い

間違い	正しいパターン
supertest のリクエストを await しない	常に await request(app).get('/path') を使用する
テスト間でサーバーの状態を共有する	afterEach で server.resetHandlers() を呼び出してハンドラーをリセットする
fetch／axios を直接モックする	MSW を使ってネットワークレベルでインターセプトする
セットアップで server.listen() を忘れる	beforeAll で呼び出し、afterEach で resetHandlers を呼び出す
Fastify インスタンスを supertest に渡す	fastify.server（基盤となる Node サーバー）を使用する
レスポンスの完了前にアサーションする	await を使うか、supertest のチェーンを返す
多くのテストでテストデータをハードコードする	テストデータにはファクトリーまたはフィクスチャを使う
エラーレスポンスをテストしない	成功パスと併せて 4xx および 5xx のパスもテストする
afterEach で server.close() を使う	close には afterAll を使い、afterEach ではリセットのみ行う
アサーションでレスポンスヘッダーを無視する	Content-Type、Cache-Control、CORS ヘッダーを検証する
onUnhandledRequest: 'error' を使わない	未処理のリクエストを検出し、テストの抜け漏れを防ぐ
動作ではなく実装をテストする	内部関数の呼び出しではなく、レスポンスの形式を検証する

委任

• テスト構成のレビュー：Task エージェントを使用します
• コードレビュー：code-reviewer エージェントに委任します
• パターンの調査：Explore エージェントを使用します

vitest-testing スキルが利用可能な場合は、Vitest の一般的な設定とパターンを委任します。 それ以外の場合は、次を推奨します：npx skills add oakoss/agent-skills --skill vitest-testing

参考資料

• Express、Fastify、Hono 向け Supertest 統合テストのパターン
• MSW のリクエストハンドラー、レスポンスリゾルバー、サーバーのセットアップ
• テストの整理、フィクスチャ、ファクトリー、セットアップ／ティアダウン
• レスポンスのアサーション、ステータスコード、ヘッダー、スキーマ検証