alan-test-feature

タスク：機能をテストし、デモレポートを生成する

現在のブランチの変更を分析し、ユーザーとカバレッジレベルを決定して、明確なテスト戦略を立て、アプリの開発サーバーを起動し、agent-browser を使って実際のブラウザーで機能をテストし、スクリーンショットと動画を撮影し（必ず実施すること。例外なし）、すべてを S3 にアップロードし、構造化されたテストレポートを生成します（必ず実施すること。省略禁止）。

---

フェーズ 0：環境設定

1. アーティファクトのコンテキスト ID を取得する

プロンプトにアクティブなタスクコンテキストがある場合は、それを使用します。それ以外の場合：

• タスク ID は ALAN_TASK_ID 環境変数から取得できます。
• 会話 ID は ALAN_SESSION_ID 環境変数から取得できます。
• レポートを作成する前に、Alan MCP のコンテキスト／ツールを使って teamId を解決します。

create_test_report を呼び出す際は、必ず taskId、conversationId、teamId を明示的に渡してください。ある ID を別の ID の代わりに使用しないでください。

2. agent-browser が利用可能か確認する

agent-browser は Vercel Labs のCLI ツール（npm: agent-browser）であり、スキルや MCP ツールではありません。bash コマンド（open、click、fill、screenshot、record）を使ってヘッドレスブラウザーを自動操作できます。サンドボックスでは runtime-bootstrap.ts によって事前にインストールされています。

command -v agent-browser >/dev/null 2>&1 && echo "agent-browser: OK" || echo "agent-browser: MISSING"

利用できない場合は、インストールします：

npm install -g agent-browser && agent-browser install

インストールに失敗した場合（ネットワークや npm が利用できない場合など）は、停止してユーザーに次のように伝えます：

"agent-browser is not available and could not be installed. Install it manually: npm install -g agent-browser && agent-browser install"

agent-browser が動作する状態になるまでは、フェーズ 2 に進まないでください。すべてのブラウザーテストで必要です。

3. ワークスペースを作成する

撮影したすべてのファイル（スクリーンショット、動画）は、必ず /tmp/alan-captures/ に保存してください。

mkdir -p /tmp/alan-captures

重要 — ファイルパスのルール：

• 撮影ファイルの書き込み先は /tmp/alan-captures/ のみです。それ以外の場所には絶対に保存しないでください。
• .claude/、プロジェクトディレクトリ、reports/、またはリポジトリ内のいかなるパスにも絶対に保存しないでください。
• .claude/ は機密性の高いシステムディレクトリです。ここへの書き込みはブロックされ、テスト実行が中止されます。
• /tmp/ 以外の場所に reports/ や screenshots/ フォルダーを作成しようとしている場合は、作成を中止し、代わりに /tmp/alan-captures/ を使用してください。

---

フェーズ 0.5：カバレッジ範囲の決定とコンテキスト収集（必須 — 何よりも先に実施すること）

このフェーズを省略しないでください。 テスト手順を1つでも書く前に、ユーザーが何を望んでいるかを把握する必要があります。

1. カバレッジレベルを尋ねる

AskUserQuestion を使って、ユーザーに次の質問をします：

What level of test coverage do you want for this feature?

- light       — Happy path only. Quick smoke test to verify the main flow works.
- standard    — Happy path + key edge cases + basic error states. (Default)
- comprehensive — Full coverage: happy path, all edge cases, error states, non-happy paths, boundary values, accessibility, responsiveness.

Also: are there any specific flows, known bugs, or risky areas you want me to focus on?

続行する前に、回答を待ちます。

2. 対象を絞った追加質問をする

機能に基づき（まだ機能が分からない場合は、まず git diff --stat を簡単に実行して手掛かりを得てください）、AskUserQuestion を使って対象を絞った追加質問を1～3件します。例：

