create-agent-tests

エージェントテスト

エージェントテストを作成するスキルです。コーディングエージェントが Markdown のケースファイルをターゲット環境に対して実行し、監査可能なレポートを返します。検証は、固定的で決定論的なアサーションではなく、実行するエージェントの判断と、エージェントが収集した証拠（ブラウザー、API、DB、ログ、クラウド、テレメトリー）に基づきます。

このスキルはエージェントテストを作成して実行します。各ケースは、実行結果を利用する側が使えるよう、監査可能なレポート（レポートのパス、最終ステータス PASS／FAIL／BLOCKED／ABORTED、収集した証拠の成果物）を生成します。

エージェントテストを使用する場合

UI、API、データベース、ログ、ファイル、ネットワーク、稼働中の環境の状態をまたいだ柔軟なツール駆動の判断が検証に必要で、決定論的なテストを作成するには時期尚早、脆弱、コストがかかりすぎる、または範囲が狭すぎる場合に、エージェントテストを使用します。

特に次のような場合に役立ちます。

• 視覚的な確認、インタラクション、ブラウザーコンソール、ネットワーク、トレースによる検証が必要な UI の変更。
• 確信を得るために、実環境へのリクエストと永続化された状態の確認が必要な API および DB のワークフロー。
• フロントエンド、バックエンド、ストレージ、ジョブ、外部モック、クリーンアップをまたぐフルスタックのフロー。
• 安定した経路を標準的なユニットテスト、コントラクトテスト、インテグレーションテスト、YAML E2E テスト、またはその他の決定論的なテストに移行する前の、探索的な回帰チェック。

エージェントテストは決定論的なテストの代わりにはなりません。経路が安定したら、価値の高いエージェントテストのフローを、標準的な決定論的テスト（ユニットテスト、コントラクトテスト、インテグレーションテスト、YAML E2E テストなど）に移行することを優先してください。

プロジェクトのレイアウト

エージェントテストは、ターゲットリポジトリ内の tests/agent/ に配置します。

tests/agent/agent-test-suites.json   suite manifest (project-owned)
tests/agent/<feature>/<case>.md       case files, one logical journey each
tests/agent/run-agent-verification.ts runner/orchestrator
agent-test-reports/                    generated reports; do not hand-edit

実際の agent-test-suites.json、ケースファイル、フィクスチャのセットアップ、認証／セッションのブートストラップ、CI の配線、エンジンのシークレットと MCP 設定、ステージング／本番環境での変更ポリシー、クリーンアップの責任範囲は、そのリポジトリが管理します。

まずローカルの規約を確認する

作成を始める前に、tests/agent/agent-test-template.md があるか確認してください。存在する場合は、これをローカルの正式な規約として扱います。ユーザーから規約の更新を明示的に求められない限り、広範な検索で規約を再発見したり、置き換えたりしないでください。

ローカルのハーネスが存在せず、エージェントテストが最小限のコストで十分な証拠を得られる場合は、このスキルに含まれるスターターをコピーして、必要に応じてスキャフォールドを作成します。

• <skill-dir>/assets/agent-test-template.md → tests/agent/agent-test-template.md
• <skill-dir>/assets/agent-test-suites.example.json → tests/agent/agent-test-suites.example.json
• <skill-dir>/assets/run-agent-verification.ts → tests/agent/run-agent-verification.ts

プロジェクトが実際にエージェントテストを採用する場合にのみ、これらをコピーしてください。エージェントテストを採用していないリポジトリには、あらかじめ追加しないでください。その後、サンプルを基に実際のマニフェストを作成します。

cp tests/agent/agent-test-suites.example.json tests/agent/agent-test-suites.json

ケースの作成

各ケースは<skill-dir>/assets/agent-test-template.md（またはローカルの テンプレート）から作成します。適切なケースでは、実行エージェントが推測しにくいようにします。

• テスト対象の要件、リスク、または動作を明記し、その情報源へのリンクを記載します。
• 実際のプロジェクトのコンテキストを記入します。環境ごとのURL、アカウント／組織、フィクスチャと 変更のポリシー、DB／ログ／クラウドへのアクセス、本番環境での合成データのポリシー、そして クリーンアップの担当者を記載します。
• 環境の事前確認（対象環境でケースを実行できることの確認）と 製品の検証（チェックの実行）を分けます。
• 具体的なチェックを列挙します。ブラウザーのページ／状態、APIのルートとステータスコード、DBの テーブル／行、監査イベント、ログフィルター、テレメトリークエリ、タイミングを記載します。
• テスト自体が作成する状態に対する各アサーションは、無条件にします。任意の機能（「UIにXが あればYを検証する」など）に依存するチェックでは、エージェントがXを見つけられなければYを 検証せずにPASSできてしまい、ケースが提供するはずのカバレッジが黙って失われます。管理下にある フィクスチャ（新規作成したトークンや組織など）では、その機能の存在を必須にし、それを直接 アサートします。条件付きの表現は、実際に環境に依存する部分に限って使用します。
• 各動作で必要となる証拠を具体的に記載します。
• ケースは移植可能な状態に保ちます。環境固有の詳細は手順ではなく、testing-environments セクションに記載します。
• 生のシークレットは決して保存しないでください。変数名、ロール、アクセス方法のみを記録します。

実行

対象リポジトリに、使用するパッケージマネージャーに合わせたパッケージスクリプトを追加します。

{ "scripts": { "agent:verify": "tsx tests/agent/run-agent-verification.ts" } }

スイートまたは単一のケースを実行します。

pnpm agent:verify --target local --suite smoke --project-name "<project name>"
pnpm agent:verify --target local --case tests/agent/<feature>/<case>.md

references/runner.mdには、ランナーのデフォルト設定、フラグ、対応する環境変数、レポートの ステータス契約がすべて記載されています。

レポートのステータス契約

各ケースのレポートは、必ず次のいずれか1行だけで終わる必要があります。

Status: PASS
Status: FAIL
Status: BLOCKED
Status: ABORTED

• PASS / FAIL：環境の事前確認が完了し、製品の検証が実行されました。
• BLOCKED：環境またはセットアップの問題でケースを実行できませんでした（DB／ログへのアクセス不足、 URLに到達できない、ログイン／セッションの初期化に失敗、フィクスチャまたは承認の不足）。 環境上のブロッカーを理由にFAILを報告してはいけません。
• ABORTED：オーケストレーションが中断された場合に限ります。リリースゲートではABORTEDを無視して ケースを再実行します。中断の場合、最後をPASS／FAIL／BLOCKEDにしてはいけません。

必須ケースがPASSを返さない場合、ランナーは失敗します。

ケースでブラウザーを操作する場合は、監査可能な証拠（HTMLレポート、スクリーンショット一式、 動画、トレース、またはプロジェクト標準の同等物）を収集します。ブラウザーについてのテキストのみの 報告では不十分です。

出力

実行後、レポートのパスに監査可能なレポートが生成されます。レポートは最後にStatus:の行を ちょうど1行含み、収集した証拠の成果物（HTMLレポート、スクリーンショット、動画、トレース、ログ）が あれば、それらも含みます。このレポートと証拠が成果物です。このスキルを呼び出したものがそれらを 使用します。

使用しない場合

• 決定論的なユニットテスト、コントラクトテスト、統合テスト、またはYAML E2Eテストのほうが、 より低コストで長期間有効な証明になる場合は、代わりに標準の決定論的な形式を使用します。
• ライブ環境、アクセス権、またはフィクスチャが利用できない場合は、実行できないケースを 作成するのではなく、ブロッカーを記録します。