# 画面設計書 30-testament all

## 概要

本ドキュメントは、Testamentツールの`all`コマンドに関する画面設計書である。

### 本画面の処理概要

testament allコマンドは、testsディレクトリ配下のすべてのカテゴリの全テストを実行する包括的なテスト実行コマンドである。

**業務上の目的・背景**：Nimコンパイラの品質保証において、全テストスイートの実行は最も重要な検証作業である。リリース前やCIパイプラインにおいて、すべてのテストが成功することを確認する必要がある。`all`コマンドは、この包括的なテスト実行を自動化し、結果を一元的に管理する。

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

**主要な操作・処理内容**：
1. testsディレクトリ配下のすべてのカテゴリを収集
2. 各カテゴリを並列プロセスで実行
3. 全テスト結果を集計
4. 最終的な統計情報を表示

**画面遷移**：
- 遷移元: シェル/ターミナルからの直接実行
- 遷移先: 処理完了後、全体統計を表示してシェルに戻る（失敗があればexit code 1）

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

## 関連機能

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

## 画面種別

コマンドライン（CLI）

## URL/ルーティング

```
# 基本使用法
testament all

# ターゲット指定
testament --targets:"c cpp js" all

# 特定のNimコンパイラを使用
testament --nim:/path/to/nim all

# バッチ実行（CI用）
testament --batch:0_4 all  # 4分割の最初のバッチ

# シミュレーション（実際には実行しない）
testament --simulate all
```

## 入出力項目

### コマンドラインオプション（all固有）

| オプション | 型 | 説明 |
|-----------|-----|------|
| --targets | string | 対象ターゲット（c, cpp, js, objc） |
| --nim | string | 使用するNimコンパイラのパス |
| --batch | string | バッチ番号_総バッチ数（例: 0_4） |
| --simulate | flag | 実行せずにテストリストを表示 |
| --megatest | on/off | メガテストの有効/無効 |
| --skipFrom | string | スキップリストファイル |

### 入力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| arguments | seq[string] | 追加のコンパイラオプション（テストに渡される） |

### 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 進捗情報 | string | `progress[all]: X/Y starting: cat: category_name` |
| テスト結果 | string | 各カテゴリのテスト結果 |
| 最終統計 | string | 全体の成功/失敗/スキップ数 |

## 表示項目

allコマンド実行時の表示:

| 表示項目 | 説明 | 例 |
|---------|------|-----|
| 進捗 | カテゴリ処理の進捗 | `progress[all]: 5/30 starting: cat: stdlib` |
| カテゴリ結果 | 各カテゴリのテスト結果 | 通常のPASS/FAIL表示 |
| 最終結果 | 成功時 | `Used nim to run the tests.` |
| 最終結果 | 失敗時 | `FAILURE! total: X passed: Y skipped: Z failed: W` |

## イベント仕様

### 1-カテゴリ収集

1. testsディレクトリを走査（行779-783）
2. testdata, nimcache以外のディレクトリをカテゴリとして収集
3. AdditionalCategories（stdlib等）を追加（行785）
4. megatest有効時はMegaTestCatを追加（行786）

### 2-並列実行

1. 各カテゴリに対してコマンドを構築（行789-791）
2. `execProcesses`で並列実行（行803）
3. `progressStatus`コールバックで進捗を表示

### 3-結果集計

1. 各プロセスの終了コードを確認
2. 失敗があればquit(1)

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| テスト結果記録 | SQLiteDB | INSERT | 各カテゴリのテスト結果がbackend経由で保存 |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|---------|
| 情報 | `progress[all]: X/Y starting: cat: Z` | カテゴリ処理開始時 |
| 情報 | `Used nim to run the tests. Use --nim to override.` | 全テスト成功時 |
| エラー | `FAILURE! total: X passed: Y skipped: Z failed: W` | テスト失敗時 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| テスト失敗あり | exit code 1で終了 |
| カテゴリが見つからない | スキップして次のカテゴリへ |