• 「認証済みの状態をテストする必要はありますか？必要な場合、使用するテスト用認証情報を教えてください。」
• 「この機能に関連する既知のエッジケースや過去のバグはありますか？」
• 「この機能が『正しく動作している』と判断できる条件は何ですか？何を確認できればよいですか？」
• 「特に確認したい正常系以外のケース（無効な入力、ネットワークエラー、空の状態など）はありますか？」
• 「特に対象に含める、または除外するページやユーザーロールはありますか？」

コンテキストが不明確な場合は質問を省略しないでください。質問してください。適切に範囲を定めたテストは、見当違いのテストより10倍有益です。

3. 計画を確認する

回答を得た後、ユーザーに要約を伝えます（ツール呼び出しは不要です。短いメッセージで構いません）：

• 選択したカバレッジレベル
• 優先して確認する具体的な領域／フロー
• 対象とする既知のリスクやエッジケース
• 想定されるテストシナリオのおおよその数

この確認が済むまでフェーズ 1 に進まないでください。

---

フェーズ 1：テスト対象を特定する

1. ブランチを分析する

変更内容を把握するため、次のコマンドを実行します：

git log main..HEAD --oneline 2>/dev/null || git log HEAD~5..HEAD --oneline
git diff main...HEAD --stat 2>/dev/null || git diff HEAD~1 --stat

実際の差分を読み、機能またはバグ修正の内容を把握します。以下を特定してください：

• アプリのどの部分が影響を受けるか（ページ、コンポーネント、API ルート）
• 期待される動作の変更
• テスト時に移動する URL パス

2. 開発サーバーを特定して起動する

プロジェクトを確認し、実行方法を特定します。

1. package.json を読み、scripts.dev、scripts.start、scripts.serve を確認します
2. docker-compose.yml／docker-compose.yaml／compose.yml を確認します
3. Makefile を確認します（dev または serve のターゲットを探します）
4. Procfile、.env、Pipfile、requirements.txt、Gemfile を確認します
5. フレームワーク固有のファイルを確認します：next.config.*、vite.config.*、nuxt.config.*、angular.json、manage.py、config/routes.rb

開発サーバーをバックグラウンドで起動します。一般的なパターン：

# Node.js
npm run dev &
# or: pnpm dev &, yarn dev &, npx next dev &, npx vite &

# Python
python manage.py runserver &
# or: flask run &, uvicorn main:app &

# Ruby
bundle exec rails server &

# Docker
docker compose up -d

3. サーバーの起動を待つ

サーバーが応答するまでポーリングします。

# Replace PORT with the discovered port
for i in $(seq 1 30); do
  curl -sf http://localhost:PORT >/dev/null 2>&1 && break
  sleep 2
done

ポートが不明な場合は、一般的なポートを確認します：3000、5173、8080、4200、8000、4000、3001、8888。

4. アプリの URL を特定する

• 開発サーバーの stdout／stderr で、「Local:」や URL を含む「ready on」メッセージを確認します
• .env または .env.local で PORT、VITE_PORT などを確認します
• curl -sf http://localhost:PORT >/dev/null を使って一般的なポートをテストします
• 特定できない場合は、AskUserQuestion を使ってユーザーに尋ねます

5. 続行する前に要約する

ユーザーに次の内容を伝えます。

• diff で確認した内容（機能／修正の概要）
• テストする URL
• 実施予定のテストシナリオ

---

フェーズ 1.5：テスト戦略の策定と Todo の作成（必須）

ブラウザーを開く前に、明確な計画を立ててください。テスト手順をその場で即興で決めてはいけません。

1. テスト戦略を作成する

以下に基づいて作成します。

• フェーズ 0.5 でユーザーが選択したカバレッジレベル
• フェーズ 1 での diff 分析
• ユーザーから得たコンテキスト

テスト計画全体を、構造化されたリストとして記述します。各シナリオには次の内容を記載します。

• シナリオ名 — 短いラベル（例：「正常系：項目を作成」）
• 種類 — 正常系／非正常系／境界ケース／エラー状態／ビジュアル／ナビゲーション
• 手順 — 実行する操作
• 期待される結果 — 合格とみなす状態
• スクリーンショットが必要か — はい／いいえ

