api-test-suite-builder

API テストスイートビルダー

Tier: POWERFUL Category: エンジニアリング Domain: テスト / API 品質

---

概要

さまざまなフレームワーク（Next.js App Router、Express、FastAPI、Django REST）にわたって API ルート定義をスキャンし、認証、入力検証、エラーコード、ページネーション、ファイルアップロード、レート制限を網羅する包括的なテストスイートを自動生成します。Vitest+Supertest（Node）または Pytest+httpx（Python）用の、そのまま実行できるテストファイルを出力します。

---

主な機能

• ルート検出 — ソースファイルをスキャンして、すべての API エンドポイントを抽出します
• 認証カバレッジ — 有効／無効／期限切れのトークン、認証ヘッダーの欠落
• 入力検証 — 必須フィールドの欠落、型の不一致、境界値、インジェクションの試行
• エラーコードマトリクス — 各ルートの 400/401/403/404/422/500
• ページネーション — 最初／最後／空／過大なページ
• ファイルアップロード — 有効、サイズ超過、MIME タイプの誤り、空
• レート制限 — バーストの検出、ユーザーごとの制限とグローバル制限

---

使用する場面

• 新しい API の追加時 — 実装前にテストのひな形を生成します（TDD）
• テストのないレガシー API — スキャンしてベースラインのカバレッジを生成します
• API コントラクトのレビュー — 既存のテストが現在のルート定義と一致しているか確認します
• リリース前の回帰チェック — すべてのルートに少なくともスモークテストがあることを確認します
• セキュリティ監査の準備 — 悪意のある入力を使ったテストを生成します

---

ルート検出

Next.js App Router

# Find all route handlers
find ./app/api -name "route.ts" -o -name "route.js" | sort

# Extract HTTP methods from each route file
grep -rn "export async function\|export function" app/api/**/route.ts | \
  grep -oE "(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)" | sort -u

# Full route map
find ./app/api -name "route.ts" | while read f; do
  route=$(echo $f | sed 's|./app||' | sed 's|/route.ts||')
  methods=$(grep -oE "export (async )?function (GET|POST|PUT|PATCH|DELETE)" "$f" | \
    grep -oE "(GET|POST|PUT|PATCH|DELETE)")
  echo "$methods $route"
done

Express

# Find all router files
find ./src -name "*.ts" -o -name "*.js" | xargs grep -l "router\.\(get\|post\|put\|delete\|patch\)" 2>/dev/null

# Extract routes with line numbers
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" \
  src/ --include="*.ts" | grep -oE "(get|post|put|delete|patch)\(['\"][^'\"]*['\"]"

# Generate route map
grep -rn "router\.\|app\." src/ --include="*.ts" | \
  grep -oE "\.(get|post|put|delete|patch)\(['\"][^'\"]+['\"]" | \
  sed "s/\.\(.*\)('\(.*\)'/\U\1 \2/"

FastAPI

# Find all route decorators
grep -rn "@app\.\|@router\." . --include="*.py" | \
  grep -E "@(app|router)\.(get|post|put|delete|patch)"

# Extract with path and function name
grep -rn "@\(app\|router\)\.\(get\|post\|put\|delete\|patch\)" . --include="*.py" | \
  grep -oE "@(app|router)\.(get|post|put|delete|patch)\(['\"][^'\"]*['\"]"

Django REST Framework

# urlpatterns extraction
grep -rn "path\|re_path\|url(" . --include="*.py" | grep "urlpatterns" -A 50 | \
  grep -E "path\(['\"]" | grep -oE "['\"][^'\"]+['\"]" | head -40

# ViewSet router registration
grep -rn "router\.register\|DefaultRouter\|SimpleRouter" . --include="*.py"

---

テスト生成パターン

認証テストマトリクス

認証が必要なエンドポイントごとに、以下を生成します。

テストケース	期待されるステータス
Authorization ヘッダーなし	401
無効なトークン形式	401
有効なトークン、ユーザーロールが不適切	403
期限切れの JWT トークン	401
有効なトークン、適切なロール	2xx
削除済みユーザーのトークン	401

入力検証マトリクス

リクエストボディを持つ POST/PUT/PATCH エンドポイントごとに、以下を生成します。

テストケース	期待されるステータス
空のボディ {}	400 または 422
必須フィールドの欠落（1つずつ）	400 または 422
型の誤り（int が期待される箇所に string）	400 または 422
境界値：最小値-1 の値	400 または 422
境界値：最小値	2xx
境界値：最大値	2xx
境界値：最大値+1 の値	400 または 422
文字列フィールドへの SQL インジェクション	400 または 200（サニタイズ済み）
文字列フィールドへの XSS ペイロード	400 または 200（サニタイズ済み）
必須フィールドの null 値	400 または 422

---

テストファイルの例

→ 詳細は references/example-test-files.md を参照してください

ルートスキャンからのテスト生成

コードベースが提供されたら、次の手順に従います。

1. 上記の検出コマンドを使ってルートをスキャンします
2. 各ルートハンドラーを読み、以下を把握します。
   • 想定されるリクエストボディのスキーマ
   • 認証要件（ミドルウェア、デコレーター）
   • 戻り値の型とステータスコード
   • ビジネスルール（所有権、ロールチェック）
3. 上記のパターンを使い、ルートグループごとにテストファイルを生成します
4. テストには内容がわかる名前を付けます。"returns 401 when token is expired" のようにし、"auth test 3" のような名前は避けます
5. テストデータにはファクトリー／フィクスチャを使い、ID をハードコードしないでください
6. ステータスコードだけでなく、レスポンスの形状も検証します

---

よくある落とし穴

• 正常系のテストだけを行う — バグの 80% はエラー経路に潜んでいます。まずはエラー経路をテストしてください
• テストデータの ID をハードコードする — ファクトリー／フィクスチャを使ってください。ID は環境によって変わります
• テスト間で状態を共有する — afterEach/afterAll で必ずクリーンアップしてください
• 振る舞いではなく実装をテストする — API の処理方法ではなく、API が返す内容をテストしてください
• 境界値テストの不足 — ページネーションや制限では、1つずれるエラーが非常によく発生します
• トークンの有効期限をテストしない — 期限切れのトークンは無効なトークンとは異なる動作をします
• Content-Type を無視する — API が誤ったコンテンツタイプ（json が期待される場面での xml）を拒否することをテストしてください

---

ベストプラクティス

1. エンドポイントごとに describe ブロックを1つ用意します。失敗を切り分けやすく、読みやすくなります
2. 最小限のデータを用意します。データベース全体を読み込まず、テストに必要なものだけを作成します
3. 共通のセットアップには beforeAll、クリーンアップには afterAll を使います。コストの高い処理に beforeEach は使いません
4. ステータスコードだけでなく、具体的なエラーメッセージやフィールドを検証します
5. 機密フィールド（パスワード、シークレット）がレスポンスに含まれないことをテストします
6. 認証テストでは、「ヘッダーなし」のケースと「無効なトークン」のケースを必ず分けてテストします
7. レート制限のテストは最後に追加します。並列実行すると、ほかのテストスイートに干渉することがあります