# テスト方針書

## 概要

本ドキュメントは、Payload CMSプロジェクトにおけるテスト戦略・テスト方針を定義する。Payloadはモノレポ構造を持つNext.js統合型CMSであり、コアパッケージ、データベースアダプター、プラグイン、UIコンポーネントなど多様なパッケージで構成される。品質保証のため、単体テスト、結合テスト、E2Eテスト、型テストを組み合わせた包括的なテスト戦略を採用している。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト (Unit Tests) | 個別のユーティリティ関数、純粋関数の動作検証 | 開発者（各パッケージ担当） |
| 結合テスト (Integration Tests) | Payload API、データベース操作、認証、フィールド処理等の統合動作検証 | 開発者（テストスイート担当） |
| E2Eテスト (End-to-End Tests) | 管理画面UI、ユーザーフロー、ブラウザ操作の検証 | 開発者（フロントエンド/フルスタック） |
| 型テスト (Type Tests) | TypeScript型定義の整合性検証 | 開発者（型定義担当） |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | コレクション操作、フィールド処理、認証、ローカライゼーション等のCMS機能検証 | PR作成時、mainブランチプッシュ時 |
| 回帰テスト | 既存機能への影響確認 | CI/CDパイプライン実行時 |
| アクセシビリティテスト (a11y) | 管理画面UIのアクセシビリティ検証 | E2Eテスト内で実施 |
| データベース互換性テスト | MongoDB、PostgreSQL、SQLite間の動作互換性検証 | CI/CDパイプライン実行時（マトリクス実行） |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 開発者によるテスト実行 | Docker Compose（MongoDB/PostgreSQL）、インメモリDB |
| CI環境 (GitHub Actions) | 自動テスト実行 | Ubuntu 24.04、Node.js、Dockerサービス（Redis、MongoDB、PostgreSQL）、LocalStack (S3) |
| Prod-like環境 | E2Eテスト用のプロダクション相当環境 | パッケージをビルド・パック後にテスト |

### データベース環境

| データベース | コンテナイメージ | 用途 |
| --- | --- | --- |
| MongoDB | mongodb/mongodb-community-server:8.2-ubi9 + mongot | 結合/E2Eテスト（デフォルト） |
| PostgreSQL | ghcr.io/payloadcms/postgis-vector:latest | 結合テスト（代替DB） |
| SQLite | インメモリ | 結合テスト（代替DB） |
| MongoDB Atlas | mongodb-atlas-local (Docker) | Atlas Vector Search テスト |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Vitest | 単体テスト、結合テストフレームワーク | 4.0.15 |
| Playwright | E2Eテストフレームワーク | 1.58.2 |
| tstyche | 型テストフレームワーク | 3.5.0 |
| axe-core | アクセシビリティ検証 | 4.11.0 |
| @axe-core/playwright | Playwright統合アクセシビリティテスト | 4.11.0 |
| LocalStack | AWS S3モックサービス | Docker経由 |
| Redis | KVストアテスト | Docker経由 |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な目標値は設定されていない |
| 分岐カバレッジ | 明示的な目標値は設定されていない |

注: 本プロジェクトではカバレッジ目標の明示的な数値設定は確認できない。代わりに、機能ごとの包括的なテストスイートによる品質担保を行っている。

## テストデータ

### テストデータ準備方針

1. **シードファイル**: 各テストスイートは専用の`seed.ts`を持ち、テストに必要なデータを事前に投入
2. **ファクトリーパターン**: テストヘルパー(`test/__helpers/`)を使用してテストデータを動的生成
3. **自己完結型テスト**: 各テストはデータを作成し、テスト終了時にクリーンアップ
4. **環境変数**: テスト用の認証情報は`test/credentials.ts`で管理（dev@payloadcms.com / test）

### テストデータ管理ルール

- テストで作成したデータは必ず削除する（`afterEach`/`afterAll`フックを使用）
- 複数テストで共通するクリーンアップは`afterEach`で一元化
- 作成したリソースのIDは共有配列で追跡管理

## 不具合管理

### 不具合報告・追跡

