test-gap-analyzer

テストギャップ分析スキル

目的

このスキルは、コードベースを自動的に分析し、テストされていない関数、カバレッジの低い領域、未作成のエッジケーステストを特定します。amplihack のテストピラミッド（ユニットテスト 60％、統合テスト 30％、E2E テスト 10％）に沿って、優先度とリスクへの影響ごとに整理した、実行可能なテスト提案を生成します。

このスキルを使用するタイミング

• コードレビュー：PR をマージする前に、テストのギャップを特定します
• テスト計画：リスクに基づいて、次にテストする項目の優先順位を決めます
• カバレッジの改善：カバレッジの低い領域を体系的に対象にします
• エッジケースの発見：テストされていない障害モードや境界値を見つけます
• 新しいモジュール：リリース前に包括的なテストカバレッジを確保します
• レガシーコード：テストカバレッジを段階的に改善します
• リファクタリング：変更の前後でカバレッジを確認します

主な概念

amplihack のテストピラミッド

テストは次の割合に沿って作成する必要があります。

• ユニットテスト 60％：モックした依存関係を使って、個々の関数やメソッドの動作をテストします
• 統合テスト 30％：複数のコンポーネントが連携して動作することをテストします
• E2E テスト 10％：ユーザーのワークフロー全体をエンドツーエンドでテストします

このスキルは、カバレッジの優先度を付けながら、これらの層にテストをバランスよく配分できるよう支援します。

ギャップ分析のカテゴリ

このスキルは、次の領域におけるギャップを特定します。

1. 未テストの関数／メソッド：テストカバレッジがまったくない関数
2. カバレッジの低い領域：目標しきい値（85％以上）を下回るモジュールや関数
3. 不足しているエッジケース：境界条件、エラーパス、null チェック
4. 統合テストのギャップ：テストされていないコンポーネント間の相互作用
5. エラーパスのカバレッジ：例外処理と障害モード

分析プロセス

ステップ 1：コードベースのスキャン

アナライザーは次の処理を行います。

1. 指定されたディレクトリ内のすべてのソースコードファイルを検出します
2. すべての関数、メソッド、クラスを特定します
3. コード構造と依存関係をマッピングします
4. 現在のテストカバレッジを判定します（利用可能な場合）

ステップ 2：カバレッジ分析

各関数／メソッドについて、次の処理を行います。

1. テストが存在するか確認します
2. カバレッジデータが利用可能な場合、行カバレッジを計算します
3. テストされていない分岐とパスを特定します
4. エラーハンドリングのカバレッジを記録します

ステップ 3：ギャップの特定

ギャップを次の基準で分類します。

1. リスクレベル：関数の複雑さと重要度に基づいて、高・中・低に分類します
2. 種類：未テスト、一部カバレッジ、エッジケース不足
3. 工数：十分なテストを書くために必要な時間を見積もります
4. 影響：システムの信頼性に対する関数の重要度

ステップ 4：テスト提案の生成

各ギャップについて、次の内容を生成します。

1. 具体的なテストケースの説明
2. サンプルコード付きのテストテンプレート
3. 対象にすべきエッジケース
4. 期待される動作
5. テストすべきエラー条件

ステップ 5：優先順位付け

提案を次の基準で整理します。

1. リスクへの影響（重要な関数を優先）
2. テストピラミッドにおける配分
3. 必要な工数
4. 依存関係

スキルの機能

コード分析

• Python、JavaScript、TypeScript、Go のコードベースをスキャンします
• すべてのパブリック関数とプライベート関数を特定します
• 追加のテストが必要な複雑な関数を検出します
• 関数の依存関係をマッピングします
• 未使用のパラメーターや実行されないコードパスを見つけます

カバレッジの検出

• .coverage ファイルを解析します（Python）
• coverage.json レポートを分析します
• カバーされていない分岐を特定します
• 一部のみテストされている関数を見つけます
• カバレッジしきい値への違反を検出します

テストギャップの発見

• テストがまったくない関数
• 一度も実行されていない分岐
• テストされていないエラーパス
• 見落とされている境界条件
• カバーされていない統合ポイント
• 不足しているタイムアウトのシナリオ
• リソース枯渇のケース

エッジケースの特定

• null／None の入力
• 空のコレクション
• 境界値（0、max_int など）
• Unicode／マルチバイト文字列
• 並行処理の問題
• リソース制限
• 型の不一致
• async／await のパターン

テストテンプレートの生成

次の項目にすぐ使えるテストテンプレートを提供します。

• ユニットテスト（モックした依存関係）
• 統合テスト（実際のコンポーネント）
• E2E テスト（ワークフロー全体）
• パラメーター化テスト
• プロパティベーステスト
• パフォーマンステスト

使用例

例 1：Python プロジェクトの分析

User: Analyze test coverage gaps in my src/ directory

Claude:
1. Scans src/ for all Python files
2. Reads .coverage or uses ast analysis
3. Identifies untested functions
4. Generates gap report with suggestions

