run-test-plan

テスト計画の実行

YAML テスト計画を実行し、セットアップコマンド、ヘルスチェック、各テストを順番に実行します。最初の失敗時に、詳細なデバッグ出力を表示して停止します。

前提条件

• agent-browser CLI：ブラウザテストを行うには、PATH 上で agent-browser コマンドラインツールを利用できる必要があります。

引数

• --plan <path>：テスト計画へのパス（デフォルト：docs/testing/test-plan.yaml）
• --skip-setup：セットアップコマンドとヘルスチェックをスキップします（失敗後の再実行用）

ステップ 1：テスト計画を解析する

テスト計画を読み込み、検証します。

# Resolve plan path from --plan (default shown)
PLAN_PATH="${PLAN_PATH:-docs/testing/test-plan.yaml}"

# Check file exists
ls "$PLAN_PATH" || { echo "Error: Test plan not found: $PLAN_PATH"; exit 1; }

# Validate YAML
python3 -c "import yaml; yaml.safe_load(open('$PLAN_PATH'))" || { echo "Error: Invalid YAML: $PLAN_PATH"; exit 1; }

YAML から以下を抽出します。

• setup.commands：セットアップコマンドのリスト
• setup.health_checks：ポーリングする URL のリスト
• tests：テストケースの配列

ステップ 2：セットアップを実行する（--skip-setup を指定していない場合）

2a. 前提条件を確認する

setup.prerequisites が存在する場合は、それぞれを確認します。

# For each prerequisite in setup.prerequisites
<prerequisite.check> || { echo "Prerequisite not met: <prerequisite.name>"; exit 1; }

2b. 環境変数を設定する

setup.env が存在する場合は、各変数をエクスポートします。${VAR} 形式の変数は、現在の環境から解決します。

# For each key/value in setup.env
export <key>="<value>"

2c. ビルドする

setup.build が存在する場合は、ビルドコマンドを順番に実行します。

# For each command in setup.build
<command> || { echo "Build failed: <command>"; exit 1; }

2d. サービスを起動する

setup.services が存在する場合は、長時間実行するプロセスを起動し、ヘルスチェックを待ちます。

# For each service in setup.services
nohup <service.command> > .beagle/service-<index>.log 2>&1 &
echo $! > .beagle/service-<index>.pid

health_check が設定されている各サービスについて、準備が整うまでポーリングします。

timeout=<service.health_check.timeout or 30>
url=<service.health_check.url>
elapsed=0

while [ $elapsed -lt $timeout ]; do
  if curl -s -o /dev/null -w "%{http_code}" "$url" | grep -qE "^(200|301|302)"; then
    echo "✓ Health check passed: $url"
    break
  fi
  sleep 2
  elapsed=$((elapsed + 2))
done

if [ $elapsed -ge $timeout ]; then
  echo "✗ Health check timeout: $url"
  exit 1
fi

2e. 以前のセットアップ形式

計画で以前のフラット形式（prerequisites／build／services ではなく、setup.commands と setup.health_checks）が使われている場合は、setup.commands を順番に実行し、従来どおり setup.health_checks をポーリングします。

ステップ 3：ゲート — テスト開始前にセットアップが準備完了していること

確認可能なすべての条件が満たされるまで、ステップ 4 を開始しないでください。

1. 計画の読み込み： --plan で指定したファイル（デフォルトは docs/testing/test-plan.yaml）が存在し、YAML として解析できること（ステップ 1 と同じ確認を行います）。
2. セットアップの分岐：
   • --skip-setup を使用しない場合：存在するすべての setup.prerequisites チェックが終了コード 0 で終了していること、すべての setup.build コマンドが成功していること、各サービスの health_check がタイムアウトまでに HTTP 200、301、または 302 に到達していること、または従来の setup.commands の後に setup.health_checks が成功していること。
   • --skip-setup を使用する場合：TC-01 の前に、計画で引き続き必要なものが稼働していることを確認します。最低限、テストが依存する setup.health_checks 内の各 URL、または setup.services[].health_check.url の各 URL に対して、curl（または同等の方法）が少なくとも 1 回成功することを確認します。
3. 証拠の保存先： mkdir -p docs/testing/evidence が成功し、そのディレクトリが存在すること。

いずれかのゲートに失敗した場合は停止し、セットアップまたはフラグを修正して、テストを実行しないでください。

ステップ 4：テストを順番に実行する

計画内の各テストについて、次の手順を行います。

4a. テスト開始をログに記録する

## Running: TC-XX - <test.name>

