test-feature

引数：$ARGUMENTS

Inbox Zero のエンドツーエンド機能テスターです。ブラウザー、API、CLI、評価テストの作成など、必要な手段を使って、機能が正しく動作することを検証します。

呼び出されたとき

ユーザーがテストする機能を説明します。説明がなければ、最近のコード変更から推測できます。説明が曖昧な場合は、git diff と git log を確認し、最近の変更から何が実装されたかを把握してください。

ユーザーから既存の worktree、ブランチ、または PR をテストするよう指定されることがあります。その場合は、そのディレクトリに cd し、そこで環境をセットアップしてください。メインの開発サーバーがすでに実行中の場合は、別のポートを使用します（例：PORT=3001 pnpm dev）。

ステップ 0：環境のセットアップ

テストの前に、ローカル環境が準備できていることを確認してください。これらの手順は何度実行しても問題ありません。すでに済んでいるものは省略してください。

1. 開発サーバーが実行中か確認する：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 を実行します。応答があれば、手順 2～4 も確認したうえで、手順 5 に進んでください。
2. .env が存在することを確認する：apps/web/.env がない場合（worktree ではよくあります）、共有場所からのシンボリックリンクを試してください：

   ln -sf ~/.inbox-zero/.env apps/web/.env
   ln -sf ~/.inbox-zero/.env.test apps/web/.env.test  # for eval tests
   

   シンボリックリンク元が存在しない場合は、環境変数ファイルの場所をユーザーに尋ねてください。
3. 必要な機能フラグを有効にする：.env.example を確認し、機能に必要な環境変数（例：NEXT_PUBLIC_EXTERNAL_API_ENABLED=true）がないか調べてください。apps/web/.env に不足しているものがあれば、追加してください。重要：NEXT_PUBLIC_* 変数はビルド時に組み込まれます。開発サーバーの実行中に .env に追加した場合は、反映させるためにサーバーを必ず再起動してください。テスト後ではなく、テスト前に行ってください。この手順を省略して「機能が有効になっていない」とテスト結果として報告してはいけません。それはセットアップの失敗であり、テスト結果ではありません。
4. 依存関係をインストールする：node_modules が古いか見つからない場合は、pnpm install を実行してください。
5. 開発サーバーを起動する（ブラウザーテスト／API テストに必要な場合）：バックグラウンドで pnpm dev を実行してください。準備ができるまで待ち、応答が返るまで localhost:3000 をポーリングしてください（最大 60 秒）。手順 3 で NEXT_PUBLIC_* 環境変数を追加し、サーバーがすでに実行中だった場合は、いったん停止してからここで再起動してください。

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

作業を始める前に、適切なテスト方法を決めてください。複数の方法を組み合わせることもよくあります。

テスト対象	方法
UI の動作、設定ページ、視覚的な変更	ブラウザー QA — アプリを操作してスクリーンショットを撮ります
Google Workspace 連携（Drive、Calendar、Gmail）	データのセットアップには gws CLI、検証にはブラウザーを使用します
API エンドポイント	HTTP リクエストを直接実行します（curl/fetch）。必要に応じて API キーを使い、アプリの API 経由で実行します
AI／LLM の出力品質（下書き、分類、ルール）	評価テスト — __tests__/eval/ にテストを作成するか、既存のテストを実行します
メール処理ワークフロー	範囲に応じて、E2E フローテストまたはブラウザー QA を行います

実行前に、2～3 文でテスト計画をユーザーに伝えてください。必要なアクセス権や認証情報がない場合は、あらかじめその旨を伝えてください。

ステップ 2：テストデータを準備する

機能に必要なテストデータを作成してください。例：

• Google Drive：gws drive files create を使ってフォルダーやファイルを作成するか、ブラウザーで作成します
• Gmail：gws gmail users messages send を使うか、ブラウザーからテストメールを送信します
• Calendar：gws calendar events insert を使ってテストイベントを作成します
• アプリ設定：ブラウザーを使って設定（ルール、文章スタイル、接続済みアカウントなど）を構成します

gws を使う場合は、ファイル、フォルダー、イベントを作成する操作がブラウザーのクリックより速く、確実なため、データのセットアップには優先して使用してください。アプリ固有の設定など、UI でしか行えない操作にはブラウザーを使用してください。

ステップ 3：テストを実行する

ブラウザテスト（agent-browser CLI 経由）

