元ファイル: システム要件定義の分析と汎用化方法/汎用 E2E テスト完全ガイド.md

汎用 E2E テスト完全ガイド

非エンジニア向け Claude Code プロジェクト共通テスト体系

作成日： 2026年5月23日
根拠： walkinglabs ハーネスエンジニアリング講義10・11・12 1

0. E2Eテストとは何か（1分で理解する）

E2E（End-to-End）テストとは、「ユーザーが実際に使う一連の流れ全体」を最初から最後まで通して確認するテストです。

ユニットテスト（部品テスト）：
  「投稿ボタンのコードが正しく書かれているか」を確認する

E2Eテスト（全体テスト）：
  「記事を書いて → 投稿ボタンを押して → 読者に届く」
  という一連の流れ全体が正しく動くかを確認する

なぜ部品テストだけでは不十分か： 部品は全部正しく動いていても、部品同士をつなぐ「接続部分」で壊れることが最も多い。E2Eテストはその接続部分を含めた全体を確認する唯一の方法である。

1. E2Eテストシナリオの作成方法（具体的なステップ）

ステップ1：「ユーザーが達成したいこと」を1文で書く

シナリオは必ず「ユーザー視点」で書く。技術的な言葉は使わない。

✅ 良い例：「記事を自動生成して、Substackに投稿する」
❌ 悪い例：「APIエンドポイントにPOSTリクエストを送信する」

ステップ2：正常系・異常系・境界系の3種類を必ず書く

種類	意味	例
正常系	すべてが正しく動く場合	記事が正常に投稿される
異常系	何かが壊れた場合	APIが落ちていた場合
境界系	限界値・特殊ケース	文字数が上限ちょうどの場合

正常系だけ書いて満足するのが最も危険なパターン。異常系こそが本番で起きる。

ステップ3：各シナリオを以下の5項目で記述する

### シナリオ ID：[S-01]
**目的：** [何を確認するか・1文]
**前提条件：** [テスト開始時の状態]
**実行手順：**
  1. [最初の操作]
  2. [次の操作]
  3. [最後の操作]
**期待結果：** [何が起きるべきか・具体的に]
**確認方法：** [どうやって確認するか・誰でもできる方法で]
**合否判定：** [ ] PASS / [ ] FAIL
**FAILの場合の記録欄：** [原因・発生箇所・対応状況]

ステップ4：「確認方法」は必ず「人間が目で見て確認できる」レベルで書く

✅ 良い例：「テスト用メールアドレス（test@example.com）の受信箱を開き、
           件名に[TEST]が含まれるメールが届いていることを確認する」

❌ 悪い例：「正常に動作することを確認する」（何を見ればいいか不明）

ステップ5：シナリオに「実行禁止条件」を付ける

本番データや本番環境に触れることを防ぐため、各シナリオに制約を付ける。

⚠️ 実行前チェック（全シナリオ共通）
- [ ] テスト用アカウントを使用していることを確認
- [ ] 本番データベースに接続していないことを確認
- [ ] dry-run モードが有効になっていることを確認

2. 設計段階からE2Eを組み込む開発プロセス（全体像）

全体の流れ

Phase 0：要件定義
  ↓
  「何を作るか」を定義する
  ↓
Phase 1：E2Eシナリオ作成（← ここが「設計段階での組み込み」）
  ↓
  「何ができれば完成か」を定義する
  ↓
Phase 2：SDD（詳細設計）
  ↓
  E2Eシナリオを満たすための設計を行う
  ↓
Phase 3：実装
  ↓
  E2Eシナリオを満たすようにコードを書く
  ↓
Phase 4：E2Eテスト実行
  ↓
  全シナリオをPASS/FAILで記録する
  ↓
Phase 5：RYGゲート判定
  ↓
  全シナリオPASS → Green → 完了宣言可能
  1件でもFAIL → Red → 実装に戻る

重要： Phase 1 で書いたシナリオが「完了の定義書」になる。Phase 4 でそのシナリオを全部通過して初めて「完成した」と言える。

なぜ設計段階で書くのか

設計段階でシナリオを書くと、以下の副次効果が生まれる。

副次効果①：要件の曖昧さが即座に発覚する
「記事を投稿する」というシナリオを書こうとすると、「投稿が成功したかどうかをどうやって確認するのか」という問いが生まれる。この問いに答えられない場合、要件定義が不完全であることが設計段階で判明する。