- **GitHub Issues**: バグレポート、機能リクエストの管理
- **GitHub Pull Requests**: コードレビュー、テスト結果の確認
- **CI/CDステータス**: テスト失敗時のアーティファクト保存（test-results）

### Flakyテスト対策

- CI環境ではVitest/Playwrightにリトライ機構を設定
- Vitest: CI環境で最大2回リトライ（`retry: process.env.CI ? 2 : 0`）
- Playwright: CI環境で最大5回リトライ（`retries: CI ? 5 : undefined`）

## CI/CD連携

### GitHub Actions ワークフロー

| ジョブ | トリガー | 内容 |
| --- | --- | --- |
| lint | PR作成時、mainプッシュ時 | ESLint、StyleLint実行 |
| build | 関連ファイル変更時 | 全パッケージのビルド |
| tests-unit | ビルド成功後 | 単体テスト実行 |
| tests-types | ビルド成功後 | TypeScript型テスト実行 |
| tests-int | ビルド成功後 | 結合テスト実行（MongoDB/PostgreSQL/SQLiteマトリクス、シャーディング対応） |
| tests-e2e | ビルド成功後 | E2Eテスト実行（MongoDB、シャーディング対応） |
| build-and-test-templates | ビルド成功後 | テンプレートプロジェクトのビルド・テスト |
| tests-type-generation | ビルド成功後 | 型生成テスト |
| all-green | 全テスト完了後 | 最終ステータスチェック |

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

```bash
# 全テスト実行
pnpm run test

# 単体テスト
pnpm run test:unit

# 結合テスト（MongoDB）
pnpm run test:int

# 結合テスト（PostgreSQL）
pnpm run test:int:postgres

# 結合テスト（SQLite）
pnpm run test:int:sqlite

# E2Eテスト
pnpm run test:e2e

# E2Eテスト（プロダクション環境）
pnpm run test:e2e:prod

# 型テスト
pnpm run test:types
```

### 並列実行・シャーディング

- **結合テスト**: データベースごとにシャード分割してCI実行
- **E2Eテスト**: テストスイートごとにシャード分割、`--fully-parallel`フラグで並列実行
- **Playwrightワーカー数**: ローカル16、CI環境はシリアル実行（`--workers=1`）またはスイート設定による

## テストディレクトリ構造

```
test/
├── __helpers/           # テストヘルパー、ユーティリティ
│   └── shared/
│       ├── db/          # データベース Docker Compose設定
│       │   ├── mongodb/
│       │   ├── postgres/
│       │   └── mongodb-atlas/
│       ├── NextRESTClient.js
│       └── initPayloadInt.js
├── <feature-name>/      # 機能別テストディレクトリ
│   ├── config.ts        # Payload設定ファイル
│   ├── int.spec.ts      # 結合テスト
│   ├── e2e.spec.ts      # E2Eテスト
│   └── payload-types.ts # 生成された型定義
├── playwright.config.ts # Playwright設定
├── vitest.setup.ts      # Vitest セットアップ
└── credentials.ts       # テスト用認証情報
```

## 備考

### テスト作成ガイドライン

1. **自己完結性**: テストは独立して実行可能であること
2. **命名規則**: テスト名は`should`で始める（例: `should create document with custom ID`）
3. **1テスト1検証**: 各テストは1つの振る舞いのみを検証
4. **スラッグ共有**: コレクション・グローバルスラッグは共有ファイルで定義
5. **変数宣言後の空行**: 可読性向上のため空行を挿入

### 環境変数

| 変数名 | 用途 |
| --- | --- |
| PAYLOAD_DATABASE | 使用データベース（mongodb/postgres/sqlite） |
| POSTGRES_URL | PostgreSQL接続URL |
| MONGODB_URL | MongoDB接続URL |
| REDIS_URL | Redis接続URL |
| PAYLOAD_DROP_DATABASE | データベースドロップフラグ |
| DISABLE_LOGGING | ログ出力抑制フラグ |

### ブラウザ設定（E2Eテスト）

- **ブラウザ**: Chromium
- **トレース**: CI環境では初回リトライ時のみ取得
- **スクリーンショット**: デフォルト無効
- **ビデオ**: デフォルト無効
