configure-api-tests

/configure:api-tests

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

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

このスキルを使用する場面...	別の方法を使用する場面...
Pact コンシューマー／プロバイダーコントラクトテストを設定するとき	個々のユニットテストを作成するとき（/configure:tests）
OpenAPI リクエスト／レスポンス検証を設定するとき	単一の API エンドポイントを手動で検証するとき
JSON Schema または Zod スキーマテストを追加するとき	一般的なテストカバレッジを確認するとき（/configure:coverage）
CI で破壊的な API 変更を検出するとき	API 設計の判断をレビューするとき（code-review agent）
プロジェクト全体の API テスト準拠状況を監査するとき	一般的な CI/CD ワークフローを設定するとき（/configure:workflows）

コンテキスト

• プロジェクトルート：!pwd
• パッケージファイル：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' \)
• Pact 依存関係：!find . -maxdepth 1 \( -name package.json -o -name pyproject.toml \) -exec grep -l 'pact' {} +
• OpenAPI 仕様：!find . -maxdepth 1 \( -name 'openapi.yaml' -o -name 'openapi.json' -o -name 'swagger.json' \)
• Pact ディレクトリ：!find . -maxdepth 1 -type d -name 'pacts'
• コントラクトテスト：!find tests -maxdepth 2 -type d -name 'contract'
• プロジェクト標準：!find . -maxdepth 1 -name '.project-standards.yaml'

パラメーター

コマンド引数から解析します：

• --check-only：変更を加えずに準拠状況を報告します（CI/CD モード）
• --fix：確認を求めずに修正を自動適用します
• --type <pact|openapi|schema>：特定の種類に絞り込みます

API テストの種類：

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

実行

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

ステップ 1：既存の API テスト基盤を検出する

次の指標を確認します：

指標	コンポーネント	状態
依存関係に pact がある	Pact コントラクトテスト	インストール済み
openapi.yaml または swagger.json	OpenAPI 仕様	存在
@apidevtools/swagger-parser	OpenAPI 検証	設定済み
依存関係に ajv がある	JSON Schema 検証	設定済み
pacts/ ディレクトリ	Pact コントラクト	存在

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

検出した各コンポーネントについて、完全性を確認します：

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

• @pact-foundation/pact（JS）または pact-python（Python）がインストールされている
• コンシューマーテストが定義されている
• プロバイダー検証が設定されている
• Pact Broker または PactFlow が設定されている（任意）
• CI/CD パイプラインと統合されている

OpenAPI 検証：

• OpenAPI 仕様ファイルが存在する
• リクエスト検証ミドルウェアが設定されている
• テストでレスポンス検証を行っている
• スキーマの自動生成が設定されている
• 破壊的変更を検出できる

スキーマテスト：

• JSON Schema 定義が存在する
• ajv または同等のバリデーターがインストールされている
• レスポンス検証ヘルパーがある
• スキーマのバージョン管理方針がある

ステップ 3：準拠レポートを生成する

書式付きの準拠レポートを出力します：

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

Contract Testing (Pact):
  @pact-foundation/pact    package.json               [INSTALLED | MISSING]
  Consumer tests           tests/contract/consumer/   [FOUND | NONE]
  Provider tests           tests/contract/provider/   [FOUND | NONE]
  Pact Broker              CI configuration           [CONFIGURED | OPTIONAL]
  can-i-deploy             CI gate                    [CONFIGURED | OPTIONAL]

OpenAPI Validation:
  OpenAPI spec             openapi.yaml               [EXISTS | MISSING]
  Spec version             OpenAPI 3.1                [CURRENT | OUTDATED]
  Request validation       middleware                 [CONFIGURED | MISSING]
  Response validation      test helpers               [CONFIGURED | MISSING]
  Breaking change CI       oasdiff                    [CONFIGURED | OPTIONAL]

Schema Testing:
  JSON Schemas             schemas/                   [EXISTS | N/A]
  Schema validator         ajv/zod                    [INSTALLED | MISSING]
  Response validation      test helpers               [CONFIGURED | MISSING]

Overall: [X issues found]

Recommendations:
  - Add Pact consumer tests for service dependencies
  - Configure OpenAPI response validation in tests
  - Add breaking change detection to CI

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

ステップ 4：API テストを設定する（--fix が指定された場合、またはユーザーが確認した場合）

検出したプロジェクトの種類に応じて修正を適用します。REFERENCE.md のテンプレートを使用して、次の項目を設定します：

1. Pact コントラクトテスト - 依存関係をインストールし、コンシューマー／プロバイダーのテストファイルを作成します
2. OpenAPI 検証 - バリデーターをインストールし、テストヘルパーを作成します
3. Zod によるスキーマテスト - Zod をインストールし、スキーマ定義を作成します
4. 破壊的変更の検出 - oasdiff をインストールし、CI チェックを追加します

JavaScript／TypeScript プロジェクトでは bun add --dev でインストールします。Python では uv add --group dev でインストールします。

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

.github/workflows/api-tests.yml を作成し、次のジョブを追加します。

• コンシューマー契約テスト
• プロバイダー検証（必要に応じてサービスコンテナーを使用）
• OpenAPI 仕様の検証
• PR での破壊的変更の検出

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

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

.project-standards.yaml を更新します。

standards_version: "2025.1"
last_configured: "[timestamp]"
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：最終レポートを出力する

適用したすべての変更、追加したスクリプト、設定をユーザーが検証するための次の手順をまとめて出力します。

詳細なテンプレートとコード例については、REFERENCE.md を参照してください。

エージェント向けの最適化

コンテキスト	コマンド
迅速な準拠チェック	/configure:api-tests --check-only
すべての問題を自動修正	/configure:api-tests --fix
Pact 契約のみ	/configure:api-tests --fix --type pact
OpenAPI 検証のみ	/configure:api-tests --fix --type openapi
スキーマテストのみ	/configure:api-tests --fix --type schema

フラグ

フラグ	説明
--check-only	修正を提案せずにステータスを報告します
--fix	確認を求めずにすべての修正を自動適用します
--type <type>	特定のタイプ（pact、openapi、schema）に絞ります

例

# 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 ドキュメント：https://docs.pact.io
• OpenAPI 仕様：https://swagger.io/specification
• Zod ドキュメント：https://zod.dev