• Live testing over mocks
• Agent execution to preserve context
• YAML specs as documentation and tests
• Persistent results committed to git

1. Test in production/staging with good logging
2. Use agents to run tests (keeps main context clean)
3. Define tests declaratively in YAML (human-readable, version-controlled)
4. Focus on integration (real servers, real data)

• Main context stays clean for development
• Agent can run many tests without context pressure
• Results come back as a summary
• Failed tests get detailed investigation

1. Discovery - Claude examines the project:
   • What MCP servers are configured?
   • What APIs or tools exist?
   • What does the code do?
2. Test Design - Claude creates project-specific tests:
   • Test cases for the actual tools/endpoints
   • Expected values based on real behavior
   • Edge cases relevant to this domain
3. Structure - Using patterns from this skill:
   • YAML specs in

     tests/

     directory
   • Optional testing agent in

     .claude/agents/

   • Results saved to

     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")

• How to structure YAML test specs
• What validation rules are available
• How to create testing agents
• When to use parallel execution

• What to actually test
• Expected values and behaviors
• Domain-specific edge cases

• 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

undefined

1. Reads YAML test specs
2. Executes tool calls with params
3. Validates responses against expectations
4. Reports results

model: sonnet

1. Find test specs:

   tests/*.yaml

2. Parse and execute each test
3. Validate responses
4. Report pass/fail summary

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

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

• Expected: Contains "expected value"
• Actual: Response was empty
• Params:

  { action: search, query: "" }

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

• name: basic_search params: { query: "hello" } expect: { status: success, count_gte: 0 }
• name: filtered_search params: { query: "hello", filter: "recent" } expect: { contains: "results" }

undefined

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

• Has its own context (won't bloat main conversation)
• Can run 10-50 tests independently
• Returns a summary when done
• Inherits MCP tools from parent session

• 50 tests in main context = context exhaustion
• 50 tests across 5 agents = clean context + faster execution
• Each agent reports pass/fail summary, not every test detail

• Group tests by feature area or MCP server
• 10-20 tests per agent is ideal
• Too few = overhead of spawning not worth it
• Too many = agent context fills up

1. Start with smoke tests: Basic connectivity and auth
2. Test edge cases: Empty results, errors, special characters
3. Use descriptive names:

   search_with_date_filter

   not

   test1

4. Group related tests: One file per feature area
5. Add after bugs: Every fixed bug gets a regression test
6. Commit results: Create history of test runs

• Not a Jest/Vitest replacement (use those for unit tests)
• Not enforcing TDD (use what works for you)
• Not a test runner library (the agent IS the runner)
• Not about mocking (we test real systems)

• templates/test-spec.yaml

  - Generic test spec template

• templates/test-agent.md

  - Testing agent template

• references/validation-rules.md

  - Complete validation rule reference