# テスト戦略書（Test Strategy）

**文書番号:** TEST-001  
**バージョン:** 1.0  
**作成日:** 2025-11-02  
**最終更新:** 2025-11-02

---

## 1. テスト戦略概要

### 1.1 目的
Tree-sitter Analyzerプロジェクトのテスト活動全体の方針、アプローチ、リソース配分を定義し、エンタープライズグレードの品質を保証する。

### 1.2 テスト目標

| 目標 | 指標 | 現状 |
|------|------|------|
| **機能網羅性** | 全機能のテストケース作成 | ✅ 達成 |
| **コードカバレッジ** | > 80% | ~85% |
| **テスト合格率** | 100% | ✅ 100% |
| **回帰防止** | 全リリースで回帰テスト実施 | ✅ 実施中 |
| **自動化率** | > 95% | ✅ 達成 |

### 1.3 テストスコープ

#### テスト対象（In-Scope）
- ✅ コア解析エンジン
- ✅ 言語プラグイン（Python, Java, JavaScript, TypeScript, CSS, HTML, Markdown = 7言語）
- ✅ MCP統合機能（8ツール）
- ✅ CLIツール（主要7コマンド: DefaultCommand, QueryCommand, TableCommand, AdvancedCommand, SummaryCommand, StructureCommand, PartialReadCommand + 4情報コマンド）
- ✅ 検索機能（fd/ripgrep統合）
- ✅ キャッシュシステム
- ✅ セキュリティ機能
- ✅ 非同期処理
- ✅ API（公開メソッド）

#### テスト対象外（Out-of-Scope）
- ❌ 外部ツール内部（fd, ripgrep, tree-sitter）
- ❌ サードパーティライブラリ内部
- ❌ ユーザー環境の設定
- ❌ インストールプロセス（別途手動確認）

---

## 2. テストアプローチ

### 2.1 テストピラミッド

```
        ┌─────────────────┐
        │   E2Eテスト     │  数: 未設定（開発中）
        │  (実ワークフロー)│  速度: 遅
        └─────────────────┘  信頼: 高
               ▲
               │
        ┌─────────────────┐
        │   統合テスト     │  数: 19（マーカー設定済）
        │  (モジュール連携)│  速度: 中
        └─────────────────┘  信頼: 中
               ▲
               │
        ┌─────────────────┐
        │   単体テスト     │  数: 349（マーカー設定済）
        │  (関数・メソッド)│  速度: 速
        └─────────────────┘  信頼: 低~中

        その他（マーカー未設定）: 3,002件
```

### 2.2 テストレベル定義

#### レベル1: 単体テスト（Unit Test）
**目的:** 個別の関数・メソッドの正確性検証

**対象:**
- 個別関数
- クラスメソッド
- ユーティリティ
- データ変換ロジック

**実装方針:**
- pytest使用
- 高速実行（< 0.1秒/テスト）
- モック・スタブ活用
- エッジケース網羅

**例:**
```python
def test_element_to_summary_item():
    """UnifiedElement.to_summary_item()のテスト"""
    element = UnifiedElement(...)
    summary = element.to_summary_item()
    assert summary["type"] == "class"
    assert "name" in summary
```

#### レベル2: 統合テスト（Integration Test）
**目的:** モジュール間連携の検証

**対象:**
- サービス間連携
- プラグイン統合
- キャッシュ連携
- API呼出しチェーン

**実装方針:**
- 実環境に近い設定
- 外部依存は実際のツール使用
- データフロー検証
- エラー伝播確認

**例:**
```python
def test_mcp_analyze_with_cache():
    """MCPツールとキャッシュの統合テスト"""
    # 初回解析（キャッシュミス）
    result1 = mcp_analyze_code_structure(...)
    # 2回目（キャッシュヒット）
    result2 = mcp_analyze_code_structure(...)
    assert result1 == result2
    assert cache_hit_rate > 0
```

#### レベル3: E2Eテスト（End-to-End Test）
**目的:** ユーザーワークフロー全体の検証

**対象:**
- CLIコマンド実行
- MCPクライアント連携
- ファイル入出力
- エラーハンドリング

**実装方針:**
- 実際のコマンドライン実行
- 実ファイル使用
- 出力結果の完全検証
- ユーザー視点のシナリオ

**例:**
```bash
# CLIコマンドのE2Eテスト
tree-sitter-analyzer examples/Sample.java --output-format json
# 出力検証
assert json.loads(output)["total_functions"] == 5
```

### 2.3 テストタイプ

#### 機能テスト（Functional Testing）
**目的:** 仕様通りの動作確認

