# テスト方針書

## 概要

本ドキュメントは、Windows Terminal（Microsoft/Terminal）プロジェクトにおけるテスト方針を定義する。本プロジェクトはC++およびC#のハイブリッド構成を持つ大規模Windowsアプリケーションであり、TAEF（Test Authoring and Execution Framework）を中核としたテスト基盤を採用している。ユニットテスト、フィーチャーテスト（結合テスト）、UI自動化テスト、ファジングテストの4層構成でテスト品質を担保する。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト（ut_*） | 各コンポーネント（Types, Host, TextBuffer, Adapter, Parser, TIL, Interactivity, App）の個別クラス・関数レベルの動作検証 | 開発者 |
| 結合テスト（ft_*） | コンポーネント間の連携検証。Host API、ConPTY、TerminalApp間のインタラクション確認 | 開発者・QA |
| システムテスト（ft_uia） | UI自動化によるエンドツーエンド検証。WinAppDriver/Seleniumを用いたUIオートメーションテスト | QA |
| 受入テスト | パッケージ検証（Test-WindowsTerminalPackage.ps1）によるリリース前のインストール・動作確認 | QA・リリース管理者 |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | ユニットテスト（ut_*）およびフィーチャーテスト（ft_*）による機能の正当性検証 | コミット時・プルリクエスト時 |
| 性能テスト | PGO（Profile-Guided Optimization）によるプロファイリングベースの性能最適化検証 | リリースビルド時 |
| セキュリティテスト | AuditModeビルド構成による静的解析・セキュリティチェック | 定期ビルド時 |
| ファジングテスト | VTCommandFuzzer、Host Fuzzerによるランダム入力に対する耐性検証 | 定期実行・リリース前 |
| アクセシビリティテスト | AccessibilityTests.cs によるUI Automation APIを通じたアクセシビリティ準拠検証 | UI変更時 |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 開発者による単体テスト・フィーチャーテスト実行 | Visual Studio + TAEF (te.exe)、Win32/x64/ARM64対応 |
| Azure Pipelines | CI/CDパイプラインでの自動テスト実行 | MSBuildCache (Azure Pipelines版)、Helix統合 |
| Helix テスト基盤 | 大規模分散テスト実行・結果レポーティング | HelixTestHelpers.cs、WTTログ変換、Azure DevOps連携 |
| GitHub Actions | スペルチェック・プロジェクト管理の自動化 | Ubuntu (spelling2.yml)、Windows (winget.yml) |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| TAEF (te.exe) | C++/C#テストの実行フレームワーク。テスト定義・実行・結果収集の中核 | 10.100.251104001 |
| WinAppDriver | Windows UIオートメーションテスト用ドライバサーバー | dep/WinAppDriver/ 同梱版 |
| Selenium WebDriver | UIテスト実行のWebDriverプロトコル実装 | 3.5.0 |
| Appium WebDriver | モバイル・デスクトップUI自動化テストクライアント | 3.0.0.2 |
| clang-format | C++ソースコードの自動フォーマッティング | .clang-format設定準拠 |
| check-spelling | GitHub Actionsによるスペルチェック | v0.0.25 |
| MSBuildCache | ビルドキャッシュによるCI高速化 | 0.1.283-preview |
| PGO Helpers | Profile-Guided Optimization支援 | 0.2.34 |
| CppWinRT | C++/WinRTプロジェクション生成 | 2.0.250303.1 |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | プロジェクトとして明示的な数値目標は設定されていない（PGOベースのプロファイリングで補完） |
| 分岐カバレッジ | プロジェクトとして明示的な数値目標は設定されていない |

**補足**: 本プロジェクトでは、カバレッジ数値目標よりもテストレベルの網羅性（76テストプロジェクト、4層テスト構成）と、ファジングによるエッジケース発見を重視している。PGO（Profile-Guided Optimization）により実行パスのプロファイリングを行い、性能面での最適化に活用している。

## テストデータ

### テストデータの準備方針

1. **CommonState ヘルパー（C++）**: `src/inc/test/CommonState.hpp` に定義されたテストヘルパークラスにより、テスト用のグローバルスクリーンバッファ、入力バッファ、フォント設定、テキストバッファを標準化された方法で準備・クリーンアップする。
   - 標準バッファサイズ: 80x80（ウィンドウ）、80x300（バッファ）
   - 標準フォントサイズ: 8x12

2. **Common ヘルパー（フィーチャーテスト）**: `src/host/ft_host/Common.hpp` により、テストバッファのセットアップ・クリーンアップ、V1/V2互換モード切り替えを提供する。

3. **UIテストヘルパー（C#）**: `src/host/ft_uia/Common/` 配下のヘルパー群（AutoHelpers, Globals, NativeMethods, RegistryHelper, ShortcutHelper等）により、UIオートメーションテスト用の共通機能を提供する。

4. **TAEFテンプレート**: `src/inc/consoletaeftemplates.hpp` により、Windows型（SMALL_RECT, COORD等）のカスタム比較・出力トレイツを提供し、テスト結果の可読性を向上させる。

5. **テストデータ駆動テスト**: TAEFの `TestData::TryGetValue` マクロ（`INIT_TEST_PROPERTY`）を活用し、データ駆動テストによるパラメータ化されたテストケースを実現する。

## 不具合管理

