# webui-test-platform

**Repository Path**: aiagentdemo/webui-test-platform

## Basic Information

- **Project Name**: webui-test-platform
- **Description**: 当 AI 能自己打开浏览器、自己看页面、自己点按钮、失败了还能自己改——手工回归测试，可能真的要变天了。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-19
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebUI 智能测试平台

一个前后端分离、AI 驱动的 Web UI 自动化测试平台。支持 **Playwright 录制**用例、用例**编辑与调试**、
从需求文档/手工用例**智能生成** agent-browser 可执行用例、执行中**失败步骤智能自愈**、
测试任务统一调度执行与 **AI 结果分析**。智能能力全部运行在可部署到任意设备的**独立 Agent Worker** 上。

> 引擎定位：**agent-browser 是唯一执行引擎**（生成 / 调试 / 任务 / 自愈 / 分析全走它）；
> **Playwright 只承担「录制」**（CDP 结构化录制 + Codegen 脚本录制）。录制产出的结构化步骤
> 自动转为 agent-browser 的 Web DSL 执行，Codegen 脚本作为产物可导出、接入 CI。

## 六大功能

1. **Playwright 录制**：两种模式
   - CDP 注入式结构化录制：在浏览器中的点击/输入/跳转实时转成平台统一的步骤 JSON；
   - Playwright Codegen：拉起官方录制器，产出标准 Python 脚本，可导出、便于接入 CI。
2. **用例编辑与调试**：网页端增删改步骤、定位器与断言，支持整条回放与**单步调试**，实时日志 + 失败截图。
3. **智能生成**：粘贴需求文档或手工用例，Agent 先用 **agent-browser 抓取真实页面控件快照**增强，
   再由大模型生成正反向用例（语义选择器 + 断言）。
4. **失败步骤智能优化**：任一步失败即截图 + 当前页面快照喂给「自愈模型」改写该步并重试（默认 2 轮），全过程存证。
5. **测试任务**：混合选择录制 / Codegen / 智能生成用例统一执行，自动产出通过率与 AI 分析报告。
6. **发布会风首页**：介绍平台能力、自愈闭环与分布式架构。

## 架构

```
frontend (Vue3 + Vite)  ──HTTP/SSE──▶  backend (FastAPI + SQLite)
                                          │ 注册/心跳 + 轮询领作业 + 进度回传
                                          ▼
                          agent-worker（独立 Python 服务，可部署 N 个到任意设备）
                             ├─ agent-browser 引擎：执行 / 快照 / 断言（唯一执行引擎）
                             ├─ Playwright：仅录制（CDP 结构化 / Codegen）
                             └─ LLM：用例生成 / 失败自愈 / 结果分析（三通道独立配置）
```

- 主平台只负责管理、队列调度、SSE 推送与产物存储；浏览器操作与大模型调用都在 Worker 所在设备本地完成。
- **agent-browser CLI**（[vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser)）：
  为 AI Agent 设计的浏览器自动化命令行。执行循环为
  `open → snapshot -i（语义控件树）→ 选择器映射最新 @ref → click/type/fill/… → eval 断言`。
- 大模型为 OpenAI 兼容接口（默认火山方舟 ARK），用例生成 / 智能优化 / 结果分析三个通道独立配置。

## 目录结构

```
webui-test-platform/
├── backend/          FastAPI 主平台（用例/需求/任务/录制/队列/SSE/模型配置）
├── agent-worker/     独立 Agent 服务（注册心跳、领作业、agent-browser 执行、Playwright 录制、AI 生成/自愈/分析）
└── frontend/         Vue3 前端（首页、录制、生成、用例、任务、节点、模型配置）
```

## 快速开始

### 1. 主平台 backend

```bash
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # 可改端口、WORKER_TOKEN、默认模型
python run.py                 # 默认 http://localhost:8077
```

### 2. Agent Worker（可在本机或任意设备，可起多个）