**カバー範囲:**
- 全MCPツール（2実装）:
  - **公開版** (`tree_sitter_analyzer.mcp.server` - PyPI配布中, 8ツール): check_code_scale, analyze_code_structure, extract_code_section, set_project_path, query_code, list_files, search_content, find_and_grep
  - **新設計版** (`tree_sitter_analyzer.interfaces.mcp_server` - 開発中, 8ツール): analyze_file, analyze_code, extract_elements, execute_query, validate_file, get_supported_languages, get_available_queries, get_framework_info
- 全CLIコマンド（主要7コマンド + 4情報コマンド）:
  - **主要コマンド**: DefaultCommand, QueryCommand, TableCommand, AdvancedCommand, SummaryCommand, StructureCommand, PartialReadCommand
  - **情報コマンド**: ListQueriesCommand, DescribeQueryCommand, ShowLanguagesCommand, ShowExtensionsCommand
- 全言語プラグイン（7言語: Python, Java, JavaScript, TypeScript, CSS, HTML, Markdown）
- コア解析機能

#### 非機能テスト（Non-Functional Testing）

##### パフォーマンステスト
**目的:** 速度・メモリ効率の検証

**測定項目:**
- 解析速度（行数/秒）
- メモリ使用量
- キャッシュヒット率
- 並行処理効率

**ツール:** pytest, pytest-cov, pytest-asyncio, pytest-mock, pytest-benchmark, memory-profiler

##### セキュリティテスト
**目的:** 脆弱性の検出・防止

**検証項目:**
- パストラバーサル攻撃耐性（ProjectBoundaryManager）
- シンボリックリンク悪用防止
- ReDoS攻撃防止（RegexSafetyChecker）
- 入力検証（SecurityValidator）
- ファイルアクセス権限チェック

**ツール:** bandit, SecurityValidator（独自実装）, 手動侵入テスト

##### 互換性テスト
**目的:** 多環境での動作保証

**テスト環境:**
- Python: 3.10, 3.11, 3.12, 3.13
- OS: Windows 10/11, macOS 12+, Ubuntu 20.04+, Ubuntu 22.04+
- MCPクライアント: Claude Desktop, Cursor, その他MCP互換クライアント

##### ユーザビリティテスト
**目的:** 使いやすさの評価

**評価項目:**
- エラーメッセージの明確さ
- ドキュメントの完全性
- CLIヘルプの充実度

#### 回帰テスト（Regression Testing）
**目的:** 既存機能の保護

**実施タイミング:**
- 毎PR
- 毎リリース
- 重要な変更後

**対象:** 全既存テストケース（3370+）

---

## 3. テスト環境

### 3.1 テスト環境構成

| 環境 | 用途 | 構成 |
|------|------|------|
| **開発環境** | 開発者ローカル | Python 3.10+, pytest, 全依存関係 |
| **CI環境** | 自動テスト | GitHub Actions（Ubuntu, Windows, macOS） |
| **統合環境** | 統合テスト | 本番同等の設定 |

### 3.2 テストデータ

#### サンプルコード
**場所:** `examples/`

**内容:**
- BigService.java（大規模Javaファイル、1000+行）
- ModernJavaScript.js（ES6+機能）
- ComprehensiveTypeScript.ts（型システム、複雑な型定義）
- comprehensive_sample.html（HTML5、複雑な構造）
- comprehensive_sample.css（CSS3、アニメーション）
- sample.py（Python基本構造）
- ReactComponent.jsx（React JSX）
- ReactTypeScriptComponent.tsx（React + TypeScript）
- その他7言語の各種サンプル

#### テスト用プロジェクト
**場所:** `tests/fixtures/`

**内容:**
- 小規模プロジェクト（数ファイル）
- 中規模プロジェクト（数十ファイル）
- エッジケース用特殊ファイル

### 3.3 テストツール

| ツール | バージョン | 用途 |
|--------|-----------|------|
| **pytest** | 8.4.1+ | テストランナー |
| **pytest-cov** | 4.0.0+ | カバレッジ測定 |
| **pytest-asyncio** | 1.1.0+ | 非同期テスト |
| **pytest-mock** | 3.14.1+ | モック・スタブ |
| **pytest-benchmark** | 4.0.0+ | パフォーマンステスト |
| **memory-profiler** | 0.61.0+ | メモリプロファイリング |
| **bandit** | 1.7.5+ | セキュリティ脆弱性検出 |

**注:** バージョンは`pyproject.toml`の実際の指定値に基づいています。

---

## 4. テストケース設計

### 4.1 テストケース命名規則

```python
def test_<機能>_<条件>_<期待結果>():
    """
    テストの説明
    
    Given: 前提条件
    When: 実行内容
    Then: 期待結果
    """
    pass
```

**例:**
```python
def test_analyze_java_file_with_cache_hit():
    """
    キャッシュヒット時のJavaファイル解析テスト
    
    Given: 既にキャッシュされているJavaファイル
    When: 2回目の解析を実行
    Then: キャッシュから結果を取得し、高速に完了
    """
```

