# 画面設計書 29-testamentメイン画面

## 概要

本ドキュメントは、Testamentツールのメイン画面（CLIインターフェース）に関する画面設計書である。

### 本画面の処理概要

testamentは、Nimコンパイラおよび標準ライブラリのテストランナーである。テストケースの実行、結果の検証、HTMLレポートの生成を行う。

**業務上の目的・背景**：Nimコンパイラの品質保証において、包括的なテストスイートの実行は不可欠である。testamentは、コンパイラの挙動検証、エラーメッセージの確認、実行結果の比較など、多様なテストシナリオをサポートする。CIパイプラインに組み込むことで、リグレッションの早期検出が可能となる。

**画面へのアクセス方法**：コマンドラインから直接実行する。
```
testament [options] command [arguments]
```

**主要な操作・処理内容**：
1. コマンドライン引数を解析（コマンド、オプション）
2. テストケースを収集
3. 各テストケースをコンパイル・実行
4. 期待値と結果を比較
5. 結果をレポート

**画面遷移**：
- 遷移元: シェル/ターミナルからの直接実行
- 遷移先: 処理完了後、テスト統計を表示してシェルに戻る

**権限による表示制御**：本ツールはCLIベースであり、権限による表示制御は存在しない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | Testament | 主機能 | Nimコンパイラ用テストランナーのメイン処理 |
| 4 | コンパイラフロントエンド | 補助機能 | テスト対象コードのコンパイル |

## 画面種別

コマンドライン（CLI）

## URL/ルーティング

```
# 単一テスト実行
testament r tests/mytest.nim

# カテゴリ全体を実行
testament cat category_name

# 全テスト実行
testament all

# パターンマッチでテスト実行
testament pattern "test_*.nim"

# HTMLレポート生成
testament html
```

## 入出力項目

### コマンド

| コマンド | 説明 |
|---------|------|
| r, run | 単一テストファイルを実行 |
| c, cat, category | カテゴリ内の全テストを実行 |
| p, pat, pattern | パターンにマッチするテストを実行 |
| all | 全カテゴリの全テストを実行 |
| html | testresults.htmlを生成 |

### コマンドラインオプション

| オプション | 型 | 説明 |
|-----------|-----|------|
| --print | flag | 結果をコンソールに出力 |
| --verbose | flag | コンパイル・実行コマンドを表示 |
| --simulate | flag | テストを実行せずにリストを表示 |
| --failing | flag | 失敗/スキップのテストのみ表示 |
| --targets | string | 対象ターゲット（c, cpp, js, objc） |
| --nim | string | 使用するNimコンパイラのパス |
| --directory | string | 作業ディレクトリを変更 |
| --colors | on/off | 色付け表示の有効/無効 |
| --backendLogging | on/off | バックエンドログの有効/無効 |
| --megatest | on/off | メガテストの有効/無効 |
| --valgrind | on/off | valgrindの有効/無効 |
| --skipFrom | string | スキップリストファイル |

### 入力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| command | string | 実行コマンド |
| arguments | seq[string] | コマンド引数（テストファイル、カテゴリ名等） |

### 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| テスト結果 | string | PASS/FAIL/SKIP/JOINEDの表示 |
| 統計情報 | string | 合計、成功数、失敗数、スキップ数 |

## 表示項目

テスト結果として以下の情報が表示される:

| 表示項目 | 説明 | 例 |
|---------|------|-----|
| PASS | 成功したテスト | `PASS: tests/foo/test1.nim c (1.23 sec)` |
| FAIL | 失敗したテスト | `FAIL: tests/foo/test2.nim c (0.45 sec)` |
| SKIP | スキップされたテスト | `SKIP: tests/foo/test3.nim` |
| Expected/Gotten | 失敗時の期待値と実際値 | diff形式で表示 |
| 統計 | 最終統計 | `total: 100 passed: 95 skipped: 3 failed: 2` |

## イベント仕様

### 1-コマンドライン解析

1. initOptParserでオプションを解析（行693-756）
2. コマンドを特定（all, cat, pattern, run, html）
3. テスト対象を特定

### 2-テスト実行（all/cat/pattern）

1. processCategory関数でカテゴリ処理（行807）
2. makeTestでテスト情報を構築（行627-634）
3. testSpec関数で実際のテストを実行（行603-619）

