testing-patterns

测试模式

一种务实的测试方法，强调：

• 实时测试，而非模拟
• Agent 执行，以保留上下文
• YAML 规范，兼作文档和测试
• 持久化结果，并提交到 git

理念

这不是传统的 TDD。相反：

1. 在生产/预发布环境中测试，并做好日志记录
2. 使用 Agent 运行测试（保持主上下文整洁）
3. 以声明式方式在 YAML 中定义测试（便于阅读并纳入版本控制）
4. 聚焦集成（真实服务、真实数据）

为什么采用基于 Agent 的测试？

在主对话中运行 50 项测试会耗尽整个上下文窗口。将任务委派给子 Agent 后：

• 主上下文可保持整洁，用于开发
• Agent 可以在不受上下文压力影响的情况下运行许多测试
• 结果会以摘要形式返回
• 失败的测试会得到详细调查

命令

命令	用途
/create-tests	探查项目，生成测试规范和测试 Agent
/run-tests	通过 Agent 执行测试并报告结果
/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/ 测试 Agent
   • 将结果保存到 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 测试规范
• 有哪些可用的验证规则
• 如何创建测试 Agent
• 何时使用并行执行

你的项目提供：

• 实际要测试的内容
• 预期值和行为
• 特定领域的边缘情况

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。

创建测试 Agent

测试 Agent 会继承会话中的 MCP 工具。创建一个 Agent，使其：

1. 读取 YAML 测试规范
2. 使用参数执行工具调用
3. 根据预期验证响应
4. 报告结果

Agent 模板

重要：如果需要访问 MCP，请勿指定 tools 字段。指定任何工具后，该字段就会成为允许列表，而 "*" 会按字面值解释（而非通配符）。完全省略 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。

结果格式

测试结果会以 Markdown 格式保存，以便纳入 git 历史记录：

# 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. 创建测试 Agent

复制 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"

并行测试执行

同时运行多个测试 Agent，加快大型测试套件的执行速度：

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

每个 Agent：

• 拥有自己的上下文（不会让主对话膨胀）
• 可以独立运行 10-50 个测试
• 完成后返回摘要
• 继承父会话的 MCP 工具

为什么要使用并行 Agent？

• 在主上下文中运行 50 个测试 = 上下文耗尽
• 将 50 个测试分配给 5 个 Agent = 上下文干净 + 执行更快
• 每个 Agent 报告通过/失败摘要，而不是每项测试的详细信息

批处理策略：

• 按功能领域或 MCP 服务对测试分组
• 每个 Agent 运行 10-20 个测试为宜
• 测试太少 = 启动 Agent 的开销不值得
• 测试太多 = Agent 上下文会被占满

MCP 测试

对于 MCP 服务，测试 Agent 会继承已配置的 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. 使用描述性名称：使用 search_with_date_filter，而不是 test1
4. 对相关测试分组：每个功能领域对应一个文件
5. 修复 Bug 后添加测试：每个已修复的 Bug 都要添加回归测试
6. 提交结果：创建测试运行记录

这不是什么

• 不是 Jest/Vitest 的替代品（单元测试请使用它们）
• 不强制采用 TDD（选择适合你的方式）
• 不是测试运行器库（Agent 本身就是运行器）
• 与模拟无关（我们测试真实系统）

适用场景

场景	使用此工具	使用传统测试
MCP 服务验证	是	否
API 集成	是	配合单元测试
浏览器工作流	是	配合组件测试
单元测试	否	是（Jest/Vitest）
组件测试	否	是（Testing Library）
类型检查	否	是（TypeScript）

相关资源

• templates/test-spec.yaml - 通用测试规范模板
• templates/test-agent.md - 测试 Agent 模板
• references/validation-rules.md - 完整的验证规则参考