# テスト方針書

## 概要

本ドキュメントは、Ghosttyプロジェクトにおけるテスト戦略、テスト環境、テストツール、およびCI/CDパイプラインでのテスト実行方針を定義する。GhosttyはZig言語で実装されたクロスプラットフォームターミナルエミュレータであり、macOS、Linux（GTK/Wayland/X11）、Windows、Android、iOS、WebAssemblyなど多様なプラットフォームをサポートしている。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト | 各Zigモジュールの関数・構造体の正確性を検証 | 開発者 |
| 結合テスト | コンポーネント間の連携（ターミナルエミュレーション、レンダリング、フォント処理等）を検証 | 開発者 |
| システムテスト | 完全なアプリケーションビルドの動作確認、各プラットフォームでの起動・基本操作の検証 | 開発者/CI |
| 受入テスト | Nix VMベースの統合テスト、実際のデスクトップ環境での動作検証 | CI/QA |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | Zigの組み込みテスト機能による単体テスト、libghostty-vtモジュールテスト | コミット時・PR時 |
| 性能テスト | ベンチマークツール（GraphemeBreak, CodepointWidth, TerminalParser等）による性能測定 | リリース前・必要に応じて |
| メモリリークテスト | Valgrindによるメモリリーク検出 | PR時・リリース前 |
| フォーマット・静的解析テスト | zig fmt, prettier, swiftlint, alejandra, shellcheck, typosによるコード品質チェック | コミット時・PR時 |
| 統合テスト（VMテスト） | Nix VMによるGNOME環境での実際の動作検証 | PR時・mainブランチマージ時 |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| Linux (x86_64) | 主要テスト環境 | Ubuntu系、Nix環境、GTK4、Wayland/X11 |
| Linux (aarch64) | ARMプラットフォームテスト | ARM64 Linux、Nix環境 |
| macOS (Tahoe/Xcode 26) | macOSネイティブアプリテスト | macOS、Xcode 26、macOS SDK 26 |
| Windows | Windowsビルドテスト | Windows 2022、PowerShell |
| Nix VM (GNOME) | 統合テスト環境 | NixOS VM、GNOME Desktop、home-manager |
| Docker (Debian 13) | Debianビルドテスト | Debian 13コンテナ |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Zig Test Framework | 単体テスト・結合テスト | Zig 0.15.2 |
| Valgrind | メモリリーク検出 | システム標準 |
| Nix/NixOS | テスト環境構築・VM統合テスト | nixos-unstable |
| zig fmt | Zigコードフォーマット検証 | Zig 0.15.2 |
| prettier | ドキュメント・リソースフォーマット | devShell.nix指定バージョン |
| swiftlint | Swiftコードリント (macOS) | devShell.nix指定バージョン |
| alejandra | Nixコードフォーマット | devShell.nix指定バージョン |
| shellcheck | シェルスクリプト検証 | devShell.nix指定バージョン |
| typos | タイポ検出 | devShell.nix指定バージョン |
| pinact | GitHub Actionsピン検証 | devShell.nix指定バージョン |
| blueprint-compiler | GTK Blueprintファイル検証 | 0.16.0以上 |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な目標値なし（Zigのテストフレームワーク特性による） |
| 分岐カバレッジ | 明示的な目標値なし |

**備考**: Ghosttyプロジェクトでは、カバレッジツールによる数値目標よりも、重要なコンポーネント（ターミナルエミュレーション、フォント処理、レンダリング等）のテスト網羅性を重視している。

## テストデータ

テストデータは以下のディレクトリに配置されている:

- `src/config/testdata/` - テーマ設定テストデータ（theme_dark, theme_light, theme_simple）
- `src/terminal/kitty/testdata/` - Kittyプロトコル関連テストデータ（画像データ等）
- `src/crash/testdata/` - クラッシュダンプ解析テストデータ
- `src/font/shaper/testdata/` - フォントシェイピングテストデータ（アラビア語テキスト等）
- `src/font/sprite/testdata/` - スプライトフォントテストデータ（各種Unicode範囲のPNG画像）

テストデータは実際の使用シナリオを再現するため、実データに基づいたものが使用されている。

## 不具合管理

