# 通知設計書 7-テスト失敗詳細通知

## 概要

本ドキュメントは、Jestテストフレームワークにおけるコンソール出力機能のうち、テスト失敗時の詳細なエラーメッセージとスタックトレースをコンソールへ出力する「テスト失敗詳細通知」の設計を記載する。

### 本通知の処理概要

テスト失敗詳細通知は、テストが失敗した際に詳細なエラー情報（失敗理由、期待値と実際値の差分、スタックトレース等）をコンソールへ出力する機能である。DefaultReporter.printTestFileFailureMessageメソッドで実行される。

**業務上の目的・背景**：テストが失敗した場合、開発者は失敗の原因を特定して修正する必要がある。テスト失敗詳細通知により、アサーションの失敗内容、期待値と実際値の比較、エラーが発生したコードの場所などの詳細情報が提供され、デバッグ作業を効率化する。

**通知の送信タイミング**：テストファイルの実行完了時（onTestResult → printTestFileFailureMessage内）で、failureMessageが存在する場合に出力される。

**通知の受信者**：テストを実行した開発者のコンソール（標準エラー出力）に表示される。

**通知内容の概要**：失敗したテストケースのエラーメッセージ（アサーション失敗の詳細、例外メッセージ等）とスタックトレースが表示される。また、スナップショットテストの状態（追加/更新/削除/不一致）も併せて表示される。

**期待されるアクション**：開発者はエラーメッセージとスタックトレースを確認し、失敗の原因を特定して、テストコードまたはプロダクションコードを修正する。

## 通知種別

コンソール出力（標準エラー出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（printTestFileFailureMessage内で直接呼び出し） |
| 優先度 | 高 |
| リトライ | なし |

### 送信先決定ロジック

logメソッドを通じて標準エラー出力（process.stderr）に対して出力する。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | process.stderr |
| 形式 | テキスト（フォーマット済み） |

### 本文テンプレート

```
  ● {testName}

    {errorType}: {errorMessage}

      {expectedValue}
      {receivedValue}

      {stackTrace}
```