### 4.2 テストケース構造（AAA パターン）

```python
def test_example():
    # Arrange（準備）
    input_data = "test data"
    expected = "expected result"
    
    # Act（実行）
    result = function_under_test(input_data)
    
    # Assert（検証）
    assert result == expected
```

### 4.3 エッジケーステスト

**必須エッジケース:**
- 空入力（空ファイル、空文字列）
- 最大値（巨大ファイル、長い行）
- 異常値（不正なパス、無効な引数）
- 境界値（0, 1, 最大-1, 最大, 最大+1）
- 特殊文字（Unicode、制御文字）
- 存在しないリソース（ファイル、パス）

---

## 5. テスト実施

### 5.1 テスト実行手順

#### 開発環境での実行

```bash
# 全テスト実行
uv run pytest

# カバレッジ付き実行
uv run pytest --cov=tree_sitter_analyzer --cov-report=html

# 特定ファイルのみ
uv run pytest tests/test_api.py

# マーカーによるフィルタ
uv run pytest -m "not slow"        # 高速テストのみ
uv run pytest -m integration       # 統合テストのみ
uv run pytest -m "not integration" # 単体テストのみ
uv run pytest -m asyncio           # 非同期テストのみ

# 並列実行（高速化）
uv run pytest -n auto              # CPU数に応じて並列実行
```

**利用可能なマーカー:**
- `@pytest.mark.asyncio` - 非同期テスト（779件）
- `@pytest.mark.integration` - 統合テスト（19件）
- `@pytest.mark.unit` - 単体テスト（349件）
- `@pytest.mark.slow` - 時間のかかるテスト（未設定）
- `@pytest.mark.e2e` - E2Eテスト（未設定）

**注:** 現在、3,002件のテストはマーカー未設定です。テストマーカーの整備を進めています。

#### CI/CDでの実行

**GitHub Actionsワークフロー:**
```yaml
- name: Run tests
  run: |
    uv run pytest --cov=tree_sitter_analyzer --cov-report=xml
    uv run pytest --cov=tree_sitter_analyzer --cov-report=html
```

### 5.2 テスト実行スケジュール

| タイミング | 実行内容 | 所要時間 | 実行環境 |
|-----------|---------|---------|---------|
| **毎コミット** | 高速単体テスト | 2-5分 | ローカル |
| **毎PR** | 全テスト（3プラットフォーム × 4 Pythonバージョン） | 15-30分 | GitHub Actions（Ubuntu, Windows, macOS） |
| **毎日（夜間）** | 完全テスト + パフォーマンステスト | 1-2時間 | CI環境 |
| **リリース前** | 完全テスト + 手動テスト + 互換性テスト | 2-4時間 | 全環境 |

### 5.3 失敗時の対応

**テスト失敗時の手順:**
1. エラーメッセージ確認
2. ローカル再現試行
3. 原因特定（コード/テスト/環境）
4. 修正実施
5. 再テスト
6. PR更新

**CIテスト失敗時:**
- 一時的な失敗（ネットワーク等）: 再実行
- 恒久的な失敗: 即座に修正

---

## 6. カバレッジ目標

### 6.1 全体目標

| モジュール | カバレッジ目標 | 現状 | 備考 |
|-----------|---------------|------|------|
| **全体** | > 80% | ~85% | 目標達成 ✅ |
| **コアエンジン** | > 90% | ~90% | 目標達成 ✅ |
| **言語プラグイン** | > 85% | ~85% | 目標達成 ✅ |
| **MCPツール** | > 90% | ~90% | 目標達成 ✅ |
| **CLI** | > 80% | ~80% | 目標達成 ✅ |
| **セキュリティ** | 100% | ~95% | 改善中 |
| **API** | > 95% | ~95% | 目標達成 ✅ |

### 6.2 カバレッジ測定

**ツール:** pytest-cov

**コマンド:**
```bash
uv run pytest --cov=tree_sitter_analyzer --cov-report=html
```

**レポート:** `htmlcov/index.html`

### 6.3 カバレッジ向上戦略

1. **未カバー行の特定**
   - カバレッジレポート分析
   - 優先度付け（コア機能優先）

2. **テスト追加**
   - エッジケース追加
   - エラーパス追加

3. **リファクタリング**
   - 到達不能コード削除
   - テスタビリティ向上

---

## 7. 品質メトリクス

### 7.1 テストメトリクス

| メトリクス | 測定方法 | 目標 | 現状 |
|-----------|---------|------|------|
| **テスト数** | pytest集計 | 継続的増加 | 3,370件 ✅ |
| **テスト合格率** | CI結果 | 100% | 100% ✅ |
| **平均実行時間** | CIログ | < 30分（全テスト） | ~20分 ✅ |
| **フレーク率** | 失敗分析 | < 1% | < 0.5% ✅ |
| **カバレッジ** | pytest-cov | > 80% | ~85% ✅ |

