api-test-suite-builder

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

各種フレームワーク（Next.js App Router、Express、FastAPI、Django REST、Go net/http）の API ルート定義をスキャンし、リクエスト／レスポンスのスキーマを分析して、認証、認可、入力検証、エラーハンドリング、ページネーション、ファイルアップロード、レート制限、コントラクトテスト、負荷テストを網羅する包括的なテストスイートを生成します。Vitest+Supertest（Node）、Pytest+httpx（Python）、または k6（負荷テスト）ですぐに実行できるテストファイルを出力します。

主な機能

• ルートの検出と分析 — ソースファイルをスキャンしてエンドポイントを抽出し、リクエスト／レスポンスのスキーマを解析して、Node、Python、Go の各フレームワークで認証ミドルウェアと認可ルールを検出します。
• テストマトリクスの生成 — 認証（有効／無効／期限切れのトークン、誤ったロール）、入力検証（必須項目の欠落／型の不一致／境界値／インジェクション）、エラー経路（400／401／403／404／409／422／429／500）、ページネーション、ファイルアップロード、レート制限を対象にします。
• コントラクトテスト — OpenAPI からのテスト生成、Pact のコンシューマー駆動型コントラクト、破壊的変更検出のためのスキーマスナップショットテストに対応します。
• 負荷テスト — ランプアップパターンと SLA のしきい値を備えた k6 スクリプト、レイテンシのパーセンタイル追跡（P50／P95／P99）、同時ユーザーのシミュレーションに対応します。

使用するタイミング

• API を新たに追加した場合 — 実装前にテストのひな形を生成します（TDD）。
• テストのないレガシー API がある場合 — スキャンしてベースラインとなるカバレッジを生成します。
• リリース前 — すべてのルートに少なくともスモークテストがあることを確認します。
• API コントラクトを変更する場合 — 破壊的変更を検出してテストします。
• セキュリティ監査 — 敵対的な入力のテストを生成します。
• パフォーマンス検証 — 負荷テストのベースラインを作成します。

最初に確認すること

スイートを生成する前に、次の入力を確認してください。不明または曖昧な項目があれば、推測せずに質問してください。

• 対象フレームワーク — Vitest+Supertest、Pytest+httpx、または k6（--framework を介して出力するテストファイル形式を決定します）
• 仕様またはルートのソース — OpenAPI 仕様、またはスキャン対象のソースファイル（ジェネレーターが解析する入力）
• テスト範囲 — 認証、入力検証、コントラクト、負荷、または全項目（生成するテストカテゴリ）

停止ルール：出力に最も影響する 2～3 項目だけを質問してください。ユーザーが「とりあえず下書きして」と言った場合は、そのまま進め、成果物の冒頭に前提を列挙してください。

ツール

ツール	用途	コマンド
test_generator.py	OpenAPI／Swagger 仕様から API テストのひな形を生成します	python scripts/test_generator.py spec.json --framework vitest --output tests/
coverage_analyzer.py	仕様のエンドポイントと既存のテストファイルを比較して、抜けを特定します	python scripts/coverage_analyzer.py spec.json tests/ --threshold 95
contract_validator.py	OpenAPI スキーマコントラクトに対してレスポンスのサンプルを検証します	python scripts/contract_validator.py spec.json samples/ --strict

参考資料

タスクに合った参考資料を読み込んでください。このファイルは簡潔に保ち、必要に応じて詳細を参照します。

• references/route-detection-and-matrices.md — フレームワークごとのルート検出用シェルコマンド、および実例となる TypeScript コードを含む、認証／入力検証／ページネーションの完全なテストマトリクスを記載しています。コードベースのスキャンや主要なテストケースの作成時に読みます。
• references/contract-and-load-testing.md — Pact のコンシューマー駆動型コントラクトテストと k6 の負荷テストスクリプト一式に加えて、ローカル、ステージング、クラウドで負荷テストを実行するコマンドを記載しています。コントラクトテストやパフォーマンステストの追加時に読みます。
• references/workflow-and-quality.md — 9 ステップの生成ワークフロー、再利用可能なテストヘルパーのパターン（認証、認証済みリクエスト、ファクトリー）、よくある落とし穴、ベストプラクティス、トラブルシューティング表、成功基準を記載しています。スイートの生成前と出荷前に読みます。

対象範囲と制限事項

このスキルの対象：

• Node.js、Python、Go の各フレームワークにおける REST API のルート定義からのテストスイート生成
• 認証、認可、入力検証、ページネーション、エラーパスのテスト生成
• Pact を使用したコンシューマー駆動型契約テストとスキーマスナップショット検証
• k6 と Artillery を使用した負荷テストおよびパフォーマンステスト用スクリプトの生成

このスキルの対象外：

• GraphQL API のテスト（スキーマレビューのパターンについては engineering/api-design-reviewer を参照）
• エンドツーエンドのブラウザーテストや UI インタラクションテスト（engineering/playwright-pro を参照）
• データベースのマイグレーションテストやスキーマ検証（engineering/database-schema-designer を参照）
• 入力のサニタイズチェックを超えるセキュリティ侵入テスト（engineering/skill-security-auditor を参照）

統合ポイント

スキル	統合	データフロー
engineering/api-design-reviewer	テストを生成する前に API 設計を検証します	設計レビューの出力によって、このスキルがテストを生成するエンドポイントの契約が定義されます
engineering/ci-cd-pipeline-builder	生成されたテストを CI/CD パイプラインに組み込みます	生成されたテストファイルと k6 スクリプトが、合格／不合格のゲートを備えたパイプラインのステージとして追加されます
engineering/playwright-pro	API テストを E2E ブラウザーテストで補完します	API テストスイートがバックエンドの動作を検証し、Playwright テストがそれらの API を利用するフロントエンドを検証します
engineering/database-schema-designer	テストフィクスチャをデータベーススキーマに合わせます	スキーマ定義に基づいて、生成されたテストヘルパーで使用するファクトリー関数とシードデータが作成されます
engineering/observability-designer	本番環境でテスト対象のエンドポイントを監視します	負荷テストのしきい値（P95、P99）が、本番環境のダッシュボードにある同じエンドポイントのアラートルールに反映されます
engineering/performance-profiler	負荷テストのしきい値を満たさないエンドポイントを調査します	k6 の結果で遅いエンドポイントを特定し、profiler スキルがコードレベルで根本原因を追跡します