cruldra/agent-testing

智能体 UAT 验收测试

适用场景

• 用户说"测试一下 XX 智能体"
• 用户说"验收测试 XX agent"
• 用户想验证智能体能否正常执行、输出是否满足预期
• 新智能体开发完成后的冒烟验证

核心原则

1. 优先复用：项目已有 CLI > 已有测试脚本 > 编写专用脚本
2. 真实场景：使用接近生产环境的输入数据，而非简单 mock
3. 结构化记录：每次测试都生成可追溯的测试报告

目录结构

所有测试产物统一放在 .tests/ 目录下：

.tests/
├── {test-name}/                    # 每个测试一个目录
│   ├── README.md                   # 测试说明（目的、智能体信息、输入输出规格）
│   ├── wave-{N}/                   # 第 N 波次
│   │   ├── input/                  # 输入数据
│   │   │   ├── case-1.json         # 测试用例 1 的输入
│   │   │   └── case-2.json         # 测试用例 2 的输入
│   │   ├── expected/               # 期望输出（可选，用于自动化比对）
│   │   │   ├── case-1.json
│   │   │   └── case-2.json
│   │   ├── output/                 # 实际输出（运行后生成）
│   │   │   ├── case-1.json
│   │   │   └── case-2.json
│   │   ├── run.py                  # 波次运行脚本（仅在无法复用 CLI 时创建）
│   │   └── report.md               # 本波次测试报告
│   └── wave-{N+1}/                 # 下一波次（修复问题后重测）
│       └── ...

工作流程

第一步：识别测试目标

1. 确认要测试的智能体名称和所在模块
2. 阅读智能体的 schemas（输入/输出结构）
3. 阅读智能体的核心逻辑，了解预期行为
4. 确认智能体的调用方式（HTTP 端点、CLI 命令、Python 函数）

第二步：准备测试环境

1. 检查 .tests/{test-name}/ 是否已存在
2. 如果不存在，创建目录结构和 README.md
3. 如果已存在，查看历史波次，确定新波次编号

第三步：确定调用方式（优先级从高到低）

优先级 1：复用项目 CLI
  - 检查项目中是否有现成的 CLI 命令可以调用该智能体
  - 例如：uv run python -m smart_sales.xxx.cli

优先级 2：复用已有测试脚本
  - 检查 backend/tests/ 或 .tests/ 下是否有可复用的脚本

优先级 3：通过 HTTP 端点调用
  - 如果智能体注册了 HTTP 路由（如 /agents/{name}/run），使用 curl 或 httpx 调用

优先级 4：编写专用运行脚本
  - 在 wave-{N}/run.py 中编写最小化的调用脚本
  - 脚本必须：
    a. 从 input/ 目录读取测试数据
    b. 调用智能体
    c. 将结果写入 output/ 目录
    d. 输出简要的执行摘要到 stdout

第四步：准备测试数据

1. 为每个测试用例创建 input/case-{N}.json
2. 数据应覆盖：
   - 正常路径（golden path）：典型的、预期会成功的输入
   - 边界情况：极端值、空值、最大长度等
   - 异常情况（可选）：明显无效的输入，验证错误处理
3. 如果有明确的期望输出，创建 expected/case-{N}.json

第五步：执行测试

1. 运行测试（根据第三步确定的方式）
2. 捕获智能体输出，保存到 output/case-{N}.json
3. 记录执行时间、是否成功、错误信息（如有）

第六步：评估结果并生成报告

生成 wave-{N}/report.md，格式如下：

# {test-name} 测试报告 - 波次 {N}

- 测试时间：{ISO 时间}
- 智能体：{agent-name}
- 调用方式：{CLI / HTTP / 脚本}

## 测试用例汇总

| 用例 | 状态 | 耗时 | 备注 |
|------|------|------|------|
| case-1 | PASS/FAIL | Xs | ... |
| case-2 | PASS/FAIL | Xs | ... |

## 详细结果

### case-1: {用例描述}

**输入摘要**：...
**输出摘要**：...
**评估**：
- [ ] 智能体正常执行（无报错、无超时）
- [ ] 输出结构符合 schema
- [ ] 输出内容合理（语义正确、无幻觉）
- [ ] 关键字段非空且有意义

### case-2: ...

## 发现的问题

1. ...

## 结论

{PASS / FAIL / PARTIAL}：{一句话总结}

第七步：迭代（如需要）

如果发现问题：
1. 记录问题到当前波次的 report.md
2. 修复智能体代码
3. 创建新波次目录 wave-{N+1}/
4. 复用或调整测试数据，重新执行

检查清单

- [ ] 确认智能体名称和模块路径
- [ ] 阅读智能体 schemas（输入/输出）
- [ ] 确定调用方式（CLI > 脚本 > HTTP > 专用脚本）
- [ ] 创建 .tests/{test-name}/ 目录结构
- [ ] 编写 README.md（测试目的、智能体信息）
- [ ] 准备测试数据（至少包含 golden path）
- [ ] 执行测试并捕获输出
- [ ] 评估每个用例的结果
- [ ] 生成测试报告
- [ ] 如有问题，开始新波次

注意事项

• 测试脚本用 uv run 执行，不直接用 python
• 每个波次是独立的，不要覆盖之前波次的数据
• 报告中的评估应包含主观判断（输出是否"合理"），不仅仅是 schema 验证