# テスト方針書

## 概要

本ドキュメントは、Actual Budget（ローカルファースト個人財務管理システム）プロジェクトにおけるテスト方針を定義するものです。本プロジェクトはモノレポ構成を採用しており、複数のパッケージ（loot-core、desktop-client、sync-server、api、crdt等）で構成されています。各パッケージに対して適切なテスト戦略を適用し、品質を担保します。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト | 個々のモジュール・関数の動作検証。ビジネスロジック、ユーティリティ関数、データ処理の正確性を確認 | 開発者（Vitest使用） |
| 結合テスト | 複数モジュール間の連携検証。API、サービス層、データベース操作の統合動作を確認 | 開発者（Vitest + Supertest使用） |
| E2Eテスト（機能テスト） | ユーザー視点でのアプリケーション全体の動作検証。予算管理、取引登録、スケジュール管理等の主要機能を検証 | 開発者・QA（Playwright使用） |
| VRT（Visual Regression Test） | UI/UXの視覚的な回帰を検出。スクリーンショット比較によりデザインの一貫性を確保 | 開発者（Playwright使用） |
| 受入テスト | ユーザー要件を満たしているかの検証。PR/マージ時の自動テストで確認 | 開発者・レビュアー |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | 予算機能、取引管理、銀行同期、スケジュール、ルール管理等の主要機能の動作検証 | PR作成時、マージ時、デイリービルド |
| 性能テスト | データベースクエリ、同期処理、大量データ処理のパフォーマンス確認 | 必要に応じて手動実施 |
| セキュリティテスト | CodeQLによる静的セキュリティ解析。脆弱性の早期検出 | PR作成時、週次（毎週土曜11:23 UTC） |
| 回帰テスト | 既存機能への影響を確認するためのE2E・VRTテスト | PR作成時、マージ時 |
| 互換性テスト | Electron、ブラウザ、モバイルUIでの動作確認 | E2Eテスト内で実施 |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 開発者による単体・結合テストの実行 | Node.js 22以上、Yarn 4.9.1以上、各パッケージのvitest.config設定 |
| CI環境（単体・結合） | GitHub Actions上での自動テスト実行 | Ubuntu Latest、Node.js 22、lageによる並列実行 |
| CI環境（E2E・VRT） | GitHub Actions上でのE2E・VRTテスト実行 | Playwright v1.57.0 Docker（mcr.microsoft.com/playwright:v1.57.0-jammy）、5シャード並列実行 |
| CI環境（Desktopアプリ） | Electronアプリのテスト実行 | Ubuntu Latest + xvfb（仮想ディスプレイ） |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Vitest | 単体テスト・結合テストフレームワーク | ^4.0.16 |
| Playwright | E2Eテスト・VRTフレームワーク | 1.57.0 |
| Testing Library | Reactコンポーネントのテストユーティリティ | @testing-library/react 16.3.0 |
| Supertest | HTTPリクエストのテスト | ^7.2.2 |
| fast-check | プロパティベーステスト | 4.5.3 |
| jsverify | プロパティベーステスト | ^0.8.4 |
| mockdate | 日付のモック | ^3.0.5 |
| fake-indexeddb | IndexedDBのモック（Webテスト用） | ^6.2.5 |
| CodeQL | 静的セキュリティ解析 | GitHub提供の最新版 |
| lage | モノレポ向けタスクランナー（テスト並列実行） | ^2.14.15 |
| oxlint | リンター（品質チェック） | ^1.41.0 |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な目標値は設定されていないが、主要機能・ビジネスロジックのテストカバーを推奨 |
| 分岐カバレッジ | 明示的な目標値は設定されていないが、主要機能・ビジネスロジックのテストカバーを推奨 |

## テストデータ

テストデータの準備は以下の方針で行います。

1. **モックデータ**: `packages/loot-core/src/server/tests/mockData.json` に共通のモックデータを定義
2. **モックサーバー**: `packages/loot-core/src/server/tests/mockSyncServer.ts` で同期サーバーをモック
3. **フィクスチャ**:
   - E2Eテスト用: `packages/desktop-client/e2e/fixtures.ts`
   - GoCardlessサービステスト用: `packages/sync-server/src/app-gocardless/services/tests/fixtures.js`
4. **ファクトリ**: `packages/loot-core/src/mocks/` ディレクトリにモック生成ユーティリティを配置
5. **スナップショット**: テスト結果のスナップショットは `__snapshots__/` ディレクトリに保存

## 不具合管理

不具合の管理は以下の方法で行います。

1. **Issue管理**: GitHub Issuesを使用
   - バグ報告テンプレートに従って報告
   - ラベル付けによる分類（bug、priority等）
2. **テスト失敗の通知**: CI/CDパイプラインで失敗時にGitHub Actions経由で通知
3. **VRT差分レポート**: PlaywrightのHTMLレポートをアーティファクトとして保存（30日間保持）
4. **自動修正**: `autofix.yml` ワークフローによる自動フォーマット・リント修正

## CI/CD連携

CI/CDパイプラインでのテスト実行は以下の構成で行います。

### ワークフロー構成

| ワークフロー | トリガー | 実行内容 |
| --- | --- | --- |
| `check.yml` (Test) | push (master), PR, merge_group | lint、typecheck、単体テスト、マイグレーションチェック |
| `e2e-test.yml` (E2E Tests) | PR, merge_group | 機能E2Eテスト（5シャード並列）、VRTテスト（5シャード並列）、Desktopアプリテスト |
| `build.yml` (Build) | push (master), PR, merge_group | API、CRDT、Web、Serverのビルド検証 |
| `codeql.yml` (CodeQL) | push (master), PR, 週次スケジュール | JavaScript静的セキュリティ解析 |

### テスト実行フロー

1. **PR作成時**:
   - Lint・型チェック → 単体テスト → E2Eテスト・VRT → ビルド検証
   - すべてのチェックがパスしないとマージ不可

2. **マージ時（master）**:
   - 同様のテストスイートを実行
   - Nightlyビルドのトリガー

3. **レポート・アーティファクト**:
   - テスト結果: GitHub Actionsのアーティファクトとして保存
   - VRTレポート: HTMLレポートとして30日間保持
   - カバレッジレポート: 生成されるがCI上での公開設定は未確認

### 並行実行戦略

- **E2Eテスト**: 5シャードに分割して並列実行（`--shard=${{ matrix.shard }}/5`）
- **VRTテスト**: 5シャードに分割して並列実行
- **concurrency設定**: 同一PR/ブランチでの重複実行を自動キャンセル（masterブランチ除く）

## 備考

1. **テストファイル命名規則**:
   - 単体・結合テスト: `*.test.ts`, `*.test.tsx`
   - E2Eテスト: `*.test.ts`（e2eディレクトリ配下）
   - specファイル: `*.spec.js`, `*.spec.ts`（主にsync-server）
   - モバイルテスト: `*.mobile.test.ts`

2. **テスト実行コマンド**:
   - 全テスト: `yarn test`
   - E2Eテスト: `yarn e2e`
   - VRTテスト: `yarn vrt`
   - Desktopアプリテスト: `yarn e2e:desktop`

3. **テスト環境の制約**:
   - Node.js 22以上が必須
   - Yarn 4.9.1以上が必須
   - Playwright実行にはChromiumブラウザが必要

4. **モノレポ構成の考慮事項**:
   - 各パッケージに独自のvitest.config設定
   - ルートのvitest.configで全パッケージのテストをプロジェクトとして統合
   - lageによるパッケージ間の依存関係を考慮したテスト実行順序管理
