Test_Agent/AGENTS.md
jiawei.chen 6f6053ff51 feat: TestAgent 智能测试平台 v1.0
- CLI + Web 双平台,基于 LLM 的 TDD+DDD 自动化测试生成
- 集成 unified-test-platform 903 个 D-Cloud 用例 + 13 个 Robogo 场景
- Agent 5 步流水线: 扫描 -> DDD -> LLM 生成测试
- 精确回归 + UI 变更检查
- 可视化 HTML 测试报告
- 暗色/亮色主题切换
- 19 个 API 端点 + 6 个 SPA 页面
- 15/15 项 TDD+DDD 合规
2026-07-08 11:27:38 +08:00

6.4 KiB
Raw Blame History

AGENTS.md

本项目为 TestAgent 配置与运行时文档,用于驱动 LLM 自动生成符合 TDD+DDD 规范的测试用例,并提供 Web 可视化管理平台。

运行环境

  • Web 平台:Flask 后端(端口 5002)+ React SPA 前端(端口 5174 开发模式,生产构建后由 Flask 托管)
  • CLI 模式:Python 3.9+,Click 命令行框架
  • 语言模型:DeepSeek Chat(默认)/ OpenAI / Anthropic(通过兼容 API 接入)
  • 已有用例:集成 unified-test-platform 的 tests/ 目录,可浏览和运行 800+ 存量测试

启动方式

Web 平台

# 启动后端(托管前端 SPA)
python -m backend
# 访问 http://localhost:5002

# 前端开发模式(热更新)
cd frontend && pnpm dev
# 访问 http://localhost:5174,API 代理到 5002

# 前端构建(生产)
cd frontend && pnpm build
# 产物输出到 frontend/dist/,由 Flask 直接托管

CLI 命令行

# 完整扫描生成
python main.py run -r <git-url> -k <api-key>

# 精确回归
python main.py diff -r <git-url> -k <api-key> -a HEAD~3

# 领域分析(不调 LLM,免费)
python main.py analyze -r <git-url> -k <api-key>

Web 平台功能

控制台 (/dashboard)

  • 统计概览:仓库数、任务数、报告数、已有用例模块数
  • 快速操作:跳转扫描仓库 / 运行已有用例 / 查看任务
  • 能力展示:8 项平台能力卡片

仓库管理 (/repos)

  • 添加 Git 仓库 → 自动扫描(clone/pull + AST 分析 + DDD 建模)
  • 扫描完成后可执行:DDD 分析 / 生成测试 / 精确回归 / 全流程一键执行
  • 实时 SSE 日志流显示扫描/分析/生成进度
  • 展示限界上下文列表

任务管理 (/tasks)

  • 任务列表:名称、类型、状态(运行中/通过/失败/等待中)、创建时间
  • 实时 SSE 日志流(点击「日志」按钮)
  • 运行中任务可停止,已完成任务可删除
  • 5 秒轮询自动刷新状态

测试报告 (/reports)

  • 报告列表:通过/失败标识、通过数/失败数、完成时间
  • 详情面板:总运行/通过/失败/耗时统计
  • 运行日志回放
  • 失败截图查看

已有用例 (/existing)

  • 左侧:22 个测试模块列表(来自 unified-test-platform)
  • 中间:19 个测试标记(smoke/e2e/api/ui/flow/各模块标记)
  • 右侧:运行配置(有头/无头模式)+ 运行按钮
  • 选中模块后显示该模块的具体测试文件
  • 实时 SSE 日志流显示 pytest 输出

知识来源

Agent 知识全部来自 skills/ 目录下的 SKILL.md 文件:

  • skills/tdd-methodology/ — TDD 红-绿-重构循环、FIRST 原则、AAA 模式、测试替身
  • skills/ddd-patterns/ — 限界上下文、聚合根、实体、值对象、领域服务、仓储模式
  • skills/test-framework/ — 测试分层(冒烟/集成/系统/回归)、指标门禁、CI/CD 流水线
  • skills/language-patterns/ — Python/TypeScript/Go 多语言测试模式

