# webui-autotest

**Repository Path**: svnspot/webui-autotest

## Basic Information

- **Project Name**: webui-autotest
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-01
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebUI自动化测试系统

基于多模态大模型与多智能体协作的自动化测试系统，支持页面分析、脚本生成、脚本执行与报告管理。后端使用 FastAPI，前端使用 Vite + React，测试执行集成 MidScene.js 与 Playwright。
该项目是参考**但问智能大模型自动化测试课程与配套代码**所构建

## 功能概览
- 页面与元素分析：多模态模型识别页面结构与交互。
- 测试脚本管理：Playwright/YAML 脚本的创建、搜索、统计。
- 脚本执行编排：单脚本与批量执行，实时状态（SSE）。
- 测试报告：自动汇总与查看最新报告。

## 目录结构
```
ui-automation/
├── backend/        # FastAPI 后端与服务层
│   ├── app/        # 应用代码（API、服务、配置、数据库）
│   ├── requirements.txt
│   ├── .env.example / .env
│   └── README.md   # 后端详细说明
├── frontend/       # Vite + React 前端
│   ├── src/        # 页面与服务模块
│   ├── start.bat / start.sh
│   └── package.json
└── docs/           # 架构与流程文档
```

## 环境准备
- Python 3.8+
- Node.js 18+
- 可选：MySQL 8.0+、Redis 6.0+（用于增强功能与持久化）
- Playwright 浏览器运行环境（需要安装浏览器）

## 后端启动（FastAPI）
1) 安装依赖
```
cd backend
pip install -r requirements.txt
```
2) 安装 Playwright 浏览器
```
playwright install
```
3) 配置环境变量（复制并修改）
- 复制 `backend/.env.example` 为 `backend/.env`，根据需要填写：
  - 服务器：`HOST`、`PORT`、`RELOAD`
  - CORS：`BACKEND_CORS_ORIGINS`
  - 数据库：`DATABASE_URL` 或 `MYSQL_*`（未配置时可禁用数据库）
  - 模型密钥：`DEEPSEEK_API_KEY`、`QWEN_VL_API_KEY`、`UI_TARS_API_KEY`
  - Playwright/MidScene：`MIDSCENE_SERVICE_URL`、`MIDSCENE_SCRIPT_PATH`
  - 可选开关：设置 `USE_DATABASE=false` 可在启动时跳过数据库连接

4) 启动服务
```
# 开发模式（自动重载）
python app/main.py

# 或生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000
```
5) 验证 API 与文档
- 访问 `http://localhost:8000/api/v1/docs`

## 前端启动（Vite + React）
1) 安装依赖并启动
```
cd frontend
npm install
npm run dev
```
- Windows 可直接双击 `frontend/start.bat`
- macOS/Linux 可运行 `frontend/start.sh`

2) 配置前端 API 地址
- 在 `frontend/.env.local`（或 `.env`）中设置：
```
VITE_API_URL=http://localhost:8000
```
- 前端默认从 `VITE_API_URL + /api/v1` 访问后端接口（如需自定义，界面设置页也可修改）。

3) 访问前端
- 打开 `http://localhost:5173`

## Playwright 工作空间配置
系统默认使用一个本地工作空间来执行脚本：
- 默认路径（当前代码内）：`C:\Users\86134\Desktop\workspace\playwright-workspace`
- 必须包含：`package.json`、`e2e/` 目录与测试文件 `*.spec.ts`

初始化示例（在你的工作空间目录内执行）：
```
npm init -y
npm i -D @playwright/test
npm i @midscene/web
npx playwright install
```
将测试脚本放置到 `e2e/` 目录，例如：`e2e/test_example.spec.ts`

工作空间路径说明：
- 生成器使用 `MIDSCENE_SCRIPT_PATH`（来自后端 `.env`）保存生成的脚本。
- 执行器当前在代码中固定了路径（`app/agents/web/playwright_script_executor_agent.py` 的 `self.playwright_workspace`），如需修改请更新该文件中的路径或保持默认路径一致。

## 常用 API（示例）
- 执行单个脚本（文件系统脚本）
```
POST /api/v1/web/scripts/execute/single
Form:
  script_name: test.spec.ts
  base_url: https://example.com
  headed: false
```
- 建立 SSE 流（前端用于实时监控）
```
GET /api/v1/web/scripts/stream/{session_id}
```
- 查看最新测试报告（按执行 ID）
```
GET /api/v1/web/reports/view/{execution_id}
```
- 更多接口请查看：`http://localhost:8000/api/v1/docs`

## 常见问题
- 数据库连接失败
  - 设置 `USE_DATABASE=false` 跳过数据库；或正确配置 `DATABASE_URL` / `MYSQL_*`。
- 前端 API 404/跨域
  - 确认后端已启动，`VITE_API_URL` 指向后端；更新 `BACKEND_CORS_ORIGINS`。
- 报告无法查看
  - 确认工作空间路径、报告目录 `midscene_run/report` 存在；执行完成后再访问报告接口。
- Playwright 执行异常
  - 检查 Node.js 与浏览器安装；在工作空间内运行 `npx playwright test` 验证基础环境。

## 开发建议
- 保持 `.env` 中密钥安全，避免提交到版本库。
- 变更工作空间路径时，同时更新 `.env` 与执行器代码路径，确保一致。
- 后端日志输出位置可通过 `LOG_FILE` 与 `LOG_LEVEL` 调整。

## 声明
该项目是**但问智能大模型自动化测试课程与配套代码**的个人练习项目，使用较多课程配套代码，如有侵权请联系删除
---
如需更详细的后端接口与模块说明，请参阅 `backend/README.md`；系统总体架构说明见 `docs/WebUI自动化测试系统_技术架构与业务流程总结.md`。