testing-patterns

テストのパターン

次の点を重視した、実用的なテストアプローチです。

• モックよりもライブテスト
• コンテキストを維持するためのエージェントによる実行
• ドキュメントとテストを兼ねたYAML 仕様
• Git にコミットする永続的な結果

基本理念

これは従来の TDD ではありません。代わりに、次のように進めます。

1. 適切なログを記録しながら、本番環境／ステージング環境でテストします
2. エージェントを使ってテストを実行します（メインコンテキストをクリーンに保ちます）
3. YAML で宣言的にテストを定義します（人が読みやすく、バージョン管理できます）
4. 統合に重点を置きます（実際のサーバーと実際のデータを使用します）

エージェントベースのテストを使う理由

メインの会話で 50 件のテストを実行すると、コンテキストウィンドウを使い切ってしまいます。サブエージェントに委任すると、次のメリットがあります。

• メインコンテキストを開発用にクリーンに保てます
• エージェントはコンテキストの負荷を気にせず、多数のテストを実行できます
• 結果は要約として返されます
• 失敗したテストについては詳細な調査が行われます

コマンド

コマンド	目的
/create-tests	プロジェクトを調査し、テスト仕様とテスト用エージェントを生成します
/run-tests	エージェント経由でテストを実行し、結果を報告します
/coverage	カバレッジレポートを生成し、未カバーのコードパスを特定します

簡単なワークフロー：

