# 機能設計書 22-@jest/reporters

## 概要

本ドキュメントは、Jestのテスト結果レポート出力機能（@jest/reporters）の機能設計を記述する。このパッケージは、テスト実行結果をさまざまな形式で出力するためのレポーター群を提供する。

### 本機能の処理概要

@jest/reportersは、Jestテスティングフレームワークにおけるテスト結果のレポート機能を担当するパッケージである。テスト実行の進行状況をリアルタイムで表示し、テスト完了後に結果のサマリーやカバレッジ情報を出力する。

**業務上の目的・背景**：テスト結果を開発者にわかりやすく伝えることは、テスト駆動開発やCI/CDパイプラインにおいて極めて重要である。開発者はテストの成功・失敗を即座に把握し、失敗したテストの詳細情報を元にデバッグを行う必要がある。@jest/reportersは、コンソール出力、カバレッジレポート、CI統合など、多様なニーズに対応するレポーター機能を提供する。

**機能の利用シーン**：
- テスト実行時のリアルタイム進行状況表示
- テスト完了後の結果サマリー出力
- コードカバレッジレポートの生成
- GitHub Actionsなどのci環境でのアノテーション出力
- デスクトップ通知によるテスト結果通知

**主要な処理内容**：
1. BaseReporter: すべてのレポーターの基底クラス
2. DefaultReporter: 標準的なテスト結果出力
3. VerboseReporter: 詳細なテスト結果出力（テストケース単位）
4. SummaryReporter: テスト実行サマリーの出力
5. CoverageReporter: コードカバレッジレポートの生成
6. GitHubActionsReporter: GitHub Actionsアノテーション出力
7. NotifyReporter: デスクトップ通知

**関連システム・外部連携**：
- istanbul: コードカバレッジの計測・レポート生成
- node-notifier: デスクトップ通知（オプショナル依存）
- GitHub Actions: CIアノテーション出力
- @jest/test-result: テスト結果のデータ構造

**権限による制御**：この機能に権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | ホームページ | 補助機能 | テスト結果表示機能の紹介（Great Exceptions） |
| 9 | Jest Platformページ | 補助機能 | レポーター機能の利用方法 |
| 22 | Configurationページ | 補助機能 | reporters設定オプションの説明 |

## 機能種別

レポート出力 / データ表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| globalConfig | Config.GlobalConfig | Yes | Jestのグローバル設定 | - |
| context | ReporterContext | No | レポーターコンテキスト（初回実行フラグ等） | - |
| options | SummaryReporterOptions | No | SummaryReporter用オプション | summaryThresholdは数値型 |

### 入力データソース

- テスト実行結果（TestResult、AggregatedResult）
- カバレッジデータ（V8カバレッジまたはBabelカバレッジ）
- 設定ファイル（jest.config.js等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| コンソール出力 | string | テスト結果の文字列出力 |
| カバレッジレポート | File | HTML/JSON/LCOVなどのカバレッジファイル |
| デスクトップ通知 | Notification | システム通知（NotifyReporter） |
| GitHubアノテーション | string | GitHub Actions用の特殊フォーマット出力 |

### 出力先

- 標準出力（stdout）/ 標準エラー出力（stderr）
- カバレッジディレクトリ（coverageDirectory設定）
- システム通知

## 処理フロー

### 処理シーケンス

```
1. onRunStart: テスト実行開始時の初期化
   └─ 推定実行時間の表示、ステータス初期化

2. onTestStart/onTestFileStart: 各テストファイル開始時
   └─ 実行中のテストファイル名をステータスに追加

3. onTestCaseResult: 各テストケース完了時
   └─ 個別テストケースの結果をステータスに反映

4. onTestResult/onTestFileResult: 各テストファイル完了時
   └─ テスト結果ヘッダー出力、失敗メッセージ出力

5. onRunComplete: テスト実行完了時
   └─ サマリー出力、カバレッジレポート生成
```

### フローチャート

```mermaid
flowchart TD
    A[テスト実行開始] --> B[onRunStart]
    B --> C[テストファイルループ]
    C --> D[onTestFileStart]
    D --> E[テストケースループ]
    E --> F[onTestCaseResult]
    F --> G{全テストケース完了?}
    G -->|No| E
    G -->|Yes| H[onTestFileResult]
    H --> I{全テストファイル完了?}
    I -->|No| C
    I -->|Yes| J[onRunComplete]
    J --> K[サマリー出力]
    J --> L[カバレッジレポート生成]
    K --> M[終了]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-22-01 | デフォルトレポーター | reporters設定が未指定の場合、DefaultReporterとSummaryReporterが使用される | 常時 |
| BR-22-02 | Verboseモード | --verbose指定時はVerboseReporterが使用される | --verbose オプション指定時 |
| BR-22-03 | カバレッジしきい値 | coverageThreshold設定を満たさない場合、エラーとなる | カバレッジしきい値設定時 |
| BR-22-04 | サマリー表示条件 | 失敗テスト + ランタイムエラー > 0 かつ テスト数 > summaryThreshold(20) の場合、失敗サマリーを再表示 | 常時 |

### 計算ロジック

- カバレッジしきい値チェック: statements/branches/lines/functions の各カバレッジ率がしきい値を満たすか判定
- 推定実行時間: 過去の実行履歴に基づいて推定

## データベース操作仕様

### 操作別データベース影響一覧

データベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | TypeError | summaryThresholdオプションが数値型でない場合 | 数値型で指定 |
| - | CoverageThresholdError | カバレッジしきい値を満たさない場合 | コードカバレッジを改善 |
| - | ReportWriteError | カバレッジレポート書き込み失敗時 | 出力ディレクトリの権限確認 |

### リトライ仕様

CoverageWorkerでのカバレッジ計測処理には最大2回のリトライが設定されている。

## トランザクション仕様

トランザクション処理は存在しない。

## パフォーマンス要件

- リアルタイム出力のため、出力バッファリングは100msのデバウンス処理
- カバレッジ計測は並列ワーカーで実行可能（maxWorkersに基づく）

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

特になし。ローカル環境でのテスト結果出力のため、セキュリティリスクは低い。

## 備考

- node-notifierはオプショナル依存であり、NotifyReporter使用時のみ必要
- GitHub Actions環境では自動的にアノテーション形式で出力される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-reporters/src/types.ts` | Reporterインターフェース、ReporterContext、SummaryOptionsの定義 |