副次効果②：実装の方向性が明確になる
「テスト用メールアドレスに届くことを確認する」と書いた瞬間、「テスト用メールアドレスを用意する必要がある」という実装上の要件が明らかになる。

副次効果③：完了の定義が共有される
非エンジニアとエンジニア（またはAI）が「何ができれば完成か」を同じ言葉で共有できる。

3. 汎用 E2E_TEST_SCENARIOS.md テンプレート

このテンプレートをすべてのプロジェクトで使い回す。プロジェクト固有の内容だけを書き換える。

# E2E_TEST_SCENARIOS.md
# プロジェクト名：[プロジェクト名]
# 作成日：[YYYY-MM-DD]
# ステータス：[DRAFT / READY / IN_PROGRESS / COMPLETE]

---

## ⚠️ このファイルの使い方

1. このファイルは実装開始前に作成すること
2. 全シナリオがPASSするまで「完了しました」と言ってはならない
3. 実行時は必ずテスト環境・テスト用アカウントを使用すること
4. 本番データ・本番環境への接続は禁止

---

## 実行前チェックリスト（毎回確認）

- [ ] テスト用アカウントでログインしている
- [ ] テスト環境（本番ではない）に接続している
- [ ] dry-run モードが有効になっている（該当する場合）
- [ ] バックアップが取られている（データを扱う場合）

---

## 正常系シナリオ

### S-01：[メインの正常フロー]
**目的：** [最も基本的な使い方が動くことを確認する]
**前提条件：**
- [条件1]
- [条件2]
**実行手順：**
1. [操作1]
2. [操作2]
3. [操作3]
**期待結果：** [具体的に何が起きるべきか]
**確認方法：** [どこを見て・何を確認するか]
**合否判定：** [ ] PASS / [ ] FAIL
**実行日時：**
**実行者（人 or AI）：**
**FAIL時の記録：**

---

### S-02：[別の正常フロー（あれば）]
（同じ形式で記述）

---

## 異常系シナリオ

### S-03：[最も起きやすいエラーケース]
**目的：** [エラーが適切に処理されることを確認する]
**前提条件：** [エラーが起きる状態を作る方法]
**実行手順：**
1. [エラーを意図的に起こす操作]
2. [システムの反応を観察する]
**期待結果：** [エラーメッセージが表示される / ログに記録される / 通知が届く]
**確認方法：** [ログファイルの場所 / 通知の確認場所]
**合否判定：** [ ] PASS / [ ] FAIL
**実行日時：**
**実行者（人 or AI）：**
**FAIL時の記録：**

---

### S-04：[外部サービス障害時の動作]
**目的：** [外部APIが落ちていても安全に処理されることを確認する]
**前提条件：** [外部APIへの接続を意図的に切断する]
**実行手順：**
1. [接続を切断する]
2. [通常の操作を試みる]
**期待結果：** [エラーが記録され、データが失われないこと]
**確認方法：** [ログ・データの確認方法]
**合否判定：** [ ] PASS / [ ] FAIL

---

## 境界系シナリオ

### S-05：[上限値・下限値のテスト]
**目的：** [限界値での動作を確認する]
**前提条件：** [上限ちょうどのデータを用意する]
**実行手順：**
1. [上限値のデータで操作する]
**期待結果：** [正常に処理される / 適切な警告が出る]
**確認方法：** [結果の確認方法]
**合否判定：** [ ] PASS / [ ] FAIL

---

## テスト結果サマリー

| シナリオID | 種類 | 結果 | 実行日 | 備考 |
|---|---|---|---|---|
| S-01 | 正常系 | [ ]PASS / [ ]FAIL | | |
| S-02 | 正常系 | [ ]PASS / [ ]FAIL | | |
| S-03 | 異常系 | [ ]PASS / [ ]FAIL | | |
| S-04 | 異常系 | [ ]PASS / [ ]FAIL | | |
| S-05 | 境界系 | [ ]PASS / [ ]FAIL | | |

---

## RYGゲート判定

- **Green（完了可）：** 全シナリオ PASS
- **Yellow（要確認）：** 境界系のみ FAIL、正常系・異常系は全 PASS
- **Red（完了不可）：** 正常系または異常系に 1 件でも FAIL

**現在の判定：** [ ] Green / [ ] Yellow / [ ] Red

