# テスト方針書

## 概要

本ドキュメントは、OpenCodeプロジェクトにおけるテスト戦略、テスト環境、使用ツール、およびCI/CDパイプラインでのテスト実行方針を定義するものです。OpenCodeはAI駆動の開発ツールであり、TypeScript/JavaScript（Bun runtime）で構築されたモノレポ構成のプロジェクトです。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト | 個々のモジュール・関数・クラスの動作を検証 | 開発者 |
| 結合テスト | コンポーネント間の連携・統合動作を検証 | 開発者 |
| E2Eテスト | ユーザー視点でのアプリケーション全体の動作を検証 | 開発者 / QA |
| 型チェック | TypeScriptの型安全性を検証 | 開発者（CI自動実行） |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | 各機能の要件充足を検証（単体・E2E） | 開発中・PR作成時 |
| UIテスト | ブラウザ上でのUI動作を検証（Playwright） | PR作成時・CI |
| 回帰テスト | 既存機能への影響がないことを検証 | CI（PR・dev pushごと） |
| 静的解析 | 型チェックによるコード品質検証 | CI（PR・dev pushごと） |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 開発者が手動でテストを実行 | macOS / Windows / Linux + Bun 1.3.9 |
| CI環境（Linux） | 自動テスト実行 | blacksmith-4vcpu-ubuntu-2404 |
| CI環境（Windows） | クロスプラットフォーム検証 | blacksmith-4vcpu-windows-2025 |
| E2Eサンドボックス | 隔離されたE2Eテスト環境 | 一時ディレクトリ + モックサーバー |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Bun Test | 単体テスト・結合テストランナー | 1.3.9 |
| Playwright | E2E（End-to-End）テスト | 1.51.0 - 1.57.0 |
| Happy-DOM | 単体テスト用DOM環境モック | 20.0.11 |
| TypeScript（tsgo） | 型チェック | 5.8.2 |
| Turbo | モノレポテストオーケストレーション | 2.5.6 |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な目標未設定（継続的改善） |
| 分岐カバレッジ | 明示的な目標未設定（継続的改善） |

**備考**: 現時点ではカバレッジの数値目標は明文化されていません。コードレビューとテスト追加の習慣により品質を担保しています。

## テストデータ

### 単体テスト

- `tmpdir` ヘルパー関数を使用して一時ディレクトリを作成
- テスト用の設定ファイル（`opencode.json`）を動的に生成
- Git初期化オプションによりリポジトリ環境を再現
- テスト完了後に自動クリーンアップ（`Symbol.asyncDispose`）

### E2Eテスト

- `createTestProject` / `cleanupTestProject` によるプロジェクト管理
- `seedProjects` によるストレージ初期化
- サンドボックス環境変数（`XDG_DATA_HOME`, `XDG_CACHE_HOME`等）で隔離
- モックモデル（`opencode/big-pickle`, `opencode/gpt-5-nano`）を使用

## 不具合管理

- GitHub Issuesで不具合を管理
- PR作成時には関連Issueの参照が必須（`Fixes #<number>` / `Closes #<number>`）
- PRテンプレートにより検証方法の記載が必須
- `needs:issue` / `needs:compliance` ラベルによる自動トラッキング

## CI/CD連携

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

| イベント | 実行テスト |
| --- | --- |
| `push` to `dev` | 単体テスト + E2Eテスト + 型チェック |
| `pull_request` | 単体テスト + E2Eテスト + 型チェック |
| `workflow_dispatch` | 手動実行（全テスト） |

### ワークフロー構成

1. **test.yml**（メインテストワークフロー）
   - `unit` ジョブ: `bun turbo test` で単体テストを並列実行
   - `e2e` ジョブ: Playwright によるE2Eテスト（`unit`完了後に実行）
   - `required` ジョブ: 全テスト成功の検証

2. **typecheck.yml**（型チェックワークフロー）
   - `bun typecheck` による型検証

3. **pr-standards.yml**（PR品質チェック）
   - タイトルフォーマット検証（Conventional Commits）
   - Issue参照チェック
   - PRテンプレート準拠チェック

### クロスプラットフォームテスト

- Linux（Ubuntu 24.04）とWindows（Windows 2025）で並列実行
- マトリクス戦略による同一テストの複数環境実行
- リトライ戦略: CI環境では2回リトライ

### テスト成果物

- Playwrightレポート（HTML形式）
- テスト結果アーティファクト（失敗時のみ保持、7日間）
- スクリーンショット・ビデオ（失敗時のみ）
- トレース（初回リトライ時）

## 備考

### テストファイル命名規則

- 単体テスト: `*.test.ts`
- E2Eテスト: `*.spec.ts`（`packages/app/e2e/` ディレクトリ配下）

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

```bash
# 単体テスト（パッケージ単位）
bun --cwd packages/opencode test
bun --cwd packages/app test:unit

# E2Eテスト
bun --cwd packages/app test:e2e:local

# 全テスト（Turbo経由）
bun turbo test

# 型チェック
bun typecheck
```

### テスト構成ファイル

| ファイル | 用途 |
| --- | --- |
| `packages/app/playwright.config.ts` | Playwright E2E設定 |
| `packages/app/happydom.ts` | Happy-DOM初期化・モック設定 |
| `turbo.json` | Turboタスク依存関係定義 |
| `.github/workflows/test.yml` | CIテストワークフロー |

### テストヘルパー・フィクスチャ

| ファイル | 用途 |
| --- | --- |
| `packages/opencode/test/fixture/fixture.ts` | 一時ディレクトリ作成・テスト環境構築 |
| `packages/app/e2e/fixtures.ts` | Playwrightカスタムフィクスチャ |
| `packages/app/e2e/actions.ts` | E2Eテスト用アクションヘルパー |
| `packages/app/e2e/utils.ts` | E2Eテスト用ユーティリティ |
| `packages/app/script/e2e-local.ts` | ローカルE2E実行スクリプト |
