# HANDOFF — 平台自动化测试交接文档（UI自动化窗口）

> **生成时间**: 2026-07-22
> **当前分支**: `platform-auto-test`
> **最近提交**: `a9074f8c` fix(executor): 修复FastAPI端点执行Playwright报asyncio检测错误
> **状态**: ✅ 深层交互用例步骤优化完成，通过率从 30% 提升到 76%

---

## ⚠️ 开始工作前必读

**多窗口并行开发冲突规避**：如需开多个 Claude Code 窗口同时开发，**必须先阅读** `Docs/多窗口并行开发指南.md`，了解：
- 端口隔离（8001/8002）
- 数据库操作错开
- Playwright 执行互斥（不可同时执行用例）
- Git 提交协作

**当前多窗口状态**：本项目有两个窗口同时在开发：
- **本窗口**：UI 自动化测试模块（会议管理、数据分析、运维管理、管理看板）
- **另一窗口**：安全测试模块（API安全测试、华为红线检查、漏洞回归等）— 交接文档见 `HANDOFF_安全测试.md`

---

## 一、项目概览

**平台自动化测试可视化系统 (platform-auto-test)** — Web 可视化自动化测试平台，核心创新是用例录制器。

- **技术栈**: FastAPI + SQLAlchemy(async) + SQLite + Playwright(同步API) + WebSocket / Vue 3 + Element Plus + Vite 5 + TypeScript + ECharts
- **被测系统**: 统一管理平台 (https://192.168.5.44)
- **登录凭据**: admin@xty / Ubains@13579 · 验证码固定 `csba`
- **远程仓库**: http://git.ubainsyun.com/bing/ubains-module-test.git
- **当前分支**: `platform-auto-test`（主分支：`main`）

### 目录结构（关键路径）

```
platform-auto-test/
├── backend/app/
│   ├── main.py                 # FastAPI 入口（Windows ProactorEventLoop）
│   ├── executors/
│   │   └── playwright_executor.py  # UI测试执行引擎（13种动作+11种断言，支持iframe）
│   ├── services/execution_service.py  # 执行调度（含 run_all_cases_sync）
│   └── scripts/
│       ├── create_deep_interaction_cases_v2.py  # 深层用例创建脚本（已优化）
│       ├── test_executor_direct.py    # 执行器直接调用测试
│       └── test_single_case.py        # FastAPI端点单用例测试
├── frontend/src/
│   ├── views/Cases.vue         # 用例管理
│   ├── views/Execution.vue     # 执行中心
│   └── ...
├── Docs/PRD/
│   ├── 需求文档/用例管理/
│   │   ├── _PRD_需求文档_深层交互用例步骤优化.md       # 本次P0需求文档
│   │   └── _执行计划_深层交互用例步骤优化.md           # 本次P0计划执行文档
│   └── ...
└── HANDOFF.md                  # 本文档
```

---

## 二、本次会话任务（已完成）

### 深层交互用例步骤优化 ✅

**问题背景**：25 个深层交互用例执行通过率仅约 30%，主要问题：canvas 等待超时、重复登录、选择器不精确、导航等待不足。

**完成的优化**：

1. **删除冗余登录步骤** ✅
   - 移除了 `build_base_steps()` 函数（8步登录流程）
   - 用例步骤从"导航到目标菜单"开始，`auto_login=True` 由执行器处理
   - 步骤 order 从 1 开始连续编号

2. **优化 canvas 等待策略** ✅
   - canvas 等待超时从 15s 提升到 30s
   - 增加 ECharts 特定选择器回退链：`[".echarts", ".chart-container canvas", "canvas", "[class*='chart']"]`
   - 增加"等待图表渲染完成"步骤（3s 延时确保 ECharts 完成绘制）

3. **优化导航等待策略** ✅
   - 导航后等待目标页面特征元素（canvas/.el-table），而非仅 `wait body`
   - 增加"等待页面渲染完成"步骤（3s 延时应对动画）

4. **优化选择器精确度** ✅
   - 筛选器选择器增加上下文限定（`.el-select:nth-child(n) .el-input`）
   - 下拉选项选择器增加可见性限定（`.el-select-dropdown:visible`）
   - 使用 `selectors` 列表提供多选器回退链

5. **修复执行器 `_do_wait` 方法** ✅
   - 增加快速检查阶段：先 1s 超时快速检查每个选择器
   - 将总超时均分给每个选择器，避免 4 个选择器 × 30s = 120s
   - 效果：canvas 等待从 120s 降到 4s

6. **修复执行器 `element_count_min` 断言** ✅
   - 支持 `params.min_count` 参数（之前仅支持 `params.expected`）
   - 向后兼容：`min_count` 不存在时回退到 `expected`

7. **脚本支持更新已有用例** ✅
   - 新增 `update_or_create_case()` 函数
   - 按名称查找已有用例，找到则更新，否则创建

**执行结果**：

| 指标 | 优化前 | 优化后 |
|------|--------|--------|
| 通过率 | ~30% | **76%** (19/25) |
| 单用例耗时 | 120-130s | **10-20s** |
| 重复登录 | 有 | **无** |

**失败用例分析**（6 个，均为业务数据/页面结构问题）：

| 用例 | 失败原因 | 类型 |
|------|---------|------|
| 管理看板-表格数据验证 | 表格数据行 0 行（被测系统数据为空） | 数据问题 |
| 会议概览-筛选器交互验证 | canvas 等待超时（页面无 canvas） | 页面结构 |
| 会议室概览-筛选器验证 | canvas 等待超时（页面无 canvas） | 页面结构 |
| 会议统计-下拉筛选验证 | 筛选器选择器不匹配 | 选择器 |
| 历史记录-RSE-表格数据验证 | 菜单不存在（名称不正确） | 菜单名称 |
| 通知统计-筛选器验证 | 页面无 .el-select 元素 | 页面结构 |

**相关文档**：
- `Docs/PRD/需求文档/用例管理/_PRD_需求文档_深层交互用例步骤优化.md`
- `Docs/PRD/需求文档/用例管理/_执行计划_深层交互用例步骤优化.md`

---

## 三、历史已完成事项

### 3.1 用例创建

1. ✅ 创建了 25 个深层交互用例脚本 `create_deep_interaction_cases_v2.py`
2. ✅ 用例成功写入数据库（数据库总用例数：141个）
   - 管理看板：13个（+6）
   - 运维管理：15个（+7）
   - 数据分析：34个（+12）

### 3.2 用例步骤修复

1. ✅ **删除了"点击展开功能中心"步骤**：登录后 .block 菜单已可见，无需额外点击
2. ✅ **删除了登录步骤**：`auto_login=True` 时执行器会自动登录，用例步骤不应包含登录步骤

### 3.3 首页探索发现

- 首页有 29 个 .block 菜单卡片（前24个和后5个重复）
- 登录后 .block 元素已可见，不需要点击"展开功能中心"
- 点击 `.block:has-text("管理看板")` 可正常跳转

---

## 四、待解决问题

### 4.1 6 个失败用例需针对性修复

1. **会议概览/会议室概览**：页面可能没有 canvas 图表，需探索实际 DOM 结构
2. **会议统计-下拉筛选验证**：筛选器选择器需调整
3. **历史记录-RSE**：菜单名称可能不准确，需确认实际菜单文本
4. **通知统计/管理看板表格**：页面结构/数据可能与预期不符

### 4.2 执行器端口问题

8001 端口有僵尸进程（旧 uvicorn --reload），强制 kill 后仍会重生。当前通过 8002 端口绕过。需要找到并清理所有相关进程。

---

## 五、下一步计划

| 优先级 | 待办 | 说明 |
|--------|------|------|
| **P0** | 修复 6 个失败用例 | 探索实际 DOM 结构，调整选择器和等待策略 |
| **P1** | 提交代码 | 脚本优化 + 执行器修复 + 文档 待 git commit |
| **P1** | 清理 8001 端口僵尸进程 | 旧 uvicorn --reload 进程未清理 |
| **P2** | 批量执行全量用例 | 验证 117 个 UI 用例的执行情况 |
| **P3** | 清理临时脚本 | 根目录有多个临时探索脚本待清理 |

---

## 六、关键踩坑记录（绝对不要重复踩）

| # | 现象 | 根因 | 正确做法 |
|---|------|------|---------|
| 1 | `NotImplementedError` / Sync API inside asyncio | Windows 默认 SelectorEventLoop 不支持子进程 | 同步 API + ProactorEventLoop + 线程池 |
| 2 | 第二次执行 `start()` 失败 | 共享执行器 `_is_running` 状态 | 每用例新建 PlaywrightExecutor 实例 |
| 3 | 请求 `/api/api/cases` 404 | `baseURL:'/api'` 与路径叠加 | baseURL 留空，路径写完整 `/api/...` |
| 4 | `SQLite database is locked` | 同步执行并发写入 | check_same_thread=False + pool_pre_ping |
| 5 | bash 中 `start` 启动 CMD 失败 | MSYS 封装损坏 `&&` 引号 | `MSYS_NO_PATHCONV=1 cmd.exe /c start ...` |
| 6 | 前端页面空白 | `useRoute()` 在 computed 内调用 | 移到 setup 顶层 |
| 7 | `NOT NULL constraint failed: error_message` | 字段 nullable=False 但成功时为 None | 改为 nullable=True |
| 8 | 菜单text=选择器失败 | 被测系统菜单是.block>p | `.block:has-text("菜单名")` |
| 9 | **auto_login+重复登录** | 用例含登录步骤 | **auto_login=True时不要包含登录步骤** |
| 10 | **"点击展开功能中心"无效** | 登录后.block已可见 | **删除此步骤** |
| 11 | **Playwright asyncio检测错误** | run_in_executor中调用 | **`asyncio.set_event_loop(None)` 绕过检测** |
| 12 | **FastAPI端点执行失败** | Playwright检测到asyncio循环 | **在工作线程中设置 event_loop=None** |
| 13 | **_do_wait 多选器超时过长** | 4选择器×30s=120s | **快速检查+均分超时** |
| 14 | **element_count_min断言失败** | `params.min_count`未支持 | **修复执行器支持min_count参数** |
| 15 | **uvicorn --reload僵尸进程** | Windows进程管理异常 | **清除__pycache__，kill所有进程，换端口** |

---

## 七、启动与验证

```bash
# 后端（端口 8001）
cd backend
pip install -r requirements.txt
playwright install chromium
uvicorn app.main:app --reload --port 8001

# 前端（端口 3000）
cd frontend
npm install
npm run dev
```

- 前端: http://localhost:3000
- API 文档: http://localhost:8001/docs
- 被测系统: https://192.168.5.44 (admin@xty / Ubains@13579 / csba)

### 快速验证执行引擎

```bash
cd backend
PYTHONIOENCODING=utf-8 python scripts/test_executor_direct.py    # 直接调用
PYTHONIOENCODING=utf-8 python scripts/test_single_case.py        # API端点测试
```

### 验证深层用例优化效果

```bash
cd backend
PYTHONIOENCODING=utf-8 python scripts/create_deep_interaction_cases_v2.py  # 更新用例步骤
# 然后在前端执行中心批量执行深层交互用例
```

---

## 八、未提交变更（待 git commit）

### 修改的文件

| 文件 | 变更说明 |
|------|---------|
| `backend/scripts/create_deep_interaction_cases_v2.py` | 重写步骤构建逻辑，删除冗余登录，优化模板 |
| `backend/app/executors/playwright_executor.py` | 修复 _do_wait 多选器超时 + element_count_min 支持 min_count |
| `Docs/PRD/需求文档/用例管理/_PRD_需求文档_深层交互用例步骤优化.md` | 新增需求文档 |
| `Docs/PRD/需求文档/用例管理/_执行计划_深层交互用例步骤优化.md` | 新增计划执行文档 |
| `HANDOFF.md` | 更新交接文档 |

### 数据库变更

- `backend/data/test_platform.db` — 25 个深层用例的 steps 已更新

---

## 九、文档索引

| 文档 | 路径 |
|------|------|
| CLAUDE.md | `CLAUDE.md` |
| 多窗口并行开发指南 | `Docs/多窗口并行开发指南.md` |
| 深层用例优化需求文档 | `Docs/PRD/需求文档/用例管理/_PRD_需求文档_深层交互用例步骤优化.md` |
| 深层用例优化执行计划 | `Docs/PRD/需求文档/用例管理/_执行计划_深层交互用例步骤优化.md` |
| 问题处理文档 | `Docs/PRD/问题处理/` |
| 需求文档 | `Docs/PRD/需求文档/` |
| 安全测试交接文档 | `HANDOFF_安全测试.md` |
| HANDOFF.md | `HANDOFF.md`（本文档） |

---

## 十、用例统计

| 模块 | 用例数 | 深层用例通过率 |
|------|--------|--------------|
| 会议管理 | 50 | - |
| 数据分析 | 34 | - (深层12个，9通过3失败) |
| 运维管理 | 15 | - (深层7个，6通过1失败) |
| 管理看板 | 13 | - (深层6个，4通过2失败) |
| 登录模块 | 5 | - |
| **UI测试小计** | **117** | |
| 安全测试模块 | 24 | - |
| **总计** | **141** | **深层25个，19通过6失败(76%)** |

---

*本文档由 Claude Code 维护，供下一次会话快速恢复上下文。*
