api-tests

/configure:api-tests

API 契約、スキーマ、コンシューマーとプロバイダー間の合意を検証するための API 契約テスト基盤を確認し、設定します。

このスキルを使用する場合

次の場合にこのスキルを使用してください…	次の場合は別の方法を使用してください…
API 契約テストをセットアップする場合（Pact、OpenAPI、スキーマ）	既存の API テストを実行する場合（bun test またはテストランナーを直接使用）
OpenAPI 仕様への準拠を検証する場合	OpenAPI 仕様の内容を編集する場合（エディターを直接使用）
CI に破壊的変更の検出を追加する場合	一般的な CI ワークフローをセットアップする場合（/configure:workflows を使用）
API テスト基盤の状態を確認する場合	単体テストまたは統合テストをセットアップする場合（/configure:tests または /configure:integration-tests を使用）
Pact のコンシューマー／プロバイダーワークフローを設定する場合	特定の API エンドポイントの失敗をデバッグする場合（詳細出力を有効にしてテストランナーを使用）

コンテキスト

• ロックファイル：!find . -maxdepth 1 \( -name 'bun.lockb' -o -name 'bun.lock' -o -name 'package-lock.json' -o -name 'yarn.lock' \)
• プロジェクトファイル：!find . -maxdepth 1 \( -name 'tsconfig.json' -o -name 'pyproject.toml' -o -name 'package.json' \)
• Pact のインストール状況：!find . -maxdepth 1 \( -name package.json -o -name 'requirements*.txt' -o -name pyproject.toml \) -exec grep -l "pact-foundation/pact\|pact-python" {} +
• OpenAPI 仕様：!find . -maxdepth 2 \( -name 'openapi.yaml' -o -name 'openapi.yml' -o -name 'openapi.json' -o -name 'swagger.json' -o -name 'swagger.yaml' \)
• スキーマバリデーター：!find . -maxdepth 1 -name 'package.json' -exec grep -l '"ajv"\|"zod"' {} +
• OpenAPI 検証ライブラリ：!find . -maxdepth 1 -name 'package.json' -exec grep -l "swagger-parser\|@apidevtools" {} +
• Pact 契約ディレクトリ：!find . -maxdepth 1 -type d -name \'pacts\'
• 契約テスト：!find . -maxdepth 3 -type d -name 'contract'
• API テストファイル：!find . -maxdepth 4 \( -name '*.pact.*' -o -name '*.openapi.*' -o -name '*.contract.*' \)
• CI ワークフロー：!find . -path '*/.github/workflows/*' -maxdepth 3 \( -name '*api*' -o -name '*contract*' -o -name '*pact*' \)

パラメーター

$ARGUMENTS を解析し、次のフラグを確認します。

フラグ	説明	デフォルト
--check-only	変更を加えずに状態を報告します	オフ
--fix	確認を求めずにすべての修正を自動適用します	オフ
--type <type>	特定の種類に絞ります：pact、openapi、または schema	すべての種類

API テストの種類：

種類	用途
Pact	マイクロサービス、複数のコンシューマー、破壊的変更の検出
OpenAPI	API ファースト開発、ドキュメント主導のテスト
スキーマ	シンプルな検証、GraphQL API、単一サービス

実行

この API テストの準拠状況チェックを実行します。

ステップ 1：プロジェクト基盤を検出する

既存の API テストを示す項目がないか、プロジェクトをスキャンします。

検出項目	コンポーネント	確認対象
依存関係に pact がある	Pact 契約テスト	package.json または pyproject.toml
openapi.yaml または swagger.json	OpenAPI 仕様	ルートディレクトリまたは docs/ ディレクトリ
@apidevtools/swagger-parser	OpenAPI 検証	package.json の devDependencies
依存関係に ajv または zod がある	スキーマ検証	package.json の依存関係
pacts/ ディレクトリ	Pact 契約	プロジェクトルート

--type が指定されている場合は、該当するコンポーネントのみを確認します。

ステップ 2：現在の状態を分析する

各 API テストコンポーネントの完全性を確認します。

コントラクトテスト（Pact）：

1. @pact-foundation/pact（JS/TS）または pact-python（Python）がインストールされているか確認します
2. tests/contract/consumer/ にコンシューマーテストがあるか確認します
3. tests/contract/provider/ にプロバイダー検証があるか確認します
4. CI ファイルに Pact Broker の設定があるか確認します
5. can-i-deploy の CI ゲートがあるか確認します

OpenAPI 検証：

1. OpenAPI 仕様ファイルが存在し、有効か確認します
2. リクエスト検証ミドルウェアがあるか確認します
3. テストにレスポンス検証があるか確認します
4. 破壊的変更の検出（oasdiff）があるか確認します

