# 通知設計書 13-カバレッジレポート出力通知

## 概要

本ドキュメントは、Jestテストフレームワークにおけるカバレッジレポート出力通知機能の設計について記載する。CoverageReporterクラスの`onRunComplete`メソッドによって実装され、テスト実行完了後にカバレッジレポートをコンソールに出力する。

### 本通知の処理概要

**業務上の目的・背景**：コードカバレッジは、テストがソースコードをどの程度網羅しているかを示す重要な指標である。カバレッジレポートを出力することで、開発者はテストの品質を把握し、カバレッジが不足している領域を特定できる。デフォルトではtext-summary形式で出力され、ステートメント、ブランチ、関数、行のカバレッジ率を一目で確認できる。

**通知の送信タイミング**：テスト実行完了後、`onRunComplete`メソッドが呼び出された際に出力される。`_addUntestedFiles`による未テストファイルのカバレッジ収集と`_getCoverageResult`によるカバレッジ結果の集計が完了した後に出力される。

**通知の受信者**：コンソールを監視している開発者。CI/CD環境ではログ収集システムを通じて開発チーム全体に共有される。

**通知内容の概要**：カバレッジレポーターの設定に応じて、text、text-summary、lcov、html等の形式でカバレッジ情報が出力される。デフォルトはtext-summary形式で、全体のカバレッジ率がコンパクトに表示される。

**期待されるアクション**：開発者はカバレッジ率を確認し、カバレッジが低い場合は追加のテストを作成する。CI/CD環境ではカバレッジ閾値のチェックと組み合わせて品質ゲートとして使用する。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | なし |

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

設定された`coverageReporters`に応じて出力先が決定される。text/text-summaryは標準出力に出力。html/lcovはファイルシステムに出力。

## 通知テンプレート

### コンソール出力形式

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準出力（stdout）またはファイル |
| 形式 | テキスト（text-summary）またはHTML/LCOV |

### 本文テンプレート（text-summary形式）

```
=============================== Coverage summary ===============================
Statements   : XX.XX% ( XXX/XXX )
Branches     : XX.XX% ( XXX/XXX )
Functions    : XX.XX% ( XXX/XXX )
Lines        : XX.XX% ( XXX/XXX )
================================================================================
```

### サポートされるレポート形式

| 形式 | 出力先 | 説明 |
|------|-------|------|
| text | stdout | 詳細なファイル別カバレッジ表 |
| text-summary | stdout | サマリーのみ |
| html | coverageDirectory/lcov-report/ | HTMLレポート |
| lcov | coverageDirectory/lcov.info | LCOV形式 |
| json | coverageDirectory/coverage-final.json | JSON形式 |
| cobertura | coverageDirectory/cobertura-coverage.xml | Cobertura XML |

### 添付ファイル

なし（ファイル形式の場合はcoverageDirectoryに出力）

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| coverageMap | カバレッジデータ | _getCoverageResult().map | Yes |
| coverageReporters | レポート形式の配列 | _globalConfig.coverageReporters | No |
| coverageDirectory | 出力ディレクトリ | _globalConfig.coverageDirectory | Yes |
| watermarks | カバレッジの色分け閾値 | getWatermarks() | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| テスト完了後 | onRunComplete | カバレッジ収集が有効 | CoverageReporter.onRunComplete()で実行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| カバレッジ収集無効 | --coverage オプションが指定されていない場合 |
| useStderr=true & レポーターなし | useStderrが有効でcoverageReportersが空の場合、text-summaryを自動追加しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[onRunComplete呼び出し] --> B[_addUntestedFiles]
    B --> C[_getCoverageResult]
    C --> D{coverageReporters設定?}
    D -->|空 & !useStderr| E[text-summary追加]
    D -->|設定あり| F[設定を使用]
    E --> G[各レポーター実行]
    F --> G
    G --> H{レポーター配列?}
    H -->|Yes| I[additionalOptionsを分離]
    H -->|No| J[デフォルトオプション]
    I --> K[istanbulReports.create]
    J --> K
    K --> L[reportContext.execute]
    L --> M[aggregatedResults.coverageMap設定]
    M --> N[_checkThreshold]
    N --> O[終了]
