# バッチ設計書 10-runuia.cmd

## 概要

本ドキュメントは、WinAppDriver を起動し、コンソールの UI オートメーションテストを TAEF で実行するスクリプト `runuia.cmd` のバッチ設計書である。

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

runuia.cmd は、OpenConsole プロジェクトの UI オートメーション（UIA）テストを実行するバッチスクリプトである。WinAppDriver を起動した後、TAEF を使用して Conhost.UIA.Tests.dll を実行する。テストでは VtApp.exe をパラメータとして渡し、UI オートメーションによるコンソールの操作テストを行う。

**業務上の目的・背景**：ユニットテストやフィーチャーテストではカバーできない、ユーザーインターフェースレベルの動作を自動テストするために使用される。WinAppDriver（Windows Application Driver）を介して UI オートメーション API を使用し、コンソールウィンドウの操作・検証を自動化する。実際のユーザー操作に近いレベルでのテストにより、UI のリグレッションを検出できる。テストの構成は tests.xml と同期させる必要がある。

**バッチの実行タイミング**：UI 関連の変更後、リリース前の包括的テスト時に手動で実行する。UI テストは実行に時間がかかるため、ユニットテスト・フィーチャーテストよりも実行頻度は低い。

**主要な処理内容**：
1. WinAppDriver.exe のバックグラウンド起動
2. TAEF（TE.exe）による Conhost.UIA.Tests.dll の実行（VtApp パラメータ付き）

**前後の処理との関連**：razzle.cmd で設定された TAEF、OPENCON、ARCH 環境変数を前提とする。事前に Debug ビルドが完了し、テスト DLL、VtApp.exe、WinAppDriver が利用可能である必要がある。runut.cmd（ユニットテスト）、runft.cmd（フィーチャーテスト）と合わせて使用される。

**影響範囲**：テスト実行のみであるが、WinAppDriver プロセスがバックグラウンドで起動され、テスト終了後も手動で終了する必要がある。テスト中はコンソールウィンドウが操作されるため、デスクトップ上に視覚的な影響がある。

## バッチ種別

テスト実行

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（UI テスト時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| razzle.cmd 実行済み | TAEF、OPENCON、ARCH 環境変数が設定されていること |
| Debug ビルド完了 | Conhost.UIA.Tests.dll と VtApp.exe が Debug ビルド出力に存在すること |
| WinAppDriver | dep/WinAppDriver/WinAppDriver.exe が利用可能であること |
| TAEF インストール済み | TE.exe（TAEF テストランナー）が利用可能であること |
| デスクトップ環境 | UI テストのためデスクトップセッションが必要 |

### 実行可否判定

テスト DLL や WinAppDriver が存在しない場合はエラーとなる。明示的な事前チェックは行わない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| %* | 可変引数 | No | - | TAEF（TE.exe）に転送される追加オプション |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Conhost.UIA.Tests.dll | テスト DLL | コンソール UI オートメーションテスト |
| VtApp.exe | 実行ファイル | テスト対象の VT アプリケーション |
| WinAppDriver.exe | 実行ファイル | Windows Application Driver（UI オートメーションドライバー） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | TAEF テスト結果 |
| WinAppDriver プロセス | バックグラウンドプロセス | テスト実行用の WinAppDriver が起動される |

### 出力ファイル仕様

ファイル出力はない（TAEF のオプションにより WTT ログ等が出力される場合あり）。

## 処理フロー

### 処理シーケンス

```
1. WinAppDriver の起動
   └─ start コマンドで WinAppDriver.exe をバックグラウンド起動
2. TAEF による UI オートメーションテスト実行
   └─ call %TAEF% で Conhost.UIA.Tests.dll を実行
   └─ /p:VtApp パラメータで VtApp.exe のパスを指定
   └─ 追加引数 %* も TAEF に転送
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[WinAppDriver.exe をバックグラウンド起動]
    B --> C["TAEF で Conhost.UIA.Tests.dll 実行（VtApp パラメータ付き）"]
    C --> D[テスト結果出力]
    D --> E[バッチ終了]
    E -.->|手動| F[WinAppDriver.exe を手動終了]
```

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

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

該当なし。本バッチはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非0 | テスト失敗 | いずれかの UI テストが失敗した場合 | テスト結果を確認し、UI 関連コードを修正 |
| 非0 | WinAppDriver 起動失敗 | WinAppDriver.exe が見つからないまたは起動できない場合 | WinAppDriver のインストールを確認 |
| 非0 | DLL 未検出 | テスト DLL または VtApp.exe が存在しない場合 | Debug ビルドを実行してテスト DLL を生成 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

テスト失敗時は TAEF の出力から失敗したテストケースを特定する。WinAppDriver のプロセスが残留している場合は手動で終了する。UI テストは環境依存性が高いため、デスクトップの解像度、DPI 設定、他のウィンドウの影響などを確認する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1 テスト DLL の全 UI テストケース |
| 目標処理時間 | 数分〜数十分（UI テストは比較的時間がかかる） |
| メモリ使用量上限 | TAEF + WinAppDriver + テスト対象アプリに依存 |

## 排他制御

UI テストはデスクトップ上でウィンドウ操作を行うため、同時に複数の UI テストセッションを実行することはできない。テスト中はデスクトップの操作を控える必要がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| テスト結果 | テスト実行中・完了時 | TAEF によるテスト結果（Pass/Fail/Skip） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- コメントに "Keep this file in sync with tests.xml" とあり、テスト構成を tests.xml と同期させる必要がある。
- WinAppDriver はバックグラウンドで起動されるため（`start` コマンド使用）、テスト完了後も手動で終了する必要がある。コメントにも "You'll have to close it yourself." と明記されている。
- テスト DLL と VtApp.exe のパスは Debug 構成にハードコードされている（`%OPENCON%\bin\%ARCH%\Debug\`）。Release ビルドのテストには対応していない。
- `/p:VtApp=` パラメータにより、テスト内で使用する VT アプリケーションのパスを TAEF に渡している。
- WinAppDriver は `dep/WinAppDriver/` ディレクトリに配置されている（NuGet パッケージまたは手動配置）。