### 3-テスト検証

1. callNimCompilerでコンパイル（行174-230）
2. 実行結果と期待値を比較（cmpMsgs等）
3. finishTest/addResultで結果を記録（行279-345）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| テスト結果記録 | SQLiteDB | INSERT | backend.writeTestResultで結果を保存 |

testamentはSQLiteデータベースに結果を保存し、HTMLレポート生成に使用する。

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|---------|
| 情報 | `PASS: test_name (X.XX sec)` | テスト成功時 |
| エラー | `FAIL: test_name` | テスト失敗時 |
| 情報 | `SKIP: test_name` | テストスキップ時 |
| 情報 | `Used nim to run the tests. Use --nim to override.` | 実行完了時 |
| エラー | `FAILURE! total: X passed: Y skipped: Z failed: W` | 失敗があった場合 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 引数なし | Usageを表示して終了 |
| 不明なコマンド | Usageを表示して終了 |
| テストファイルが見つからない | スキップとして記録 |
| コンパイルエラー | FAILとして記録、詳細を表示 |
| タイムアウト | reTimetimeoutとして記録 |

## 備考

- テスト結果はtestresults.dbに保存される
- Azure Pipelines統合がサポートされている
- メガテスト機能で複数のテストを1つのコンパイルにまとめることが可能
- valgrindによるメモリリーク検出をサポート
- specファイル（.nim）内のコメントでテスト動作を制御

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | testament.nim | `testament/testament.nim` | TResults型（行88-91）、統計情報 |
| 1-2 | testament.nim | `testament/testament.nim` | TTest型（行92-99）、テスト情報 |
| 1-3 | specs.nim | `testament/specs.nim` | TSpec型、テスト仕様 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | testament.nim | `testament/testament.nim` | main関数（行684-841） |

**主要処理フロー**:
1. **行693-756**: コマンドライン解析
2. **行762-803**: "all"コマンド処理
3. **行804-827**: 各コマンドの分岐処理

#### Step 3: テスト実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | testament.nim | `testament/testament.nim` | testSpec関数（行603-619） |
| 3-2 | testament.nim | `testament/testament.nim` | testSpecHelper関数（行489-569） |
| 3-3 | testament.nim | `testament/testament.nim` | callNimCompiler関数（行174-230） |

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

```
main (行684)
    │
    ├─ initOptParser - オプション解析 (行693)
    │
    ├─ [all コマンド]
    │      │
    │      └─ execProcesses - 並列実行 (行803)
    │
    ├─ [cat コマンド]
    │      │
    │      └─ processCategory (行807)
    │             │
    │             └─ testSpec (行603)
    │                    │
    │                    ├─ parseSpec - テスト仕様読み込み
    │                    │
    │                    └─ testSpecHelper (行489)
    │                           │
    │                           ├─ callNimCompiler (行174)
    │                           │
    │                           └─ finishTest / addResult
    │
    ├─ [run コマンド]
    │      │
    │      └─ processSingleTest (行824)
    │
    └─ [html コマンド]
           │
           └─ generateHtml (行826)
```

### データフロー図

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

コマンドライン            testament                       ターミナル/DB
    │                         │                              │
    │  command, tests         │                              │
    │────────────────────────>│                              │
    │                         │                              │
    │                    テストケース収集                    │
    │                         │                              │
    │                    Nimコンパイラ呼び出し              │
    │                         │                              │
    │                    結果検証                            │
    │                         │                              │
    │                         │  PASS/FAIL表示               │
    │                         │──────────────────────────────>│
    │                         │                              │
    │                         │  DB保存                      │
    │                         │──────────────────────────────>│
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| testament.nim | `testament/testament.nim` | ソース | メイン処理、テスト実行 |
| specs.nim | `testament/specs.nim` | ソース | テスト仕様パース |
| backend.nim | `testament/backend.nim` | ソース | DB操作、結果保存 |
| htmlgen.nim | `testament/htmlgen.nim` | ソース | HTMLレポート生成 |
| azure.nim | `testament/azure.nim` | ソース | Azure Pipelines統合 |
| categories.nim | `testament/categories.nim` | ソース | カテゴリ処理（include） |