### 7.2 品質トレンド

**追跡項目:**
- テスト数の推移（現在3,370件）
- カバレッジの推移
- 検出バグ数
- 修正時間

---

## 8. リスクと緩和策

### 8.1 テストリスク

| リスク | 影響度 | 発生確率 | 緩和策 |
|--------|--------|---------|--------|
| 外部ツール依存 | 高 | 低 | モック使用、互換性テスト |
| 環境差異 | 中 | 中 | 3プラットフォームCI |
| テストメンテナンス負荷 | 中 | 高 | リファクタリング、DRY原則 |
| カバレッジ低下 | 高 | 中 | カバレッジゲート、定期レビュー |

### 8.2 緩和アクション

1. **外部依存の最小化**
   - モック・スタブの活用
   - 統合テストで実ツール検証

2. **クロスプラットフォーム対応**
   - CI/CDで3OS自動テスト
   - プラットフォーム固有コードの分離

3. **テストコードの品質**
   - テストコードレビュー
   - テストリファクタリング

---

## 9. テスト成果物

### 9.1 テストドキュメント

| ドキュメント | 場所 | 更新頻度 |
|-------------|------|---------|
| **テスト戦略書** | 本文書 | 四半期 |
| **テスト計画書** | TEST-002 | 各リリース |
| **テストケース一覧** | TEST-003 | 継続的 |
| **テスト実施記録** | TEST-004 | 各実施後 |

### 9.2 テストレポート

| レポート | 形式 | 頻度 |
|---------|------|------|
| **カバレッジレポート** | HTML | 毎PR |
| **CI結果レポート** | GitHub Actions | 毎コミット |
| **品質サマリ** | Markdown | 月次 |
| **リリーステストレポート** | Markdown | 各リリース |

---

## 10. テスト改善計画

### 10.1 短期改善（3ヶ月）

- [x] テスト数 > 3,000件達成（現在3,370件）
- [x] カバレッジ > 80% 達成（現在~85%）
- [x] テスト実行時間 < 30分達成（現在~20分）
- [ ] セキュリティカバレッジ 100% 達成（現在~95%）
- [ ] パフォーマンステスト拡充（ベンチマーク追加）
- [ ] テストマーカー整備（現在3,002件未設定 → 全テストにマーカー付与）

### 10.2 中期改善（6ヶ月）

- [x] E2Eテスト自動化 > 95%（現在ほぼ100%）
- [ ] 視覚的回帰テスト導入（HTML/CSS出力の検証）
- [ ] プロパティベーステスト導入（hypothesis使用）
- [ ] テストデータ生成の自動化
- [ ] E2Eマーカーの整備（明示的なE2Eテスト分類）

### 10.3 長期改善（12ヶ月）

- [ ] AIベーステスト生成（LLM活用）
- [ ] ミューテーションテスト導入（mutmut使用）
- [ ] 継続的パフォーマンス監視（トレンド分析）
- [ ] カオステスト導入（ランダム入力テスト）

---

## 改訂履歴

| バージョン | 日付 | 変更内容 | 承認者 |
|-----------|------|---------|--------|
| 1.0 | 2025-11-02 | 初版作成 | aisheng.yu |
| 1.1 | 2025-01-XX | 実装コードとの照合・修正<br>- MCP実装が2系統あることを確認（公開版と新設計版）<br>- 公開版: `tree_sitter_analyzer.mcp.server` (PyPI配布中)<br>- 新設計版: `tree_sitter_analyzer.interfaces.mcp_server` (開発中)<br>- 言語プラグイン数: 10→7に修正<br>- CLIコマンド数: 4→7に修正<br>- テスト数: 3,370件を確認（一致）<br>- ツールバージョン情報を更新<br>- セキュリティテスト詳細を追加 | GitHub Copilot |
| 1.2 | 2025-01-04 | 実装コードとの照合・追加修正<br>- テストピラミッド数値を実測値に修正:<br>  * 単体テスト: 3000+ → 349（マーカー設定済）<br>  * 統合テスト: 300+ → 19（マーカー設定済）<br>  * E2Eテスト: 100+ → 未設定（開発中）<br>  * その他: 3,002（マーカー未設定）<br>- CLIコマンド詳細を明確化（主要7コマンド + 4情報コマンド）<br>- テストマーカー状況を詳細化（779件asyncio、349件unit、19件integration）<br>- テスト実行スケジュールを実際のCI設定に合わせて修正（3プラットフォーム × 4 Pythonバージョン）<br>- pytest-covバージョン: 6.0.0+ → 4.0.0+（pyproject.toml実測）<br>- pytest-asyncioバージョン: 0.24.0+ → 1.1.0+（pyproject.toml実測）<br>- 改善計画にテストマーカー整備とE2Eマーカー整備を追加 | GitHub Copilot |