すべてのブラウザー操作にはagent-browserスキルを使用します。基本的な流れは、開く → スナップショットを取得する → 操作する → 再度スナップショットを取得する → スクリーンショットを撮る、です。

• 直接 URL で移動する：サイドバーのリンクに対するagent-browser clickは不安定な場合があります。agent-browser --cdp 9222 open <full-url>を使用してください。
• ビューポートを1440x900に設定する：Headless Chromeのデフォルトのビューポートは非常に小さいサイズです。接続後、CDP経由で設定します。

  TARGET_ID=$(curl -s http://127.0.0.1:9222/json | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).find(t=>t.type==='page'&&!t.url.startsWith('chrome')).id")
  node -e "const d=JSON.stringify({id:1,method:'Emulation.setDeviceMetricsOverride',params:{width:1440,height:900,deviceScaleFactor:1,mobile:false}});const ws=new WebSocket('ws://127.0.0.1:9222/devtools/page/$TARGET_ID');ws.onopen=()=>ws.send(d);ws.onmessage=()=>ws.close();"
  

チャット入力欄の操作

チャットのテキストエリアにはdata-testid="chat-input"があります。次のコマンドを使用してください。

agent-browser fill "[data-testid=chat-input]" "Your message here"
agent-browser press Enter                          # submit
sleep 15-30                                        # wait for AI response
agent-browser screenshot /tmp/result.png

注意：fillとtypeでは、最初の引数にセレクター（CSSセレクターまたは@ref）が必要です。セレクターを指定せずにtype "some text"を実行しないでください。これは別のコマンドであるkeyboard typeとして実行されます。CSSセレクターが複数の要素に一致する場合は、agent-browser snapshotを使用して一意の@ref識別子を取得してください。

• ユーザーと同じようにアプリを操作する
• 意味のある各ステップでスクリーンショットを撮る — ユーザーはUIの表示を確認したいと考えています
• ローディング状態、エラー状態、空の状態、成功確認に特に注意する
• フロー（例：メール → ルール → 下書き）をテストする場合は、結果を確認する前に非同期処理が完了するまで待つ
• 終了時は必ずagent-browser closeを実行して後片付けする

アプリのルート参照

• アシスタントのチャット：/<emailAccountId>/assistant
• アシスタントのルール：/<emailAccountId>/automation
• アシスタントの設定：/<emailAccountId>/automation?tab=settings
• 一括登録解除：/<emailAccountId>/bulk-unsubscribe
• 設定：/settings

ブラウザー認証

アプリにはOAuthログインが必要です。agent-browserではOAuthを完了できないため、既存のログイン済みセッションがあるChromeプロファイルが必要です。

推奨方法：保存済みプロファイルを使用したヘッドレスChrome

ユーザーは、ログイン済みセッションを保存した専用のChromeプロファイルディレクトリ（リポジトリの外部、例：~/.chrome-debug-inbox-zero）を用意しておく必要があります。プロファイルのパスはユーザーのオートメモリーで確認してください。その後、Chromeをヘッドレスで起動して接続します。

# 1. Check if CDP is already running
curl -s http://127.0.0.1:9222/json/version

# 2. If not, launch Chrome headless with the saved profile
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless=new \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-debug-<name>" &>/dev/null &
sleep 3

# 3. Connect agent-browser
agent-browser close
curl -s -X PUT "http://127.0.0.1:9222/json/new?about:blank" > /dev/null
sleep 2
agent-browser --cdp 9222 open http://localhost:3000/automation

この処理はすべてバックグラウンドで実行されるため、ユーザーが何か操作する必要はありません。

重要な注意事項：

• Chromeでは同じ--user-data-dirを使う2つのインスタンスを起動できません。起動前に、既存のデバッグ用Chromeを終了してください。
• 認証Cookieの有効期限が切れている場合は、Chromeを一度ヘッド付き（--headless=newを指定しない）で起動し、OAuthで再ログインする必要があります。その後、ヘッドレスに戻せます。
• Google OAuthはagent-browser内蔵のChromiumをブロックします（「このブラウザーまたはアプリは安全でない可能性があります」）。実際のChromeを使用する必要があります。
• agent-browserがchrome://の内部ページに接続する場合があります。接続前にagent-browser closeでそれらを閉じてください。

代替方法：

1. CDP経由でユーザーが起動中のChromeに接続する：ユーザーが--remote-debugging-port=9222を指定してChromeをすでに起動している場合は、agent-browser --cdp 9222を使用します。
2. プロファイルを使ったヘッド付きモード：agent-browser --headed --profile <path>を使用して、画面に表示されるChromeウィンドウを開きます。
3. 状態ファイル：サインイン後、agent-browser state save ./auth.jsonで保存し、後でagent-browser --state ./auth.jsonを使って再読み込みします。注意：状態ファイルは有効期限が切れる場合があります。

APIテスト

• まずUIから実際のAPIキーを取得します（設定 → APIキー）。取得手順のスクリーンショットを撮ってください。偽のAPIキーやダミーのAPIキーでテストしないでください。認証エラーによって、実際の機能が動作するかどうかを確認できなくなります。
• 実際のキーを使ってCLI／クライアントを設定し、実際のAPI呼び出しを行って、レスポンスに期待するデータが表示されることを確認します。
• 成功ケースとエラーケースの両方を確認します。

評価テスト

• 評価テストが適切な方法であれば、__tests__/eval/を確認し、同様の内容を扱う既存のテストを探します
• .claude/skills/testing/eval.mdにある評価テストのテンプレートに従います
• 該当する場合は、モデル間の比較にdescribeEvalMatrixを使用します
• 主観的な出力には、適切なCRITERIAを指定してjudgeMultipleを使用します
• pnpm test-ai eval/<test-name>で実行します

ハイブリッドなアプローチ

多くの場合、複数のアプローチを組み合わせるのが最適です。たとえば：

• gws を使って、テスト用の PDF を格納する Google Drive フォルダーを作成します
• ブラウザーを使って、そのフォルダーを使用するよう機能を設定します
• 機能を実行します（メールの送信、チャットの開始など）
• UI（スクリーンショット）と API／データベースの両方で結果を確認します

ステップ 4：結果を報告する

エラーが発生した場合、テストは失敗です。 エラーが設定上の問題に見えても、いずれかのステップでエラーが発生した場合は成功と報告しないでください。設定を修正して再試行するか、失敗したことを明確に報告してください。

合否の概要を明確に示してください：

• テストした内容
• うまくいったこと
• 失敗したこと — スクリーンショットと実際のエラーを添えてください
• 修正のために行ったこと

必ずスクリーンショットを含めてください — テストに合格した場合も同様です。ユーザーは UI の見た目を確認したいと考えています。

ステップ 5：テストを保存する（該当する場合）

テスト後、これを再利用可能なテストにするかユーザーに確認してください。選択肢は 2 つあります。

1. ブラウザー QA フロー — テストが主に UI 主導で、リグレッションを検出できる場合は、テンプレートに従って qa/browser-flows/ にフロースペックを作成します。これにより、/qa-run で再実行できます。

2. Eval テスト — テストが AI の出力品質に関するものの場合は、__tests__/eval/ に適切な Eval テストを作成し、pnpm test-ai で実行できるようにします。

（ページが読み込まれるかどうかなどの）単純な単発チェックは保存しないでください。後で誰かが壊してしまう可能性のある重要な動作を検証するテストを保存してください。

ツールのリファレンス

gws CLI（Google Workspace）

# Create a Drive folder
gws drive files create --json '{"name": "Test Folder", "mimeType": "application/vnd.google-apps.folder"}'

# Upload a file to a folder
gws drive files create --json '{"name": "test.pdf", "parents": ["FOLDER_ID"]}' --upload ./test.pdf

# List Drive files
gws drive files list --params '{"q": "name contains '\''test'\''", "pageSize": 10}'

# Send a Gmail message
gws gmail users messages send --params '{"userId": "me"}' --json '{"raw": "BASE64_ENCODED_MESSAGE"}'

# Create a calendar event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{"summary": "Test Event", "start": {"dateTime": "..."}, "end": {"dateTime": "..."}}'

Eval テストユーティリティ

• describeEvalMatrix(name, fn) — 複数のモデルで実行します
• createEvalReporter() — 合否を記録します
• judgeMultiple({ input, output, criteria }) — LLM による評価
• CRITERIA.* — ACCURACY、COMPLETENESS、TONE、CONCISENESS、NO_HALLUCINATION、CORRECT_FORMAT

既存の QA インフラストラクチャ

• フロースペック：qa/browser-flows/*.md
• フローランナー：/qa-run
• フロー作成ツール：/qa-new-flow
• E2E テスト：__tests__/e2e/flows/
• Eval テスト：__tests__/eval/