Skip to content

TEST_SUMMARY.md

Latest commit

 

History

History
390 lines (313 loc) · 9.92 KB

TEST_SUMMARY.md

File metadata and controls

390 lines (313 loc) · 9.92 KB

AI Agent Backend 测试框架总结

📋 概述

为后端服务器的 AI agent 功能编写了完整的测试套件，包含单元测试、路由测试、集成测试和检查清单。

🎯 添加的内容

1. 测试框架配置

文件：packages/server/vitest.config.ts

  • 配置 Vitest 作为测试框架
  • 设置 Node.js 环境
  • 配置覆盖率报告

文件：packages/server/package.json (更新)

添加了测试依赖和脚本：

{
  "devDependencies": {
    "vitest": "^1.1.0",
    "@vitest/ui": "^1.1.0"
  },
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest --coverage"
  }
}

文件：packages/server/src/__tests__/setup.ts

  • 全局测试设置
  • 环境变量初始化
  • 清理工作配置

2. 单元测试文件

📄 ai-error-handler.test.ts (340+ 行)

测试 AI 错误处理和恢复机制

覆盖功能点：

  • ✅ 错误分类（超时、网络、API、解析、验证）
  • ✅ 错误可重试性判断
  • ✅ 用户友好的错误消息
  • ✅ 超时处理 (withTimeout())
  • ✅ 重试逻辑和指数退避 (withRetry())
  • ✅ HTTP 状态码映射 (4xx, 5xx, 429)
  • ✅ 网络错误识别 (ECONNREFUSED, ENOTFOUND 等)

测试数量： 25+ 个测试用例

关键场景：

✓ 识别 429 Rate Limit 错误为可重试
✓ 识别 5xx 服务器错误为可重试
✓ 识别 4xx 客户端错误为不可重试
✓ 网络错误自动重试 3 次（初始 + 2 次）
✓ 指数退避：2秒 → 4秒 → 8秒（受最大延迟限制）
✓ 超时在 60 秒后触发
✓ 用户收到中文错误消息

📄 ai.service.test.ts (230+ 行)

测试核心 AI 服务（agent 循环管理）

覆盖功能点：

  • ✅ LLM 初始化（OpenAI vs AIHUBMIX）
  • ✅ 系统提示构建（包含日期和用户群组）
  • ✅ 对话历史加载和保存
  • ✅ 时间冲突检测
  • ✅ 5 个工具执行（创建、查询、更新、完成、删除任务）
  • ✅ Agent 循环迭代和终止

测试数量： 20+ 个测试用例

关键场景：

✓ 创建任务时检测重叠时间段
✓ 全天任务不参与冲突检测
✓ 加载最近 20 条消息作为上下文
✓ 过滤掉系统消息（仅保留用户和助手消息）
✓ Agent 循环最多 10 次迭代（防止无限循环）
✓ 工具调用结果传回 AI 模型
✓ 保存用户消息和助手响应到数据库
✓ 任务信息包含在响应 payload 中

📄 ai.routes.test.ts (300+ 行)

测试 HTTP 路由处理

覆盖功能点：

  • ✅ POST /api/ai/chat 端点验证和处理
  • ✅ GET /api/ai/messages 端点
  • ✅ 输入验证（空、仅空格、非字符串）
  • ✅ 消息修剪
  • ✅ 限制参数验证（最小 1、最大 100、默认 20）
  • ✅ 系统消息过滤
  • ✅ 时间顺序排序
  • ✅ 身份验证和授权

测试数量： 30+ 个测试用例

关键场景：

✓ 空消息返回 400 错误
✓ 仅空格消息被拒绝
✓ 消息被修剪后处理（去除前后空格）
✓ 历史记录限制自动限制在 100 以内
✓ 限制小于 1 自动调整为 1
✓ 系统消息从历史记录中过滤
✓ 消息按时间顺序返回（最早的优先）
✓ 只有认证用户才能访问
✓ 服务错误被转换为友好消息

📄 ai.integration.test.ts (400+ 行)

端到端集成测试（完整工作流程）

覆盖工作流程：

  • ✅ 任务创建完整流程
  • ✅ 任务查询和过滤
  • ✅ 任务更新流程
  • ✅ 任务完成流程
  • ✅ 任务删除流程（带确认）
  • ✅ 群组成员和分配
  • ✅ 时间冲突处理
  • ✅ 多轮对话
  • ✅ 错误恢复

测试数量： 35+ 个测试用例

关键工作流程：

1. 创建任务工作流：
   用户消息 → AI 调用工具 → 创建任务 → 返回成功消息

2. 冲突处理：
   检测到重叠时间 → AI 询问用户 → 建议其他时间

3. 查询工作流：
   用户请求 → 应用过滤器 → 返回格式化列表

4. 多轮对话：
   加载历史上下文 → 理解相关引用 → 执行操作

3. 文档和指南

📄 src/__tests__/README.md

详细的测试文档（500+ 行）包括：

  • 测试结构说明
  • 运行测试的命令
  • 覆盖率目标
  • Mock 策略
  • 测试注意事项
  • 调试指南
  • CI/CD 集成建议

📄 src/__tests__/TESTING_CHECKLIST.md

完整的测试清单（400+ 行）包括：

  • 前期准备
  • 每个测试模块的检查项
  • 逐个功能点的验证
  • 故障排除指南
  • 性能和安全测试
  • 测试执行步骤
  • 签核清单