```bash
cd agent-worker
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 主执行引擎：安装 agent-browser CLI 并确保命令在 PATH 中（见官方文档）
# 录制能力（可选）：pip install playwright && playwright install chromium

cp .env.example .env          # 填 PLATFORM_URL（远程平台填实际地址）、WORKER_TOKEN
python run.py
```

启动后在前端「Agent 节点」页可见节点在线，及其 **agent-browser（执行）** 与 **Playwright（录制）** 两项能力。
多个 Worker 用不同 `WORKER_NAME` 注册；作业按能力调度，也可在页面上定向到指定节点。

### 3. 前端 frontend

```bash
cd frontend
npm install
npm run dev                   # 默认 http://localhost:5174，已代理 /api 与 /artifacts 到 8077
# 后端地址可用 VITE_BACKEND 覆盖：VITE_BACKEND=http://平台IP:8077 npm run dev
```

生产部署：`npm run build` 后用 Nginx 托管 `dist/`，并把 `/api`、`/artifacts` 反向代理到 backend。

## 使用流程

1. 在「模型配置」页填好三通道（至少配置用例生成通道，API Key 留空表示不修改）。
2. 「Playwright 录制」选有录制能力的节点 → 开始录制 → 在浏览器操作 → 停止 → 保存为用例；
   或在「智能生成」粘贴需求、选执行节点生成用例（由 agent-browser 执行）。
3. 「测试用例」中编辑、单步/整条调试，失败可开启自愈观察修复过程。
4. 「测试任务」勾选多条用例（可跨来源）创建并执行，在任务详情看实时日志、分步截图与 AI 分析报告。

## 用例步骤 DSL（agent-browser 执行）

单条结构化步骤：

```json
{ "action": "goto|click|fill|type|select|check|uncheck|press|wait|hover|screenshot|assert",
  "selector": "text=登录 / role=button name=登录 / CSS（#id、.class、标签）；goto/press 可留空",
  "value": "goto 的网址、fill/type 的输入值、select 选项、press 按键（如 Enter）、wait 毫秒数",
  "expect": { "type": "visible|hidden|text_contains|url_contains|value|checked|exists",
              "selector": "...", "value": "..." },
  "note": "步骤说明" }
```

执行要点：用例只存**语义选择器**（不存 @ref），Worker 每步动作前重新 `snapshot` 并实时映射为最新
@ref，从根本上避免 ref 失效；断言通过 `eval` 读取页面真实状态判定。

## 关键设计说明

- **录制与执行解耦**：Playwright 负责把人工操作变成结构化资产，agent-browser 负责稳定执行，
  两者通过统一步骤 DSL 衔接；纯 Codegen 脚本用例不在任务中执行（脚本可导出自行接入 CI）。
- **自愈闭环**：步骤失败 → 截图 + 页面控件快照 → 连同失败步、报错、前序步骤送 self_repair 通道
  → 模型返回改写后的单步 → 立即重试，最多 `MAX_REPAIR_ATTEMPTS` 轮；修复记录与截图全部写入报告。
- **作业队列**：SQLite 持久化，`queued/running/done/error/canceled`；运行中作业超时无心跳自动重排队，
  超过 `JOB_MAX_ATTEMPTS` 置失败。录制作业要求 playwright 能力，其余要求 agent_browser 能力。
  高并发生产建议换 PostgreSQL/MySQL。
- **安全**：生产环境请设置 backend 与所有 worker 一致的 `WORKER_TOKEN`，并通过 HTTPS/内网访问平台。

## 常见问题

- 执行/生成报「没有在线节点」：先启动 agent-worker，并确认其能力含 agent_browser。
- 无法录制：录制要求节点能力含 playwright（`pip install playwright && playwright install chromium`）。
- 智能生成/自愈报「未配置 API Key」：在「模型配置」填写对应通道并测试连通。
- agent-browser 命令找不到：安装 CLI 到 PATH，或在 worker `.env` 设置 `AGENT_BROWSER_BIN`。
- 远程设备无法连平台：worker `.env` 的 `PLATFORM_URL` 需填 Worker 可访问到的平台地址。