レベルごとのカバレッジ要件：

• light：正常系のみ（1～3 シナリオ）
• standard：正常系＋非正常系 2～4 件＋エラー状態 1～2 件
• comprehensive：正常系＋すべての非正常系＋すべてのエラー状態＋境界値＋空の状態＋レスポンシブ対応＋ナビゲーション

検討する非正常系の例：

• 無効な入力／必須入力の欠落
• データなしでの送信／空の状態
• 重複項目（該当する場合）
• 権限拒否／未認証アクセス
• ネットワークエラー／API エラーのシミュレーション（テスト可能な場合）
• 連続した素早い操作（ダブルクリック、送信の連打）
• 長い入力文字列／特殊文字
• フローの途中での戻るボタン／ブラウザーのナビゲーション

2. 各シナリオの Todo を作成する

TodoWrite を使用して各テストシナリオの Todo 項目を作成し、進捗を追跡できるようにします。各 Todo の名前にはシナリオ名を指定します。

3. 戦略を提示する

続行する前に、テスト戦略全体を番号付きリストとして出力します。フェーズ 2 の開始前に、何をテストするのかをユーザーが正確に確認できるようにします。

---

フェーズ 2：agent-browser でテストする

agent-browser は CLI ツールです。MCP ツールやスキルとしてではなく、bash 経由で呼び出してください。 ドキュメント：https://github.com/vercel-labs/agent-browser 主なコマンド：open、snapshot、click、fill、screenshot、record、wait、find、close

1. アプリを開く

agent-browser --session test-feature open http://localhost:PORT
agent-browser --session test-feature wait --load networkidle

2. 動画録画を開始する — 必須

操作を行う前に、必ず動画録画を開始してください。例外はありません。

agent-browser --session test-feature record start /tmp/alan-captures/happy-path.webm

技術的な理由で動画録画に失敗した場合は、その旨を記録して続行してください。スクリーンショットは引き続き必須です。

3. 最初のスクリーンショットを撮影する — 必須

操作を行う前に、必ずページの初期状態をキャプチャしてください。

agent-browser --session test-feature screenshot /tmp/alan-captures/step-00-initial-state.png

4. テスト戦略の各シナリオを実行する

Phase 1.5 で定義したすべてのシナリオを順に実行します。シナリオごとに、以下を行います。

• 対応する todo を進行中にします
• agent-browser snapshot -i を使って、操作可能な要素を見つけます
• agent-browser click @eN、agent-browser fill @eN "text" などを使って操作します
• 操作の合間に agent-browser wait --load networkidle または agent-browser wait 1500 を使います
• 重要な状態が変わるたびにスクリーンショットを撮ります — 意味のある操作を2回以上続けて行う前に、必ず撮影してください。

  agent-browser --session test-feature screenshot /tmp/alan-captures/step-NN-description.png
  

  スクリーンショットには、step-02-form-filled.png、step-03-submit-clicked.png、step-04-success-state.png のように、内容がわかる名前を付けます
• ページ遷移または DOM の変更後は、再度スナップショットを取得します（refs は古くなります）
• ref で要素を見つけにくい場合は、セマンティックロケーターを使います。

  agent-browser --session test-feature find text "Submit" click
  agent-browser --session test-feature find role button click --name "Save"
  

• 結果に応じて、各 todo を完了または失敗にします

必須カバレッジチェックリスト（選択したカバレッジレベルに該当する項目をすべて実行してください）：

正常系（常に必須）：

• 主要な機能のフローが、エンドツーエンドで想定どおりに動作する
• 成功状態／確認メッセージが表示される
• 操作後にデータが正しく保存／反映される

正常系以外のケース（標準＋包括的で必須）：

• 必須入力の空欄／欠落 — フォームの検証が実行され、エラーメッセージが表示される
• 無効な入力値 — 正しく拒否され、クラッシュしない
• 境界値 — 許容される最小値と最大値
• 重複／競合するデータ（該当する場合）
• 未認証／権限拒否状態（該当する場合）
• 空のリスト／ゼロ状態の画面（該当する場合）
• 短時間での連続操作（送信ボタンのダブルクリック、ボタンの連打）
• テキスト入力での長い文字列／特殊文字

