Write E2e Case

---
name: write-e2e-case
description: "e2eのケースを、AIが画面を実際に操作して確かめた手順からPlaywrightのテストに書き起こし、対応表と機能一覧に載せる。落ちたケースは、意図した画面の変更による操作の壊れなら直し、製品の退行や期待する結果の失敗なら直さずに報告する。対応表で受け持つケースのない対象を埋めるとき、機能一覧の「手動」「未確認」をe2eにするとき、'この操作をe2eにして'、'e2eが落ちたので直して'、'/write-e2e-case'で使う。"
---

# e2eのケースを書いて直す

AIが画面を利用者と同じように操作して、通る手順と安定したセレクタを見つけ、Playwrightのテストに書き起こす。画面から呼ばれないAPIや、画面では組み合わせが多すぎる不正な入力・権限・上流のエラーは、`write-api-case`でAPIのケースにする。書き起こしたテストはリポジトリに置き、CIでは書いたとおりに動かすだけにする。コミットは、ユーザーの依頼か承認を経て、`CLAUDE.md`のGitの規則に従って行う。AIは書くときと直すときにだけ使い、CIで操作や判定をさせない。

前提は、プロジェクトに検証スキル（`.claude/skills/verify-<app>/`）と、e2eのケースの対応表（`~/.claude/references/verification-map.md`）があり、CIで対応表を照合していること（ワークフローが`verify-map check --ledger`を動かしている）。この3つが揃わなければ、AIがケースを足す条件（`CLAUDE.md`の「調査と検証」）を満たさない。その場合はこのスキルでケースを足さず、候補を示して人に選んでもらう（`spec`）か、`/create-e2e-ci`で対応表とCIの照合を整えることを提案する。

## 1. 書く対象を決める

次のどれかから、1回に扱う対象を決める。

- `verify-map check --ledger`が「受け持つケースも例外もない」と出した対象
- 機能一覧で`手動`や`未確認`の札が付いたサブ機能
- ユーザーが名指しした操作

対象ごとに、期待する結果とその根拠を決める。根拠は`spec`の受け入れ条件と同じ基準（ユーザーの指示、承認済みの仕様、機能一覧、既存の公開契約）にし、今の実装の動きを正解の根拠にしない。保存・更新は開き直したあとの状態まで、不正な入力は変更・送信されないことまで含める。根拠が見つからないものは書かずに、`仕様確認`として報告に回す。

## 2. 操作を探る

検証スキルでアプリを起動し、ブラウザで利用者と同じ操作をして、次を見つける。

- **通る手順**: どの順に何を操作すれば、期待する結果が観測できるか
- **安定したセレクタ**: ARIAのロールとラベル、`getByLabel`、`getByText`の完全一致を優先する。CSSのクラスや要素の順番には頼らない。セレクタがなければ、アプリにラベルを足すかをユーザーに聞く
- **観測できる結果**: 画面の文言、要素の状態（有効・無効、表示・非表示）、APIの応答、モックが受けた要求

DOMにない対象（キャンバスに描いた線や図形など）は、座標を目で決めて書かない。APIの応答やモックのデータなど観測できる値から、画面上の位置を計算する。例えば地図なら、初期の中心とズームから、応答の座標をWeb Mercatorで画面の位置に直す。アプリの内部の状態（ストア、地図のオブジェクト）は読まない。

## 3. 書き起こす

- 1ケース1本のテストにし、ケースIDのタグを1つ付ける（`{ tag: '@case:<id>' }`）
- 同じ変更で、`scenarios.json`にケース（`covers`、`aspects`）を足し、確かめるサブ機能の札を`［e2e: <id>］`にする。サブ機能の一部だけを確かめるなら範囲付きの札にし、残りの範囲には`手動`か`未確認`の札を残す
- 描画を待つ箇所は、固定の待ち時間ではなく、`expect(...).toPass()`や、自動で待つassertionで書く。固定の待ちは、「起きないこと」を確かめる直前だけに使い、その前に同じ操作で「起きること」を確かめるケースを別に持つ
- 内部のsetterやテスト専用の経路を通さない。モックの状態を変えて見る異常系は、既存のモックの仕組みを使う

## 4. 確かめる

