# 機能設計書: Testament (No.27)

## 1. 機能概要

### 1.1 機能名
Testament (testament/testament.nim)

### 1.2 機能説明
Nimコンパイラおよび標準ライブラリのテストフレームワーク。テストケースの発見、実行、結果集計を行い、CI/CD環境（Azure Pipelines、AppVeyor等）との統合をサポート。カテゴリ別テスト、パターンマッチング、並列実行、メガテスト等の高度なテスト機能を提供。

### 1.3 関連画面
- CLI（コマンドラインインターフェース）
- testresults.html（結果レポート）

## 2. 機能詳細

### 2.1 入力
| 項目 | 型 | 必須 | 説明 |
|------|-----|------|------|
| command | string | Yes | all, cat, pcat, pattern, run, html |
| arguments | string | No | カテゴリ名、パターン、ファイルパス等 |
| --targets | string | No | ターゲット（c cpp js objc） |
| --nim | string | No | 使用するNimコンパイラ |
| --print | flag | No | 結果をコンソールに出力 |
| --verbose | flag | No | 詳細出力モード |
| --simulate | flag | No | ドライラン |
| --megatest | on/off | No | メガテスト有効/無効 |
| --valgrind | on/off | No | Valgrindサポート |
| --batch | string | No | バッチ処理パラメータ |

### 2.2 テスト仕様（TSpec）
テストファイルの先頭コメントから解析:
| 項目 | 説明 |
|------|------|
| action | compile, run, reject |
| output | 期待出力 |
| exitcode | 期待終了コード |
| targets | 対象ターゲット |
| matrix | オプション組み合わせ |
| timeout | タイムアウト秒数 |
| retries | リトライ回数 |

### 2.3 処理フロー
1. **初期化**
   - azure.init() / backend.open()
   - オプション解析

2. **テスト発見**
   - tests/配下のカテゴリディレクトリ走査
   - パターンマッチングによる選択

3. **テスト実行**
   - callNimCompiler()でコンパイル
   - execCmdEx2()で実行
   - 結果を期待値と比較

4. **結果集計**
   - TResultsに集計
   - Azure/AppVeyor API送信
   - HTML生成

### 2.4 出力
| 項目 | 型 | 説明 |
|------|-----|------|
| コンソール | stream | PASS/FAIL結果 |
| testresults.html | file | HTML形式レポート |
| 終了コード | int | 0=成功, 1=失敗 |

## 3. ビジネスルール

### 3.1 テストアクション
| アクション | 説明 |
|------------|------|
| actionCompile | コンパイル成功を検証 |
| actionRun | コンパイル＆実行し出力検証 |
| actionReject | 特定エラーでの失敗を検証 |

### 3.2 結果列挙型
| 値 | 説明 |
|----|------|
| reSuccess | 成功 |
| reDisabled | 無効化 |
| reJoined | メガテスト統合 |
| reBuildFailed | ビルド失敗 |
| reNimcCrash | コンパイラクラッシュ |
| reOutputsDiffer | 出力不一致 |
| reExitcodesDiffer | 終了コード不一致 |
| reTimeout | タイムアウト |

### 3.3 カテゴリ
tests/配下のディレクトリがカテゴリとなる:
- tests/async/
- tests/stdlib/
- tests/compiler/
- 等

## 4. 技術仕様

### 4.1 使用ライブラリ
- std/strutils, pegs, os, osproc
- std/streams, json, parseopt
- std/browsers, terminal, algorithm
- testament/backend, specs, azure, htmlgen

### 4.2 主要データ構造
```nim
type
  TResults = object
    total, passed, failedButAllowed, skipped: int
    data: string

  TTest = object
    name: string
    cat: Category
    options: string
    testArgs: seq[string]
    spec: TSpec
    startTime: float
    debugInfo: string
```

### 4.3 キャッシュ戦略
```nim
proc nimcacheDir(filename, options: string, target: TTarget): string =
  let hashInput = options & $target
  result = "nimcache" / (filename & '_' & hashInput.getMD5)
```

### 4.4 並列実行
```nim
quit osproc.execProcesses(cmds, {poEchoCmd, poStdErrToStdOut,
                                 poUsePath, poParentStreams},
                          beforeRunEvent = progressStatus)
```

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

### 5.1 推奨読解順序

1. **testament.nim 86-100行目**: 型定義
2. **testament.nim 684-845行目**: main関数
3. **testament.nim 174-230行目**: callNimCompiler
4. **testament.nim 489-570行目**: testSpecHelper
5. **testament.nim 603-620行目**: testSpec

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

```
testament [command] [args]
  |
  +-- main()
        +-- azure.init() / backend.open()
        +-- [all] execProcesses(並列)
        +-- [cat] processCategory()
        |         +-- testSpec()
        |               +-- testSpecHelper()
        |                     +-- callNimCompiler()
        +-- [run] processSingleTest()
        +-- azure.finalize() / backend.close()
```

### 5.3 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| testament/testament.nim | メイン | テスト実行制御 |
| testament/specs.nim | データ | テスト仕様解析 |
| testament/backend.nim | データ | 結果DB |
| testament/azure.nim | 統合 | Azure連携 |
| testament/htmlgen.nim | 出力 | HTML生成 |
| testament/categories.nim | 制御 | カテゴリ処理 |

## 6. 変更履歴

| 日付 | 変更者 | 変更内容 |
|------|--------|----------|
| 2026-02-17 | Claude | 初版作成 |