- **Issue管理**: GitHubのIssueを使用
- **不具合分類**: ラベルによる分類（bug, enhancement等）
- **優先度管理**: GitHub Milestoneによる管理
- **ワークフロー**: Issue → PR → レビュー → マージ → クローズ

## CI/CD連携

### GitHub Actionsワークフロー

テストは `.github/workflows/test.yml` で定義されており、以下のジョブが実行される:

#### 必須テストジョブ

| ジョブ名 | 説明 |
| --- | --- |
| test | 基本的な単体テスト（`zig build test`） |
| test-gtk | GTKランタイムテスト（X11/Wayland組み合わせマトリックス） |
| test-simd | SIMDオプション有効/無効でのビルドテスト |
| test-sentry-linux | Sentryクラッシュレポート機能のビルドテスト |
| test-i18n | 国際化機能のビルドテスト |
| test-macos | macOSでの単体テスト |
| valgrind | Valgrindによるメモリリークテスト |

#### ビルド検証ジョブ

| ジョブ名 | 説明 |
| --- | --- |
| build-linux | Linux (x86_64/aarch64) ビルド |
| build-macos | macOS (Xcode) ビルド |
| build-macos-freetype | FreeTypeバックエンドでのmacOSビルド |
| build-windows | Windowsビルド（continue-on-error） |
| build-nix | Nixパッケージビルド（releasefast/debug） |
| build-flatpak | Flatpakビルド |
| build-snap | Snapビルド |
| build-dist | ソースtarball作成・検証 |
| build-libghostty-vt | 各種ターゲット向けlibghostty-vtビルド |
| build-examples | サンプルプログラムのビルド |
| build-bench | ベンチマークツールのビルド |

#### リンター・フォーマッタージョブ

| ジョブ名 | 説明 |
| --- | --- |
| zig-fmt | Zigコードフォーマット検証 |
| prettier | ドキュメントフォーマット検証 |
| swiftlint | Swiftコードリント |
| alejandra | Nixコードフォーマット検証 |
| typos | タイポ検出 |
| shellcheck | シェルスクリプト検証 |
| translations | 翻訳ファイル検証 |
| blueprint-compiler | GTK Blueprintファイル検証 |
| pinact | GitHub Actionsピン検証 |

### テスト実行トリガー

- **push**: 全ブランチでのプッシュ時
- **pull_request**: PRオープン・更新時
- **workflow_dispatch**: 手動実行

### スキップ条件

- `VOUCHED.td` ファイルのみの変更時はテストをスキップ
- パスベースのフィルタリングにより、変更されたファイルに関連するテストのみを実行

### Nix VM統合テスト

`nix/tests.nix` で定義されたNixOS VMベースの統合テストが実施される:

- **basic-version-check**: Ghosttyバージョン確認
- **basic-window-check-gnome**: GNOMEデスクトップでのウィンドウ表示テスト
- **ssh-integration-test**: SSH terminfo統合テスト

## テストコマンド

### 開発者向けテストコマンド

```bash
# 基本的な単体テスト
zig build test

# テストフィルタ付き実行
zig build test -Dtest-filter=<filter>

# Valgrindでのメモリリークテスト
zig build run-valgrind

# Valgrindでのテスト実行
zig build test-valgrind

# libghostty-vtテスト
zig build test-lib-vt

# フォーマットチェック
zig fmt --check .

# Nix環境でのテスト
nix develop -c zig build test
```

### CI環境でのテスト実行

```bash
# 基本テスト
nix develop -c zig build -Dapp-runtime=none test

# GTKビルドテスト
nix develop -c zig build -Dapp-runtime=gtk -Demit-docs -Demit-webdata

# 各種オプションでのテスト
nix develop -c zig build test -Dsimd=true/false
nix develop -c zig build -Dsentry=true/false
nix develop -c zig build -Di18n=true/false
```

## 備考

- Ghosttyは複数プラットフォーム対応のため、CI/CDでは各プラットフォーム固有の環境でビルド・テストを実施している
- macOSビルドにはXcode 26およびmacOS SDK 26が必要
- WindowsビルドはPowerShellで実行され、エラーが発生しても継続される（continue-on-error: true）
- Nix VM統合テストにより、実際のデスクトップ環境での動作を検証している
- メモリリーク検出にはValgrindを使用し、GTK由来の既知のリークは `valgrind.supp` で抑制されている
