# バッチ設計書 10-run-vrt

## 概要

本ドキュメントは、Visual Regression Test（VRT）をDocker環境で実行するスクリプト「run-vrt」の設計仕様を記載したものです。

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

このバッチは、Playwrightを使用してUIの視覚的な回帰テストをDocker環境で実行します。Dockerコンテナ内でPlaywrightテストを実行することで、一貫した環境でのスクリーンショット比較が可能になります。

**業務上の目的・背景**：UIの変更が意図しない視覚的な変化を引き起こしていないかを検出することは、品質保証において重要です。VRT（Visual Regression Test）は、スクリーンショットのベースライン画像と現在の画像を比較し、差分を検出するテスト手法です。Docker環境で実行することで、ローカル環境の差異（フォントレンダリング、OS、ブラウザバージョン等）による偽陽性を排除し、CI/CDパイプラインでも同じ結果を再現できます。

**バッチの実行タイミング**：手動実行またはCI/CDパイプラインからの自動実行。UIの変更後、PRマージ前のレビューサイクルで実行されます。

**主要な処理内容**：
1. node_modulesの存在確認、必要に応じてyarnで依存関係インストール
2. コマンドライン引数からE2E_START_URLを設定
3. その他の引数をVRT_ARGSとして収集
4. テストパラメータを表示
5. Dockerコンテナ（Playwright公式イメージ）でVRTを実行
6. ホストのワークディレクトリをマウントしてテスト実行

**前後の処理との関連**：テスト対象のアプリケーションが起動している必要があります。通常は`yarn start:browser`等でローカルサーバーを起動した状態で実行します。テスト結果はスクリーンショットの差分として出力されます。

**影響範囲**：テスト実行のみ、データの変更なし。スクリーンショットファイルの更新の可能性あり。

## バッチ種別

テスト / 品質保証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（UI変更時、PR作成時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 / CI/CD |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Docker | Dockerがインストールされ、稼働していること |
| ネットワーク接続 | Dockerイメージのプル、テスト対象へのアクセスが可能 |
| テスト対象起動 | テスト対象アプリケーションが起動していること |
| yarn利用可能 | yarnコマンドが利用可能であること |

### 実行可否判定

常に実行可能。テスト対象が起動していない場合はテストが失敗します。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --e2e-start-url | string | No | https://localhost:3001 | テスト対象のURL |
| その他 | string | No | なし | Playwrightに渡される引数 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| テスト定義ファイル | TypeScript/JavaScript | Playwrightテストファイル |
| ベースラインスクリーンショット | 画像 | 比較元のスクリーンショット |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト実行ログ |
| スクリーンショット | 画像 | 差分スクリーンショット（差分検出時） |
| テストレポート | HTML | Playwrightテストレポート |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | テスト結果に依存 |
| 出力先 | packages/desktop-client/test-results/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. node_modules確認
   └─ 存在しないまたは空の場合: yarn実行
2. 環境変数設定
   └─ E2E_START_URL（デフォルト: https://localhost:3001）
3. 引数解析
   ├─ --e2e-start-url: E2E_START_URLに設定
   └─ その他: VRT_ARGSに追加
4. パラメータ表示
   ├─ E2E_START_URL
   └─ VRT_ARGS
5. Docker実行
   ├─ イメージ: mcr.microsoft.com/playwright:v1.57.0-jammy
   ├─ オプション: --rm --network host
   ├─ ボリューム: $(pwd):/work/
   └─ コマンド: yarn vrt $VRT_ARGS
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{node_modules存在?}
    B -->|No| C[yarn実行]
    B -->|Yes| D{node_modules空?}
    D -->|Yes| C
    D -->|No| E[E2E_START_URL設定]
    C --> E
    E --> F[引数解析ループ]
    F --> G{--e2e-start-url?}
    G -->|Yes| H[E2E_START_URL更新]
    G -->|No| I[VRT_ARGSに追加]
    H --> J[次の引数へ]
    I --> J
    J --> K{引数残り?}
    K -->|Yes| F
    K -->|No| L[パラメータ表示]
    L --> M[Docker run実行]
    M --> N[Playwright VRT実行]
    N --> O[バッチ終了]
```

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

該当なし。テスト実行はデータベース操作を行いません（テスト対象アプリ内での操作を除く）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | docker-error | Dockerが起動していない | Dockerを起動 |
| - | network-error | テスト対象にアクセスできない | テスト対象サーバーを起動 |
| - | test-failure | VRTテスト失敗（差分検出） | 差分を確認、必要に応じてベースライン更新 |
| - | image-pull-error | Dockerイメージ取得失敗 | ネットワーク接続を確認 |

### リトライ仕様

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

### 障害時対応

1. Docker未起動：Dockerデーモンを起動
2. イメージプルエラー：ネットワーク接続とDocker Hubへのアクセスを確認
3. テスト対象アクセスエラー：テスト対象サーバーが起動しているか確認、URLを確認
4. VRT失敗：差分画像を確認し、意図した変更であればベースライン更新

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

該当なし。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | テストケース数に依存 |
| 目標処理時間 | テストケース数に依存（数分〜数十分） |
| メモリ使用量上限 | Dockerコンテナのデフォルト |

## 排他制御

同時実行は推奨されません。同一テスト対象に対して複数のVRTを同時実行すると、結果が不安定になる可能性があります。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | 実行開始時 | 「Running VRT tests with the following parameters:」 |
| パラメータログ | 実行開始時 | E2E_START_URL、VRT_ARGS |
| テストログ | テスト実行中 | Playwright出力 |
| 結果ログ | テスト完了時 | テスト結果サマリー |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDシステム |
| テスト時間 | 異常に長い場合 | 開発者 |

## 備考

- 実行コマンド: `./bin/run-vrt`
- オプション付き例: `./bin/run-vrt --e2e-start-url http://localhost:5006`
- スクリプト種別: シェルスクリプト（/bin/sh）
- Dockerイメージ: `mcr.microsoft.com/playwright:v1.57.0-jammy`
- ネットワークモード: host（ホストネットワーク共有）
- ボリュームマウント: カレントディレクトリを/work/にマウント
- VRTコマンド: `yarn vrt`（packages/desktop-client/package.json定義）
- MSYS_NO_PATHCONV=1: Windows環境でのパス変換問題を回避
- 詳細ドキュメント: https://github.com/actualbudget/actual/tree/master/packages/desktop-client#visual-regression