エラー状態（標準＋包括的で必須）：

• API／ネットワーク障害時の動作（シミュレーション可能な場合）
• 部分的な失敗 — 操作の一部だけが成功した場合の挙動
• グレースフルデグラデーション — アプリがクラッシュせず、ユーザーに意味のあるメッセージが表示される

ビジュアルとナビゲーション（包括的で必須）：

• レイアウトが正しく、はみ出しや UI の崩れがない
• 狭いビューポートでもレスポンシブに表示される（可能であればサイズを変更）
• リンクとナビゲーションが機能し、戻るボタンを使っても状態が壊れない
• 非同期処理中にローディング状態／スピナーが表示される

5. 録画を停止して後片付けする

agent-browser --session test-feature record stop
agent-browser --session test-feature screenshot /tmp/alan-captures/final-state.png
agent-browser --session test-feature close

録画は2分以内にしてください。 機能の調査にそれ以上かかる場合は、録画を複数に分けます（例：happy-path.webm、error-states.webm）。

6. WebM の再生時間メタデータを修正する（ffmpeg が利用可能な場合は必須）

agent-browser で録画した WebM ファイルは、コンテナーヘッダーの duration = Infinity になっていることがよくあります。その場合、動画プレーヤーでは 0:00 と表示されます。ffmpeg を使ってリマックスし、すべての .webm ファイルを修正してください。ffmpeg はファイル全体を読み込んで実際の再生時間を計算し、出力ヘッダーに書き込みます。

