# 帳票設計書 11-html

## 概要

本ドキュメントは、Jestのカバレッジレポート機能におけるHTML形式レポートの設計仕様を定義する。istanbul-reportsライブラリを使用し、インタラクティブなHTMLカバレッジレポートを生成する機能について詳述する。

### 本帳票の処理概要

HTMLカバレッジレポートは、Jestテスト実行時に収集されたコードカバレッジ情報を、ブラウザで閲覧可能なインタラクティブなHTML形式で出力する帳票である。ファイル別、ディレクトリ別のカバレッジ率を視覚的に確認でき、各ソースファイルの行単位でのカバレッジ状況を色分け表示する。

**業務上の目的・背景**：開発チームがコードのテストカバレッジを視覚的に把握し、テストが不足している箇所を特定するために使用される。テキスト形式のレポートでは把握しにくい詳細なカバレッジ状況を、ソースコードと紐付けて確認できることで、品質向上のための改善ポイントを明確化する。

**帳票の利用シーン**：コードレビュー時のカバレッジ確認、CI/CD パイプラインでのカバレッジレポート生成、定期的な品質レポート作成、新規開発時のテスト網羅性確認において利用される。

**主要な出力内容**：
1. ディレクトリ/ファイル別カバレッジサマリー（Statements, Branches, Functions, Lines の各カバレッジ率）
2. ソースコード表示画面（行単位のカバレッジ状況を色分け表示）
3. ナビゲーションメニュー（ディレクトリ構造に基づくファイル一覧）
4. Watermark による品質状態の視覚化（低/中/高カバレッジの色分け）

**帳票の出力タイミング**：`jest --coverage` コマンド実行時、または `collectCoverage: true` 設定時にテスト完了後に自動生成される。`coverageReporters` に `'html'` を含めることで出力される。

**帳票の利用者**：開発者、QAエンジニア、テックリード、プロジェクトマネージャー

## 帳票種別

カバレッジ可視化レポート（インタラクティブHTML）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI（コマンドライン） | - | `jest --coverage` コマンド実行 |
| - | 設定ファイル | jest.config.js | `coverageReporters: ['html']` 設定 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | HTML（複数ファイル構成） |
| 用紙サイズ | N/A（Webブラウザ表示） |
| 向き | N/A |
| ファイル名 | `index.html`（エントリーポイント）、各ソースファイルに対応するHTMLファイル |
| 出力方法 | ファイルシステムへの出力 |
| 文字コード | UTF-8 |

### HTML固有設定

| 項目 | 内容 |
|-----|------|
| 出力ディレクトリ | `{coverageDirectory}/lcov-report/` |
| CSS | インライン埋め込み |
| JavaScript | インタラクティブ機能用インラインスクリプト |
| 画像 | SVGアイコン（インライン） |

## 帳票レイアウト

### レイアウト概要

HTMLレポートは複数のHTMLファイルで構成され、ディレクトリ構造を反映したナビゲーション可能なレポートを生成する。

```
coverage/lcov-report/
├── index.html                    # ルートサマリー
├── base.css                      # スタイルシート
├── prettify.js                   # コード整形スクリプト
├── sorter.js                     # テーブルソートスクリプト
├── {source-dir}/
│   ├── index.html               # ディレクトリサマリー
│   └── {source-file}.html       # ファイル別詳細
└── ...
```

### サマリーページ（index.html）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | ヘッダー | 「All files」タイトル | 固定値 | テキスト |
| 2 | カバレッジバー | 全体カバレッジ率のプログレスバー | CoverageMap | プログレスバー |
| 3 | Statements | ステートメントカバレッジ | CoverageSummary.statements | パーセント表示 |
| 4 | Branches | 分岐カバレッジ | CoverageSummary.branches | パーセント表示 |
| 5 | Functions | 関数カバレッジ | CoverageSummary.functions | パーセント表示 |
| 6 | Lines | 行カバレッジ | CoverageSummary.lines | パーセント表示 |
| 7 | ファイル/ディレクトリ一覧 | カバレッジ対象一覧 | CoverageMap.files() | テーブル |

### ファイル詳細ページ

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | ファイルパス | 対象ファイルのパス | FileCoverage.path | パンくずリスト |
| 2 | カバレッジサマリー | ファイル単位のカバレッジ | FileCoverage.toSummary() | バー + パーセント |
| 3 | ソースコード | 実際のソースコード | ソースファイル読み込み | コードブロック |
| 4 | 行番号 | 各行の行番号 | 自動生成 | 数値 |
| 5 | 実行回数 | 各行の実行回数 | FileCoverage.s | 数値（ヒット数） |
| 6 | 分岐情報 | 分岐のカバレッジ状態 | FileCoverage.b | ツールチップ |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| collectCoverage | カバレッジ収集が有効であること | Yes |
| coverageReporters | `'html'` が含まれていること | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | ファイルパス/ディレクトリ名 | 昇順（アルファベット順） |

### 改ページ条件

N/A（HTMLのため改ページは発生しない）

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

### 参照テーブル一覧

本帳票はデータベースを使用せず、テスト実行時に収集されたカバレッジデータ（メモリ上のCoverageMap）を参照する。

| データソース名 | 用途 | 取得方法 |
|---------------|------|---------|
| CoverageMap | カバレッジ情報全体 | `istanbulCoverage.createCoverageMap()` |
| FileCoverage | ファイル単位のカバレッジ | `map.fileCoverageFor(path)` |
| CoverageSummary | サマリー情報 | `fileCoverage.toSummary()` |

### データ構造詳細

#### CoverageSummary

