# バッチ設計書 8-test.yml

## 概要

本ドキュメントは、プッシュ/PRトリガーで実行される包括的なテストワークフロー `test.yml` の設計仕様を記載する。

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

本バッチは、Ghosttyプロジェクトの品質を保証するための包括的なCI/CDワークフローであり、ビルド・テスト・リンター・フォーマッターを含む多数のジョブを実行する。

**業務上の目的・背景**：Ghosttyは複数のプラットフォーム（Linux、macOS、Windows）とビルド構成（GTK、Flatpak、Snap、Nix等）をサポートする大規模プロジェクトである。コード品質を維持するため、全てのプッシュとプルリクエストに対して自動テストを実行し、問題を早期に発見する必要がある。本ワークフローは、単体テスト、ビルド検証、静的解析、フォーマットチェック、翻訳検証など、包括的な品質チェックを提供する。

**バッチの実行タイミング**：push時、PR作成/更新時、手動トリガー時

**主要な処理内容**：
1. スキップ判定（非コードファイルのみの変更時はスキップ）
2. 基本テスト（Zigユニットテスト）
3. マルチプラットフォームビルド（Linux、macOS、Windows）
4. 各種パッケージ形式ビルド（Flatpak、Snap、Nix）
5. リンター/フォーマッターチェック（zig fmt、prettier、swiftlint、alejandra、shellcheck、typos）
6. 翻訳検証、Blueprint検証
7. Valgrindによるメモリリーク検出

**前後の処理との関連**：本ワークフローが成功した場合、release-tip.ymlワークフローがトリガーされる可能性がある（mainブランチの場合）。

**影響範囲**：コードの品質ゲートとして機能し、マージ可否を決定

## バッチ種別

CI/CDワークフロー / 品質保証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（push/PR/手動） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | push, pull_request, workflow_dispatch |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| リポジトリ | ghostty-org/ghostty であること |
| 必要シークレット | CACHIX_AUTH_TOKEN, GITHUB_TOKEN 等 |

### 実行可否判定

- ghostty-org/ghostty リポジトリでのみ実行
- VOUCHED.td のみの変更の場合はスキップ可能
- パスフィルターにより特定ジョブのスキップが可能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | トリガーイベントにより決定 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| ソースコード | 各種 | リポジトリ内の全ソースコード |
| Nixキャッシュ | バイナリ | Cachixキャッシュ |
| Zigキャッシュ | バイナリ | ビルドキャッシュ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions | ステータス | 各ジョブの成功/失敗 |
| Artifacts | 各種 | ソースtarball等（build-distジョブ） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | ghostty-source.tar.gz |
| 出力先 | GitHub Actions Artifacts |
| 文字コード | - |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. skipジョブ（全ジョブ実行判定）
   └─ パスフィルターでファイル変更種別を判定
   └─ VOUCHED.tdのみ変更の場合はskip=trueを設定
2. testジョブ（基本テスト）
   └─ Zigユニットテスト実行
   └─ GTKビルドテスト
   └─ システムビルドテスト
3. 各種ビルドジョブ（testジョブ完了後）
   └─ build-bench: ベンチマークビルド
   └─ build-examples: サンプルビルド
   └─ build-flatpak/snap/nix: パッケージビルド
   └─ build-linux/macos/windows: プラットフォームビルド
   └─ build-dist: ソースtarball作成
4. 追加テストジョブ
   └─ test-gtk/simd/sentry/i18n/macos: 設定別テスト
   └─ valgrind: メモリリーク検出
5. リンター/フォーマッタージョブ
   └─ zig-fmt, prettier, swiftlint, alejandra, typos, shellcheck
6. 検証ジョブ
   └─ translations: 翻訳検証
   └─ blueprint-compiler: Blueprint検証
   └─ pinact: GitHub Actions pins検証
7. requiredジョブ（最終ステータス集約）
   └─ 全依存ジョブの結果を確認
   └─ 全成功で正常終了、1つでも失敗で異常終了
```

### フローチャート

```mermaid
flowchart TD
    A[トリガー] --> B[skipジョブ]
    B --> C{skip=true?}
    C -->|Yes| D[全ジョブスキップ]
    C -->|No| E[testジョブ]
    E --> F[ビルドジョブ群]
    E --> G[テストジョブ群]
    B --> H[リンタージョブ群]
    F --> I[requiredジョブ]
    G --> I
    H --> I
    I --> J{全成功?}
    J -->|Yes| K[正常終了]
    J -->|No| L[異常終了]
```

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

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

本バッチはデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| failure | ビルドエラー | コンパイルエラー | コードを修正 |
| failure | テスト失敗 | アサーション失敗 | テストを修正 |
| failure | フォーマット違反 | コードスタイル違反 | フォーマッターを実行 |
| failure | リントエラー | 静的解析エラー | 指摘箇所を修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動で再実行可能） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. GitHub Actionsのログを確認し、失敗原因を特定
2. ローカル環境で問題を再現・修正
3. 修正コミットをプッシュして再テスト

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 30以上のジョブ |
| 目標処理時間 | 60分以内（並列実行） |
| メモリ使用量上限 | ランナー依存 |

## 排他制御

| 項目 | 内容 |
|-----|------|
| 並行性制御 | main以外のブランチで同一ワークフローをキャンセル |
| グループ | ${{ github.workflow }}-${{ github.ref_name != 'main' && github.ref || github.run_id }} |

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | GitHub Actions標準ログ |
| 進捗ログ | ステップ実行時 | 各コマンドの出力 |
| 終了ログ | ジョブ終了時 | 成功/失敗ステータス |
| エラーログ | エラー発生時 | エラー詳細、スタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー結果 | failure | PRステータス、マージブロック |
| 実行時間 | 60分超 | タイムアウト |

## 備考

### 主要なジョブ一覧

| ジョブ名 | 説明 | 依存 |
|---------|------|------|
| skip | スキップ判定 | - |
| test | 基本テスト | skip |
| build-bench | ベンチマークビルド | test |
| build-examples | サンプルビルド | test |
| build-flatpak | Flatpakビルド | test |
| build-snap | Snapビルド | test |
| build-linux | Linuxビルド | test |
| build-macos | macOSビルド | test |
| build-windows | Windowsビルド | test |
| build-nix | Nixビルド | test |
| build-dist | ソースtarball | test |
| test-gtk | GTKテスト | test |
| test-simd | SIMDテスト | test |
| test-macos | macOSテスト | test |
| valgrind | メモリリーク検出 | test |
| zig-fmt | Zigフォーマット | skip |
| prettier | JSONフォーマット | skip |
| swiftlint | Swiftリント | skip |
| alejandra | Nixフォーマット | skip |
| shellcheck | シェルスクリプト検証 | skip |
| typos | タイポ検出 | skip |
| translations | 翻訳検証 | skip |
| blueprint-compiler | Blueprint検証 | skip |
| pinact | Actions pins検証 | skip |
| required | 最終ステータス | 全ジョブ |

### キャッシュ設定

- Nixキャッシュ: /nix
- Zigキャッシュ: /zig（Linux）、/Users/runner/zig（macOS）
- Cachix: ghostty キャッシュ使用

### ランナー

- Linux: namespace-profile-ghostty-{xsm,sm,md,lg}
- macOS: namespace-profile-ghostty-macos-tahoe
- Windows: windows-2022
