# 画面設計書 33-testament html

## 概要

本ドキュメントは、Nimコンパイラプロジェクトのテストフレームワーク「Testament」における「html」サブコマンドの画面設計書である。testament htmlはテスト結果をHTML形式のレポートとして出力する機能を提供する。

### 本画面の処理概要

testament htmlコマンドは、testresultsディレクトリに保存されたJSON形式のテスト結果を読み込み、視覚的に確認しやすいHTMLレポートを生成する機能を提供する。Bootstrapベースのモダンなデザインで、テスト結果を一覧・フィルタリング可能な形式で出力する。

**業務上の目的・背景**：大規模なテストスイートの実行結果をCLI出力のみで確認するのは困難である。HTMLレポートとして出力することで、ブラウザ上で結果を視覚的に確認でき、成功・失敗・スキップの統計情報、個別テストの詳細（期待値と実際の値の比較）を容易に把握できる。CI/CDパイプラインでアーティファクトとして保存し、チームで共有する用途にも適している。

**画面へのアクセス方法**：コマンドラインから`testament html`の形式で実行する。テスト実行後に結果がtestresultsディレクトリに保存されている必要がある。`--print`オプションを併用すると、生成後にデフォルトブラウザでレポートを開く。

**主要な操作・処理内容**：
1. testresults/*.jsonディレクトリから全てのJSONファイルを読み込み
2. 各テスト結果を集計し、成功/失敗/スキップの統計を計算
3. Bootstrapベースのテンプレート（testamenthtml.nimf）を使用してHTML生成
4. 各テスト結果をパネル形式で出力（期待値・実際値の詳細含む）
5. testresults.htmlファイルとして保存
6. --printオプション時はデフォルトブラウザで開く

**画面遷移**：
- 遷移元：testament メイン画面（コマンドライン引数に「html」を指定）
- 遷移先：生成されたtestresults.html（ブラウザで表示、--print時）

**権限による表示制御**：特になし。CLIツールとして実行権限があれば使用可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | Testament | 主機能 | テスト結果のHTML形式出力処理 |

## 画面種別

CLIコマンド実行画面（HTMLレポート生成）

## URL/ルーティング

```
testament html [options]
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 | 例 |
|--------|-----|------|------|-----|
| --print | flag | No | 生成後にブラウザで開く | - |
| --failing | flag | No | 失敗テストのみ表示 | - |

### 入力ファイル

| ファイル | パス | 形式 | 説明 |
|----------|------|------|------|
| テスト結果JSON | testresults/*.json | JSON | 各テスト実行の結果ファイル |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| HTMLファイル | file | 生成されるレポートファイル（testresults.html） |

### 出力ファイル構造

| セクション | 内容 |
|-----------|------|
| ヘッダー | マシン名、コミット、ブランチ情報 |
| サマリー | 総テスト数、成功/スキップ/失敗の数と割合 |
| テスト一覧 | 各テストのパネル形式一覧 |
| フッター | 生成日時 |

## 表示項目

### HTMLレポート表示項目

| 項目 | 表示形式 | 説明 |
|------|----------|------|
| Machine | テキスト | テスト実行マシン名 |
| Commit | テキスト | Gitコミットハッシュ |
| Branch | テキスト | Gitブランチ名 |
| Total Tests | 数値 | 総テスト数 |
| Passed | 数値 + % | 成功テスト数と割合（緑） |
| Ignored | 数値 + % | スキップテスト数と割合（青） |
| Failed | 数値 + % | 失敗テスト数と割合（赤） |

### テストパネル表示項目

| 項目 | 表示形式 | 説明 |
|------|----------|------|
| テスト名 | テキスト | テストファイル名とオプション |
| カテゴリ | テキスト | テストカテゴリ |
| ターゲット | テキスト | c/cpp/js/objc |
| アクション | テキスト | run/compile/reject |
| 結果 | バッジ | PASS（緑）/FAIL（赤）/SKIP（青） |
| Expected | コードブロック | 期待される出力 |
| Gotten | コードブロック | 実際の出力 |

## イベント仕様

### 1-HTMLレポート生成

ユーザーが`testament html`を実行すると以下の処理が行われる：

1. main()関数でコマンドライン引数を解析
2. `action`が"html"の場合、generateHtml()を呼び出し
3. allTestResults()でtestresults/*.jsonを読み込み
4. 各JSONファイルの配列要素を走査
5. 結果種別（reSuccess/reDisabled/reJoined等）ごとにカウント
6. 成功/スキップ/失敗の割合を計算
7. generateHtmlBegin()でHTMLヘッダーを出力
8. generateAllTestsContent()でテスト一覧を出力
9. 各テストに対してgenerateTestResultPanelPartial()でパネルを出力
10. generateHtmlEnd()でフッターを出力
11. testresults.htmlとして保存
12. --printオプション時はopenDefaultBrowser()で開く

### 2-失敗テストフィルタリング

--failingオプションが指定された場合：

1. allTestResults(onlyFailing=true)を呼び出し
2. reSuccessの結果を除外
3. 失敗テストのみをレポートに含める

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 結果読み込み | testresults/*.json | SELECT | JSON形式のテスト結果を読み込み |
| レポート出力 | testresults.html | INSERT | HTMLレポートを生成・保存 |

### 入力ファイル構造（testresults/*.json）

| フィールド | 型 | 説明 |
|-----------|-----|------|
| name | string | テスト名 |
| category | string | カテゴリ名 |
| target | string | ターゲット |
| action | string | アクション |
| result | string | 結果（reSuccess等） |
| expected | string | 期待値 |
| given | string | 実際の値 |
| commit | string | Gitコミット |
| branch | string | Gitブランチ |
| machine | string | マシン名 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG001 | エラー | "[ERROR] ignoring json file that is not an array: {file}" | 不正なJSONファイル検出時 |

## 例外処理

| 例外条件 | 処理内容 | エラーメッセージ |
|----------|----------|-----------------|
| JSONファイルが配列でない | スキップして警告表示 | "[ERROR] ignoring json file that is not an array: {file}" |
| testresultsディレクトリがない | 空のレポートを生成 | なし |
| JSONパースエラー | 該当ファイルをスキップ | parseFile()のエラー |

## 備考

- 生成されるHTMLはBootstrap 3.3.7を使用したレスポンシブデザイン
- パネルの開閉はBootstrapのcollapseコンポーネントを使用
- 結果に応じてpanel-success（緑）/panel-danger（赤）/panel-info（青）のスタイルを適用
- テスト結果が空の場合でもHTMLファイルは生成される
- generateHtml()関数はhtmlgen.nimに実装されている

---

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

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

### 推奨読解順序

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

まず、テスト結果の集計構造（AllTests）を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | htmlgen.nim | `testament/htmlgen.nim` | AllTests型（64-68行目）でテスト結果の集計構造を定義 |

**読解のコツ**: AllTestsはdata（JSONノード配列）と各種カウント・割合を保持する。totalCount, successCount, ignoredCount, failedCountでテスト数を、successPercentage等で割合を管理。

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

処理の起点となるgenerateHtml()関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | testament.nim | `testament/testament.nim` | main()関数の825-826行目でhtmlコマンド処理 |
| 2-2 | htmlgen.nim | `testament/htmlgen.nim` | generateHtml()関数（123-136行目）がメイン処理 |

**主要処理フロー**:
1. **825行目**: action == "html"の判定
2. **826行目**: generateHtml(resultsFile, optFailing)の呼び出し
3. **831行目**: --printオプション時にopenDefaultBrowser()

#### Step 3: テスト結果収集を理解する

allTestResults()の処理フローを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | htmlgen.nim | `testament/htmlgen.nim` | allTestResults()関数（70-92行目）でJSON収集 |

**主要処理フロー**:
- **72行目**: walkFiles("testresults/*.json")でファイル走査
- **73行目**: parseFile()でJSON読み込み
- **78-83行目**: 結果種別ごとにカウントをインクリメント
- **85-92行目**: 割合の計算

#### Step 4: HTML生成を理解する

HTMLテンプレートとパネル生成を把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | htmlgen.nim | `testament/htmlgen.nim` | generateTestResultPanelPartial()関数（16-62行目）でパネル生成 |
| 4-2 | htmlgen.nim | `testament/htmlgen.nim` | generateAllTestsContent()関数（98-121行目）で全体構成 |
| 4-3 | testamenthtml.nimf | `testament/testamenthtml.nimf` | HTMLテンプレート（Nimfテンプレート形式） |

**主要処理フロー**:
- **16-49行目**: 結果に応じたスタイルクラス設定（success/danger/info）
- **51-62行目**: テンプレート関数呼び出しでHTML出力
- **98-121行目**: ヘッダー情報とテスト一覧の構成

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

```
main()
    │
    ├─ [action = "html"]
    │       │
    │       └─ generateHtml()
    │               │
    │               ├─ allTestResults()
    │               │       │
    │               │       ├─ walkFiles("testresults/*.json")
    │               │       │
    │               │       └─ parseFile() / JSON解析
    │               │
    │               ├─ generateHtmlBegin()
    │               │
    │               ├─ generateAllTestsContent()
    │               │       │
    │               │       ├─ generateHtmlAllTestsBegin()
    │               │       │
    │               │       ├─ generateTestResultsPanelGroupPartial()
    │               │       │       │
    │               │       │       └─ generateTestResultPanelPartial()
    │               │       │               │
    │               │       │               ├─ generateHtmlTestresultPanelBegin()
    │               │       │               │
    │               │       │               ├─ generateHtmlTestresultOutputDetails()
    │               │       │               │
    │               │       │               └─ generateHtmlTestresultPanelEnd()
    │               │       │
    │               │       └─ generateHtmlAllTestsEnd()
    │               │
    │               └─ generateHtmlEnd()
    │
    └─ [--print] openDefaultBrowser()
```

### データフロー図

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

testresults/*.json ───▶ walkFiles() ───▶ ファイルリスト
       │                                │
       ▼                                ▼
各JSONファイル ────────▶ parseFile() ───▶ JsonNode
       │                                │
       ▼                                ▼
JsonNode配列 ─────────▶ allTestResults() ───▶ AllTests構造体
       │                                │
       ▼                                ▼
AllTests ─────────────▶ generateAllTestsContent() ───▶ HTML文字列
       │                                │
       ▼                                ▼
HTML文字列 ───────────▶ writeFile() ───▶ testresults.html
       │                                │
       ▼                                ▼
testresults.html ────▶ openDefaultBrowser() ───▶ ブラウザ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| testament.nim | `testament/testament.nim` | ソース | メインプログラム、htmlコマンド呼び出し |
| htmlgen.nim | `testament/htmlgen.nim` | ソース | HTML生成ロジック |
| testamenthtml.nimf | `testament/testamenthtml.nimf` | テンプレート | HTMLテンプレート（Nimfフォーマット） |
| backend.nim | `testament/backend.nim` | ソース | JSONファイル出力（テスト実行時） |
| testresults/*.json | `testresults/` | データ | テスト結果JSON（入力） |
| testresults.html | `.` | 出力 | 生成されるHTMLレポート |
