@sk8metal/michi-cli 0.0.8 → 0.1.0

package/docs/user-guide/testing/test-execution-flow.md

@@ -0,0 +1,396 @@
+# テスト実行フロー
+
+このドキュメントでは、michiを使用したプロジェクトでのテスト実行フロー（Phase A/B）について説明します。
+
+## テスト実行の2つのフェーズ
+
+michiでは、テストを2つのフェーズに分けて実行します：
+
+| フェーズ | タイミング | 実行方式 | テストタイプ |
+|---------|----------|---------|------------|
+| **Phase A** | PR作成前 | CI/CD自動実行 | 単体テスト、Lint、ビルド |
+| **Phase B** | リリース準備時 | 手動実行 | 統合テスト、E2E、パフォーマンス、セキュリティ |
+
+## Phase A: PR作成前の自動テスト
+
+### 目的
+
+コード品質の基本的なチェックを自動化し、レビュワーの負担を軽減します。
+
+### 実行タイミング
+
+- **PRを作成する直前**
+- ローカルでの開発が完了した時点
+- CI/CDが自動的に実行
+
+### 実行内容
+
+#### 1. 単体テスト（必須）
+
+```bash
+# Node.js
+npm test
+
+# Java (Gradle)
+./gradlew test
+
+# PHP
+composer test
+```
+
+**合格基準**:
+- すべての単体テストが成功
+- カバレッジ95%以上（推奨）
+
+#### 2. Lint（必須）
+
+```bash
+# Node.js
+npm run lint
+
+# Java (Gradle)
+./gradlew checkstyleMain
+
+# PHP
+composer phpstan
+```
+
+**合格基準**:
+- Lintエラー: 0件
+- Lint警告: できる限り0件
+
+#### 3. ビルド（必須）
+
+```bash
+# Node.js
+npm run build
+
+# Java (Gradle)
+./gradlew build
+
+# PHP
+composer install --no-dev
+```
+
+**合格基準**:
+- ビルドエラー: 0件
+
+### Phase A実行フローチャート
+
+```text
+[開発完了]
+    ↓
+[ローカルでPhase Aを実行]
+    ↓
+単体テストが失敗？
+    YES → バグ修正 → 再実行
+    NO → ↓
+    ↓
+Lintエラーがある？
+    YES → コード修正 → 再実行
+    NO → ↓
+    ↓
+ビルドが失敗？
+    YES → エラー修正 → 再実行
+    NO → ↓
+    ↓
+[PR作成]
+    ↓
+[CI/CDが自動実行]
+    ↓
+CI/CDが成功？
+    YES → レビュー依頼
+    NO → ローカルで修正 → 再プッシュ
+```
+
+### CI/CD設定
+
+Phase AはGitHub ActionsまたはScrewdriverで自動実行されます。
+
+詳細は [ci-setup.md](../release/ci-setup.md) を参照してください。
+
+### Phase A失敗時の対応
+
+#### ケース1: 単体テストが失敗
+
+```bash
+# 失敗したテストを確認
+npm test -- --reporter=verbose
+
+# 該当するテストを実行
+npm test -- tests/unit/calculator.test.ts
+
+# バグを修正
+# テストを再実行して確認
+npm test
+```
+
+#### ケース2: Lintエラー
+
+```bash
+# 自動修正を試みる
+npm run lint:fix
+
+# 手動修正が必要な場合
+# エディタでエラー箇所を修正
+
+# 再実行して確認
+npm run lint
+```
+
+#### ケース3: ビルドエラー
+
+```bash
+# エラー詳細を確認
+npm run build
+
+# 型エラーの場合
+npm run type-check
+
+# エラーを修正
+# 再ビルドして確認
+npm run build
+```
+
+## Phase B: リリース準備時の手動テスト
+
+### 目的
+
+本番環境に近い状態で、システム全体の動作を検証します。
+
+### 実行タイミング
+
+- **PRがmainブランチにマージされた後**
+- **リリースタグを作成する前**
+- 手動で実行
+
+### 実行内容
+
+#### 1. 統合テスト（推奨）
+
+複数コンポーネント間の連携を検証します。
+
+```bash
+# Node.js
+npm run test:integration
+
+# Java (Gradle)
+./gradlew integrationTest
+
+# PHP
+composer test:integration
+```
+
+**確認項目**:
+- API層とデータベース層の連携
+- 外部サービスとの統合
+- トランザクション処理
+
+#### 2. E2Eテスト（推奨）
+
+ユーザー視点での完全なフローを検証します。
+
+```bash
+# Playwright
+npx playwright test
+
+# Cypress
+npx cypress run
+
+# Selenium
+npm run test:e2e
+```
+
+**確認項目**:
+- ユーザー登録フロー
+- 商品購入フロー
+- ログイン/ログアウト
+- エラー処理
+
+#### 3. パフォーマンステスト（任意）
+
+システムの性能を検証します。
+
+```bash
+# 負荷テストツールを使用
+# 例: Apache JMeter, k6, Artillery
+```
+
+**確認項目**:
+- レスポンスタイム
+- スループット
+- リソース使用率
+
+#### 4. セキュリティテスト（任意）
+
+セキュリティ脆弱性を検証します。
+
+```bash
+# セキュリティスキャンツールを使用
+# 例: OWASP ZAP, Snyk
+```
+
+**確認項目**:
+- 認証/認可
+- 入力値検証
+- SQL インジェクション
+- XSS
+
+### Phase B実行フローチャート
+
+```text
+[PRマージ完了]
+    ↓
+[Phase B開始]
+    ↓
+━━━━━━━━━━━━━━━━
+統合テスト（推奨）
+━━━━━━━━━━━━━━━━
+    ↓
+統合テストが失敗？
+    YES → バグ修正 → PR作成 → マージ → Phase B再実行
+    NO → ↓
+    ↓
+━━━━━━━━━━━━━━━━
+E2Eテスト（推奨）
+━━━━━━━━━━━━━━━━
+    ↓
+E2Eテストが失敗？
+    YES → バグ修正 → PR作成 → マージ → Phase B再実行
+    NO → ↓
+    ↓
+━━━━━━━━━━━━━━━━━━━━━━━━
+パフォーマンステスト（任意）
+━━━━━━━━━━━━━━━━━━━━━━━━
+    ↓
+性能要件を満たす？
+    YES → ↓
+    NO → 最適化 → PR作成 → マージ → Phase B再実行
+    ↓
+━━━━━━━━━━━━━━━━━━━
+セキュリティテスト（任意）
+━━━━━━━━━━━━━━━━━━━
+    ↓
+脆弱性が見つかった？
+    YES → 修正 → PR作成 → マージ → Phase B再実行
+    NO → ↓
+    ↓
+[Phase B完了]
+    ↓
+[リリースタグ作成]
+```
+
+### Phase B失敗時の対応
+
+Phase Bで問題が見つかった場合：
+
+1. **バグ修正のPRを作成**
+2. **Phase Aを通過させる**（CI/CD自動実行）
+3. **PRをマージ**
+4. **Phase Bを再実行**
+
+**重要**: Phase Bで見つかった問題は、必ずPR → Phase A → マージのフローを経て修正します。直接mainブランチにコミットしてはいけません。
+
+## Phase A と Phase B の違い
+
+| 項目 | Phase A | Phase B |
+|------|---------|---------|
+| **実行タイミング** | PR作成前 | リリース準備時 |
+| **実行方式** | CI/CD自動 | 手動 |
+| **テストタイプ** | 単体テスト | 統合、E2E、パフォーマンス、セキュリティ |
+| **実行頻度** | 毎PR | リリース前のみ |
+| **実行時間** | 数分 | 数十分〜数時間 |
+| **目的** | 基本品質保証 | 本番環境準備 |
+
+## テスト実行のベストプラクティス
+
+### 1. Phase Aは必ず成功させてからPR作成
+
+```bash
+# ローカルで事前確認
+npm test && npm run lint && npm run build
+
+# すべて成功したらPR作成
+gh pr create --head feature/xxx --base main
+```
+
+### 2. Phase Bは計画的に実行
+
+Phase Bは時間がかかるため、計画的に実行します：
+
+- **事前準備**: テスト環境、テストデータの準備
+- **時間確保**: 十分な時間を確保（数時間）
+- **チーム共有**: Phase B実行中であることをチームに共有
+
+### 3. テスト失敗時は慌てずに対応
+
+```text
+テスト失敗
+    ↓
+1. エラーログを確認
+2. 再現手順を特定
+3. 原因を調査
+4. 修正方法を検討
+5. 修正を実装
+6. テストで検証
+7. PR作成
+```
+
+### 4. テストはマスタテストとして常に最新を保つ
+
+テストファイルは常に最新の仕様を反映した「マスタテスト」として管理します：
+
+```text
+tests/
+├── unit/
+│   ├── user-service.test.ts      # 常に最新の仕様を反映
+│   └── calculator.test.ts
+├── integration/
+│   ├── user-api.test.ts          # 常に最新の仕様を反映
+│   └── payment.test.ts
+└── e2e/
+    ├── user-registration.test.ts # 常に最新の仕様を反映
+    └── checkout.test.ts
+```
+
+**仕様変更・機能追加時の対応**:
+
+- **新機能追加**: 既存のテストファイルに新しいテストケースを追加
+- **仕様変更**: 既存のテストケースを更新（TDDの原則に従って）
+- **機能削除**: 不要になったテストケースを削除
+
+**メリット**:
+- テスト実行時間が一定に保たれる
+- テストが常に最新の仕様を反映
+- メンテナンスが容易
+
+**phase-0、phase-1のような履歴管理はしない**
+
+## チェックリスト
+
+### Phase A実行前
+
+- [ ] ローカルですべてのテストが成功している
+- [ ] Lintエラーがない
+- [ ] ビルドが成功している
+- [ ] 新規追加したコードのテストを書いた
+
+### Phase B実行前
+
+- [ ] PRがmainブランチにマージ済み
+- [ ] テスト環境が準備されている
+- [ ] テストデータが準備されている
+- [ ] 十分な時間が確保されている
+
+### リリースタグ作成前
+
+- [ ] Phase Bのすべてのテストが成功している
+- [ ] 重大なバグが残っていない
+- [ ] パフォーマンス要件を満たしている（該当する場合）
+- [ ] セキュリティチェックが完了している（該当する場合）
+
+## 次のステップ
+
+- [リリースフロー](../release/release-flow.md): リリースタグ作成からGitHub Releaseまで
+- [テスト失敗時の対応](./test-failure-handling.md): テスト失敗時の詳細な対処方法
+- [CI/CD設定](../release/ci-setup.md): CI/CDの設定方法