# ai-testcase-agent

**Repository Path**: aiagentdemo/ai-testcase-agent

## Basic Information

- **Project Name**: ai-testcase-agent
- **Description**: AI 测试用例生成与执行 Agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 测试用例生成与执行 Agent

对外提供 HTTP 服务的多 Agent 测试系统：**需求文档/手工步骤 → 生成手工用例 → 用户确认 → 单用例逐步执行（每步智能优化）→ 测试报告**。

基于 **FastAPI + LangGraph**，浏览器自动化对接官方 [agent-browser](https://agent-browser.dev/) CLI。无 API Key、无浏览器时自动降级为 mock，离线即可端到端跑通。

---

## 界面预览

![AI 测试用例生成与执行 Agent](./页面截图.png)

## 需求对照

| # | 需求 | 实现 |
|---|------|------|
| 1 | 输入手工用例/需求文档 → 生成手工用例 | `app/agents/casegen_agent.py`，支持 **.md / .docx** 输入（`app/loaders/doc_loader.py`） |
| 2 | 下载用例供确认，JSON 展示 | `GET /api/cases/{id}/download`，确认门状态机 `awaiting_confirmation → confirmed` |
| 3 | 确认后第二 Agent 生成 agent-browser 命令执行 → 报告 | `app/agents/exec_agent.py` + `app/runners/browser_runner.py`，产出 JSON+HTML 报告 |
| 4 | 配置文件指定不同 Agent 用不同大模型；加载 skill 与 mcp | `config.yaml` + `app/llm/factory.py` + `app/loaders/{skill,mcp,context}_loader.py`；skill 与 mcp 同时注入【用例生成】和【UI命令生成】两个 Agent |
| 5 | RAG 管理用例生成上下文，执行完清除 | `app/rag/context_manager.py`，按 session 隔离，`cleanup` 节点 `clear()` |
| 6 | 补充其他 Agent 功能 | 确认门(HITL)、**步骤级失败智能优化**、执行轨迹、配置自检接口、离线 mock |

---

## 目录结构

```
ai-testcase-agent/
├── backend/      # 后端：FastAPI + LangGraph（app/、tests/、config.py、main.py、config.yaml、skills/、mcp/ 等）
├── frontend/     # 前端：Vite + Vue3 单页应用
└── README.md
```

## 快速开始

```bash
cd backend
pip install -r requirements.txt
cp config.example.yaml config.yaml      # 按需修改各 Agent 的模型

# 离线端到端测试（无需 key / 浏览器）—— 推荐先跑
python -m tests.test_e2e_offline

# 启动 HTTP 服务
python main.py                          # 默认 http://localhost:8080
# 打开 http://localhost:8080/docs 交互式调试
```

## 前端（Vue3 · 浅色科技风）

`frontend/` 是 Vite + Vue3 单页应用，浅色科技风、电光紫→青签名渐变。四个页面：

- **探索执行台**：需求录入（文本/上传 .md/.docx）→ 生成手工用例 → 表格内编辑 → 确认 → 单个用例执行，实时展示终端风命令轨迹（命令/推理/优化标记/输出）与报告下载。
- **模型配置**：为 `casegen` / `exec` 两个 Agent 分别下拉选择大模型（含万擎/OpenAI/DeepSeek/Ollama/Mock 预设），保存写回 `config.yaml`；含运行参数（Mock 执行、优化重试次数）。
- **Skill 管理**：新增/编辑/删除 SKILL.md（写盘到 `skills/`，即时 reload 注入 Agent 提示）。
- **MCP 管理**：新增/编辑/删除/启停 MCP server（写盘到 `mcp/servers.json`）。

```bash
cd frontend
npm install
npm run dev        # 开发：http://localhost:5173，已配置 /api 代理到 8080
npm run build      # 生产：产物在 frontend/dist
```

开发时同时启动后端（`python main.py`）与前端（`npm run dev`），访问 http://localhost:5173 即可。

离线测试预期输出：

```
[OK] 健康检查
[OK] 配置可见：agents=['casegen', 'exec'], skills=1 个
[OK] 生成用例：... (状态=待确认)
[OK] 用例可下载为 JSON 供确认
[OK] 用例已确认，确认门解除
[OK] 单用例逐步执行：2/2 通过；1 个步骤经过智能优化重试
[OK] 测试报告可下载 (zip: summary.json + report.html)
[OK] 用例执行完成后 RAG 上下文已清除（需求5）
全部通过 ✅
```

---

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/cases/generate` | 提交 `requirement_text` 或上传 `.md/.docx` 文件，生成用例 |
| GET  | `/api/cases/{task_id}` | 查询用例与状态 |
| GET  | `/api/cases/{task_id}/download` | 下载用例 JSON 供确认 |
| POST | `/api/cases/{task_id}/confirm` | 确认（可回传修改后的用例） |
| POST | `/api/runs/{task_id}/execute` | 执行**单个**用例（body 传 `case_id`、`base_url`） |
| GET  | `/api/runs/{task_id}` | 查执行状态与报告 |
| GET  | `/api/runs/{task_id}/report?case_id=...` | 下载报告 zip |
| GET  | `/api/system/config` | 查看各 Agent 模型、已加载 skill/mcp |
| GET  | `/health` | 健康检查 |

典型调用顺序：`generate` →（`download` 核对）→ `confirm` → `execute` → `report`。

---

## 执行模型：单用例逐步执行 + 步骤智能优化（决策4）

对已确认用例的每个步骤：

1. `snapshot -i --json` 取当前页面真实可交互元素（含 `@e2` 这类 ref）。
2. Exec Agent 据此生成该步的 agent-browser 命令并执行。
3. **失败时**：把"失败命令 + 错误输出 + 最新快照"回喂大模型，让它优化命令（换 ref / 改 fill / 补 wait），重试至多 `max_optimize_retries` 次。
4. 记录每步 `StepResult`（含 `attempts`、`optimized` 标记）。

ref 始终基于实时快照，比一次性静态生成命令鲁棒得多。

agent-browser 命令集（严格对照官方）：`open <url>` / `snapshot -i --json` / `click <sel>` / `type <sel> <text>` / `fill <sel> <text>` / `press <key>` / `wait ...` / `screenshot [path]` / `eval <js>` / `close`，会话用 `--session <id>` 隔离。

---

## 多模型配置（需求4）

`config.yaml` 中每个 Agent 独立配置 provider/模型，`LLMFactory.for_agent(name)` 按名实例化。`provider: openai_compatible` 的 `base_url` 可指向 OpenAI / Ollama / vLLM 等任意兼容端点。缺 key 或 `fallback_to_mock: true` 时自动用 MockLLM。

**默认已适配公司万擎大模型**（OpenAI 兼容网关，配置同 `smart-test-platform/backend/.env.example`）：

```yaml
agents:
  casegen:
    provider: openai_compatible
    base_url: https://XXXX/api/agent/v1/apps
    model: XXXXX
    api_key_env: OPENAI_API_KEY    # export OPENAI_API_KEY=...
    temperature:                   # 留空 = 不发送（企业网关可能拒绝额外参数）
    max_tokens:                    # 留空 = 不发送
    use_json_mode: false           # 万擎不支持 response_format，靠文本抽取 JSON
```

兼容要点（与你现有 `services/llm.py` 一致）：`temperature`/`max_tokens` 留空时**完全不发送**，对万擎只发 `model + messages` 最稳；`use_json_mode: false` 时不发 `response_format`，Agent 内部用 `_extract_json` 从文本中稳健解析 JSON。改用 OpenAI 官方时把 `base_url`/`model` 换掉、并可设 `temperature: 0`、`use_json_mode: true`。

切换到真实 agent-browser：把 `config.yaml` 的 `execution.use_mock` 设为 `false`，`agent_browser_cmd` 指向你安装的 CLI 即可。

## Skill 与 MCP 注入（需求4）

skill 与 mcp 会被加载并**同时注入到两个生成环节**——生成手工用例（CaseGen Agent）与生成 UI 命令（Exec Agent，含失败优化）：

- **SkillLoader** 扫描 `skills.dirs` 下的 `SKILL.md`，按关键词匹配相关技能描述。
- **McpLoader** 读取 `mcp/servers.json`（标准 MCP `mcpServers` 格式），登记可用工具服务。
- **`app/loaders/context.py` 的 `agent_context(keyword)`** 把两者合并成提示片段，两个 Agent 在调用大模型前都会拼入：用例生成用关键词 `case`，UI 命令生成用关键词 `command`。

要新增能力：把 `SKILL.md` 放进 `skills/` 目录、或在 `mcp/servers.json` 增加一个 server（带可选 `description`），无需改代码即被自动加载注入。`GET /api/system/config` 可查看已加载的 skill 与 mcp。

---

## 项目结构

```
ai-testcase-agent/
├── backend/
│   ├── main.py                     # FastAPI 入口
│   ├── config.py / config.example.yaml
│   ├── app/
│   │   ├── api/        cases.py · runs.py · system.py · manage.py   # HTTP 路由
│   │   ├── agents/     casegen_agent.py · exec_agent.py    # 两个 Agent
│   │   ├── graph/      workflow.py                          # LangGraph 工作流
│   │   ├── llm/        factory.py                           # 多模型工厂(含smart mock)
│   │   ├── rag/        context_manager.py                   # 内存向量库
│   │   ├── loaders/    doc_loader.py · skill_loader.py · mcp_loader.py · context.py
│   │   ├── runners/    browser_runner.py                    # 逐步执行+优化(含mock)
│   │   ├── services/   task_store.py · config_store.py · skill_store.py · mcp_store.py
│   │   └── models/     schemas.py                           # Pydantic
│   ├── skills/manual-case-generation/SKILL.md · ui-command-generation · ui-exploratory-flow
│   ├── mcp/servers.json
│   └── tests/test_e2e_offline.py   # 离线端到端
└── frontend/                       # Vite + Vue3 单页（探索执行台 / 模型 / Skill / MCP）
    └── src/  api.js · router.js · App.vue · views/ · components/
```

阅读顺序建议：`backend/config.example.yaml` → `backend/app/llm/factory.py` → `backend/app/agents/*` → `backend/app/runners/browser_runner.py` → `backend/app/graph/workflow.py` → `backend/tests/test_e2e_offline.py`。

---

*已通过离线端到端测试验证：md 输入、用例生成、确认门、单用例逐步执行、步骤智能优化、报告产出、RAG 上下文清理全部正常；HTTP 服务正常启动（9 个端点）。*