# 深层交互用例步骤优化需求文档

> **文档版本**: v1.0
> **创建日期**: 2026-07-22
> **文档状态**: 初稿待评审
> **负责人**: czj

---

## 一、背景

### 1.1 问题描述

当前 `platform-auto-test` 平台中，管理看板、运维管理、数据分析三个模块的 25 个深层交互用例执行时存在以下问题：

1. **canvas 等待超时**：管理看板相关用例执行时，`wait_for_selector("canvas", timeout=15000)` 经常超时失败
2. **重复登录**：`build_base_steps()` 包含完整登录步骤（order 1-8），但用例配置 `auto_login=True`，导致执行器先自动登录，再执行步骤中的登录操作，造成重复登录和状态混乱
3. **选择器不够健壮**：部分选择器（如 `.el-select:first-child .el-input`、`.el-select-dropdown__item:first-child`）过于通用，可能匹配到错误元素
4. **导航后缺少充分等待**：点击菜单后仅 `wait_for_selector("body")`，未等待页面实际内容加载完成

### 1.2 根因分析

通过代码审查和执行日志分析，发现以下根因：

| # | 问题 | 根因 | 影响范围 | 严重程度 |
|---|------|------|---------|---------|
| 1 | canvas 等待超时 | canvas 元素可能在 iframe 中渲染，`_do_wait` 虽支持 iframe 回退但超时时间 15s 可能不够；部分页面 canvas 延迟渲染 | 管理看板 6 个用例、数据分析 7 个用例 | ★★★★★ |
| 2 | 重复登录 | `build_base_steps()` 硬编码了 8 步登录流程，但 `auto_login=True` 时执行器已自动登录 | 全部 25 个深层用例 | ★★★★★ |
| 3 | 选择器不精确 | `.el-select:first-child` 等选择器依赖 DOM 顺序，页面结构变化即失效 | 涉及筛选器操作的 8 个用例 | ★★★★☆ |
| 4 | 导航等待不足 | 点击菜单后仅 `wait body`，未等 networkidle 或目标元素 | 全部 25 个深层用例 | ★★★☆☆ |
| 5 | 步骤 order 冲突 | `build_base_steps()` 返回 order 1-8，`build_navigate_to_menu_steps()` 从 order 10 开始，中间有 gap 且与 auto_login 步骤冲突 | 全部 25 个深层用例 | ★★☆☆☆ |

### 1.3 关键发现

1. **`build_base_steps()` 是冗余的**：当 `auto_login=True` 时，执行器 `do_login()` 方法已完整处理登录流程（包括协议弹窗确认），步骤中不应再包含登录步骤
2. **canvas 超时可能是 iframe 问题**：被测系统部分页面使用 iframe 嵌入，canvas 可能在 iframe 内渲染，需要先定位 iframe 再等待 canvas
3. **`_do_wait` 已支持 iframe 回退**：执行器的 `_do_wait` 方法已实现 iframe 遍历回退，但 15s 超时对于 iframe 内的 canvas 可能不够

---

## 二、需求内容

### 2.1 目标

优化深层交互用例的步骤定义，解决 canvas 等待超时和重复登录问题，使 25 个深层用例的执行通过率从当前约 30% 提升到 80% 以上。

### 2.2 功能需求

#### 2.2.1 移除冗余登录步骤

**现状**：`build_base_steps()` 包含 8 步登录流程，与 `auto_login=True` 冲突。

**需求**：
- 删除 `build_base_steps()` 函数，所有深层用例不再包含登录步骤
- 用例步骤从"导航到目标页面"开始（即原 `build_navigate_to_menu_steps` 的内容）
- 保持 `auto_login: True` 配置不变，由执行器自动处理登录
- 步骤 order 从 1 开始重新编号

#### 2.2.2 优化 canvas 等待策略

**现状**：`wait_for_selector("canvas", timeout=15000)` 单一等待，超时即失败。

**需求**：
- 增加 canvas 等待超时时间至 30s（iframe 内渲染更慢）
- 增加"等待页面加载"的前置步骤：先 `wait networkidle`，再等待 canvas
- 对于可能无 canvas 的页面（如运维数据 iframe 空白页），使用更宽松的断言（`element_exists` 替代 `element_count_min`）
- 增加"等待页面动画完成"的延时步骤（`wait_for_timeout 2000ms`）

#### 2.2.3 优化导航等待策略

**现状**：点击菜单后仅 `wait_for_selector("body")`，等待不充分。

**需求**：
- 点击菜单后增加 `wait_for_load_state("networkidle")` 等待
- 替换 `wait body` 为等待目标页面特征元素（如 canvas、.el-table、.el-select 等）
- 增加导航后 1-2s 延时，应对页面动画

#### 2.2.4 优化选择器精确度

**现状**：部分选择器过于通用。

**需求**：
- 筛选器选择器增加上下文限定（如 `.filter-bar .el-select` 替代 `.el-select`）
- 下拉选项选择器增加可见性限定（如 `.el-select-dropdown:visible .el-select-dropdown__item:first-child`）
- 为关键元素增加多选器回退链（利用执行器已有的 `_resolve_selectors` 机制）

#### 2.2.5 统一用例步骤模板

**现状**：每个用例独立构建步骤，模板不统一。

**需求**：
- 建立统一的深层用例步骤模板：
  1. 导航到目标菜单
  2. 等待页面加载（networkidle + 特征元素）
  3. 执行交互操作
  4. 验证结果
- 模板函数支持参数化（菜单名、等待元素、交互步骤、断言步骤）

### 2.3 非功能需求

- **向后兼容**：修改后的用例步骤格式与现有执行器兼容，无需修改执行器代码
- **执行效率**：优化后单用例执行时间不显著增加（允许增加 5-10s 等待时间以换取稳定性）
- **可维护性**：步骤模板化，后续新增用例可复用模板函数

---

## 三、影响范围

### 3.1 受影响文件

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `backend/scripts/create_deep_interaction_cases_v2.py` | 修改 | 重写步骤构建逻辑，删除 `build_base_steps()`，优化模板 |
| `backend/data/test_platform.db` | 数据 | 需更新数据库中 25 个深层用例的 steps 数据 |

### 3.2 不受影响

- 执行器代码（`playwright_executor.py`）— 无需修改
- 前端代码 — 无需修改
- 其他模块用例（会议管理 50 个、登录模块 5 个）— 不受影响

---

## 四、验收标准

| 验收项 | 标准 |
|-------|------|
| 登录步骤移除 | 深层用例步骤中不包含任何登录相关步骤，auto_login=True 正常工作 |
| canvas 等待优化 | 管理看板用例 canvas 等待不再超时（超时时间 ≥ 30s） |
| 导航等待优化 | 点击菜单后等待 networkidle + 特征元素，页面加载完成后再操作 |
| 选择器精确度 | 筛选器选择器增加上下文限定，不再误匹配 |
| 执行通过率 | 25 个深层用例执行通过率 ≥ 80%（允许因被测系统数据缺失导致的断言失败） |
| 步骤模板化 | 新增用例可复用模板函数，步骤 order 从 1 开始连续编号 |

---

*本文档遵循项目 PRD 规范，修改需求时请同步更新。*