1. **テスト失敗時の自動診断情報収集**:
   - `/ScreenCaptureOnError`: テスト失敗時にスクリーンショットを自動取得
   - `/miniDumpOnError`: テスト失敗時にミニダンプを自動出力
   - `/unsupported_miniDumpOnTimeout`: タイムアウト時にもミニダンプを出力

2. **WTTログ**: TAEF実行結果はWTT（Windows Test Technologies）ログ形式で出力され、`Get-WttLog.ps1` スクリプトで取得可能。

3. **Helix結果レポート**: `HelixTestHelpers.cs` によりテスト結果を構造化パース。テスト名、実行時間、Pass/Fail/Skip状態、スクリーンショット、再実行結果を管理する。`ConvertWttLogToXUnit.ps1` でxUnit形式に変換し、`OutputTestErrorsForAzureDevops.ps1` でAzure DevOpsに報告する。

4. **GitHub Issues/Pull Requests**: GitHub Actionsとの連携により、プロジェクト管理（addToProject.yml）やスペルチェック（spelling2.yml）の結果がPRにフィードバックされる。

## CI/CD連携

### パイプライン構成

1. **Azure Pipelines（メインCI/CD）**:
   - MSBuildCacheによるビルドキャッシュ（`Microsoft.MSBuildCache.AzurePipelines` v0.1.283-preview）
   - テストDLLのビルド → `Run-Tests.ps1` によるTAEF実行
   - Helix基盤での分散テスト実行
   - WTTログ → xUnit変換 → Azure DevOps結果レポート

2. **GitHub Actions**:
   - `spelling2.yml`: push/PR時のスペルチェック（check-spelling/check-spelling@v0.0.25）
   - `addToProject.yml`: Issue/PRのプロジェクトボード自動追加
   - `winget.yml`: WinGetパッケージ管理

### テスト実行フロー

```
ビルド (MSBuild)
  ├── C++テストプロジェクト (*.vcxproj) → テストDLL
  │     └── te.exe による TAEF テスト実行
  │           ├── ユニットテスト (ut_*)
  │           ├── フィーチャーテスト (ft_host, ft_pty)
  │           └── ファジングテスト (ft_fuzzer)
  └── C#テストプロジェクト (*.csproj) → テストアセンブリ
        └── TE.Managed による TAEF テスト実行
              └── UIオートメーションテスト (ft_uia)
                    └── WinAppDriver連携
```

### テスト実行コマンド

```powershell
# Run-Tests.ps1 による実行
.\build\scripts\Run-Tests.ps1 `
    -MatchPattern "*.UnitTests.dll" `
    -Platform "x64" `
    -Configuration "Debug" `
    -LogPath ".\TestResults" `
    -AdditionalTaefArguments @("/ScreenCaptureOnError", "/miniDumpOnError")
```

### 対応プラットフォーム・構成

| プラットフォーム | 構成 |
| --- | --- |
| Win32 (x86) | Debug, Release, AuditMode, Fuzzing |
| x64 | Debug, Release, AuditMode, Fuzzing |
| ARM64 | Debug, Release, AuditMode, Fuzzing |

## 備考

### テストプロジェクト一覧

本プロジェクトには76個のテストプロジェクト（.vcxproj）が含まれ、以下のカテゴリに分類される。

#### ユニットテスト (ut_*)

| プロジェクト | 対象コンポーネント | 位置 |
| --- | --- | --- |
| Types.Unit.Tests | 型定義ライブラリ | src/types/ut_types/ |
| Host.UnitTests | コンソールホスト | src/host/ut_host/ |
| host.unittest (lib) | ホストテストライブラリ | src/host/ut_lib/ |
| TextBuffer.Unit.Tests | テキストバッファ | src/buffer/out/ut_textbuffer/ |
| Adapter.UnitTests | VTアダプター | src/terminal/adapter/ut_adapter/ |
| Parser.UnitTests | VTパーサー | src/terminal/parser/ut_parser/ |
| til.unit.tests | TILユーティリティ | src/til/ut_til/ |
| Interactivity.Win32.UnitTests | Win32インタラクティビティ | src/interactivity/win32/ut_interactivity_win32/ |
| TerminalApp.UnitTests | ターミナルアプリ | src/cascadia/ut_app/ |

#### フィーチャーテスト (ft_*)

| プロジェクト | 対象コンポーネント | 位置 |
| --- | --- | --- |
| Host.FeatureTests | ホストAPI統合 | src/host/ft_host/ |
| Host.Tests.UIA (C#) | UI自動化 | src/host/ft_uia/ |
| Host.IntegrityTests | 整合性検証 | src/host/ft_integrity/ |
| winconpty.FeatureTests | ConPTY機能 | src/winconpty/ft_pty/ |
| TerminalApp.LocalTests | アプリローカルテスト | src/cascadia/LocalTests_TerminalApp/ |

#### ファジングテスト

| プロジェクト | 対象 | 位置 |
| --- | --- | --- |
| Host Fuzzer | ホストコンポーネント | src/host/ft_fuzzer/ |
| VTCommandFuzzer | VTエスケープシーケンス | src/terminal/parser/ft_fuzzer/ |
| FuzzWrapper | ファジングラッパー | src/terminal/parser/ft_fuzzwrapper/ |

### テストリスト管理

`src/testlist/Microsoft.Console.Tests.testlist` により、CIで実行されるテストメタデータ群を一元管理している。各テストプロジェクトは `testmd.definition` ファイルでコンポーネント名、実行タイプ、依存パッケージ等のメタデータを定義する。
