# 执行器准确率优化需求文档

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

---

## 一、背景

### 1.1 问题描述

当前 `platform-auto-test` 平台的测试用例执行准确率低于预期。对比同仓库的 `pc自动化测试`（Playwright 原生 E2E 测试，51 个工作流，通过率 100%），平台在相同目标系统上的执行成功率明显偏低。

### 1.2 根因分析

通过深度对比两套方案的实现源码，发现主要差距在以下维度：

| 维度 | pc自动化测试 | platform-auto-test | 影响程度 |
|------|-------------|-------------------|----------|
| 选择器质量 | 手写多级 CSS 链，唯一性高 | 录制器生成单层 class，易匹配多个 | ★★★★★ |
| 等待策略 | 显式 waitFor(visible) + 500-800ms 延时 | 等待超时后静默继续 | ★★★★☆ |
| 交互健壮性 | force click + 多选器回退 + triple-click 清空 | 简单 click/fill，无回退 | ★★★★☆ |
| 重试粒度 | 单步重试 + 动作特定 recovery | 整用例从第 1 步重来 | ★★★☆☆ |
| 日志反馈 | 每步控制台输出带图标 | logger.debug 级别，默认不可见 | ★★☆☆☆ |

### 1.3 关键发现

代码审查中发现两个关键问题：

1. **SelectorMapper 悬空**：`backend/app/utils/selector_mapper.py` 已定义丰富的多选器回退链，但执行器从未导入使用
2. **WebSocket 回调未接通**：`execution_service.py` 的 `_create_step_callback` 已实现但从未传给 `executor.execute_case()`，导致前端无法实时看到步骤执行

---

## 二、需求内容

### 2.1 目标

提升平台执行器的执行准确率，使其在同等条件下达到与 `pc自动化测试` 接近的通过率（>90%），同时保持平台的"可视化/录制器"定位。

### 2.2 功能需求

#### 2.2.1 多选择器回退机制

**现状**：每个步骤依赖单一 CSS 选择器，无备选方案。

**需求**：
- 执行器支持单个步骤传入多个选择器（`selectors: List[str]`）
- 主选择器失败时自动尝试下一个，全部失败才标记为 failed
- 集成 SelectorMapper 中预定义的丰富选择器链
- 兼容旧格式（仅 `params.selector` 单值）

#### 2.2.2 显式等待策略

**现状**：动作前等待过于简单，缺少延时和状态检查。

**需求**：
- 每个动作前执行 `wait_for_selector(state="visible")` 显式等待
- 每个动作后根据类型增加 300-2000ms 延时（应对页面动画）
- 导航后等待 `networkidle`
- 加载遮罩两阶段等待（先等 visible 再等 hidden）

#### 2.2.3 交互健壮性增强

**现状**：`_do_click` 无 force 参数，`_do_fill` 不清空输入，`_do_assert` 无重试。

**需求**：
- Click 支持 `force=True` 参数，绕过覆盖层
- Fill 执行 triple-click → Ctrl+A → Delete → fill 清空模式
- 输入框填充前等待元素可见
- 断言验证支持重试（如列表数量断言等待 3 秒后重试）

#### 2.2.4 单步重试机制

**现状**：整用例从头重试，浪费时间和资源。

**需求**：
- 单步执行失败后自动重试（默认 2 次）
- 重试间隔 1 秒
- 配置项 `step_retry_count` 可调
- 整用例重试保留为可选配置（默认禁用）

#### 2.2.5 实时执行反馈

**现状**：WebSocket 步骤回调已实现但未接通。

**需求**：
- 接通 `_create_step_callback` 到 `executor.execute_case()`
- 每步执行完成通过 WebSocket 推送 `step_update` 事件
- 前端 Execution.vue 实时显示步骤执行情况

#### 2.2.6 统一的步骤数据结构

**现状**：Schema / Recorder / Executor 三处步骤表示不一致。

**需求**：
- `StepDefinition` 增加可选字段（向后兼容）：
  - `selectors: List[str]` — 多选择器回退链
  - `page_key: str` — SelectorMapper 页面标识
  - `element_key: str` — 元素标识
  - `force: bool` — 强制点击
  - `wait_after: int` — 自定义操作后延时
- Recorder 统一使用 `StepDefinition` 格式
- 旧数据（仅 `params.selector`）继续有效

### 2.3 非功能需求

- 向后兼容：现有 26 个用例无需修改即可继续执行
- 执行效率：单步重试不显著增加整体执行时间
- 稳定性：Windows 11 + Playwright 同步 API + 线程池仍正常

---

## 三、Why

执行准确率是自动化测试平台的**核心指标**。当前平台虽然有完整的 Web 管理界面、录制器、报告系统，但如果执行准确率不可靠，这些功能的价值将大打折扣。`pc自动化测试` 项目已验证了这些最佳实践在同一个目标系统上的有效性，本需求旨在将这些已证明有效的策略引入平台。

## 四、How to apply

当后续修改执行器逻辑时：
1. 确保新增字段全部 Optional，不影响旧数据
2. 多选择器回退按优先级排序，首个为最优选择器
3. 等待时间以实际页面动画时间为准，不过度延长
4. 日志统一使用图标前缀（✓/⚠/✗/ℹ/⏳）
5. 修改后运行现有 26 个用例回归验证

---

## 五、验收标准

| 验收项 | 标准 |
|-------|------|
| 多选择器回退 | 主选择器失效时，自动切换到备选选择器执行成功 |
| 等待策略 | 页面动画/弹窗后，操作正常执行不报元素不可见 |
| 交互健壮性 | 覆盖层上的元素可通过 force click 点击；输入框先清空再填充 |
| 单步重试 | 某步失败后自动重试 2 次，不重新执行前置步骤 |
| 实时反馈 | 前端 WebSocket 收到每步的 step_update 事件 |
| 向后兼容 | 旧格式 26 个用例无需修改，正常执行 |
| 日志 | 后端控制台输出带图标前缀的步骤执行日志 |