## 備考

- `all`コマンドは子プロセスとして各カテゴリを`pcat`コマンドで実行する
- `pcat`は`cat`と同等だが、joinableテストは実行しない（megatestで処理）
- バッチ実行により、CIで複数ジョブに分割可能
- Azure Pipelinesとの統合により、テスト結果がCI上で可視化される
- シミュレーションモードで実行計画を確認可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | testament.nim | `testament/testament.nim` | testsDir定数（行45）、カテゴリ収集の基点 |
| 1-2 | testament.nim | `testament/testament.nim` | AdditionalCategories（categories.nim内） |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | testament.nim | `testament/testament.nim` | main関数内の"all"分岐（行762-803） |

**主要処理フロー**:
1. **行766-772**: 自身のコマンドライン構築
2. **行777-786**: カテゴリ収集
3. **行788-791**: コマンドリスト構築
4. **行793-803**: 並列実行

#### Step 3: 並列実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | testament.nim | `testament/testament.nim` | progressStatus関数（行793-794） |
| 3-2 | osproc.nim | `lib/pure/osproc.nim` | execProcesses関数 |

**主要処理フロー**:
- **行793-794**: progressStatus関数
```nim
proc progressStatus(idx: int) =
  echo "progress[all]: $1/$2 starting: cat: $3" % [$idx, $cats.len, cats[idx]]
```

- **行796-803**: 実行ブロック
```nim
if simulate:
  # シミュレーションモード
  for i, cati in cats:
    progressStatus(i)
    processCategory(r, Category(cati), p.cmdLineRest, testsDir, runJoinableTests = false)
else:
  addExitProc azure.finalize
  quit osproc.execProcesses(cmds, {poEchoCmd, poStdErrToStdOut, poUsePath, poParentStreams}, beforeRunEvent = progressStatus)
```

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

```
main (行684)
    │
    ├─ [action == "all"] (行762)
    │      │
    │      ├─ myself構築 - 自身のパス+オプション (行766-776)
    │      │
    │      ├─ walkDir(testsDir) - カテゴリ収集 (行779-783)
    │      │
    │      ├─ cats.add(AdditionalCategories) (行785)
    │      │
    │      ├─ cats.add(MegaTestCat) - megatest有効時 (行786)
    │      │
    │      ├─ cmds構築 - 各カテゴリのコマンド (行788-791)
    │      │
    │      └─ execProcesses(cmds) - 並列実行 (行803)
    │             │
    │             └─ progressStatus - 進捗表示 (行793-794)
    │
    └─ [各子プロセス: pcat コマンド]
           │
           └─ processCategory (行816)
                  │
                  └─ testSpec (行603)
```

### データフロー図

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

コマンドライン            testament                       ターミナル
    │                         │                              │
    │  all                    │                              │
    │────────────────────────>│                              │
    │                         │                              │
    │                    testsディレクトリ走査              │
    │                         │                              │
    │                    カテゴリリスト構築                 │
    │                         │                              │
    │                    ┌────┴────┐                        │
    │                    │ 子プロセス │ × N (並列)          │
    │                    └────┬────┘                        │
    │                         │                              │
    │                    各カテゴリのテスト実行              │
    │                         │                              │
    │                         │  progress[all]: X/Y          │
    │                         │──────────────────────────────>│
    │                         │                              │
    │                    結果集計                            │
    │                         │                              │
    │                         │  FAILURE! or success         │
    │                         │──────────────────────────────>│
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| testament.nim | `testament/testament.nim` | ソース | allコマンド処理、並列実行制御 |
| categories.nim | `testament/categories.nim` | ソース | AdditionalCategories定義、カテゴリ処理 |
| backend.nim | `testament/backend.nim` | ソース | DB操作、結果保存 |
| azure.nim | `testament/azure.nim` | ソース | Azure Pipelines統合 |
| osproc.nim | `lib/pure/osproc.nim` | ライブラリ | execProcesses関数 |