Context: <test.context>

4b. ステップを実行する

test.steps 内の各ステップについて、ステップの種類を判断し、該当する方法で実行します。

シェルコマンド（run: ステップ）：

最も一般的なステップの種類です。コマンドを Bash 経由で実行し、標準出力、標準エラー出力、終了コードを取得します。

# Execute the command, capture output and exit code
<command> 2>&1
echo "EXIT_CODE: $?"

ステップ 4c での評価に使うため、すべての出力を取得します。シェルステップには、次のようなものがあります。

• CLI バイナリの呼び出し（例：./target/debug/myapp status --all）
• データベースクエリ（例：psql "${DATABASE_URL}" -c "SELECT ..."）
• ファイルの確認（例：ls -la /path/to/expected/output）
• プロセスのライフサイクル確認（例：timeout 5 ./myapp 2>&1 || true）
• 人が端末で入力するその他のコマンド

curl アクション（action: curl ステップ）：

curl -X <method> \
  -H "Content-Type: application/json" \
  <additional headers> \
  -d '<body>' \
  "<url>" \
  -o response.json \
  -w "%{http_code}" > status_code.txt

# Capture response for evaluation
cat response.json
cat status_code.txt

agent-browser CLI アクション：

agent-browser で始まるステップは、ブラウザー自動化コマンドです。

# Navigate
agent-browser open <url>

# Snapshot interactive elements (always do before interacting)
agent-browser snapshot -i

# Interact using refs from snapshot output (@e1, @e2, etc.)
agent-browser fill @<ref> "<value>"
agent-browser click @<ref>

# Wait for conditions
agent-browser wait --url "<pattern>"
agent-browser wait --text "<text>"
agent-browser wait --load networkidle

# Capture evidence
agent-browser screenshot docs/testing/evidence/<test.id>.png

重要： 要素を操作する前に、必ず agent-browser snapshot -i を実行して有効な参照を取得してください。ページ遷移後や DOM に大きな変更があった後は、再度スナップショットを取得してください。

スクリーンショットを docs/testing/evidence/<test.id>.png に保存します。

4c. 結果の評価

ゲート — PASS／FAIL の判定前に成果物を確認します：

• run: ステップ： 標準出力と標準エラーが記録され、終了コードが記録されていること（例：EXIT_CODE: の行または同等のもの）。
• action: curl ステップ： レスポンス本文と HTTP ステータスが既知のパス（例：response.json、status_code.txt、またはプランで指定されたパス）に記録されていること。
• agent-browser ステップ： ナビゲーションまたは DOM の変更後、アサーションの前に新しい agent-browser snapshot -i が存在すること。テストで証拠を記録する場合、スクリーンショットのファイルパスが作成されているか、失敗が明示されていること。

次に、エージェントの推論を用いて、実際の結果を test.expected と比較します：

• 期待される動作の説明を読みます
• 実際のレスポンス／スクリーンショットと比較します
• PASS または FAIL を判定します

4d. PASS の場合

✓ TC-XX PASSED: <test.name>

次のテストに進みます。

4e. FAIL の場合

直ちに停止します。ステップ 6 に進みます。

Step 5: すべてのテストが合格した場合

## Test Results: ALL PASSED

| ID | Name | Result |
|----|------|--------|
| TC-01 | <name> | ✓ PASS |
| TC-02 | <name> | ✓ PASS |
| ... | ... | ... |

**Total:** N/N tests passed

### Evidence

Screenshots saved to `docs/testing/evidence/`

### Cleanup

Stopping background services...

クリーンアップします：

# Kill background services
for pidfile in .beagle/service-*.pid .beagle/dev-server.pid; do
  if [ -f "$pidfile" ]; then
    kill $(cat "$pidfile") 2>/dev/null
    rm "$pidfile"
  fi
done

Step 6: 失敗時 — デバッグプロンプトを生成

テストが失敗した場合、詳細なデバッグ出力を生成します：

6a. コンテキストを収集

# Get changed files relevant to the failure
git diff --name-only $(git merge-base HEAD origin/main)..HEAD

# Get recent changes in files mentioned in test.context
git diff $(git merge-base HEAD origin/main)..HEAD -- <relevant_files>

6b. デバッグレポートを出力

## Test Failure: TC-XX - <test.name>

### What Failed

**Test:** <test.name>
**Expected:**
<test.expected>

**Actual:**
<Describe what actually happened - response code, error message, screenshot description>

### Relevant Changes in This PR

<For each file mentioned in test.context or related to the failure:>
- `<file>` (lines X-Y) - <brief description of changes>

