# webtest-agent · AI 网页测试智能体

基于 **LLM 决策 + 无头浏览器执行** 的端到端网页测试系统。用自然语言描述测试目标，AI 自动打开页面、逐步操作、断言验证、生成带截图的测试报告。

## 架构

```
┌─────────────────────────────────────────────┐
│  HTTP API (Flask)                           │
│  POST /api/tasks → 发起测试                  │
│  GET  /api/tasks → 任务列表/状态              │
│  GET  /api/tasks/<id>/report → HTML 报告     │
├─────────────────────────────────────────────┤
│  Agent 循环（每任务一线程）                    │
│  LLM(火山引擎 doubao) 决策下一步动作           │
│  agent-browser CLI 执行（无头 Chrome）        │
│  断言器 + 截图留证 + 报告生成                  │
└─────────────────────────────────────────────┘
```

## 快速开始

```bash
./start.sh              # 启动（默认 16051 端口）
./start.sh stop         # 停止
```

### API 用法

```bash
# 发起测试
curl -X POST http://localhost:16051/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","goal":"验证标题包含 Example Domain，点击 Learn more 验证跳转","max_steps":12}'

# 查看任务
curl http://localhost:16051/api/tasks/<task_id>

# 查看报告
curl http://localhost:16051/api/tasks/<task_id>/report

# 停止任务
curl -X POST http://localhost:16051/api/tasks/<task_id>/stop
```

## AI 动作协议

LLM 每步输出一个 JSON 动作，由 agent-browser 执行：

| 动作 | 说明 |
|------|------|
| `click` | 点击元素（`@e1` 或 `text:按钮文字`） |
| `fill` | 输入框填值 |
| `select` | 下拉框选择 |
| `press` | 按键（Enter/Tab 等） |
| `wait` | 等待（毫秒 / `text:xx` / `url:xx`） |
| `scroll` | 滚动页面 |
| `assert` | 断言（text/url/title/element，PASS/FAIL） |
| `screenshot` | 截图留证 |
| `done` / `fail` | 结束任务并总结 |

## 关键特性

- **自然语言驱动**：测试目标直接用中文描述
- **自我修复**：元素找不到时 LLM 自动换定位策略重试
- **断言验证**：文本/URL/标题/元素存在性，输出 PASS/FAIL
- **证据留存**：关键步骤自动截图，HTML 报告内嵌展示
- **并发控制**：默认最多 2 个任务并发（`config.py` 可调）

## 配置

见 `config.py`：LLM 端点/模型、最大步数、超时、并发数均可通过环境变量覆盖。

## 依赖

- Python 3.10+（Flask 3.0）
- agent-browser CLI（node 安装）：`npm install -g agent-browser`
- 无头 Chrome（agent-browser install 自动安装）