# バッチ設計書 13-Run-Tests.ps1

## 概要

本ドキュメントは、指定パターンに一致するテストDLLを検索しTAEFで実行するPowerShellスクリプト `Run-Tests.ps1` の設計書である。

### 本バッチの処理概要

Run-Tests.ps1は、指定されたマッチパターンに基づいてテストDLLを再帰的に検索し、各DLLに対応するTAEF（te.exe）で実行するPowerShellスクリプトである。WTTログ出力にも対応している。

**業務上の目的・背景**：OpenConsoleプロジェクトのCI/CD環境（Helix等）において、テストDLLを動的に検出・実行するための汎用テストランナーが必要とされている。テストDLLが特定のディレクトリ構成に配置される場合、テストDLL隣にあるte.exeを優先的に使用することで、リソースファイル（resources.pri）の依存関係を正しく解決できる。固定的なDLLリストを管理する必要がなく、ファイル名パターンによる柔軟なテスト選択が可能である。

**バッチの実行タイミング**：CI/CDパイプライン（Helixテスト基盤等）からの自動実行、または開発者による手動実行。

**主要な処理内容**：
1. 指定されたルートディレクトリからマッチパターンに一致するテストDLLを再帰的に検索する
2. WTTログが指定されている場合、WTTロギングオプションを構成する
3. 各テストDLLについて、同じディレクトリにte.exeが存在するか確認する
4. ローカルte.exeがある場合はそれを使用し、なければルートのte.exeを使用する
5. te.exeごとにテストDLLをグループ化して実行する
6. いずれかのテストが失敗した場合、終了コード1を返す

**前後の処理との関連**：ビルド完了後に実行される。CI/CD環境ではHelixテスト基盤から呼び出される。ConvertWttLogToXUnit.ps1（No.57）でWTTログをXUnit形式に変換する後続処理と連携する可能性がある。

**影響範囲**：テスト実行のみ。WTTログ出力を指定した場合はログファイルが生成される。

## バッチ種別

テスト実行

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（CI/CDまたは手動） |
| 実行時刻 | CI/CDパイプラインのスケジュールに依存 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | CI/CDパイプライン / 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ビルド完了 | テストDLLがビルド出力ディレクトリに存在すること |
| te.exe利用可能 | ルートディレクトリまたはテストDLLと同じディレクトリにte.exeが存在すること |
| PowerShell | PowerShell実行環境が利用可能であること |

### 実行可否判定

指定パターンに一致するDLLが検索結果に存在し、te.exeが利用可能であること。DLLが見つからない場合はテストが実行されずに正常終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| MatchPattern | string | Yes | なし | テストDLLを検索するファイル名パターン（例：*.Tests.dll） |
| Platform | string | Yes | なし | ビルドプラットフォーム（例：x64） |
| Configuration | string | Yes | なし | ビルド構成（例：Debug, Release） |
| LogPath | string | No | なし | WTTログファイルの出力パス |
| Root | string | No | .\bin\$Platform\$Configuration | テストDLLの検索ルートディレクトリ |
| AdditionalTaefArguments | string[] | No | なし | TAEFに渡す追加引数 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| テストDLL | DLL | MatchPatternに一致するテストDLLファイル群 |
| te.exe | 実行ファイル | TAEFテストランナー |
| resources.pri | PRI | テストフィクスチャが依存するリソースファイル（DLLと同じディレクトリに必要） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト実行結果、WTTロギング有効化メッセージ |
| WTTログ | ファイル | LogPath指定時にWTTログファイルを出力 |
| 終了コード | 整数 | 0: 全テスト成功、1: いずれかのテスト失敗 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | LogPathパラメータで指定 |
| 出力先 | LogPathパラメータで指定 |
| 文字コード | WTTログ形式に依存 |
| 区切り文字 | 該当なし（WTTログ形式） |

## 処理フロー

### 処理シーケンス

```
1. パラメータ受け取り
   └─ MatchPattern, Platform, Configuration, LogPath, Root, AdditionalTaefArgumentsを受け取る
2. テストDLL検索
   └─ Get-ChildItem -Recurse -Filter でルートディレクトリからDLLを再帰検索
3. WTTロギング設定（LogPath指定時）
   └─ /enablewttlogging, /appendwttlogging, /logFile オプションを構成
4. te.exeマッピング
   └─ 各テストDLLについて同ディレクトリのte.exeを探索
   └─ ローカルte.exeがなければルートのte.exeを使用
5. テストDLLグループ化
   └─ te.exeごとにテストDLLをグループ化
6. テスト実行
   └─ 各グループのte.exeでテストDLLを実行
   └─ 失敗時に$anyFailedフラグを設定
7. 終了コード返却
   └─ いずれか失敗: Exit 1、全成功: Exit 0
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B["パラメータ受け取り"]
    B --> C["Get-ChildItem でテストDLL検索"]
    C --> D{LogPath指定?}
    D -->|Yes| E["WTTロギングオプション設定"]
    D -->|No| F["te.exeマッピング"]
    E --> F
    F --> G["te.exeごとにDLLグループ化"]
    G --> H["各グループでテスト実行"]
    H --> I{失敗あり?}
    I -->|Yes| J["Exit 1"]
    I -->|No| K["Exit 0"]
```

## データベース操作仕様

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

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | テスト失敗 | いずれかのテストケースが失敗した場合 | テスト結果を確認し該当コードを修正する |
| なし | DLL未検出 | パターンに一致するDLLが存在しない場合 | ビルドが完了しているか確認する |
| なし | te.exe不在 | te.exeが見つからない場合 | TAEFがインストールされているか確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（スクリプト内にリトライ機構なし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

テスト失敗時はWTTログまたは標準出力を確認し、失敗したテストケースを特定する。CI/CD環境ではConvertWttLogToXUnit.ps1でXUnit形式に変換し、テスト結果を解析する。

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | パターンに一致するテストDLL数に依存 |
| 目標処理時間 | 明示的な制約なし |
| メモリ使用量上限 | 明示的な制約なし |

## 排他制御

特別な排他制御は行わない。te.exeごとにテストDLLをグループ化して順次実行するため、同じte.exeを同時に複数回呼び出すことはない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| WTTロギング有効化 | LogPath指定時 | "WTT Logging Enabled"メッセージ |
| 実行情報 | テスト実行前 | "Running {te.exe} (for {DLL名})"（Verbose出力） |
| テスト結果 | テスト実行中 | TAEFの標準出力 |
| WTTログ | テスト実行後 | WTTログファイル（LogPath指定時） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDパイプライン |

## 備考

- テストDLLの一部はresources.priファイルに依存するため、DLLと同じディレクトリにあるte.exeを優先的に使用するロジックが実装されている。
- CmdLetBinding属性が付与されており、-Verboseパラメータで詳細な実行情報を出力できる。
- te.exeごとにGroup-Objectでグループ化してから実行するため、異なるディレクトリのte.exeが混在する環境にも対応している。
- ソースファイルパス: `build/scripts/Run-Tests.ps1`
