現代のソフトウェア開発では、信頼性の高いテスト自動化が品質保証とリリース速度の両立に不可欠です。本稿では、GitHub IssuesとGit worktreeを基盤とするテスト自動化フレームワークを紹介します。このアプローチは、テストタスクの可視化、環境分離、並列実行を自然に実現し、開発フローにスムーズに組み込めます。

設計思想と構成要素

本フレームワークは「テストをコードとして管理する」ことを前提に設計されています。主な特徴は以下の通りです：

• Issue駆動型テスト管理：各テストケースや検証要件をGitHub Issueとして定義し、ラベル（test:unit, test:integration）で分類
• worktreeベースの環境分離：異なるテストスコープ（例：ユニット／インテグレーション）用に独立した作業ツリーを自動生成
• エージェント型実行エンジン：verify-agentという専用コンポーネントがテストのセットアップ・実行・解析を一貫して担当
• 状態感知型コマンド体系：テストライフサイクルに応じた明確なステップ（準備 → 実行 → 評価）をCLIで表現

主要コンポーネント

verify-agent エージェント

テスト実行の中核となるモジュールで、YAML形式の設定ファイル（.ccpm/agents/verify.yaml）に基づき動作します。対応機能には以下が含まれます：

• テストフレームワークの自動検出（Jest, pytest, Vitestなど）
• 依存関係の整合性チェック（package-lock.jsonやpoetry.lockとの照合）
• 実行ログの構造化収集（JSON Lines形式）
• 失敗時のスタックトレースと再現手順の提案

コアCLIコマンド

単体検証の自動化フロー

最小単位の機能検証を高速かつ反復可能にするための手順です。

ステップ1：環境準備

ccpm verify setup --layer=unit --target=auth-service

この操作により、auth-service専用のworktreeが生成され、必要なテストライブラリが確認されます。

ステップ2：検証実行

ccpm verify run --layer=unit --filter="login_.*"

verify-agentは指定された正規表現にマッチするテストのみを実行し、結果をlogs/unit-20240517.jsonlへ逐次書き込みます。

ステップ3：結果解析

実行後、ccpm verify report --input=logs/unit-*.jsonlにより以下が出力されます：

• カバレッジ統計（lines: 89.2%, functions: 92.1%）
• 遅延が顕著なテストケース（test_login_with_invalid_token: 1.2s）
• 失敗理由の簡易分類（assertion_error, timeout, network_unreachable）

結合検証の自動化フロー

複数コンポーネント間の相互作用を検証するための高信頼性フローです。

ステップ1：統合環境構築

ccpm verify setup --layer=integration --services="db,api,gateway"

Docker Composeによるローカルサービス群の起動、テスト用データベースの初期化、および環境変数の注入を行います。

ステップ2：シナリオ実行

ccpm verify run --layer=integration --scenario=user-onboarding-v2

事前に定義されたYAMLシナリオ（scenarios/user-onboarding-v2.yaml）に従い、API連携→DB書き込み→通知送信の全フローを実行します。

ステップ3：相互作用評価

生成されるレポートには以下が含まれます：

• サービス間通信の成功/失敗比率（例：gateway→api: 99.8% success）
• HTTPステータスコード分布（2xx: 96%, 4xx: 3%, 5xx: 1%）
• 非同期処理の完了時間ヒストグラム（p95: 420ms）

CI/CD連携の実装例

GitHub Actionsでの自動テストトリガーは、以下のようにシンプルに実装可能です：

# .github/workflows/verify.yml
on:
  pull_request:
    branches: [main]
    types: [opened, synchronize]

jobs:
  unit-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Setup CCPM
        run: curl -sL https://get.cc.pm | bash
      - name: Run unit verification
        run: ccpm verify run --layer=unit --coverage
      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with: { file: ./coverage/lcov.info }

運用上の推奨事項

• テストの粒度制御：単体テストは「1関数＝1テスト」、結合テストは「1ユースケース＝1シナリオ」を原則とする
• 環境の不変性確保：worktree名にタイムスタンプを含め、CIジョブごとに完全に分離した環境を提供
• 結果の機械可読性：すべての出力をJSON Lines形式で記録し、LogstashやGrafanaとの連携を想定
• フィードバックの迅速化：PRコメントにテスト結果のサマリーを自動挿入（GitHub App連携）