**読解のコツ**: Reporterインターフェースは各レポーターが実装すべきメソッド（onRunStart, onTestResult, onRunComplete等）を定義している。これらのメソッドはテスト実行のライフサイクルに沿って呼び出される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-reporters/src/index.ts` | パッケージの公開API、エクスポートされるレポータークラス |

**主要処理フロー**:
- **26-32行目**: 各レポータークラスのエクスポート（BaseReporter, CoverageReporter, DefaultReporter等）
- **40-49行目**: utilsオブジェクトのエクスポート（formatTestPath, getSummary等のユーティリティ関数）

#### Step 3: 基底クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BaseReporter.ts | `packages/jest-reporters/src/BaseReporter.ts` | 全レポーターの基底クラス |

**主要処理フロー**:
- **21-73行目**: BaseReporterクラスの定義
- **24-26行目**: log()メソッド - stderrへのメッセージ出力
- **28-33行目**: onRunStart() - テスト開始時のpreRunMessage削除
- **52-54行目**: _setError() - レポート中のエラー設定
- **58-60行目**: getLastError() - エラー取得

#### Step 4: デフォルトレポーターを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | DefaultReporter.ts | `packages/jest-reporters/src/DefaultReporter.ts` | 標準的なテスト結果出力 |

**主要処理フロー**:
- **45-65行目**: コンストラクタ - ステータス初期化、stdout/stderrラップ
- **67-116行目**: __wrapStdio() - 出力バッファリング処理
- **147-152行目**: onRunStart() - テスト開始時の処理
- **170-189行目**: onTestResult() - テスト結果出力
- **199-235行目**: printTestFileHeader() - テストファイルヘッダー出力

#### Step 5: カバレッジレポーターを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | カバレッジレポート生成 |

**主要処理フロー**:
- **50-57行目**: コンストラクタ - カバレッジマップ初期化
- **59-68行目**: onTestResult() - カバレッジデータ収集
- **70-107行目**: onRunComplete() - カバレッジレポート生成
- **224-435行目**: _checkThreshold() - カバレッジしきい値チェック
- **437-516行目**: _getCoverageResult() - カバレッジ結果の取得と変換

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

```
@jest/core (TestScheduler)
    │
    └─ @jest/reporters
           │
           ├─ BaseReporter (基底クラス)
           │      │
           │      ├─ DefaultReporter
           │      │      └─ VerboseReporter
           │      │
           │      ├─ SummaryReporter
           │      │
           │      ├─ CoverageReporter
           │      │      └─ CoverageWorker
           │      │
           │      ├─ GitHubActionsReporter
           │      │
           │      └─ NotifyReporter
           │
           └─ utils
                  ├─ formatTestPath
                  ├─ getResultHeader
                  ├─ getSnapshotSummary
                  └─ getSummary
```

### データフロー図

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

TestResult ────────▶ DefaultReporter ────────▶ コンソール出力
                           │
AggregatedResult ──▶ SummaryReporter ────────▶ サマリー出力
                           │
V8Coverage ────────▶ CoverageReporter ───────▶ カバレッジレポート
                           │                        (HTML/JSON/LCOV)
                           │
                    GitHubActionsReporter ───▶ GitHub Annotations
                           │
                    NotifyReporter ──────────▶ デスクトップ通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-reporters/src/index.ts` | ソース | パッケージエントリーポイント |
| types.ts | `packages/jest-reporters/src/types.ts` | ソース | 型定義 |
| BaseReporter.ts | `packages/jest-reporters/src/BaseReporter.ts` | ソース | 基底レポータークラス |
| DefaultReporter.ts | `packages/jest-reporters/src/DefaultReporter.ts` | ソース | デフォルトレポーター |
| VerboseReporter.ts | `packages/jest-reporters/src/VerboseReporter.ts` | ソース | 詳細レポーター |
| SummaryReporter.ts | `packages/jest-reporters/src/SummaryReporter.ts` | ソース | サマリーレポーター |
| CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | ソース | カバレッジレポーター |
| CoverageWorker.ts | `packages/jest-reporters/src/CoverageWorker.ts` | ソース | カバレッジ計測ワーカー |
| GitHubActionsReporter.ts | `packages/jest-reporters/src/GitHubActionsReporter.ts` | ソース | GitHub Actions統合 |
| NotifyReporter.ts | `packages/jest-reporters/src/NotifyReporter.ts` | ソース | 通知レポーター |
| Status.ts | `packages/jest-reporters/src/Status.ts` | ソース | 実行ステータス管理 |
| getSummary.ts | `packages/jest-reporters/src/getSummary.ts` | ソース | サマリー生成 |
| getSnapshotSummary.ts | `packages/jest-reporters/src/getSnapshotSummary.ts` | ソース | スナップショットサマリー |
| package.json | `packages/jest-reporters/package.json` | 設定 | パッケージ定義 |