📄 TEST_SUMMARY.md (本文件)

项目总结和快速参考

🚀 快速开始

安装依赖

cd packages/server
pnpm install

运行所有测试

npm run test

运行测试并显示覆盖率

npm run test:coverage

运行测试 UI（可视化界面）

npm run test:ui

运行特定测试文件

npm run test -- ai-error-handler.test.ts

运行匹配某个模式的测试

npm run test -- --grep "should create task"

📊 测试覆盖范围

模块 测试数 关键场景
ai-error-handler 25+ 错误分类、重试、超时
ai.service 20+ LLM初始化、工具执行、冲突检测
ai.routes 30+ 输入验证、路由处理、认证
ai.integration 35+ 完整工作流、多轮对话、错误恢复
总计 110+ 端到端功能覆盖

🔍 测试的关键功能点

1. AI 模型连接

  • ✅ OpenAI API 密钥配置
  • ✅ AIHUBMIX 中转站配置
  • ✅ 模型初始化（gpt-4o）
  • ✅ API 调用失败重试

2. Agent 工具调用

  • ✅ create_task - 创建新任务，检测冲突
  • ✅ query_tasks - 查询任务，支持多种过滤
  • ✅ update_task - 更新任务字段
  • ✅ complete_task - 标记完成
  • ✅ delete_task - 删除任务

3. 错误处理和恢复

  • ✅ 网络错误自动重试（指数退避）
  • ✅ API 错误分类和恢复
  • ✅ 超时控制（60 秒）
  • ✅ 用户友好的错误消息

4. 对话管理

  • ✅ 消息历史加载和保存
  • ✅ 系统提示动态生成（含日期和群组）
  • ✅ 多轮对话上下文保留
  • ✅ Agent 循环最大 10 次防止死循环

5. 时间冲突检测

  • ✅ 识别重叠时间段
  • ✅ 全天任务不参与冲突
  • ✅ 不同日期无冲突
  • ✅ 冲突任务列表返回

6. 数据验证

  • ✅ 消息不能为空
  • ✅ 消息被修剪
  • ✅ 限制参数范围检查 (1-100)
  • ✅ 系统消息过滤
  • ✅ 时间顺序保证

📝 测试文件位置

packages/server/
├── vitest.config.ts                    # Vitest 配置
├── package.json                        # 添加了 test 脚本
└── src/
    └── __tests__/
        ├── setup.ts                    # 全局测试设置
        ├── ai-error-handler.test.ts    # 错误处理测试 (25+ 用例)
        ├── ai.service.test.ts          # AI 服务测试 (20+ 用例)
        ├── ai.routes.test.ts           # 路由测试 (30+ 用例)
        ├── ai.integration.test.ts      # 集成测试 (35+ 用例)
        ├── README.md                   # 测试文档
        └── TESTING_CHECKLIST.md        # 测试清单

✨ 测试特色

1. 完整的错误处理覆盖

  • 25+ 个错误处理测试
  • 包括网络错误、API 错误、超时等
  • 验证重试机制和指数退避

2. Mock 策略清晰

  • 数据库 Mock（隔离测试）
  • LangChain Mock（控制 AI 响应）
  • 服务 Mock（单元测试隔离）

3. 可读的测试组织

describe("Feature", () => {
  describe("Specific Scenario", () => {
    it("should do something specific", () => {
      // Arrange, Act, Assert
    });
  });
});

4. 详细的文档

  • README 说明每个测试文件的目的
  • TESTING_CHECKLIST 列出所有要验证的点
  • 测试代码包含注释说明工作流程

🎓 学习和维护

查看测试例子

// 查看如何编写新测试
cat packages/server/src/__tests__/ai-error-handler.test.ts

理解 Mock 使用

// 查看 Mock 策略
cat packages/server/src/__tests__/ai.service.test.ts | grep -A 5 "vi.mock"

运行特定测试学习

# 运行错误处理相关测试
npm run test -- ai-error-handler

# 看到测试通过/失败的详细输出
npm run test -- --reporter=verbose

✅ 验证清单

在部署前，请检查：

  • 所有测试通过 (npm run test)
  • 覆盖率达到 85%+ (npm run test:coverage)
  • 没有控制台错误或警告
  • 集成测试验证了完整工作流
  • 错误处理测试覆盖所有场景
  • 文档已更新

🔧 下一步

  1. 运行测试验证

    npm run test

  2. 检查覆盖率

    npm run test:coverage

  3. 按照 TESTING_CHECKLIST 逐项验证

  4. 提交包含测试的 PR

📞 常见问题

Q: 如何运行单个测试？

npm run test -- --grep "should create task"

Q: 如何调试测试？

npm run test -- ai-error-handler.test.ts --inspect-brk

Q: 覆盖率如何生成？

npm run test:coverage
# 输出会显示 html/ 目录位置

Q: 需要真实 API 密钥吗？ 不需要，测试使用 Mock，环境变量初始化为测试值。

📚 相关文档

🎉 总结

编写了 110+ 个测试用例，覆盖：

  • ✅ AI 模型连接和初始化
  • ✅ 5 个 Agent 工具的正常工作
  • ✅ 完整的工作流程（从消息到任务创建）
  • ✅ 错误处理和恢复机制
  • ✅ 数据验证和安全性
  • ✅ 时间冲突检测
  • ✅ 多轮对话管理

所有测试都可独立运行，使用清晰的 Mock 策略，附带详细文档。