4. Claude Code への指示テンプレート（コピペで使える）

E2Eシナリオ作成を依頼する指示

以下の条件でE2E_TEST_SCENARIOS.mdを作成してください。

プロジェクト：[プロジェクト名]
目的：[何を作るか・1文]
主な機能：
  - [機能1]
  - [機能2]
外部サービス：[使用するAPI・サービス名]

条件：
- 正常系シナリオを最低3つ作成すること
- 異常系シナリオを最低2つ作成すること（外部API障害を必ず含めること）
- 境界系シナリオを最低1つ作成すること
- 確認方法は「人間が目で見て確認できる」レベルで書くこと
- 本番データ・本番環境への接続は禁止と明記すること
- テンプレートは /docs/tests/E2E_TEST_SCENARIOS.md に保存すること

E2Eテスト実行を依頼する指示

E2E_TEST_SCENARIOS.md のシナリオを実行してください。

実行条件（必ず守ること）：
- テスト用アカウント（[テスト用アカウント情報]）を使用すること
- 本番データベース・本番APIには接続しないこと
- dry-run モードを使用すること（該当する場合）
- 各シナリオの結果をPASS/FAILで記録すること
- FAILの場合は原因を3行以内で記述すること
- 全シナリオ完了後にRYGゲート判定を行うこと

実行するシナリオ：[S-01, S-02, S-03 / または「全シナリオ」]

FAILシナリオの修正を依頼する指示

E2E_TEST_SCENARIOS.md の以下のシナリオがFAILしました。

FAILシナリオ：[S-03]
FAIL内容：[記録されていた原因]

以下の条件で修正してください：
- CONSTRAINTS.md の禁止事項を守ること
- FEATURE_LIST.md のスコープ外の修正は行わないこと
- 修正後に同じシナリオを再実行してPASS/FAILを記録すること
- 修正内容をPROGRESS.mdに記録すること

5. プロジェクト別 E2E シナリオの例

例①：Substack 自動投稿システム

シナリオID	種類	内容
S-01	正常系	記事を生成して下書き保存し、テスト用アカウントで確認できる
S-02	正常系	スケジュール投稿が設定した時刻に実行される
S-03	正常系	投稿完了後にSlack通知が届く
S-04	異常系	Substack APIが落ちているとき、エラーログに記録されデータが失われない
S-05	異常系	認証トークンが無効なとき、適切なエラーメッセージが出る
S-06	境界系	文字数が上限（50,000文字）のとき、正常に処理されるか警告が出る

例②：note 自動投稿システム

シナリオID	種類	内容
S-01	正常系	記事を生成してnoteの下書きとして保存される
S-02	正常系	画像付き記事が正しく投稿される
S-03	異常系	note APIが落ちているとき、リトライ処理が動く
S-04	異常系	重複投稿を検知して二重送信を防ぐ
S-05	境界系	タイトルが最大文字数のとき正常に処理される

例③：メルマガ自動配信システム

シナリオID	種類	内容
S-01	正常系	テスト用メールアドレスにメルマガが届く
S-02	正常系	配信停止リストの読者には送信されない
S-03	異常系	メールサーバーが落ちているとき、キューに積まれて後で再送される
S-04	異常系	無効なメールアドレスが含まれていても他の配信は継続される
S-05	境界系	配信リストが10,000件のとき、タイムアウトせずに完了する

6. E2Eテストを「汎用的に」運用するための3つのルール

ルール1：テンプレートは変えない、中身だけ変える
E2E_TEST_SCENARIOS.md のテンプレート構造（5項目・3種類・RYGゲート）はすべてのプロジェクトで同じにする。プロジェクトごとに変えるのはシナリオの内容だけ。

ルール2：「確認方法」に具体的な場所を必ず書く
「確認する」だけでは不十分。「どのファイルの何行目を見るか」「どのURLにアクセスするか」「どのメールアドレスの受信箱を見るか」まで書く。

ルール3：E2Eテストの結果はPROGRESS.mdに必ず記録する
テスト結果は E2E_TEST_SCENARIOS.md 内に記録するとともに、PROGRESS.md にも「E2Eテスト実行：全6シナリオ中5PASS/1FAIL」のように記録する。セッションが切れても状態が復元できる。

汎用 E2Eテスト完全ガイド（非エンジニア向けClaude Code共通体系）

要約

要点