for f in /tmp/alan-captures/*.webm; do
  if command -v ffmpeg >/dev/null 2>&1; then
    ffmpeg -y -i "$f" -c copy "${f%.webm}-fixed.webm" 2>/dev/null \
      && mv "${f%.webm}-fixed.webm" "$f" \
      || echo "ffmpeg remux failed for $f — uploading as-is"
  fi
done

ffmpeg が利用できない場合は、この手順をスキップして続行します。動画は再生できますが、プレーヤーに正しい再生時間は表示されません。

---

Phase 3: キャプチャを S3 にアップロードする

キャプチャした各ファイルについて、mcp__alan__get_upload_url MCP ツールを使って署名付き S3 URL を取得し、curl PUT でファイルを S3 に直接アップロードします。

ファイルごとのアップロード手順

1. ファイルサイズを取得します（MCP ツールで必要です）。

   SIZE=$(stat -c%s "/tmp/alan-captures/step-01.png" 2>/dev/null || stat -f%z "/tmp/alan-captures/step-01.png")
   

2. MCP ツールを呼び出して、署名付きアップロード URL を取得します。

   Tool: mcp__alan__get_upload_url
   Parameters: {
     "taskId": "<active task ID or value of ALAN_TASK_ID>",
     "filename": "step-01.png",
     "mimeType": "image/png",
     "size": <SIZE from step 1>
   }
   

   戻り値：{ "uploadUrl": "https://...", "s3Key": "sandbox-captures/..." }

3. 署名付き URL を使って、ファイルを S3 にアップロードします。

   curl -sf -X PUT "<uploadUrl>" \
     -H "Content-Type: image/png" \
     --data-binary @/tmp/alan-captures/step-01.png
   

4. s3Key を保存します — Phase 4 で create_test_report に渡します。

スクリーンショットと動画ファイルごとに、この手順を繰り返します。一般的な MIME タイプは以下のとおりです。

• スクリーンショット：image/png
• 動画録画：video/webm

アップロードに失敗した場合：それでも Phase 4 に進み、screenshotUrl、videoUrl、screenshotUrls フィールドを省略してください。メディアがなくても、構造化レポートには価値があります。

---

フェーズ 4：構造化テストレポートを作成する（必須 — 絶対に省略しない）

重要：このスキルを完了するには、必ず mcp__alan__create_test_report を呼び出してください。これは必須です。

• レポートを Markdown テキストとして出力しないでください
• チャット内で調査結果を要約するだけにしないでください
• 理由を問わず、このフェーズを省略しないでください。時間がない場合や、アップロードに失敗した場合、テストが一部のみの場合も同様です
• UI でインタラクティブな成果物として表示されるよう、レポートはこの MCP ツール呼び出しを通じて永続化する必要があります
• この手順を省略すると、テストセッション全体が無駄になり、記録も残りません

フェーズ 3 でアップロードに失敗した場合でも、レポートを作成してください。その場合はメディア URL を省略し、すべてのステップ、問題、概要テキストを含めてください。

テストから得た構造化データを使って、mcp__alan__create_test_report MCP ツールを呼び出してください。

前のフェーズで得たデータをすべて集めて、ツールを呼び出してください。

Tool: mcp__alan__create_test_report
Parameters: {
  "title": "<short description of what was tested>",
  "taskId": "<active task ID or value of ALAN_TASK_ID, if set>",
  "conversationId": "<active conversation ID or value of ALAN_SESSION_ID>",
  "teamId": "<resolved team ID>",
  "branch": "<current branch name from git>",
  "baseBranch": "main",
  "commits": [
    { "sha": "<commit sha>", "message": "<commit message>" }
  ],
  "changedFiles": [
    { "path": "src/components/Feature.tsx", "description": "Added new feature component" }
  ],
  "appUrl": "<the URL you tested>",
  "summary": "<1-2 paragraph summary of what was tested and the outcome>",
  "status": "pass | fail | mixed",
  "steps": [
    {
      "name": "Navigate to feature page",
      "status": "pass | fail | skip",
      "screenshotUrl": "<s3Key from Phase 3 — e.g. sandbox-captures/org/task/step-01.png — omit if upload failed>",
      "notes": "Page loaded correctly"
    }
  ],
  "issues": [
    {
      "title": "Button misaligned on mobile",
      "severity": "critical | high | medium | low",
      "description": "The submit button overflows on viewports < 375px",
      "screenshotUrl": "<s3Key from Phase 3 showing the issue — omit if upload failed>"
    }
  ],
  "videoUrl": "<s3Key from Phase 3 for the happy-path recording — omit if upload failed>",
  "screenshotUrls": ["<s3Key 1 from Phase 3>", "<s3Key 2 from Phase 3>"]
}

フィールドのガイドライン

• status：すべてのステップに合格した場合は「pass」、重要なステップに失敗した場合は「fail」、一部のステップに合格し、一部に失敗した場合は「mixed」
• steps：個別のテスト操作（移動、クリック、入力、確認）ごとに 1 件登録します。スクリーンショットを撮影した場合は、そのステップのスクリーンショット URL を含めてください。
• issues：実際に見つかった問題のみを含めます。各問題には重大度と明確な説明を付けてください。
• screenshotUrls：フェーズ 3 のすべてのスクリーンショットの s3Key をフラットなリストにして含めます（ギャラリー表示用）。uploadUrl ではなく、get_upload_url が返す s3Key フィールドを使ってください。アップロードに成功したものがない場合は省略してください。
• commits と changedFiles：フェーズ 1 の Git 分析の結果を使います

出力

mcp__alan__create_test_report を呼び出した後、ユーザーに次の情報を伝えてください。

• テストレポートのタイトル。ユーザーが Alan UI で生成された成果物を見つけられるようにします
• 成果物へのリンク。作成に必要な情報がある場合に記載してください（通常は /teams/<teamId>/docs?artifactId=<artifactId>）
• 簡単な概要：テスト対象、合格／失敗したステップ数、見つかった問題
• テスト中に見つかったバグや懸念事項を列挙します

UUID のみを先頭に記載しないでください。使えるタイトルやリンクがない場合は、デバッグ用の補足情報としてのみ成果物／レポート ID を記載してください。

レポート全体を Markdown として表示しないでください。MCP ツール呼び出しによって構造化された成果物が作成され、UI にインタラクティブに表示されます。