例:
```
  ● should return sum of two numbers

    expect(received).toBe(expected) // Object.is equality

    Expected: 5
    Received: 4

      at Object.<anonymous> (src/__tests__/math.test.ts:10:17)
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| failureMessage | 失敗メッセージ全体 | TestResult.failureMessage | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| イベント | onTestResult → printTestFileFailureMessage | result.failureMessage存在 | テスト結果に失敗メッセージがある場合 |

### 送信条件詳細

printTestFileFailureMessage内でresult.failureMessageが存在する場合に出力される。

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| result.failureMessage === undefined または空 | 失敗メッセージがない場合（テスト成功時） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[onTestResult発火] --> B[printTestFileFailureMessage呼び出し]
    B --> C{failureMessage存在?}
    C -->|No| E[getSnapshotStatus呼び出し]
    C -->|Yes| D[log failureMessage]
    D --> E
    E --> F[スナップショットステータス出力]
    F --> G[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

本通知はデータベースを使用しない。メモリ上のデータ構造からデータを取得する。

| データソース | 用途 | 備考 |
|-----------|------|------|
| TestResult | テスト結果 | printTestFileFailureMessage引数 |
| GlobalConfig | グローバル設定 | updateSnapshot設定の参照 |

### 参照項目詳細

#### TestResult

| 参照項目 | 用途 | 取得条件 |
|--------|------|---------|
| failureMessage | 失敗メッセージ | なし |
| snapshot | スナップショット情報 | なし |

#### GlobalConfig

| 参照項目 | 用途 | 取得条件 |
|--------|------|---------|
| updateSnapshot | スナップショット更新モード | なし |

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | printTestFileFailureMessageは安全に実行される | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | N/A |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（テスト結果出力時に即座に出力）

## セキュリティ考慮事項

- コンソール出力のみのため、外部への情報漏洩リスクはない
- エラーメッセージにはテストデータや期待値が含まれる可能性があるため、機密データをテストに使用しないよう注意が必要
- スタックトレースにはソースコードのパスが含まれる
- ローカル環境でのみ表示される

## 備考

- `failureMessage`はJest内部でフォーマット済みの文字列
- `getSnapshotStatus`は追加でスナップショット関連のステータスメッセージを生成
- `didUpdate`フラグ（updateSnapshot === 'all'）により、スナップショットが更新されたか削除待ちかが判定される
- jest-circusランナーでは、失敗メッセージは個別テストケースの結果を集約して生成される

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、通知処理で使用されるデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TestResult型 | `packages/jest-test-result` | TestResult.failureMessage、TestResult.snapshotの構造を確認 |

**読解のコツ**: failureMessageはJest内部でフォーマット済みの文字列。個別テストケースの失敗メッセージを連結したもの。

#### Step 2: エントリーポイントを理解する

処理の起点となるファイル・関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DefaultReporter.ts | `packages/jest-reporters/src/DefaultReporter.ts` | printTestFileFailureMessageメソッド |

**主要処理フロー**:
1. **237-248行目**: `printTestFileFailureMessage`メソッド
2. **242行目**: `result.failureMessage`の存在チェック
3. **243行目**: `this.log(result.failureMessage)`で失敗メッセージ出力
4. **245行目**: `didUpdate`フラグの設定
5. **246行目**: `getSnapshotStatus`呼び出し
6. **247行目**: スナップショットステータスのループ出力

#### Step 3: スナップショットステータスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | getSnapshotStatus.ts | `packages/jest-reporters/src/getSnapshotStatus.ts` | スナップショットステータス生成 |

**主要処理フロー**:
- **19-74行目**: `getSnapshotStatus`関数
- **25-31行目**: スナップショット追加時のメッセージ
- **33-38行目**: スナップショット更新時のメッセージ
- **40-47行目**: スナップショット不一致時のメッセージ
- **49-67行目**: スナップショット未チェック時のメッセージ
- **69-71行目**: スナップショットファイル削除時のメッセージ

### プログラム呼び出し階層図

```
DefaultReporter.onTestResult()
    │
    └─ printTestFileFailureMessage()
           │
           ├─ [failureMessage存在] log(failureMessage)
           │
           └─ getSnapshotStatus()
                  │
                  ├─ [added] "X snapshots written."
                  │
                  ├─ [updated] "X snapshots updated."
                  │
                  ├─ [unmatched] "X snapshots failed."
                  │
                  ├─ [unchecked]
                  │      ├─ [didUpdate] "X snapshots removed."
                  │      └─ [!didUpdate] "X snapshots obsolete."
                  │
                  └─ [fileDeleted] "snapshot file removed."
```

### データフロー図

```
[入力]                    [処理]                         [出力]

TestResult ─────────────▶ printTestFileFailureMessage()
  failureMessage                │
  snapshot                      │
    added                       ├─▶ [failureMessage存在]
    updated                     │       └─▶ log() ───▶ stderr
    unmatched                   │              └─ "● testName\n..."
    unchecked                   │
    uncheckedKeys               │
    fileDeleted                 ├─▶ getSnapshotStatus()
                                │       │
GlobalConfig ───────────────────┤       └─▶ ステータス配列
  updateSnapshot                │
                                └─▶ for (status) log() ───▶ stderr
                                           └─ "› X snapshots ..."
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DefaultReporter.ts | `packages/jest-reporters/src/DefaultReporter.ts` | ソース | printTestFileFailureMessage実装（237-248行目） |
| getSnapshotStatus.ts | `packages/jest-reporters/src/getSnapshotStatus.ts` | ソース | スナップショットステータス生成 |
| BaseReporter.ts | `packages/jest-reporters/src/BaseReporter.ts` | ソース | log()メソッド |
| TestResult型 | `packages/jest-test-result` | 型定義 | failureMessage、snapshot |