```

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

### 参照テーブル一覧

本機能はデータベースを使用しない。

### テーブル別参照項目詳細

該当なし（メモリ内のカバレッジマップを参照）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| レポート書き込み失敗 | istanbulReportsの実行でエラー | console.errorで赤色出力（エラーメッセージとスタックトレース） |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし

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

- カバレッジレポートにはファイルパスが含まれるため、公開する際は注意が必要
- HTMLレポートには詳細なソースコードが含まれる可能性がある

## 備考

- istanbul-lib-reportとistanbul-reportsを使用してレポートを生成
- V8カバレッジとIstanbulカバレッジの両方に対応
- maxColsはprocess.stdout.columnsまたは無限大に設定

---

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

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

### 推奨読解順序

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

カバレッジレポートで扱うデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L42-46: メンバー変数の定義（_coverageMap, _v8CoverageResults） |
| 1-2 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L437-440: _getCoverageResultの戻り値（map, reportContext） |

**読解のコツ**: istanbulCoverage.CoverageMapとistanbulReport.Contextの2つが核となるデータ構造。

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

処理の起点となるonRunCompleteメソッドを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L70-107: onRunCompleteメソッド全体 |

**主要処理フロー**:
1. **L74**: `_addUntestedFiles`で未テストファイルのカバレッジ収集
2. **L75**: `_getCoverageResult`でカバレッジ結果を取得
3. **L77**: try-catch開始
4. **L78-81**: coverageReportersの設定とtext-summaryのデフォルト追加
5. **L83-94**: 各レポーターの実行ループ
6. **L95**: aggregatedResults.coverageMapにマップを設定
7. **L96-103**: エラーハンドリング
8. **L106**: `_checkThreshold`でカバレッジ閾値チェック

#### Step 3: レポート生成処理の詳細

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L83-94: レポーター実行ループ |

**主要処理フロー**:
- **L83-87**: 配列形式のレポーター設定からオプションを分離
- **L88-93**: istanbulReports.create()でレポーター作成、execute()で実行

#### Step 4: カバレッジ結果の集計処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L437-516: _getCoverageResultメソッド |

**主要処理フロー**:
- **L441-505**: V8カバレッジプロバイダーの場合の処理
- **L507-515**: Istanbulカバレッジプロバイダーの場合の処理
- **L498-503, L508-513**: reportContextの作成（coverageMap, dir, watermarks）

#### Step 5: エラー処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L96-103: catch節 |

**主要処理フロー**:
- **L97-102**: console.errorでchalk.redを使用してエラーメッセージとスタックトレースを出力

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

```
CoverageReporter.onRunComplete (L70)
    │
    ├─ _addUntestedFiles (L74)
    │
    ├─ _getCoverageResult (L75)
    │      │
    │      ├─ [V8] mergeProcessCovs (L442)
    │      │      │
    │      │      ├─ v8toIstanbul (L470)
    │      │      │
    │      │      └─ converter.applyCoverage (L486)
    │      │
    │      └─ [Istanbul] _sourceMapStore.transformCoverage (L507)
    │
    ├─ istanbulReports.create (L88) ← 各レポーター
    │      │
    │      └─ execute (L93) ← レポート出力
    │
    └─ _checkThreshold (L106)
```

### データフロー図

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

testContexts ─────────────▶ _addUntestedFiles
                                   │
_v8CoverageResults ───────────────┤
_coverageMap ────────────────────┤
                                  │
                                  ▼
                          _getCoverageResult
                                  │
                                  ├──▶ map (CoverageMap)
                                  │
                                  └──▶ reportContext
                                           │
                                           ▼
                                    istanbulReports.create
                                           │
                                           ▼
                                       execute()
                                           │
                    ┌──────────────────────┼──────────────────────┐
                    ▼                      ▼                      ▼
              stdout (text)        coverageDir/          aggregatedResults
                                   (html, lcov)          .coverageMap
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | ソース | メイン実装ファイル |
| getWatermarks.ts | `packages/jest-reporters/src/getWatermarks.ts` | ソース | カバレッジ色分け閾値の取得 |
| istanbul-lib-coverage | (外部) | ライブラリ | カバレッジマップの管理 |
| istanbul-lib-report | (外部) | ライブラリ | レポートコンテキストの作成 |
| istanbul-reports | (外部) | ライブラリ | 各種形式のレポーター実装 |
| v8-to-istanbul | (外部) | ライブラリ | V8カバレッジをIstanbul形式に変換 |
| @bcoe/v8-coverage | (外部) | ライブラリ | V8カバレッジデータのマージ |
