acceptance-ui

受け入れテスト — UI

実際のブラウザーで、ユーザーと同じようにアプリを操作します。クリック、入力、送信、再読み込みを行い、画面に実際に表示される内容を検証します。コンポーネントテストではネットワークをモックしてコンポーネント自体のロジックを確認しますが、このテストでは、レンダー、リクエスト、レスポンス、再レンダー、永続化という接続された一連の動作を検証します。

acceptance-check から受け入れテスト項目の一部を指定して呼び出すか、フロントエンドの変更に対して直接実行します。項目は記載順に進めてください。

1. アプリを起動し、方法を記録する

docs/agents/project.md の Run locally (dev) を確認します。記録されているコマンドでフロントエンド（および呼び出すバックエンド）を起動します。記載がない場合は起動方法を調べてアプリを起動し、ブラウザーで読み込めることを確認してから、コマンドを ## Run locally (dev) の下にある project.md に記録します。完了条件：アプリが読み込まれ、コマンドが記録されていること。

前提条件 — 認証、データ、環境。 フローにログイン済みセッション、シード済みアカウントやフィクスチャデータ、環境設定（環境変数、テスト用データベース）が必要な場合は、リポジトリ内での用意方法を調べて project.md に記録します。各 spec で毎回手動ログインするのではなく、再利用可能なログイン済み状態（保存した storageState など）を用意してください。ログイン画面や空の画面で止まる実行は、機能ではなくテスト環境を検証していることになります。

2. e2e ハーネスを用意する

リポジトリで別の e2e フレームワーク（Cypress、WebdriverIO、Nightwatch、ネイティブモバイルドライバー）が標準として使われている場合は、そのハーネスでフローを記述します。既存の e2e ハーネスがない場合は、Playwright/Chromium を使用します。

Playwright ハーネスを確認します。@playwright/test がインストールされ、Chromium プロジェクトを含む playwright.config.* があるかを調べます。あれば、それを使います。なければ、@playwright/test をインストールし、chromium プロジェクト、開発サーバーの baseURL、テストディレクトリを含む設定を追加し、実行コマンド（… playwright test --project=chromium）を project.md に記録します。完了条件：Playwright コマンドが spec がゼロでも Chromium に対して実行でき、そのコマンドが記録されていること。

3. 各チェックリスト項目のフローを spec にする

受け入れテスト項目の UI 項目ごとに、ユーザーとして操作する Playwright spec を記述します。ロールまたはラベルで要素を特定し（getByRole、getByLabel）、入力やクリックを行い、画面上のテキスト、入力欄がクリアされたこと、リストの順序、エラーメッセージの表示など、目に見える結果を検証します。項目に「永続化する」とある場合は、page.reload() して状態が保持されることを検証します。project.md の規約に従って、各 spec に要件 ID のタグを付けます（例：test('…', { tag: '@CODE-N.M' }, …)）。

4. Chromium で実行し、問題を切り分ける

spec を Chromium のヘッドレスモードで実行します。失敗を見過ごしてはいけません。ただし、観測可能なテスト結果に基づいて分類します。失敗した spec を再実行してください。

• ユーザーに見えるアサーションでの決定的な失敗 — テキストが間違っている、ステータスが違う、表示されるべき要素がない — は製品の不具合です。 必須のサブスキル：debug を使います。失敗する spec を、修正を検証できるループとして使ってください。根本原因を修正し、回帰テストとして spec を残します。
• 非決定的な失敗（再実行で成功する）またはハーネスの不具合 — 一致しなくなったロケーター、待機不足や競合状態、シード状態の欠如 — は製品ではなく spec の不具合です。ロール／ラベルによるロケーター、待機付きアサーション、実際のフィクスチャを使って決定的にし、再実行します。

実際のアサーションで決定的に失敗した場合に限り、debug を使います。 完了条件：新規の Chromium 実行で、すべての UI フローが成功すること。

5. spec をコミットする

spec は永続的な成果物です。タグを付けてコミットし、verify スイートに加えて finish-branch で再実行されるようにします。新しい実行コマンドがあれば project.md に記録し、結果を受け入れテスト項目に記載します。完了条件：spec がコミットされ、タグ付きで、すべて成功していること。