# 帳票設計書 1-DefaultReporter

## 概要

本ドキュメントは、Jestテストフレームワークにおける標準テスト結果レポーター「DefaultReporter」の設計仕様を定義する。DefaultReporterは、テスト実行結果をコンソールに出力する基本的なレポーターであり、すべてのJestプロジェクトでデフォルトで使用される。

### 本帳票の処理概要

DefaultReporterは、Jestのテスト実行中および実行後にテスト結果をリアルタイムでコンソールに出力するレポーターである。テストファイルごとのPASS/FAIL状態、エラーメッセージ、コンソール出力、スナップショット状態などを表示し、開発者がテスト結果を即座に確認できるようにする。

**業務上の目的・背景**：開発者がテストを実行した際、その結果を即座に確認できることは開発効率に直結する。DefaultReporterは、テストの成功・失敗状態をリアルタイムで表示し、失敗時には詳細なエラーメッセージとスタックトレースを提供することで、開発者が問題を迅速に特定・修正できるようにする。また、インタラクティブなターミナル環境では、現在実行中のテストの進捗状況をステータスバーで表示し、長時間のテスト実行でもフィードバックを提供する。

**帳票の利用シーン**：テスト実行時にコンソールに自動的に出力される。CI/CD環境でのビルドログ、ローカル開発環境でのテスト実行結果確認、デバッグ時のエラー追跡などに利用される。

**主要な出力内容**：
1. テストファイルごとのPASS/FAIL状態とファイルパス
2. テスト実行時間とメモリ使用量（設定時）
3. 失敗したテストのエラーメッセージとスタックトレース
4. テスト内のconsole.log出力
5. スナップショットの追加・更新・失敗状態
6. リトライが発生した場合のリトライエラー情報

**帳票の出力タイミング**：テスト実行中および実行完了時にリアルタイムで出力される。各テストファイルの完了時にそのファイルの結果が出力され、インタラクティブモードでは実行中のテストのステータスが継続的に更新される。

**帳票の利用者**：ソフトウェア開発者、QAエンジニア、DevOpsエンジニア、CI/CDシステム

## 帳票種別

テスト結果レポート / コンソール出力

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | N/A | `jest`コマンド実行 |
| CLI-02 | コマンドライン（Watch） | N/A | `jest --watch`コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（コンソール出力） |
| 用紙サイズ | N/A（ターミナル幅に依存） |
| 向き | N/A |
| ファイル名 | N/A（標準出力/標準エラー出力） |
| 出力方法 | コンソール出力（stdout/stderr） |
| 文字コード | UTF-8 |

### コンソール出力設定

| 項目 | 内容 |
|-----|------|
| 色出力 | chalk ライブラリによるANSIカラー対応 |
| インタラクティブモード | ステータス行の動的更新対応 |
| バッファリング | 100ms遅延でのデバウンス処理 |

## 帳票レイアウト

### レイアウト概要

DefaultReporterの出力は、テスト実行の進行に合わせて動的に更新される。インタラクティブモードでは実行中のテストのステータスが表示され、各テストファイル完了時に結果が出力される。

```
┌─────────────────────────────────────┐
│      実行中ステータス（動的更新）      │
├─────────────────────────────────────┤
│      テスト結果ヘッダー               │
│      (PASS/FAIL + ファイルパス)       │
├─────────────────────────────────────┤
│      コンソール出力（あれば）          │
├─────────────────────────────────────┤
│      エラーメッセージ（失敗時）        │
├─────────────────────────────────────┤
│      スナップショット状態             │
└─────────────────────────────────────┘
```

### 実行中ステータス部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | RUNS ラベル | 実行中を示すラベル | 固定値 | 黄色背景の反転テキスト |
| 2 | プロジェクト名 | displayName設定時のプロジェクト名 | Config.ProjectConfig.displayName | 色付きラベル |
| 3 | テストファイルパス | 実行中のテストファイルパス | Test.path | 相対パス表示 |

