# バッチ設計書 34-azure-pipelines-integrationtests.yml

## 概要

本ドキュメントは、Avaloniaフレームワークの統合テストを実行するAzure Pipelines設定ファイル「azure-pipelines-integrationtests.yml」の設計仕様を記載するものです。

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

このパイプラインは、AvaloniaフレームワークのUI統合テストをmacOSとWindowsの両プラットフォームで実行します。Appiumを使用した自動化されたUIテストにより、実際のアプリケーション動作を検証する統合テストパイプラインです。

**業務上の目的・背景**：ユニットテストでは検出できないUI動作の不具合やプラットフォーム固有の問題を早期に発見するため、実際のアプリケーションを起動してUIを操作する統合テストが必要です。Appiumを使用することで、macOSとWindowsの両環境でネイティブUIの自動テストを実現し、クロスプラットフォームUIフレームワークとしての品質を保証します。

**バッチの実行タイミング**：手動トリガーまたはスケジュール設定によりAzure Pipelinesで実行されます。メインのCIパイプライン（No.33）とは別に、より時間のかかる統合テストを実行するために分離されています。

**主要な処理内容**：
1. Mac: macOSでAppiumを使用した統合テスト実行
2. Windows: WindowsでWinAppDriverを使用した統合テスト実行

**前後の処理との関連**：IntegrationTestAppサンプルプロジェクトのビルドが前提です。macOSではネイティブコードのコンパイル（CompileNative）が先行して実行されます。

**影響範囲**：Avaloniaフレームワークを使用したアプリケーションのUI動作検証に影響します。テスト結果はAzure DevOpsに公開され、UI品質の評価指標として使用されます。

## バッチ種別

CI/CD パイプライン（統合テスト）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動/スケジュール |
| 実行時刻 | 設定に依存 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動/スケジュール |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Azure DevOps接続 | Azure Pipelinesサービス接続が設定されていること |
| AvaloniaMacPool | カスタムMacエージェントプールが利用可能であること |
| Appium | Appiumがmacエージェントにインストールされていること |
| WinAppDriver | WindowsでWinAppDriverが利用可能であること |
| .NET SDK | .NET 10.0 SDKが利用可能であること |

### 実行可否判定

パイプラインはAzure DevOpsの設定に従ってトリガーされます。カスタムエージェントプール「AvaloniaMacPool」が利用可能である必要があります。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| Build.SourcesDirectory | string | Yes | (自動設定) | ソースコードのチェックアウトディレクトリ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHubリポジトリ | Git | Avaloniaソースコードリポジトリ |
| samples/IntegrationTestApp | .NETプロジェクト | 統合テスト対象アプリケーション |
| tests/Avalonia.IntegrationTests.Appium | テストプロジェクト | Appium統合テストコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| テスト結果 | TRX/XUnit | 統合テストの実行結果 |
| appium.out | テキストログ | Appiumサーバーログ（失敗時のみ公開） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| テスト結果形式 | XUnit (macOS) / TRX (Windows) |
| ログファイル | appium.out（macOS、失敗時のみ公開） |

## 処理フロー

### 処理シーケンス

```
1. Mac ジョブ（AvaloniaMacPoolで実行）
   └─ .NET 8.0 Runtime / 10.0 SDKセットアップ
   └─ ディスプレイ解像度取得
   └─ git clean でワークスペースクリーン
   └─ node/testmanagerdプロセス終了
   └─ Appiumサーバー起動（バックグラウンド）
   └─ CompileNative実行（ネイティブコードビルド）
   └─ 既存IntegrationTestApp削除
   └─ IntegrationTestAppバンドル作成
   └─ IntegrationTestApp起動
   └─ Appium統合テスト実行
   └─ IntegrationTestApp/Appium終了
   └─ 失敗時Appiumログ公開

2. Windows ジョブ（windows-2025で実行）
   └─ .NET 8.0 Runtime / 10.0 SDKセットアップ
   └─ WinAppDriver起動（4K解像度）
   └─ IntegrationTestAppビルド
   └─ テストプロジェクトビルド
   └─ Win32統合テスト実行
   └─ Appium統合テスト実行（VSTest）
   └─ テスト結果公開
   └─ WinAppDriver停止
```

### フローチャート

```mermaid
flowchart TD
    A[パイプライン開始] --> B[Mac ジョブ]
    A --> C[Windows ジョブ]

    B --> B1[.NET セットアップ]
    B1 --> B2[解像度確認]
    B2 --> B3[ワークスペースクリーン]
    B3 --> B4[Appium起動]
    B4 --> B5[CompileNative]
    B5 --> B6[IntegrationTestAppバンドル]
    B6 --> B7[統合テスト実行]
    B7 --> B8[クリーンアップ]

    C --> C1[.NET セットアップ]
    C1 --> C2[WinAppDriver起動]
    C2 --> C3[IntegrationTestAppビルド]
    C3 --> C4[テストプロジェクトビルド]
    C4 --> C5[Win32統合テスト]
    C5 --> C6[Appium統合テスト]
    C6 --> C7[テスト結果公開]
    C7 --> C8[WinAppDriver停止]

    B8 --> D[パイプライン終了]
    C8 --> D
```

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

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

本バッチはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Appiumエラー | Appiumサーバー起動失敗 | appium.outログを確認 |
| - | WinAppDriverエラー | WinAppDriver起動失敗 | エージェント設定を確認 |
| - | ビルドエラー | IntegrationTestAppビルド失敗 | ソースコードを修正 |
| - | テスト失敗 | UIテスト失敗 | テストログと動画を確認 |
| - | タイムアウト | テスト実行が長時間 | テストの最適化を検討 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | Azure Pipelinesのデフォルト設定に依存 |
| リトライ間隔 | - |
| リトライ対象エラー | 一時的なUI同期エラーなど |

### 障害時対応

統合テスト失敗時は以下を確認してください：
1. macOS: appium.outログを確認（失敗時に公開される）
2. Windows: 記録された動画ファイルを確認（record-video.runsettings使用）
3. テスト結果の詳細でエラーメッセージを確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（CI/CDプロセス） |
| コミットタイミング | - |
| ロールバック条件 | なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1パイプライン実行 |
| 目標処理時間 | 20-40分程度（UIテストのため長め） |
| メモリ使用量上限 | エージェントの制限に依存 |

## 排他制御

macOSはカスタムエージェントプール「AvaloniaMacPool」を使用するため、エージェント数に応じた同時実行制限があります。Windowsはホステッドエージェントを使用します。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ビルドログ | 各ステップ実行時 | コマンド出力、エラーメッセージ |
| Appiumログ | テスト完了後（失敗時） | appium.out |
| テスト結果 | テスト完了時 | TRX/XUnit形式の結果 |
| 動画 | テスト完了時（Windows） | record-video.runsettings設定による |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| テスト失敗 | 1件以上 | Azure DevOps通知設定に依存 |
| ジョブ失敗 | 1回 | Azure DevOps通知設定に依存 |

## 備考

- 本パイプラインは統合テスト専用であり、No.33のメインCIパイプラインとは分離されています
- macOSジョブはカスタムエージェントプール「AvaloniaMacPool」を使用します
- Appiumはバックグラウンドで起動され、ログはappium.outに出力されます
- macOSではXcode 15.2を使用してネイティブコードをビルドします
- Windowsでは4K解像度でWinAppDriverを起動します
- テスト失敗時のデバッグのため、Windowsではビデオ録画（record-video.runsettings）が有効です
- IntegrationTestAppはnet10.0ターゲットフレームワークでビルドされます