Output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Test Gap Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary:
- Total functions: 145
- Untested: 23 (16%)
- Low coverage (< 85%): 34 (23%)

CRITICAL GAPS (High Risk):
1. payment_processor.py::process_payment()
   - Untested | Handles money | 15 min effort
   - Suggested tests:
     - Valid payment processing
     - Insufficient funds error
     - Payment timeout
     - Currency conversion

MEDIUM GAPS:
2. user_service.py::validate_email()
   - 40% coverage | Missing edge cases
   - Suggested tests:
     - Unicode characters
     - Long email addresses
     - Special characters

LOW GAPS:
3. utils.py::format_date()
   - 60% coverage
   - Suggested tests:
     - Timezone handling
     - Daylight saving transitions

例 2：テストテンプレートの取得

User: Generate test templates for my untested auth module

Claude:
Creates templates organized by testing pyramid:

Unit Tests (60%):
- test_token_validation_valid()
- test_token_validation_expired()
- test_token_validation_invalid_signature()

Integration Tests (30%):
- test_auth_flow_with_database()
- test_multi_user_concurrent_auth()

E2E Tests (10%):
- test_user_login_to_protected_resource()
- test_session_persistence_across_requests()

例 3：カバレッジ改善計画

User: Help me improve test coverage from 65% to 85%

Claude:
1. Analyzes current coverage
2. Identifies gaps blocking 85% threshold
3. Prioritizes by impact
4. Estimates effort

Output:
To reach 85% coverage:
- 12 quick wins (< 2 hours each)
- 3 medium tasks (2-4 hours each)
- 2 complex tasks (4+ hours each)

Recommended order:
1. Add error case tests (5 tests, 3 hours) -> +8%
2. Cover auth edge cases (8 tests, 4 hours) -> +6%
3. Add integration tests (12 tests, 6 hours) -> +7%

分析チェックリスト

カバレッジの調査

• 対象ディレクトリ内のすべてのソースファイルを特定する
• 現在のカバレッジ率を確認する
• テストされていない関数をすべて見つける
• カバレッジが85%未満の関数を特定する
• 分岐カバレッジの不足箇所を把握する

不足箇所の分類

• リスクレベル（高／中／低）で分類する
• 不足箇所ごとの工数を見積もる
• クリティカルパスの関数を特定する
• 依存関係を見つける
• 影響度に基づいて優先順位を付ける

テスト提案の生成

• 単体テストのテンプレートを生成する
• 統合テストのテンプレートを生成する
• エッジケースを提案する
• エラーシナリオのテストを提示する
• パラメーター化テストの例を含める

レポートの生成

• 概要統計
• 優先順位別の不足箇所一覧
• 各不足箇所のテストテンプレート
• 合計工数の見積もり
• 推奨テスト順序

出力形式

標準レポート構成

# Test Gap Analysis Report

## Summary

- Total functions: N
- Untested functions: N (X%)
- Functions < 85%: N (X%)
- Average coverage: X%

## Critical Gaps (Must Test)

1. Function name | Type | Priority | Effort
   Suggested tests: [list]

## Medium Priority Gaps

[Similar structure]

## Low Priority Gaps

[Similar structure]

## Testing Pyramid Distribution

Current:

- Unit: X% | Target: 60%
- Integration: X% | Target: 30%
- E2E: X% | Target: 10%

## Test Templates

[Ready-to-use test code]

## Effort Estimate

- Quick wins: N hours
- Medium tasks: N hours
- Complex work: N hours
- Total: N hours

テストテンプレートの例

単体テストテンプレート

def test_function_name_happy_path():
    """Test function with valid inputs."""
    # Arrange
    input_data = {...}
    expected = {...}

    # Act
    result = function_name(input_data)

    # Assert
    assert result == expected

エラーケースのテンプレート

def test_function_name_invalid_input():
    """Test function raises ValueError on invalid input."""
    with pytest.raises(ValueError, match="Expected error message"):
        function_name(invalid_input)

エッジケースのテンプレート

def test_function_name_edge_case():
    """Test function handles edge case correctly."""
    # Test boundary conditions
    result = function_name(boundary_value)
    assert result is not None

統合テストテンプレート

def test_user_service_with_database(test_db):
    """Test user service with real database."""
    user_service = UserService(test_db)
    user = user_service.create_user("[email protected]")
    assert user.id is not None

哲学との整合性

徹底したシンプルさ

• 包括的なカバレッジではなく、不可欠なテストに集中する
• カバレッジは85%で十分（それ以上は効果が逓減する）
• 実装の詳細をテストしない
• コードの構造ではなく、動作をテストする

BSゼロの実装

• すべてのテストテンプレートがそのまま動作する
• プレースホルダーのテストやTODOコメントは含めない
• テストが実際の価値をもたらす
• エッジケースは具体的で、一般論にとどまらない

テストピラミッド

• 単体テストを優先する（高速で、分離されている）
• 統合テストを追加する（契約を検証する）
• E2Eテストは最小限にする（ユーザーフローを検証する）
• バランスの取れた配分で、壊れやすさを防ぐ

