# 画面設計書 14-koch tests

## 概要

本ドキュメントは、Nimコンパイラプロジェクトにおける`koch tests`サブコマンドの画面設計書です。Nimのテストスイートを実行するための処理について説明します。

### 本画面の処理概要

`koch tests`は、Nimコンパイラプロジェクトのテストスイートを実行するCLIサブコマンドです。testamentテストフレームワークを通じて、コンパイラの機能テスト、標準ライブラリのテスト、その他各種テストを実行します。

**業務上の目的・背景**：Nimコンパイラの品質保証において、包括的なテストスイートの実行は不可欠です。`koch tests`は、コンパイラの変更が既存の機能を壊していないことを確認するリグレッションテストを提供します。CI/CD環境での自動テストや、ローカル開発での検証に使用されます。

**画面へのアクセス方法**：ターミナルから以下のコマンドを実行します。
```
koch tests [options]
```

**主要な操作・処理内容**：
1. testamentテストフレームワークのコンパイル（--opt:speed）
2. 現在のNimコンパイラパスの検出
3. テストコマンドの構築と実行
4. テスト結果の表示
5. テスト失敗時のエラーコード返却

**画面遷移**：
- 遷移元: kochメイン画面（No.10）からサブコマンドとして呼び出し
- 遷移先: testament（No.29）が内部で呼び出される
- 関連: Nimコンパイラ（No.1）がテスト対象として使用される

**権限による表示制御**：特別な権限制御はありません。ファイルシステムへの読み書き権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | テスト実行 | 主機能 | テストスイートの実行管理処理 |
| 27 | Testament | 遷移先機能 | testamentを呼び出してテスト実行 |

## 画面種別

CLIコマンド実行画面（バッチ処理型）

## URL/ルーティング

```
koch tests [options]
koch test [options]
```

コマンドラインオプション:
- `all`: 全テストを実行（デフォルト）
- `cat <category>`: 指定カテゴリのテストを実行
- その他testamentのオプションがそのまま渡される

使用例:
```
koch tests              # 全テスト実行
koch tests cat async    # asyncカテゴリのテスト
koch tests --nim:bin/nim all  # 特定のnimで全テスト
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| args | string | いいえ | testamentに渡す引数 |
| category | string | いいえ | テストカテゴリ名 |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 標準出力 | text | テスト結果（成功/失敗/スキップ） |
| 終了コード | int | 0=成功、非0=失敗 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| テストコマンド | 実行されるtestamentコマンド |
| テスト結果 | 各テストの成功/失敗状態 |
| サマリー | 全体の成功/失敗数 |

## イベント仕様

### 1-全テスト実行

```
koch tests
```

1. `nimexec "cc --opt:speed testament/testament"`でtestamentをコンパイル
2. `findNim()`で使用するNimコンパイラを特定
3. `testament --nim:<path> all`でテストを実行
4. 終了コードを返却

### 2-カテゴリテスト実行

```
koch tests cat async
```

1. testamentをコンパイル
2. `testament --nim:<path> cat async`を実行
3. 指定カテゴリのテストのみ実行

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

本コマンドはデータベースを使用しません。

### ファイル操作詳細

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ビルド | testament/testament | CREATE/UPDATE | testamentのコンパイル |
| 読み取り | tests/**/*.nim | READ | テストファイルの読み込み |
| 生成 | testresults/** | CREATE | テスト結果の出力 |
| 生成 | nimcache/** | CREATE | テスト用の中間ファイル |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 情報 | nim cc --opt:speed testament/testament | testamentのコンパイル開始 |
| MSG002 | 情報 | testament --nim:<path> <args> | テスト実行開始 |
| MSG003 | 成功 | PASS: <testname> | テスト成功時 |
| MSG004 | 失敗 | FAIL: <testname> | テスト失敗時 |
| MSG005 | エラー | tests failed | テスト全体が失敗した場合 |

## 例外処理

| 例外 | 発生条件 | 対処 |
|------|---------|------|
| コンパイルエラー | testamentのコンパイル失敗 | コンパイラをbootしてから再実行 |
| テスト失敗 | 1つ以上のテストが失敗 | 終了コード非0で終了 |
| タイムアウト | テストがタイムアウト | 個別テストの問題を調査 |

## 備考

- 全テストの実行には数十分から数時間かかる場合があります
- `--batch`オプションでCI環境向けのバッチ実行が可能
- 環境変数`NIM_TESTAMENT_BATCH`でバッチモードを制御

---

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

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

### 推奨読解順序

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

テスト実行で使用される定数と変数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | L498: `|`テンプレート（デフォルト値設定） |

**読解のコツ**: `a | b`は「aが空ならb」を意味する短縮記法です。

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

testsコマンドの呼び出し処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | L762: "tests"コマンドの処理 |
| 2-2 | koch.nim | `koch.nim` | tests関数（L500-507）: テスト実行のメインロジック |

**主要処理フロー**:
1. **L501**: `nimexec "cc --opt:speed testament/testament"`でtestamentをコンパイル
2. **L502**: `quoteShell(getCurrentDir() / "testament/testament".exe)`でパスを構築
3. **L503**: `quoteShell("--nim:" & findNim())`でNimパスを追加
4. **L504**: `args|"all"`でデフォルト引数を設定
5. **L505-507**: テスト実行と結果判定

#### Step 3: testament連携を理解する

testamentテストフレームワークとの連携を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | testament/testament.nim | `testament/testament.nim` | testamentのメイン処理 |

**主要処理フロー**:
- **L503**: `--nim:`オプションでテスト対象のNimコンパイラを指定
- **L504**: `all`で全カテゴリのテストを実行、または特定カテゴリを指定

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

```
koch tests [args]
    │
    ├─ nimexec("cc --opt:speed testament/testament")
    │      │
    │      └─ findNim().quoteShell() & " cc ..."
    │             └─ nim cc testament/testament
    │
    ├─ quoteShell(getCurrentDir() / "testament/testament".exe)
    │      └─ テストコマンドパスの構築
    │
    ├─ quoteShell("--nim:" & findNim())
    │      └─ Nimコンパイラパスの追加
    │
    └─ tryExec(testCmd)
           │
           └─ testament --nim:<path> <args|all>
                  │
                  ├─ tests/async/*.nim   # カテゴリ: async
                  ├─ tests/stdlib/*.nim  # カテゴリ: stdlib
                  ├─ tests/js/*.nim      # カテゴリ: js
                  └─ ...                 # その他カテゴリ
```

### データフロー図

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

コマンドライン引数 ──────▶ parseopt処理 ────────────────▶ args

testament/testament.nim ──▶ nim cc --opt:speed ─────────▶ testament.exe

tests/**/*.nim ───────────▶ testament --nim:<path> ─────▶ テスト結果

テスト結果 ───────────────▶ tryExec() ──────────────────▶ 終了コード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | testsコマンドの実装 |
| testament.nim | `testament/testament.nim` | ソース | テストフレームワーク本体 |
| kochdocs.nim | `tools/kochdocs.nim` | ソース | findNim関数の定義 |
| tests/*.nim | `tests/**/*.nim` | テスト | 各種テストファイル |
| categories.nim | `testament/categories.nim` | ソース | テストカテゴリ定義 |
| specs.nim | `testament/specs.nim` | ソース | テスト仕様パーサー |