/create-tests        → Generates tests/specs/*.yaml + .claude/agents/test-runner.md
/run-tests           → Spawns agent, runs all tests, saves results
/run-tests api       → Run only specs matching "api"
/run-tests --failed  → Re-run only failed tests
/coverage            → Run tests with coverage, analyse gaps
/coverage --threshold 80  → Fail if below 80%

新しいプロジェクトでの開始方法

このスキルではパターンと形式を提供します。Claude はプロジェクトのコンテキストに基づいて、実際のテストを設計します。

「このプロジェクトのテストを作成して」と依頼すると、次のことが行われます。

1. 調査 - Claude がプロジェクトを確認します。

   • どの MCP サーバーが設定されていますか？
   • どの API やツールがありますか？
   • コードは何をしていますか？

2. テスト設計 - Claude がプロジェクト固有のテストを作成します。

   • 実際のツール／エンドポイントに対するテストケース
   • 実際の動作に基づく期待値
   • このドメインに関連するエッジケース

3. 構成 - このスキルのパターンを使用します。

   • tests/ ディレクトリ内の YAML 仕様
   • 任意のテスト用エージェントを .claude/agents/ に配置
   • 結果を tests/results/ に保存

例：

You: "Create tests for this MCP server"

Claude: [Discovers this is a Google Calendar MCP]
        [Sees tools: calendar_events, calendar_create, calendar_delete]
        [Designs test cases:]

        tests/calendar-events.yaml:
        - list_upcoming_events (expect: array, count_gte 0)
        - search_by_keyword (expect: contains search term)
        - invalid_date_range (expect: error status)

        tests/calendar-mutations.yaml:
        - create_event (expect: success, returns event_id)
        - delete_nonexistent (expect: error, contains "not found")

このスキルが Claude に教えること：

• YAML テスト仕様の構成方法
• 利用可能な検証ルール
• テスト用エージェントの作成方法
• 並列実行を使用するタイミング

プロジェクトが提供するもの：

• 実際にテストする対象
• 期待値と動作
• ドメイン固有のエッジケース

YAML テスト仕様の形式

name: Feature Tests
description: What these tests validate

# Optional: defaults applied to all tests
defaults:
  tool: my_tool_name
  timeout: 5000

tests:
  - name: test_case_name
    description: Human-readable purpose
    tool: tool_name  # Override default if needed
    params:
      action: search
      query: "test input"
    expect:
      contains: "expected substring"
      not_contains: "should not appear"
      status: success

検証ルール

ルール	説明	例
contains	レスポンスに文字列が含まれることを確認します	contains: "from:john"
not_contains	レスポンスに文字列が含まれないことを確認します	not_contains: "error"
matches	正規表現パターンに一致することを確認します	matches: "after:\\d{4}"
json_path	JSON パスの値を確認します	json_path: "$.results[0].name"
equals	値が完全に一致することを確認します	equals: "success"
status	成功／エラーを確認します	status: success
count_gte	配列の長さが N 以上であることを確認します	count_gte: 1
count_eq	配列の長さが N と等しいことを確認します	count_eq: 5
type	値の型を確認します	type: array

完全なドキュメントは references/validation-rules.md を参照してください。

テスト用エージェントの作成

テスト用エージェントは、セッションから MCP ツールを継承します。次の処理を行うエージェントを作成します。

1. YAML テスト仕様を読み取る
2. パラメーターを指定してツール呼び出しを実行する
3. 期待値と照らし合わせてレスポンスを検証する
4. 結果を報告する

エージェントのテンプレート

重要：MCP へのアクセスが必要な場合、tools フィールドを指定しないでください。ツールを 1 つでも指定すると許可リストとして扱われ、"*" はワイルドカードではなく文字どおりに解釈されます。親セッションからすべてのツールを継承するには、tools を完全に省略してください。

---
name: my-tester
description: |
  Tests [domain] functionality. Reads YAML test specs and validates responses.
  Use when: testing after changes, running regression tests.
# tools field OMITTED - inherits ALL tools from parent (including MCP)
model: sonnet
---

# [Domain] Tester

## How It Works

1. Find test specs: `tests/*.yaml`
2. Parse and execute each test
3. Validate responses
4. Report pass/fail summary

## Test Spec Location

tests/
├── feature-a.yaml
├── feature-b.yaml
└── results/
    └── YYYY-MM-DD-HHMMSS.md

## Execution

For each test:
1. Call tool with params
2. Capture response
3. Apply validation rules
4. Record PASS/FAIL

## Reporting

Save results to `tests/results/YYYY-MM-DD-HHMMSS.md`

完全なテンプレートは templates/test-agent.md を参照してください。

結果の形式

テスト結果は、Git の履歴に残せるよう Markdown として保存されます。

# Test Results: feature-name
**Date**: 2026-02-02 14:30
**Commit**: abc1234
**Summary**: 8/9 passed (89%)

## Results

- test_basic_search - PASSED (0.3s)
- test_with_filter - PASSED (0.4s)
- test_edge_case - FAILED

## Failed Test Details

### test_edge_case
- **Expected**: Contains "expected value"
- **Actual**: Response was empty
- **Params**: `{ action: search, query: "" }`

保存先：tests/results/YYYY-MM-DD-HHMMSS.md

ワークフロー

1. テスト仕様を作成する

# tests/search.yaml
name: Search Tests
defaults:
  tool: my_search_tool

tests:
  - name: basic_search
    params: { query: "hello" }
    expect: { status: success, count_gte: 0 }

  - name: filtered_search
    params: { query: "hello", filter: "recent" }
    expect: { contains: "results" }

2. テスト用エージェントを作成する

templates/test-agent.md をコピーし、ドメインに合わせてカスタマイズします。

3. テストを実行する

"Run the search tests"
"Test the API after my changes"
"Run regression tests for gmail-mcp"

4. 結果を確認する

結果は tests/results/ に保存されます。履歴を残すため、コミットしてください。

git add tests/results/
git commit -m "Test results: 8/9 passed"

並列テスト実行

大規模なテストスイートを高速化するため、複数のテストエージェントを同時に実行します。

"Run these test suites in parallel:
- Agent 1: tests/auth/*.yaml
- Agent 2: tests/search/*.yaml
- Agent 3: tests/api/*.yaml"

各エージェントは次のとおりです。

• 独自のコンテキストを持ちます（メインの会話が肥大化しません）
• 10～50 個のテストを独立して実行できます
• 完了時に概要を返します
• 親セッションの MCP ツールを引き継ぎます

並列エージェントを使う理由

• メインコンテキストで 50 個のテストを実行すると、コンテキストが枯渇します
• 5 つのエージェントで 50 個のテストを実行すると、コンテキストを保ったまま実行が速くなります
• 各エージェントは、すべてのテストの詳細ではなく、成功／失敗の概要を報告します

バッチ処理の戦略

• 機能領域または MCP サーバーごとにテストをグループ化します
• 1 エージェントあたり 10～20 個のテストが理想的です
• 少なすぎると、エージェントを起動するオーバーヘッドに見合いません
• 多すぎると、エージェントのコンテキストがいっぱいになります

MCP のテスト

MCP サーバーの場合、テストエージェントは設定済みの MCP を引き継ぎます。

# Configure MCP first
claude mcp add --transport http gmail https://gmail.mcp.example.com/mcp

# Then test
"Run tests for gmail MCP"

MCP テスト仕様の例：

name: Gmail Search Tests
defaults:
  tool: gmail_messages

tests:
  - name: search_from_person
    params: { action: search, searchQuery: "from John" }
    expect: { contains: "from:john" }

  - name: search_with_date
    params: { action: search, searchQuery: "emails from January 2026" }
    expect: { matches: "after:2026" }

API のテスト

REST API には Bash ツールを使用します。

name: API Tests
defaults:
  timeout: 5000

tests:
  - name: health_check
    command: curl -s https://api.example.com/health
    expect: { contains: "ok" }

  - name: get_user
    command: curl -s https://api.example.com/users/1
    expect:
      json_path: "$.name"
      type: string

ブラウザーのテスト

ブラウザーの自動化には Playwright ツールを使用します。

name: UI Tests

tests:
  - name: login_page_loads
    steps:
      - navigate: https://app.example.com/login
      - snapshot: true
    expect: { contains: "Sign In" }

  - name: form_submission
    steps:
      - navigate: https://app.example.com/form
      - type: { ref: "#email", text: "[email protected]" }
      - click: { ref: "button[type=submit]" }
    expect: { contains: "Success" }

ヒント

1. スモークテストから始める：基本的な接続と認証を確認します
2. エッジケースをテストする：空の結果、エラー、特殊文字を確認します
3. わかりやすい名前を使う：test1 ではなく search_with_date_filter を使います
4. 関連するテストをグループ化する：機能領域ごとに 1 つのファイルにまとめます
5. バグ修正後に追加する：修正したバグごとに回帰テストを追加します
6. 結果をコミットする：テスト実行の履歴を作成します

これは何ではないか

• Jest／Vitest の代替ではありません（ユニットテストにはそれらを使用してください）
• TDD を強制するものではありません（使いやすい方法を選んでください）
• テストランナーライブラリではありません（エージェント自体がランナーです）
• モックを使うものではありません（実際のシステムをテストします）

使用する場面

シナリオ	これを使用	従来のテストを使用
MCP サーバーの検証	はい	いいえ
API の統合テスト	はい	ユニットテストと併用
ブラウザーのワークフロー	はい	コンポーネントテストと併用
ユニットテスト	いいえ	はい（Jest／Vitest）
コンポーネントテスト	いいえ	はい（Testing Library）
型チェック	いいえ	はい（TypeScript）

関連リソース

• templates/test-spec.yaml - 汎用テスト仕様テンプレート
• templates/test-agent.md - テストエージェントのテンプレート
• references/validation-rules.md - 検証ルールの完全なリファレンス