他のスキルとの連携

連携するスキル

• code-quality-analyzer：複雑さを特定する
• module-spec-generator：テストを仕様に合わせる
• refactor-advisor：テストの変更を計画する
• type-safety-checker：型の契約をテストする

活用先

• CI Validation：マージ前にテストが成功することを確認する
• Documentation：モジュールの使い方を示す
• Regression Prevention：リグレッションを防ぐ

よくあるパターン

パターン 1：不足箇所を素早く発見する

User: Quick test coverage review of api/

Claude:
- Scans directory
- Identifies top 5 gaps
- Provides quick recommendations
- Total time: < 2 minutes

パターン 2：体系的にカバレッジを改善する

User: Plan test coverage improvement from 60% to 85%

Claude:
- Analyzes gaps
- Creates phased improvement plan
- Prioritizes by risk
- Provides effort estimates
- Generates all test templates

パターン 3：新規モジュールのテストを計画する

User: Generate complete test plan for new auth module

Claude:
- Analyzes module structure
- Maps public functions
- Creates test suggestions
- Balances testing pyramid
- Provides all templates

品質チェック

分析後、次の点を確認します。

• 不足箇所が正確に特定されている
• テストテンプレートをすぐに使用できる
• 工数の見積もりが現実的である
• リスク分析に基づいて優先順位が付けられている
• テストピラミッドのバランスが取れている
• エッジケースが具体的で、一般論にとどまらない
• 統合ポイントが特定されている
• エラーパスが網羅されている

避けるべきよくある落とし穴

❌ 実装を過剰にテストする

コードの仕組みではなく、動作をテストします。詳細は変更される可能性があります。

❌ 一般的すぎるエッジケース

具体的にします。「エッジケースをテストする」ではなく、「空文字列をテストする」とします。

❌ 統合を無視する

関数を個別にテストするだけにしないでください。関数がどのように連携するかをテストします。

❌ エラーパスの不足

すべてのエラー条件に対して、少なくとも1つのテストを用意します。

❌ 依存関係をテストしない

外部システムはモックしますが、統合ポイントはテストします。

成功基準

優れたテストギャップ分析では、次のことを満たします。

• テストされていない関数をすべて特定する
• リスクと影響度に基づいて優先順位を付ける
• すぐに使えるテストテンプレートを提示する
• テストピラミッドのバランスを取る
• 工数を現実的に見積もる
• エッジケースの提案を含める
• 統合の不足箇所を把握する
• 実行可能な推奨事項を提示する

効果的なテスト計画のヒント

1. 重要な機能から始める：金銭、セキュリティ、データの整合性
2. テストテンプレートを使う：ゼロから作成しない
3. ピラミッドのバランスを取る：エッジケースを過剰にテストしない
4. 実装ではなく契約をテストする：重要なのは振る舞いであり、詳細ではありません
5. 正常系とエラーケースを含める：どちらも重要です
6. カバレッジの追跡を自動化する：リグレッションを早期に検出する
7. 反復的に改善する：カバレッジ85％は現実的ですが、100％は過剰です
8. テストが存在する理由を記録する：将来のメンテナーが意図を理解できるようにします

ツールとコマンド

Python プロジェクトの場合

# Generate coverage report
coverage run -m pytest
coverage json  # Creates coverage.json

# Analyze gaps with this skill
Claude: Analyze test gaps in my project using coverage.json

TypeScript/JavaScript の場合

# Generate coverage report
jest --coverage

# Analyze gaps
Claude: Analyze test gaps in my TypeScript project

実例

分析前

Project Stats:
- 156 functions
- 52% test coverage
- Unknown untested functions
- Scattered test files

分析後

Gap Report:
- 24 untested functions (15%)
- 34 functions < 85% (22%)
- 12 critical gaps (high impact)
- 45 medium gaps (medium impact)
- 40 low gaps (low priority)

Recommendations:
1. Focus on critical gaps (payment, auth, data)
2. Add error case tests (20 tests, 8 hours)
3. Cover edge cases (15 tests, 6 hours)
4. Integration tests (12 tests, 10 hours)

Result after implementing:
- 89% test coverage
- All critical functions tested
- Balanced testing pyramid
- Improved confidence in refactoring

次のステップ

ギャップ分析後：

1. レポートを確認する：現状を把握します
2. ギャップに優先順位を付ける：まず重要な機能に注力します
3. テンプレートを使う：提案されたテストを実装します
4. テストを実行する：新しいテストがパスすることを確認します
5. カバレッジを追跡する：改善状況を監視します
6. 反復する：カバレッジを段階的に向上させます

成功指標

効果的なテストギャップ分析によって、次の成果が得られます。

• カバレッジ状況を明確に把握できる
• 実行可能な改善計画
• テストカバレッジ85％以上の達成
• バランスの取れたテストピラミッド
• 開発者の自信の向上
• デバッグとリファクタリングの迅速化
• 本番環境での問題の減少