# 機能設計書 24-@jest/test-result

## 概要

本ドキュメントは、Jestのテスト結果の型定義とデータ構造（@jest/test-result）の機能設計を記述する。このパッケージは、テスト実行結果を表現するためのTypeScript型定義とヘルパー関数を提供する。

### 本機能の処理概要

@jest/test-resultは、Jestテスティングフレームワークにおけるテスト結果のデータ構造を定義し、結果の操作・集計を行うヘルパー関数を提供するパッケージである。テストランナー、レポーター、その他のJestコンポーネント間でテスト結果を受け渡すための統一的なインターフェースを提供する。

**業務上の目的・背景**：テスト結果は、個々のテストケースからテストスイート全体、さらには複数のプロジェクトにまたがる集計結果まで、様々なレベルで管理される必要がある。@jest/test-resultは、これらの階層的なテスト結果を型安全に表現し、結果の集計・整形を行うための基盤を提供する。

**機能の利用シーン**：
- テストランナーがテスト結果を生成する際
- レポーターがテスト結果を表示用に整形する際
- カバレッジレポーターが結果を処理する際
- テスト結果プロセッサーが結果を後処理する際

**主要な処理内容**：
1. TestResult: 個別テストファイルの実行結果を表現
2. AggregatedResult: 全テストの集計結果を表現
3. AssertionResult: 個別のテストケース（it/test）の結果
4. SnapshotSummary: スナップショットテストの統計情報
5. addResult: テスト結果を集計結果に追加するヘルパー
6. formatTestResults: 結果を表示用フォーマットに変換

**関連システム・外部連携**：
- @jest/console: コンソール出力バッファ
- @jest/types: 設定・共通型定義
- istanbul-lib-coverage: カバレッジデータ
- jest-haste-map: ファイルシステム情報

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本パッケージは型定義を提供する内部機能 |

## 機能種別

データ構造定義 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| aggregatedResults | AggregatedResult | Yes (addResult) | 集計結果オブジェクト | - |
| testResult | TestResult | Yes (addResult) | 個別テスト結果 | - |
| testPath | string | Yes (buildFailureTestResult) | テストファイルパス | - |
| err | SerializableError | Yes (buildFailureTestResult) | エラー情報 | - |

### 入力データソース

- テストランナー（jest-runner）からのテスト実行結果
- テスト環境からのパフォーマンス統計
- スナップショットテストからの統計情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| TestResult | object | テストファイル単位の結果 |
| AggregatedResult | object | 全テストの集計結果 |
| FormattedTestResults | object | 表示用に整形された結果 |

### 出力先

- レポーター（@jest/reporters）
- テスト結果プロセッサー
- JSONレポート出力

## 処理フロー

### 処理シーケンス

```
1. テスト実行開始
   └─ makeEmptyAggregatedTestResult()で空の集計結果を作成

2. 各テストファイル完了
   └─ TestResult構造でテスト結果を生成
   └─ addResult()で集計結果に追加

3. 全テスト完了
   └─ AggregatedResultに全結果が集計される
   └─ formatTestResults()で表示用に整形

4. レポーター/プロセッサーで結果を処理
```

### フローチャート

```mermaid
flowchart TD
    A[テスト実行開始] --> B[makeEmptyAggregatedTestResult]
    B --> C[テストファイルループ]
    C --> D[TestResult生成]
    D --> E[addResult]
    E --> F{全テスト完了?}
    F -->|No| C
    F -->|Yes| G[AggregatedResult完成]
    G --> H[formatTestResults]
    H --> I[レポーター/プロセッサー]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-24-01 | numTodoTests初期化 | testResult.numTodoTestsが未定義の場合は0に初期化 | addResult呼び出し時 |
| BR-24-02 | テストスイートステータス判定 | skipped→pending、失敗orエラー→failed、それ以外→passed | addResult呼び出し時 |
| BR-24-03 | ステータス判定 | allTestsPassed && allTestsExecuted→passed、allTestsPassed && !allTestsExecuted→focused、それ以外→failed | formatTestResult呼び出し時 |
| BR-24-04 | スナップショット集計 | added/matched/unchecked/unmatched/updatedを各テストから累計 | addResult呼び出し時 |

### 計算ロジック

- numTotalTests = numPassingTests + numFailingTests + numPendingTests + numTodoTests
- snapshot.total = snapshot.added + snapshot.matched + snapshot.unmatched + snapshot.updated

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

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

データベース操作は存在しない（インメモリデータ構造）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | testExecError | テスト実行時にエラーが発生した場合 | buildFailureTestResultでエラー結果を生成 |

### リトライ仕様

リトライ処理は存在しない（データ構造定義パッケージ）。

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

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

## パフォーマンス要件

特になし。メモリ上でのデータ構造操作のみ。

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

特になし。テスト結果のデータ構造を定義するのみ。

## 備考

- 本パッケージは主に型定義を提供し、ランタイムロジックは最小限
- Jest 24以降でnumTodoTestsが追加された

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-test-result/src/types.ts` | 全ての型定義（TestResult, AggregatedResult等） |