| フィールド | 説明 | 型 |
|-----------|------|-----|
| statements | ステートメントカバレッジ | `{total, covered, skipped, pct}` |
| branches | 分岐カバレッジ | `{total, covered, skipped, pct}` |
| functions | 関数カバレッジ | `{total, covered, skipped, pct}` |
| lines | 行カバレッジ | `{total, covered, skipped, pct}` |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| カバレッジ率 | `(covered / total) * 100` | 小数点以下2桁 | total=0の場合は100% |
| Watermark判定 | 閾値との比較 | - | low/medium/high の3段階 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[テスト実行完了] --> B[CoverageReporter.onRunComplete]
    B --> C[カバレッジデータ収集]
    C --> D[V8/Babel プロバイダーからデータ変換]
    D --> E[istanbulReports.create html 呼び出し]
    E --> F[reportContext生成]
    F --> G[HTMLファイル生成]
    G --> H[coverage/lcov-report/へ出力]
    H --> I[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力失敗 | ディレクトリ書き込み権限なし | `Failed to write coverage reports: ERROR: ...` | coverageDirectory の権限確認 |
| ソースファイル読み込み失敗 | 元ソースが削除されている | レポート内でエラー表示 | ソースファイルの存在確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数千ファイル |
| 目標出力時間 | 大規模プロジェクトで数秒〜数十秒 |
| 同時出力数上限 | 1（シングルプロセスで出力） |

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

- 出力されるHTMLはローカルファイルシステムへの出力のみを想定
- ソースコードがそのまま出力されるため、機密コードを含む場合はレポートの取り扱いに注意
- 公開リポジトリのCI/CDでは、カバレッジレポートを公開する際にセンシティブ情報が含まれていないことを確認

## 備考

- HTMLレポートはデフォルトの `coverageReporters` には含まれていないため、明示的に設定が必要
- `coverageDirectory` で出力先を変更可能（デフォルト: `coverage/`）
- lcovレポートと同じディレクトリ構造（`lcov-report/`）に出力される

---

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

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

### 推奨読解順序

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

HTMLレポート生成に使用されるカバレッジデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.ts | `packages/jest-types/src/Config.ts` | CoverageReporterName型、CoverageReporters型の定義（行132-143） |

**読解のコツ**: istanbul-reportsのReportOptions型をインポートしており、利用可能なレポーター名はistanbul-reportsに依存している。

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

カバレッジレポート生成のエントリーポイントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | onRunCompleteメソッドでレポート生成が開始される |

**主要処理フロー**:
1. **行70-107**: `onRunComplete`メソッドでカバレッジ結果を処理
2. **行78-94**: `coverageReporters`配列をループし、各レポーターを生成
3. **行88-93**: `istanbulReports.create(reporter, options).execute(reportContext)`でレポート出力

#### Step 3: レポートコンテキスト生成を理解する

HTMLレポートに渡されるコンテキストの生成プロセスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | _getCoverageResultメソッド（行437-516） |
| 3-2 | getWatermarks.ts | `packages/jest-reporters/src/getWatermarks.ts` | Watermark閾値の計算（行11-36） |

**主要処理フロー**:
- **行498-504**: V8プロバイダー使用時のreportContext生成
- **行507-515**: Babelプロバイダー使用時のreportContext生成
- **行500-501**: coverageDirectoryとwatermarksの設定

#### Step 4: 設定のデフォルト値を理解する

HTMLレポートの設定方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Defaults.ts | `packages/jest-config/src/Defaults.ts` | デフォルトのcoverageReporters（行28） |

**主要処理フロー**:
- **行28**: デフォルト値は `['json', 'text', 'lcov', 'clover']` でhtmlは含まれない

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

```
jest --coverage
    │
    ├─ TestScheduler
    │      └─ CoverageReporter.onRunComplete()
    │             │
    │             ├─ _addUntestedFiles()（未テストファイルのカバレッジ追加）
    │             │
    │             ├─ _getCoverageResult()
    │             │      ├─ V8/Babelプロバイダーからデータ変換
    │             │      ├─ istanbulReport.createContext()
    │             │      └─ getWatermarks()
    │             │
    │             ├─ istanbulReports.create('html', options)
    │             │      └─ .execute(reportContext)
    │             │             └─ HTMLファイル群を出力
    │             │
    │             └─ _checkThreshold()（閾値チェック）
    │
    └─ coverage/lcov-report/ ディレクトリにHTML出力
```

### データフロー図

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

テスト実行結果         CoverageReporter              coverage/lcov-report/
      │                      │                              │
V8Coverage ────────▶ _getCoverageResult() ─────▶ istanbul-reports
      │                      │                    (html reporter)
BabelCoverage ─────▶ CoverageMap構築                       │
      │                      │                              │
ソースファイル ────▶ FileCoverage抽出 ──────────▶ index.html
                             │                              │
                    CoverageSummary計算 ────────▶ {file}.html
                             │
                    Watermarks適用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | ソース | カバレッジレポート生成の主要ロジック |
| getWatermarks.ts | `packages/jest-reporters/src/getWatermarks.ts` | ソース | Watermark閾値計算 |
| Config.ts | `packages/jest-types/src/Config.ts` | ソース | 型定義（CoverageReporterName等） |
| Defaults.ts | `packages/jest-config/src/Defaults.ts` | ソース | デフォルト設定値 |
| CoverageReporter.test.js | `packages/jest-reporters/src/__tests__/CoverageReporter.test.js` | テスト | CoverageReporterのユニットテスト |
| Configuration.md | `docs/Configuration.md` | ドキュメント | coverageReportersの設定説明 |