### テスト結果ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 結果ラベル | PASS/FAIL状態 | TestResult.numFailingTests | 緑(PASS)/赤(FAIL)の反転テキスト |
| 2 | プロジェクト名 | displayName設定時のプロジェクト名 | Config.ProjectConfig.displayName | 色付きラベル |
| 3 | テストファイルパス | テストファイルの相対パス | TestResult.testFilePath | 相対パス |
| 4 | 実行時間 | テスト実行時間（遅い場合） | TestResult.perfStats | 赤背景で秒表示 |
| 5 | メモリ使用量 | ヒープメモリ使用量 | TestResult.memoryUsage | MB単位 |

### エラーメッセージ部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 失敗メッセージ | テスト失敗時のエラーメッセージ | TestResult.failureMessage | スタックトレース付き |
| 2 | リトライエラー | リトライ発生時のエラー情報 | TestResult.testResults[].retryReasons | リトライ番号付き |

### スナップショット状態部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | スナップショット追加 | 新規追加されたスナップショット数 | TestResult.snapshot.added | 緑色テキスト |
| 2 | スナップショット更新 | 更新されたスナップショット数 | TestResult.snapshot.updated | 緑色テキスト |
| 3 | スナップショット失敗 | 一致しなかったスナップショット数 | TestResult.snapshot.unmatched | 赤色テキスト |
| 4 | スナップショット廃止 | 未使用のスナップショット数 | TestResult.snapshot.unchecked | 黄色テキスト |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| テスト実行 | Jestコマンドによるテスト実行 | Yes |
| スキップ判定 | testResult.skipped が false | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | テスト完了順 | 昇順（完了順に出力） |

### 改ページ条件

N/A（コンソール出力のためスクロール表示）

## データベース参照仕様

### 参照テーブル一覧

N/A（ファイルシステムベースのテスト結果を使用）

### データ構造参照

#### AggregatedResult

| 参照項目 | 帳票項目との対応 | 用途 |
|---------|----------------|------|
| startTime | ステータス表示 | テスト開始時刻 |
| numTotalTestSuites | サマリー | 総テストスイート数 |

#### TestResult