**読解のコツ**:
- TestResult（88-131行目）は単一テストファイルの結果を表す
- AggregatedResult（72-74行目）は全テストの集計結果を表す
- AssertionResult（43行目）は個別のtest/itの結果を表す
- TestContext（197-202行目）はテスト実行コンテキストを表す

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-test-result/src/index.ts` | エクスポートされる関数と型 |

**主要処理フロー**:
- **8行目**: formatTestResultsのエクスポート
- **9-14行目**: ヘルパー関数のエクスポート（addResult, buildFailureTestResult等）
- **15-34行目**: 型定義のエクスポート

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | helpers.ts | `packages/jest-test-result/src/helpers.ts` | 結果操作ヘルパー関数 |

**主要処理フロー**:
- **10-43行目**: makeEmptyAggregatedTestResult() - 空の集計結果を作成
- **45-83行目**: buildFailureTestResult() - 失敗テスト結果を構築
- **86-153行目**: addResult() - テスト結果を集計結果に追加
  - **92-94行目**: numTodoTestsの初期化
  - **96-105行目**: テスト数のカウント
  - **107-117行目**: テストスイートステータスの判定
  - **119-152行目**: スナップショットデータの集計
- **155-186行目**: createEmptyTestResult() - 空のテスト結果を作成

#### Step 4: フォーマット関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | formatTestResults.ts | `packages/jest-test-result/src/formatTestResults.ts` | 結果の整形 |

**主要処理フロー**:
- **17-69行目**: formatTestResult() - 個別テスト結果の整形
  - **22-34行目**: testExecErrorがある場合のハンドリング
  - **36-48行目**: skipped状態のハンドリング
  - **50-68行目**: 通常結果の整形とステータス判定
- **71-81行目**: formatTestResults() - 集計結果全体の整形

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

```
@jest/core (TestScheduler)
    │
    └─ @jest/test-result
           │
           ├─ types.ts (型定義)
           │      ├─ TestResult
           │      ├─ AggregatedResult
           │      ├─ AssertionResult
           │      ├─ SnapshotSummary
           │      └─ FormattedTestResults
           │
           ├─ helpers.ts (ヘルパー関数)
           │      ├─ makeEmptyAggregatedTestResult()
           │      ├─ addResult()
           │      ├─ buildFailureTestResult()
           │      └─ createEmptyTestResult()
           │
           └─ formatTestResults.ts
                  └─ formatTestResults()
```

### データフロー図

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

                        makeEmptyAggregatedTestResult()
                                    │
テストランナー ─────────▶ TestResult ─────▶ addResult() ─────▶ AggregatedResult
                                                                    │
                                                                    ▼
                                                          formatTestResults()
                                                                    │
                                                                    ▼
                                                          FormattedTestResults
                                                                    │
                                                                    ▼
                                                          レポーター/プロセッサー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-test-result/src/index.ts` | ソース | パッケージエントリーポイント |
| types.ts | `packages/jest-test-result/src/types.ts` | ソース | 型定義 |
| helpers.ts | `packages/jest-test-result/src/helpers.ts` | ソース | ヘルパー関数 |
| formatTestResults.ts | `packages/jest-test-result/src/formatTestResults.ts` | ソース | 結果整形関数 |
| package.json | `packages/jest-test-result/package.json` | 設定 | パッケージ定義 |