スキーマテスト：

1. JSON Schema または Zod の定義があるか確認します
2. バリデーター（ajv または zod）がインストールされているか確認します
3. レスポンス検証用のテストヘルパーがあるか確認します

ステップ 3：コンプライアンスレポートを生成する

書式付きのコンプライアンスレポートを出力します。

API Testing Compliance Report
==============================
Project: [name]
API Type: [REST | GraphQL | gRPC]

Contract Testing (Pact):
  Package:                   [INSTALLED | MISSING]
  Consumer tests:            [FOUND | NONE]
  Provider tests:            [FOUND | NONE]
  Pact Broker:               [CONFIGURED | OPTIONAL]

OpenAPI Validation:
  OpenAPI spec:              [EXISTS | MISSING]
  Spec version:              [CURRENT | OUTDATED]
  Request validation:        [CONFIGURED | MISSING]
  Response validation:       [CONFIGURED | MISSING]
  Breaking change CI:        [CONFIGURED | OPTIONAL]

Schema Testing:
  JSON Schemas:              [EXISTS | N/A]
  Schema validator:          [INSTALLED | MISSING]
  Response validation:       [CONFIGURED | MISSING]

Overall: [X issues found]
Recommendations: [list specific actions]

--check-only が設定されている場合は、ここで終了します。

ステップ 4：設定を適用する

--fix が設定されている場合、またはユーザーが確認した場合は、不足しているコンポーネントを修正します。Context で検出したプロジェクトの言語に基づいて、TypeScript または Python のテンプレートを選択します。

不足しているコンポーネントごとに、REFERENCE.md のテンプレートを使用して適切なファイルを作成します。

1. Pact コントラクトテスト：依存関係をインストールし、コンシューマーテストのテンプレートとプロバイダー検証のテンプレートを作成します
2. OpenAPI 検証：検証ライブラリをインストールし、OpenAPI バリデーターヘルパーとコンプライアンステストを作成します
3. スキーマテスト（Zod）：Zod をインストールし、スキーマ定義とスキーマ検証テストを作成します
4. OpenAPI の破壊的変更の検出：oasdiff をインストールし、CI ステップを追加します

ステップ 5：CI/CD 統合を設定する

次のジョブを含む .github/workflows/api-tests.yml を作成または更新します。

1. コンシューマーコントラクトテスト
2. プロバイダー検証（必要に応じてデータベースサービスを使用）
3. OpenAPI 仕様の検証と破壊的変更の検出
4. Pact アーティファクトの公開（main ブランチのみ）

package.json にテストスクリプトを追加します。REFERENCE.md の CI ワークフローテンプレートを使用します。

ステップ 6：標準の追跡情報を更新する

.project-standards.yaml を API テストの設定で更新します。

components:
  api_tests: "2025.1"
  api_tests_contract: "[pact|none]"
  api_tests_openapi: true
  api_tests_schema: "[zod|ajv|none]"
  api_tests_breaking_change_ci: true

ステップ 7：最終レポートを生成する

適用した変更の概要を、次の項目を含めて出力します。

• 作成した設定ファイル
• インストールした依存関係
• 利用可能なテストコマンド（正確な bun run / npm run コマンドを含む）
• 設定した CI/CD ジョブ
• 検証のために推奨される次のステップ

エージェント向け最適化

コンテキスト	コマンド
簡易ステータス確認	/configure:api-tests --check-only
すべての問題を自動修正	/configure:api-tests --fix
Pact のみを設定	/configure:api-tests --fix --type pact
OpenAPI のみを設定	/configure:api-tests --fix --type openapi
OpenAPI 仕様を確認	find . -maxdepth 2 \( -name 'openapi.yaml' -o -name 'swagger.json' \) 2>/dev/null
Pact のインストールを確認	grep -l "pact-foundation" package.json 2>/dev/null

例

# Check compliance and offer fixes
/configure:api-tests

# Check only, no modifications
/configure:api-tests --check-only

# Auto-fix all issues
/configure:api-tests --fix

# Configure Pact only
/configure:api-tests --fix --type pact

# Configure OpenAPI validation only
/configure:api-tests --fix --type openapi

エラー処理

エラー	解決方法
OpenAPI 仕様が見つからない	テンプレートの作成を提案します
Pact のバージョンが一致しない	アップグレード方法を提案します
スキーマ検証に失敗する	具体的なエラーを報告します
Pact Broker が設定されていない	設定手順を提示します

関連項目

• /configure:tests - 単体テストの設定
• /configure:integration-tests - 統合テスト
• /configure:all - すべてのコンプライアンスチェックを実行
• Pact のドキュメント
• OpenAPI 仕様
• Zod のドキュメント