# テスト方針書

## 概要

本ドキュメントは、Liam-HQ プロジェクトにおけるテスト方針を定義するものである。本プロジェクトはモノレポ構成で、React 19、Next.js 15、TypeScript をベースとしたフロントエンドアプリケーション群と、Supabase を利用したデータベース層で構成される。テストは単体テスト、結合テスト、E2Eテスト、データベーステストの4階層で実施する。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト | コンポーネント、ユーティリティ関数、パーサーなどの個別モジュールの動作検証 | 開発者 |
| 結合テスト | LangGraph エージェントなど、複数モジュールの連携動作検証 | 開発者 |
| E2Eテスト | ユーザー視点でのエンドツーエンドシナリオ検証、VRTによる視覚的回帰検出 | 開発者/QA |
| データベーステスト | RLS ポリシー、RPC 関数、トリガーなどの PostgreSQL 機能検証 | 開発者 |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | ビジネスロジック、データ変換、状態管理の動作確認 | PR作成時、CI実行時 |
| 視覚回帰テスト (VRT) | UIコンポーネントの視覚的変更検出 | デプロイ時 (Vercel deployment後) |
| セキュリティテスト | CodeQL による静的解析、依存関係レビュー | Push時、PR作成時 |
| データベース整合性テスト | スキーマ、RLS、トリガーの検証 | PR作成時 (db変更時) |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 開発時の即時フィードバック | Node.js + Vitest + Supabase Local |
| CI環境 (GitHub Actions) | PR・マージ時の自動テスト | Ubuntu latest + pnpm + Supabase CLI |
| Preview環境 (Vercel) | デプロイ後のE2Eテスト | Vercel Preview + Playwright |
| Production環境 (Vercel) | 本番デプロイ後のE2Eテスト | Vercel Production + Playwright |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Vitest | 単体テスト、結合テストフレームワーク | 3.2.4 |
| @vitest/coverage-v8 | カバレッジ計測 | 3.2.4 |
| Playwright | E2Eテスト、VRT | playwright.config.ts で設定 |
| pgTAP | PostgreSQLテストフレームワーク | Supabase CLI 経由 |
| Splinter | SQLリンティング | @liam-hq/db 経由 |
| CodeQL | セキュリティ静的解析 | route06/actions ワークフロー |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な目標値は未設定（プロジェクト方針に依存） |
| 分岐カバレッジ | 明示的な目標値は未設定（プロジェクト方針に依存） |

**備考**: `vitest.config.ts` にてカバレッジプロバイダー v8 が設定されており、text、json、html 形式でレポート出力が可能。テスト対象から除外されるファイルとして、`node_modules`、`dist`、`.next`、`storybook-static`、`.d.ts`、`.config.*`、`.setup.*`、`stories/**`、テストファイル自体が定義されている。

## テストデータ

### 単体・結合テスト

- モックデータおよびフィクスチャを使用
- `vitest.setup.ts` でグローバルなモック設定を実施
- 環境変数は `.env` / `.env.local` から dotenv 経由で読み込み

### データベーステスト

- `setup-testing.sql` によるテスト環境セットアップ
- pgTAP を使用したテストケース実装
- Supabase Local を使用したローカルDB環境での実行

### E2Eテスト

- `globalSetup.ts` によるテスト前処理
- `storageState.json` による認証状態の永続化
- Vercel Preview/Production 環境への実際のデプロイに対する実行

## 不具合管理

- GitHub Issues を使用した不具合トラッキング
- PR テンプレート (`pull_request_template.md`) に基づく変更管理
- CI での自動テスト失敗時は PR のマージをブロック
- E2E テスト失敗時は Slack 通知による即時アラート（Production環境のみ）

## CI/CD連携

### 単体・結合テスト (frontend-ci.yml)

- **トリガー**: Pull Request、Merge Group
- **実行条件**: フロントエンド関連ファイル変更時
- **プロセス**:
  1. pnpm セットアップ
  2. Supabase Local 起動
  3. 環境変数設定
  4. `pnpm test` 実行
  5. 生成ファイルの差分チェック

### E2Eテスト (e2e_tests.yml)

- **トリガー**: deployment_status (Vercel デプロイ完了時)
- **対象ブラウザ**: Chromium、Mobile Safari
- **実行条件**: liam-app の Production/Preview デプロイ成功時
- **プロセス**:
  1. Playwright ブラウザインストール（キャッシュ活用）
  2. E2E テスト実行
  3. 失敗時はテスト結果アーティファクトをアップロード
  4. GitHub Status への結果ポスト
  5. Production 失敗時は Slack 通知

### データベーステスト (database-ci.yml)

- **トリガー**: Pull Request（db パス変更時）、Merge Group、手動実行
- **プロセス**:
  1. Supabase CLI セットアップ
  2. Supabase Local 起動
  3. Splinter リント実行
  4. pgTAP テストセットアップ
  5. `supabase test db` 実行

### セキュリティスキャン

- **CodeQL (codeql.yml)**: Push 時に静的解析を実行
- **依存関係レビュー (dependency_review.yml)**: PR 時に脆弱性チェック

## 備考

### テスト原則 (docs/test-principles.md)

本プロジェクトでは Vladimir Khorikov の「4つの柱」に基づくテスト設計を採用：

1. **回帰からの保護** - 破壊的変更の検出
2. **リファクタリング耐性** - 内部実装変更時の安定性
3. **高速フィードバック** - 迅速な実行
4. **保守性** - 理解・修正の容易さ

### テスト優先度

- **Critical**: コアビジネスロジック、データ整合性、セキュリティ境界、決済関連
- **Medium**: 共有ユーティリティ、ユーザーインタラクション、モジュール間連携
- **Low**: 単純なロジック、純粋なUI スタイリング、設定定数

### パッケージ別テスト設定

各パッケージは独自の `vitest.config.ts` を持ち、ワークスペース構成でテストを管理：

- `frontend/apps/app` - メインWebアプリケーション
- `frontend/packages/schema` - スキーマパーサー
- `frontend/packages/ui` - UIコンポーネントライブラリ
- `frontend/packages/erd-core` - ERD可視化コア
- `frontend/internal-packages/agent` - AIエージェント（結合テスト含む）
- `frontend/internal-packages/db` - データベースユーティリティ
