# 平台自动化测试可视化系统

> **Web 可视化自动化测试平台** — 用户通过在目标网站上实际操作，系统自动捕获行为并转换为测试步骤，无需手动编写测试代码。

![Python](https://img.shields.io/badge/Python-3.10+-blue)
![FastAPI](https://img.shields.io/badge/FastAPI-0.110-green)
![Vue 3](https://img.shields.io/badge/Vue_3-3.4-brightgreen)
![Playwright](https://img.shields.io/badge/Playwright-1.40-orange)
![License](https://img.shields.io/badge/License-MIT-yellow)
![Status](https://img.shields.io/badge/Status-开发中-lightgrey)

---

## 📋 目录

- [项目概述](#-项目概述)
- [技术栈](#-技术栈)
- [项目结构](#-项目结构)
- [功能特性](#-功能特性)
- [快速开始](#-快速开始)
- [使用指南](#-使用指南)
- [API 接口](#-api-接口)
- [执行引擎能力](#-执行引擎能力)
- [开发进度](#-开发进度)
- [CI/CD](#-cicd)
- [常见问题](#-常见问题)
- [开发团队](#-开发团队)

---

## 🎯 项目概述

**平台自动化测试可视化系统** 是一个针对企业内部统一管理平台的 Web 可视化自动化测试工具。它解决了传统自动化测试需要编写代码的门槛问题，通过**用例录制器**功能，让测试人员通过实际操作即可生成测试用例。

### 核心创新

| 特性 | 说明 |
|------|------|
| 🎥 **可视化录制** | 在目标网站上操作，系统自动捕获点击、输入、导航等行为 |
| 🚀 **一键执行** | 支持单个或批量执行测试用例，实时查看执行进度 |
| 📊 **实时推送** | 基于 WebSocket 的毫秒级实时状态推送 |
| 📝 **报告生成** | 自动生成 HTML 格式的测试报告，支持导出和下载 |
| 🔄 **用例依赖** | 支持测试用例间的依赖管理，自动拓扑排序 |
| 🧹 **数据清理** | 截图、报告等资源的自动清理和数据库优化 |

---

## 🛠 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| **后端框架** | FastAPI | ^0.110.x |
| **ORM** | SQLAlchemy | ^2.0.x |
| **数据库** | SQLite (aiosqlite) | 3.x |
| **前端框架** | Vue 3 + TypeScript | ^3.4.x |
| **UI 组件库** | Element Plus | ^2.5.x |
| **构建工具** | Vite | ^5.1.x |
| **浏览器自动化** | Playwright (Chromium) | ^1.40.x |
| **实时通信** | WebSocket | FastAPI 内置 |
| **图表库** | ECharts | ^5.5.x |
| **状态管理** | Pinia | ^2.1.x |

---

## 📁 项目结构

```
platform-auto-test/
├── backend/                          # 后端服务 (Python FastAPI)
│   ├── requirements.txt              # Python 依赖清单
│   └── app/
│       ├── main.py                   # FastAPI 应用入口
│       ├── config.py                 # 应用配置管理
│       ├── database.py               # SQLite 异步引擎 & 会话管理
│       ├── models/                   # 数据模型层
│       │   ├── module.py             # 模块表模型
│       │   ├── test_case.py          # 测试用例模型
│       │   ├── execution.py          # 执行记录模型
│       │   ├── case_result.py        # 用例结果模型
│       │   └── case_dependency.py    # 用例依赖模型
│       ├── schemas/                  # Pydantic 数据校验层
│       │   ├── module.py             # 模块 CRUD Schema
│       │   └── test_case.py          # 用例 CRUD + 导入导出 Schema
│       ├── routers/                  # API 路由层 (10 个路由模块)
│       │   ├── modules.py            # 模块管理 API
│       │   ├── cases.py              # 用例管理 API
│       │   ├── executions.py         # 执行管理 API + WebSocket
│       │   ├── recorder.py           # 录制器 API
│       │   ├── stats.py              # 统计分析 API
│       │   ├── reports.py            # 报告管理 API
│       │   ├── cleanup.py            # 数据清理 API
│       │   ├── batch.py              # 批量操作 API
│       │   └── dependencies.py       # 依赖管理 API
│       ├── services/                 # 业务逻辑层
│       │   ├── module_service.py     # 模块服务
│       │   ├── case_service.py       # 用例服务
│       │   ├── execution_service.py  # 执行调度服务
│       │   ├── report_service.py     # 报告生成服务
│       │   ├── cleanup_service.py    # 数据清理服务
│       │   ├── batch_service.py      # 批量操作服务
│       │   └── dependency_service.py # 依赖管理服务
│       ├── executors/                # 测试执行引擎
│       │   └── playwright_executor.py # Playwright 执行器
│       ├── websocket/                # 实时通信
│       │   └── manager.py            # WebSocket 连接管理
│       ├── utils/                    # 工具函数
│       │   ├── id_generator.py       # UUID 生成器
│       │   ├── selector_mapper.py    # 选择器映射器
│       │   └── session_manager.py    # 会话管理器
│       └── scripts/                  # 辅助脚本 (15 个)
│
├── frontend/                         # 前端应用 (Vue 3 + TS)
│   ├── package.json                  # 依赖配置
│   ├── vite.config.ts                # Vite 构建配置
│   ├── index.html                    # HTML 入口
│   └── src/
│       ├── main.ts                   # 应用入口
│       ├── App.vue                   # 根组件 (布局 + 导航)
│       ├── router/index.ts           # 路由配置 (7 个路由)
│       ├── types/                    # TypeScript 类型定义
│       │   ├── module.ts
│       │   ├── case.ts
│       │   └── execution.ts
│       ├── api/                      # API 调用层
│       │   ├── modules.ts
│       │   ├── cases.ts
│       │   ├── executions.ts
│       │   ├── stats.ts
│       │   ├── reports.ts
│       │   └── recorder.ts
│       ├── utils/                    # 工具函数
│       │   ├── request.ts            # Axios 封装
│       │   └── websocket.ts          # WebSocket 客户端
│       ├── components/               # 公共组件
│       │   └── StepDetailPanel.vue   # 步骤详情面板
│       └── views/                    # 页面组件 (7 个)
│           ├── Dashboard.vue         # 测试总览
│           ├── Modules.vue           # 模块管理
│           ├── Cases.vue             # 用例管理
│           ├── Recorder.vue          # 用例录制
│           ├── Execution.vue         # 执行中心
│           ├── Reports.vue           # 报告中心
│           └── Settings.vue          # 系统配置
│
├── Docs/                             # 项目文档
│   └── PRD/自动化测试平台/             # PRD 需求 & 计划文档
│
├── data/                             # 运行数据 (gitignored)
│   ├── test_platform.db              # SQLite 数据库
│   ├── screenshots/                  # 执行截图
│   └── reports/                      # 生成的报告
│
├── .github/workflows/                # CI/CD 配置
│   └── ci-cd.yml                     # GitHub Actions 工作流
│
└── .claude/                          # Claude Code 配置
    └── skills/                       # 自定义技能
```

---

## ✨ 功能特性

### 🎥 用例录制器

在目标网站上通过真实操作自动生成测试用例，无需编写代码：

1. **启动录制** — 配置目标 URL，打开录制浏览器
2. **操作捕获** — 自动记录点击、输入、导航、选择等操作
3. **添加断言** — 支持可见性判断、文本验证、URL 断言等
4. **保存用例** — 录制完成自动保存为标准用例格式

### 🚀 执行引擎

支持 13 种动作类型和 8 种断言类型：

**动作类型**：`navigate` · `click` · `fill` · `select` · `hover` · `wait` · `scroll` · `press` · `check` · `uncheck` · `assert` · `screenshot` · `upload`

**断言类型**：`visible` · `hidden` · `text` · `contains` · `value` · `count` · `url` · `title`

### 📊 实时监控

- 基于 WebSocket 的毫秒级实时状态推送
- 6 种消息类型：`execution_start` · `case_start` · `step_update` · `case_complete` · `execution_complete` · `execution_cancelled`
- 自动断线重连（最多 3 次）

### 📝 报告系统

- HTML 格式测试报告，包含统计卡片、进度条、用例详情
- 支持报告生成、导出、下载
- 截图自动关联展示

### 🔄 用例依赖管理

- 支持测试用例间的依赖关系定义
- 自动拓扑排序，确保执行顺序正确
- 批量操作支持

---

## 🚀 快速开始

### 环境要求

| 环境 | 版本要求 |
|------|---------|
| Python | ^3.10 |
| Node.js | ^18.0 |
| npm | ^9.0 |
| SQLite | ^3.0 |

### 安装与启动

```bash
# 1️⃣ 克隆项目
git clone http://git.ubainsyun.com/bing/ubains-module-test.git
cd platform-auto-test

# 2️⃣ 安装后端依赖
cd backend
pip install -r requirements.txt

# 3️⃣ 安装 Playwright 浏览器
playwright install chromium

# 4️⃣ 启动后端服务 (端口 8001)
uvicorn app.main:app --reload --port 8001

# 5️⃣ 安装前端依赖 (新开终端)
cd frontend
npm install

# 6️⃣ 启动前端服务 (端口 3000)
npm run dev
```

### 访问地址

| 服务 | 地址 |
|------|------|
| 🌐 前端页面 | http://localhost:3000 |
| 📚 API 文档 (Swagger) | http://localhost:8001/docs |
| 📖 ReDoc 文档 | http://localhost:8001/redoc |
| ❤️ 健康检查 | http://localhost:8001/health |

---

## 📖 使用指南

### 1. 模块管理

- 创建测试模块分类（如"会议管理"、"登录模块"等）
- 支持卡片式展示，直观查看模块统计信息
- 模块级联删除（自动删除模块下所有用例）

### 2. 用例管理

- 在模块下创建测试用例
- 每个用例包含多个测试步骤（JSON 格式）
- 支持用例复制、导入/导出
- 支持用例依赖关系配置

### 3. 用例录制

1. 点击「启动录制」配置录制参数
2. 在弹出的浏览器窗口中操作目标系统
3. 系统自动捕获每一步操作
4. 可手动添加断言验证
5. 录制完成后保存为测试用例

### 4. 执行中心

- 选择需要执行的测试用例
- 支持批量选择和顺序执行
- WebSocket 实时推送执行进度
- 查看每一步的截图和日志
- 支持取消正在执行的测试

### 5. 报告中心

- 查看历史执行报告
- 生成 HTML 格式详细报告
- 支持报告导出和下载

---

## 🔌 API 接口

### 模块管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/modules` | 获取模块列表（分页） |
| POST | `/api/modules` | 创建模块 |
| GET | `/api/modules/{id}` | 获取模块详情 |
| PUT | `/api/modules/{id}` | 更新模块 |
| DELETE | `/api/modules/{id}` | 删除模块 |
| GET | `/api/modules/{id}/stats` | 获取模块统计 |

### 用例管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/cases` | 获取用例列表 |
| POST | `/api/cases` | 创建用例 |
| GET | `/api/cases/{id}` | 获取用例详情 |
| PUT | `/api/cases/{id}` | 更新用例 |
| DELETE | `/api/cases/{id}` | 删除用例 |
| POST | `/api/cases/{id}/copy` | 复制用例 |
| POST | `/api/cases/import` | 批量导入用例 |
| POST | `/api/cases/export` | 导出用例 |

### 执行管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/executions` | 获取执行记录列表 |
| POST | `/api/executions` | 创建执行任务 |
| GET | `/api/executions/{id}` | 获取执行详情 |
| POST | `/api/executions/{id}/run` | 启动执行 |
| POST | `/api/executions/{id}/cancel` | 取消执行 |
| GET | `/api/executions/{id}/results` | 获取执行结果 |
| WS | `/api/executions/ws/{id}` | WebSocket 实时推送 |

### 统计分析

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/stats/overview` | 总览统计 |
| GET | `/api/stats/trend` | 趋势统计 |
| GET | `/api/stats/modules` | 模块统计 |
| GET | `/api/stats/module/{id}` | 模块详情统计 |
| GET | `/api/stats/priority` | 优先级分布 |
| GET | `/api/stats/status` | 状态分布 |

### 报告管理 & 数据清理 & 录制器

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/reports/generate/{id}` | 生成 HTML 报告 |
| POST | `/api/reports/export/{id}` | 导出报告 |
| GET | `/api/reports/download/{id}` | 下载报告 |
| POST | `/api/recorder/start` | 启动录制 |
| POST | `/api/recorder/stop` | 停止录制 |
| POST | `/api/recorder/save` | 保存录制用例 |
| GET | `/api/cleanup/stats` | 存储统计 |
| POST | `/api/cleanup/cleanup` | 执行清理 |

---

## 🧪 执行引擎能力

### 选择器优先级策略

| 优先级 | 策略 | 示例 |
|--------|------|------|
| 1 | `test-id` 属性 | `[data-testid="login-btn"]` |
| 2 | `id` 属性 | `#login-btn` |
| 3 | 语义化属性 | `[aria-label="登录"]` |
| 4 | `role` 属性 | `button[role="button"]` |
| 5 | 文本内容 | `text=登录` |
| 6 | CSS 类名 | `.login-button` |
| 7 | 层级组合 | `div > button.submit` |

### 多选器回退策略

每个步骤可配置多个选择器，执行时按优先级依次尝试，前一个失败则自动回退到下一个选择器，大幅提高测试稳定性。

---

## 📈 开发进度

| 阶段 | 内容 | 状态 | 完成度 |
|------|------|------|--------|
| **Phase 1** | 基础框架搭建 | ✅ 已完成 | 100% |
| **Phase 2** | 核心功能开发 | ✅ 已完成 | 100% |
| **Phase 3** | 执行与可视化 | ✅ 已完成 | 100% |
| **Phase 4** | 分析与报告 | ✅ 已完成 | 100% |
| **Phase 5** | 扩展与优化 | 🔄 进行中 | ~30% |

### 最新测试结果

| 指标 | 数值 |
|------|------|
| 测试用例总数 | 26 |
| 通过率 | 100% (26/26) |
| 总执行次数 | 89 |
| 模块覆盖率 | 96.3% (26/27) |
| 深层交互测试 | 5 个 (含表单、搜索、断言) |

### Phase 5 待办

| 优先级 | 任务 | 状态 |
|--------|------|------|
| 🔴 P0 | 系统配置页面 (Settings.vue) | ⏳ 待开始 |
| 🔴 P0 | Pinia 状态管理 | ⏳ 待开始 |
| 🔴 P0 | 单元测试 (pytest + Vitest) | ⏳ 待开始 |
| 🟡 P1 | 数据库迁移 (Alembic) | ⏳ 待开始 |
| 🟡 P1 | 后台执行优化 | ⏳ 待开始 |
| 🟡 P1 | 前端布局抽取 | ⏳ 待开始 |
| 🔵 P2 | 定时任务 | ⏳ 待开始 |
| 🔵 P2 | Docker 部署 | ⏳ 待开始 |

---

## 🔄 CI/CD

项目配置了 GitHub Actions 自动流水线：

- **Backend Tests** — pytest + coverage
- **Frontend Tests** — lint + build
- **Integration Tests** — WebSocket 流程验证
- **Build** — 打包构建产物
- **Deploy** — 仅 master 分支触发

---

## ❗ 常见问题

### Playwright 在 Windows 上无法运行

**问题**：`NotImplementedError` (SelectorEventLoop 不支持子进程)

**解决**：项目已适配 Windows 平台，使用同步 API + 线程池方案：
```python
# main.py 已配置
asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
```
每个测试用例会创建独立的 `PlaywrightExecutor` 实例，在线程池中隔离执行。

### 前端页面空白

**问题**：`inject() can only be used inside setup()`

**解决**：确保 `useRoute()` 在 `<script setup>` 顶层调用，不要在 `computed()` 回调内调用。

### 请求报 404

**问题**：API 请求路径变成 `/api/api/cases`

**解决**：前端 `baseURL` 设为空字符串，路由路径写完整 `/api/...`。

### 数据库锁定

**问题**：`SQLite database is locked`

**解决**：项目已配置 `check_same_thread=False` + `pool_pre_ping=True`。

---

## 👥 开发团队

| 角色 | 姓名 |
|------|------|
| 开发者 | czj |

---

## 📄 文档索引

| 文档 | 路径 | 说明 |
|------|------|------|
| PRD 主文档 | `Docs/PRD/自动化测试平台/_PRD_平台自动化测试可视化系统需求文档.md` | 完整需求定义 |
| 执行计划 | `Docs/PRD/自动化测试平台/_PRD_平台自动化测试可视化系统需求文档_计划执行.md` | 分阶段执行计划 |
| 进度报告 | `Docs/PRD/自动化测试平台/_开发进度报告_20260709.md` | 含 API 清单、Phase 5 待办 |
| 测试结果 | `Docs/PRD/自动化测试平台/测试结果汇总报告.md` | 执行结果详细数据 |
| 当前进度 | `Docs/PRD/自动化测试平台/当前进度记录.md` | 含 26 个用例结果 |

---

*📅 最后更新: 2026-07-13*