| 参照項目 | 帳票項目との対応 | 用途 |
|---------|----------------|------|
| testFilePath | テスト結果ヘッダー | ファイルパス表示 |
| numFailingTests | 結果ラベル | PASS/FAIL判定 |
| failureMessage | エラーメッセージ | 失敗詳細 |
| console | コンソール出力 | console.log等の表示 |
| snapshot | スナップショット状態 | スナップショット情報 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 実行時間(秒) | perfStats.runtime / 1000 | 切り捨て | 1秒未満は表示しない |
| メモリ使用量(MB) | memoryUsage / 1024 / 1024 | 切り捨て | Math.floor使用 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[テスト開始] --> B[onRunStart: ステータス初期化]
    B --> C[onTestStart: テスト開始をステータスに追加]
    C --> D[onTestCaseResult: テストケース結果を追加]
    D --> E[onTestResult: テスト結果を出力]
    E --> F{テスト完了?}
    F -->|No| C
    F -->|Yes| G[onRunComplete: ステータスクリア]
    G --> H[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| テスト失敗 | numFailingTests > 0 | 失敗メッセージとスタックトレース | エラー内容を赤色で表示 |
| 実行エラー | testExecError が存在 | 実行時エラーメッセージ | FAILラベルと共に表示 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数千テストケースまで対応 |
| 目標出力時間 | リアルタイム（100ms以内のデバウンス） |
| 同時出力数上限 | 1（シングルスレッド出力） |

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

- テスト結果には機密情報が含まれる可能性があるため、CI/CDログの公開範囲に注意
- スタックトレースにはファイルパスが含まれるため、本番環境情報の露出に注意
- コンソール出力のキャプチャは攻撃ベクトルとなりうるため、信頼できないコードのテスト時は注意

## 備考

- VerboseReporterはDefaultReporterを継承しており、より詳細な出力を提供する
- `--silent`オプションでコンソール出力を抑制可能
- `--useStderr`オプションで標準エラー出力に出力可能

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-reporters/src/types.ts` | Reporter インターフェース、ReporterOnStartOptions、SummaryOptions の定義を確認 |
| 1-2 | @jest/test-result | `node_modules/@jest/test-result` | AggregatedResult、TestResult、Test 型の構造を確認 |

**読解のコツ**: TypeScriptの型定義を追うことで、レポーターが受け取るデータの全体像を把握できる。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-reporters/src/index.ts` | DefaultReporterのエクスポート確認（28行目） |
| 2-2 | BaseReporter.ts | `packages/jest-reporters/src/BaseReporter.ts` | 基底クラスのライフサイクルメソッド（28-49行目） |

**主要処理フロー**:
1. **28-33行目**: onRunStart - テスト実行開始時の処理
2. **36行目**: onTestCaseResult - テストケース結果の処理
3. **38-42行目**: onTestResult - テスト結果の処理
4. **46-49行目**: onRunComplete - テスト実行完了時の処理

#### Step 3: DefaultReporter の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DefaultReporter.ts | `packages/jest-reporters/src/DefaultReporter.ts` | メインのレポーター実装 |

**主要処理フロー**:
- **45-65行目**: コンストラクタ - Status インスタンスの初期化、stdout/stderrのラップ
- **67-116行目**: __wrapStdio - 標準出力のラップとバッファリング処理
- **147-152行目**: onRunStart - ステータスの初期化
- **154-156行目**: onTestStart - テスト開始のステータス追加
- **170-189行目**: onTestResult - テスト結果の出力処理
- **199-235行目**: printTestFileHeader - 結果ヘッダーとコンソール出力の表示
- **237-248行目**: printTestFileFailureMessage - エラーメッセージの表示

#### Step 4: Status クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Status.ts | `packages/jest-reporters/src/Status.ts` | 実行中ステータスの管理 |

**主要処理フロー**:
- **31-61行目**: CurrentTestList - 実行中テストのリスト管理
- **102-111行目**: runStarted - テスト実行開始時のステータス初期化
- **154-203行目**: get - ステータス表示内容の生成

#### Step 5: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | getResultHeader.ts | `packages/jest-reporters/src/getResultHeader.ts` | PASS/FAILヘッダーの生成 |
| 5-2 | getSnapshotStatus.ts | `packages/jest-reporters/src/getSnapshotStatus.ts` | スナップショット状態の生成 |

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

```
DefaultReporter
    │
    ├─ BaseReporter (継承)
    │      └─ Reporter インターフェース実装
    │
    ├─ Status
    │      ├─ CurrentTestList
    │      └─ getSummary
    │
    ├─ getResultHeader
    │      ├─ formatTestPath
    │      └─ printDisplayName
    │
    ├─ getSnapshotStatus
    │
    └─ jest-message-util
           ├─ formatStackTrace
           ├─ indentAllLines
           └─ separateMessageFromStack
```

### データフロー図

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

AggregatedResult ───▶ DefaultReporter.onRunStart ───▶ ステータス初期化
       │
Test ──────────────▶ DefaultReporter.onTestStart ───▶ ステータス更新
       │
TestCaseResult ────▶ DefaultReporter.onTestCaseResult ─▶ ステータス更新
       │
TestResult ────────▶ DefaultReporter.onTestResult ───▶ コンソール出力
       │                     │
       │                     ├─▶ printTestFileHeader
       │                     │         └─▶ getResultHeader
       │                     │
       │                     └─▶ printTestFileFailureMessage
       │                               └─▶ getSnapshotStatus
       │
       └──────────▶ DefaultReporter.onRunComplete ──▶ ステータスクリア
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DefaultReporter.ts | `packages/jest-reporters/src/DefaultReporter.ts` | ソース | メインレポーター実装 |
| BaseReporter.ts | `packages/jest-reporters/src/BaseReporter.ts` | ソース | 基底クラス |
| Status.ts | `packages/jest-reporters/src/Status.ts` | ソース | ステータス管理 |
| types.ts | `packages/jest-reporters/src/types.ts` | ソース | 型定義 |
| getResultHeader.ts | `packages/jest-reporters/src/getResultHeader.ts` | ソース | ヘッダー生成 |
| getSnapshotStatus.ts | `packages/jest-reporters/src/getSnapshotStatus.ts` | ソース | スナップショット状態 |
| getSummary.ts | `packages/jest-reporters/src/getSummary.ts` | ソース | サマリー生成 |
| index.ts | `packages/jest-reporters/src/index.ts` | ソース | エクスポート定義 |