### Evidence

<If screenshot exists:>
- Screenshot: `docs/testing/evidence/<test.id>.png`

<If API response:>
- Status code: <code>
- Response body:
```json
<response>

エラーの詳細

<レスポンスまたはログにエラーメッセージがある場合：>

<error message>

調査の提案

<エラーに基づいて、確認すべき具体的な項目を 2～3 個提案します：>

1. <エラーの種類に基づいて最初に確認する項目>
2. <変更されたファイルに関連する 2 番目の項目>
3. <環境／セットアップに関する 3 番目の項目>

デバッグセッションのプロンプト

新しいエージェントセッションを開始するには、これをコピーしてください：

---

ブランチ <branch> で発生したテスト失敗をデバッグしています。

テスト： <test.name> エラー： <エラーの簡潔な説明>

<テストで確認していた内容と、問題が発生した箇所を要約します>

関連ファイル： <このテストに関連する変更済みファイルを一覧表示します>

が発生した理由を調査してください。

### 6c. Preserve Evidence

```bash
# Ensure evidence directory exists
mkdir -p docs/testing/evidence

# Save failure context
cat > docs/testing/evidence/<test.id>-failure.md << 'EOF'
# Failure Report: <test.id>

<Full debug report content>
EOF

6d. クリーンアップして終了

# Kill background services
for pidfile in .beagle/service-*.pid .beagle/dev-server.pid; do
  if [ -f "$pidfile" ]; then
    kill $(cat "$pidfile") 2>/dev/null
    rm "$pidfile"
  fi
done

テスト結果の概要表

進行状況を示す概要表を必ず出力します：

## Test Results

| ID | Name | Result |
|----|------|--------|
| TC-01 | <name> | ✓ PASS |
| TC-02 | <name> | ✗ FAIL |
| TC-03 | <name> | - SKIP |

**Passed:** 1/3
**Failed:** TC-02

失敗後のテストは SKIP（未実行）として記録します。

検証

完了する前に：

# Verify evidence directory exists
ls -la docs/testing/evidence/

# List captured evidence
ls docs/testing/evidence/*.png docs/testing/evidence/*.md 2>/dev/null

合格条件（実行完了と判定するには、すべてを満たす必要があります）：

• ls -la docs/testing/evidence/ が終了コード 0 で終了する（ディレクトリが存在する）。
• 実行されたすべてのテストに、明示的な PASS または FAIL が記録されている（「問題なさそうだった」だけでは不可）。
• テストが失敗した場合、失敗の成果物（docs/testing/evidence/<test.id>-failure.md または同等のもの）が存在する か、期待値と実際の結果を含むデバッグレポートが出力されている。
• クリーンアップが実行されている：プランで稼働状態を維持するよう指定されていない限り、起動した実行中プロセスを指す古い .beagle/service-*.pid が残っていない。

検証チェックリスト：

• セットアップコマンドが正常に実行された（または --skip-setup を使用し、依存関係の稼働を確認した）
• テスト実行前にヘルスチェックに合格した（ステップ 3 のゲート）
• 実行した各テストの結果が記録されている
• docs/testing/evidence/ に証拠が保存されている
• 失敗時：デバッグプロンプトに期待値と実際の結果が含まれている
• 失敗時：関連する PR の変更が記載されている
• バックグラウンドプロセスがクリーンアップされている

ゲート（順番どおり）

1. プランが有効： YAML を解析でき、対象ブランチに必要なキー（setup／tests）が含まれている。
2. セットアップが正常： TC-01 の前にステップ 3 の合格条件を満たしている。
3. テストごとの成果物： PASS と判定する前にステップ 4c のゲートを満たしている。
4. 失敗時は停止： 最初の失敗でステップ 6 に進み、それ以降のテストは概要表で SKIP とする。
5. クリーンアップ： ステップ 5 またはステップ 6d を実行し、この実行で起動したバックグラウンド PID を解放する。

ルール

• 最初のテスト失敗で停止する（ほかのテストを続行しない）
• 必ず証拠を記録する（スクリーンショット、レスポンス）
• 可能な場合は、デバッグプロンプトにファイルと行番号の参照を含める
• 問題を修正した後に再実行するには --skip-setup フラグを使う
• シークレットをハードコードしない — 環境変数を使う
• 失敗時もバックグラウンドプロセスをクリーンアップする
• デバッグ用に失敗の証拠を保持する
• 新しいセッションでコピーしてすぐ使えるデバッグプロンプトを作成する