如需更新知识:直接编辑对应的 SKILL.md 文件,无需重启。

工具

Agent 通过 plugins/ 目录加载工具:

  • plugins/pylint_analyzer/ — 代码静态分析(行长度、TODO 标记、print 检测、复杂度评估)
  • plugins/test_runner/ — 测试运行器(执行 pytest、解析结果、指标门禁检查)

人格定义

Agent 人格定义在 SOUL.md 中,核心角色:

  • 身份:资深测试架构师,精通 TDD + DDD
  • 输出:可直接运行的 pytest 测试代码,无 TODO 或占位符
  • 组织:按 DDD 限界上下文组织测试目录,而非按文件结构
  • 隔离:领域层测试独立于基础设施层,领域层纯 Mock
  • 命名:test_should_<预期行为>_when_<条件> 模式
  • 模式:AAA(Arrange-Act-Assert)

API Key 配置

# 方式1:Web 平台输入框(仓库管理/任务创建页面)
# 方式2:命令行传参
python main.py run -r <git-url> -k sk-xxx

# 方式3:环境变量
export DEEPSEEK_API_KEY=sk-xxx
python main.py run -r <git-url>

# 方式4:交互式输入
python main.py run -r <git-url>
# 请输入 API Key: ****

# 方式5:.env 文件
echo "DEEPSEEK_API_KEY=sk-xxx" > .env
python main.py run -r <git-url>

配置

在 config.yaml 中配置:

agent:
  model: deepseek-chat          # 模型名称
  provider: deepseek            # deepseek / openai / anthropic
  base_url: https://api.deepseek.com
  temperature: 0.3              # 生成温度(0=确定,1=创意)
  max_tokens: 8192

test_generation:
  output_dir: tests             # 测试输出目录
  metrics_gate:
    min_coverage: 60
    min_pass_rate: 95

API 路由

路由 方法 说明
/api/health GET 健康检查
/api/repos GET/POST 仓库列表 / 扫描新仓库
/api/repos/<id>/analyze POST DDD 领域分析
/api/repos/<id>/generate POST 生成测试用例
/api/repos/<id>/diff POST 精确回归
/api/repos/<id>/full POST 全流程(扫描+分析+生成)
/api/tasks GET/POST 任务列表 / 创建任务
/api/tasks/<id>/stop POST 停止任务
/api/tasks/<id>/logs GET SSE 日志流
/api/reports GET 报告列表
/api/reports/<id> GET 报告详情
/api/existing-tests/modules GET 已有用例模块列表
/api/existing-tests/markers GET 已有用例标记列表
/api/dashboard/stats GET 控制台统计

生成规则

  1. 严格遵循 SOUL.md 定义的测试架构师角色
  2. 所有测试按 DDD 限界上下文组织,而非按源文件一对一映射
  3. 领域层测试使用 Mock 隔离所有基础设施依赖
  4. 基础设施层测试可以使用真实依赖
  5. 每个测试函数必须有 docstring 描述测试意图
  6. 使用 pytest 标记标注测试类型(smoke/integration/regression/e2e)
  7. 自动注入指标门禁断言(覆盖率 >= 60%,通过率 >= 95%)
  8. 不生成不安全的测试代码(eval、exec、硬编码密钥)
  9. 只生成测试代码,不修改被测源代码
  10. Session 领域测试独立成套件,覆盖创建/持久化/上下文携带/清除/销毁

数据持久化

  • 数据库:platform_db.json(项目根目录)
  • 任务日志:platform_reports/<task_id>.json
  • 生成的测试:output/<repo_id>/
  • 截图:platform_artifacts/screenshots/
  • 前端构建产物:frontend/dist/
  • 自动清理:任务超过 100 个时自动清除最旧 50 个及其关联资产