次の3つが揃わないケースは足さない。

1. **通る**: 手元で、足したケースを繰り返し動かし、すべて通る（目安は10回。`--repeat-each 10 --retries=0`）。1回でも落ちたら原因を直す。直せなければ、今回書いたテストは残さずに外し、ケースを`pending`（`reason`に理由）にして、サブ機能の札を`［未確認: 理由］`に戻し、もう一度下の3で照合する（`pending`のケースにテストや`［e2e］`の札があると不整合になる）
2. **条件を確かめている**: 期待値を1つ変えると落ちることを、ケースごとに確かめて元に戻す。落ちないテストは条件を確かめていない
3. **整合する**: e2eを全件動かした結果で、`verify-map check`（`--ledger`・`--tests`・`--results`）が不整合なし。足したケースだけを動かした結果で照合するなら、`--cases <動かしたケースID>`を付ける（付けないと、動かしていない既存のケースが未実行として落ちる）。どちらで照合したかと、動かしたケースを証拠に書く

結果は`evidence.md`の「e2eの結果」の表に、ケース、確かめた範囲、繰り返した回数、期待値を変えた確認を書く（`~/.claude/references/evidence.md`）。足したケースは報告でも一覧にする。

## 5. 落ちたケースを直す

e2eが落ちたら、まずトレースとエラーを読み、原因を次のどれかに分ける。

| 原因 | 見分け方 | 扱い |
|---|---|---|
| 操作の壊れ | セレクタが見つからない、手順が合わない。その原因が、承認された画面の変更か、今の作業での意図した変更にある（ボタンの文言を変えた、項目の並びを変えた） | AIが直してよい。利用者の操作として同じこと（同じロールで、名前の付いた要素を、同じ順に操作する）を保ったまま、2の手順で探り直し、4で確かめる |
| 製品の退行 | セレクタが見つからない、手順が合わない。その原因が意図した変更にない（ボタンが消えた、アクセシブルな名前やロールがなくなった、画面に移れない、キーボードで操作できなくなった） | テストを直さない。製品の不具合として報告し、`playbook`の不具合の修正に回す。別のセレクタや別の経路に替えて通すと、退行を隠すことになる |
| 期待する結果の失敗 | 操作は最後まで通り、assertionが期待値と違う値を見た | 直さない。不具合なら`playbook`の不具合の修正に回し、仕様の変更なら、期待値の変更をユーザーに承認してもらう |

操作の壊れか製品の退行か分からないときは、製品の退行として扱い、どの変更が原因かを報告する。

- 期待値を弱めて通さない。`expect`を消す、範囲を広げる、再試行の回数を増やす、のどれも、承認なしに行わない。`test.skip`や`test.fixme`にはしない（`CLAUDE.md`の「削除もskipもしない」）
- 不安定（再試行で通る）なら、原因（待ち方、データの取り合い、描画の時間）を探して直す。直せなければ、テストを外してケースを`pending`に戻すかをユーザーに聞く（テストの削除に当たるため）
- 機能を消して確認対象がなくなったケースは、対応表と一緒に消してよい。それ以外の削除は承認を得る

## 6. 見た目の比較（任意）

DOMで観測できない見た目（線の色、描画の有無）は、Playwrightのスクリーンショットの比較（`toHaveScreenshot`）でe2eにできる場合がある。使うのは、次をすべて満たすときだけにする。

- モックのデータと固定の初期表示で、毎回同じ画面になる。背景の地図タイルなど外部の画像は、固定の画像に差し替える
- 比べる範囲を、確かめたい要素の周りに絞れる
- 比較の基準の画像を、CIと同じ環境（OSとブラウザ）で作れる。手元のOSで作った画像は、CIでは合わない
- CIで10回続けて通る

基準の画像を作り直すのは、期待値を変えることに当たるので、ユーザーの承認を得てから行う。

## やらないこと

- CIでAIに操作させること、AIに結果を判定させること。結果が毎回変わりうるうえ、画面を外部に送ることになる
- e2eの外のテスト（ユニットテストなど）を足すこと。`CLAUDE.md`の規則どおり、ケースはユーザーが示す
- 既存のケースの期待値を、承認なしに変えること