# PRD需求文档 - 登录模块测试用例优化

## 一、需求背景

### 1.1 问题描述
登录模块的测试用例在执行过程中出现超时失败问题，即使实际登录成功，测试结果仍显示失败。

### 1.2 问题影响
- 测试结果不准确，误报失败
- 无法真实反映登录功能的实际状态
- 影响测试平台的可信度和使用体验
- 浪费调试时间和资源

### 1.3 现状分析
**失败的测试步骤：**
- 步骤8：验证登录成功（断言URL包含"platform"）- 超时失败

**根本原因：**
1. **断言时机不当**：URL断言是立即检查，不等待页面跳转完成
2. **超时时间不足**：页面跳转需要时间，默认30秒不够
3. **等待策略问题**：等待`networkidle`过于严格，页面未完全加载就超时
4. **元素选择器不精确**：部分选择器在实际页面上匹配不到元素

---

## 二、需求目标

### 2.1 总体目标
优化登录模块测试用例，确保测试结果准确反映实际功能状态，提高测试稳定性。

### 2.2 具体目标

| 目标项 | 当前状态 | 目标状态 | 优先级 |
|--------|---------|----------|--------|
| 测试通过率 | 0% | ≥90% | 高 |
| 超时失败率 | 100% | 0% | 高 |
| 用例执行时间 | 30-50秒 | 15-25秒 | 中 |
| 误报率 | 高 | 低 | 高 |

---

## 三、需求详情

### 3.1 功能需求

#### FR-1：优化超时配置
**需求描述：** 增加测试用例的超时时间，并支持动态配置

**详细说明：**
- 默认超时从30秒增加到60秒
- 在config中支持自定义超时时间
- 不同步骤可以有不同的超时设置

**验收标准：**
- ✅ 页面导航步骤超时设置为60秒
- ✅ 等待元素步骤超时可自定义（默认10秒）
- ✅ 断言步骤不设置超时，立即执行

#### FR-2：优化等待策略
**需求描述：** 使用更合理的等待策略替代`networkidle`

**详细说明：**
- 页面导航使用`domcontentloaded`替代`networkidle`
- 新增显式等待步骤，等待关键元素出现
- 删除不可靠的URL断言，改用元素等待

**验收标准：**
- ✅ 导航步骤不等待完全加载，只等待DOM就绪
- ✅ 后续步骤等待关键元素（如登录按钮、页面标题）
- ✅ 等待时间充足（10秒）

#### FR-3：优化元素选择器
**需求描述：** 使用更通用和稳定的选择器

**详细说明：**
- 避免使用`:nth-of-type`等不稳定选择器
- 使用属性选择器：`input[type='text']`
- 使用文本选择器：`text=登录`
- 添加选择器降级策略

**验收标准：**
- ✅ 选择器在多种场景下都能匹配
- ✅ 不依赖特定的DOM结构顺序
- ✅ 支持Element Plus等UI框架生成的类名

#### FR-4：关闭auto_login
**需求描述：** 登录测试不应依赖自动登录功能

**详细说明：**
- 登录功能测试自己控制登录流程
- auto_login会干扰登录测试的步骤执行
- 在config中设置`auto_login: false`

**验收标准：**
- ✅ 所有登录用例的config中auto_login=false
- ✅ 测试步骤完整执行，不被auto_login跳过

---

### 3.2 非功能需求

#### NFR-1：可维护性
- 用例步骤清晰，注释完整
- 参数配置化，易于修改
- 选择器可维护，有注释说明

#### NFR-2：可扩展性
- 支持添加新的测试场景
- 支持参数化测试
- 支持数据驱动

#### NFR-3：稳定性
- 连续执行3次，通过率≥90%
- 不同网络环境下执行稳定
- 不因页面加载慢而误报失败

---

## 四、技术方案

### 4.1 断言优化方案

**问题代码：**
```python
# 步骤8 - 原来的URL断言
{"action": "assert", "params": {"type": "url"}, "expected": "platform"}
```

**优化方案：**
```python
# 步骤7 - 改用元素等待
{"action": "wait", "params": {"selector": "text=统一管理平台", "timeout": 10000}}
```

**原因：**
- URL断言立即检查，不等待
- 元素等待会持续检查直到超时或成功
- "统一管理平台"文本在登录后的页面会出现

### 4.2 选择器优化方案

**问题选择器：**
```python
"selector": "input[placeholder*='用户']"  # 可能匹配不到
"selector": "input[type='text']:nth-of-type(3)"  # 依赖顺序
```

**优化选择器：**
```python
"selector": "input[type='text']"  # 通用选择器
"selector": "input[type='password']"  # 明确类型
"selector": "button"  # 简单选择器
```

**降级策略：**
- 主选择器失败后尝试备选选择器
- 先尝试精确选择器，再尝试通用选择器

### 4.3 超时配置方案

**config配置：**
```json
{
  "timeout": 60000,  // 全局超时60秒
  "retry": 0,       // 不重试
  "screenshot": true,  // 自动截图
  "auto_login": false  // 关闭自动登录
}
```

**步骤级超时：**
```json
{"params": {"selector": "input", "timeout": 10000}}  // 等待元素10秒
```

---

## 五、实施计划

### 5.1 第一阶段：用例优化（预计2小时）

**任务列表：**
1. 修改"登录功能-正常登录"用例（高优先级）
   - 删除URL断言步骤
   - 改用元素等待验证登录成功
   - 关闭auto_login
   
2. 修改"登录功能-页面访问验证"用例（高优先级）
   - 增加显式等待步骤
   - 优化选择器
   
3. 修改其他登录用例（中优先级）
   - 统一超时配置
   - 优化选择器

### 5.2 第二阶段：代码优化（预计1小时）

**任务列表：**
1. 修改playwright_executor.py
   - 改进断言逻辑，支持等待
   - 添加选择器降级策略
   
2. 测试验证
   - 执行所有登录用例
   - 验证通过率≥90%

### 5.3 第三阶段：文档输出（预计0.5小时）

**输出文档：**
1. 需求文档（本文档）
2. 执行计划文档
3. 测试报告

---

## 六、验收标准

### 6.1 功能验收

| 验收项 | 验收标准 | 验收方式 |
|--------|---------|----------|
| 用例执行 | 连续执行3次，通过率≥90% | 自动化测试 |
| 超时问题 | 不再出现30秒超时失败 | 查看执行日志 |
| 选择器匹配 | 所有选择器都能正确匹配元素 | 手动验证 |
| auto_login | 所有登录用例不依赖auto_login | 查看config配置 |

### 6.2 文档验收

- ✅ 需求文档完整，包含问题分析、解决方案
- ✅ 执行计划详细，任务分解合理
- ✅ 测试报告真实反映优化效果

---

## 七、风险评估

| 风险项 | 影响程度 | 概率 | 应对措施 |
|--------|---------|------|----------|
| 页面元素变化导致选择器失效 | 高 | 中 | 使用多种选择器策略 |
| 网络慢导致页面加载慢 | 中 | 中 | 增加超时时间 |
| Element Plus版本更新 | 低 | 低 | 选择器不依赖特定类名 |

---

## 八、附录

### 8.1 相关文件
- `backend/app/executors/playwright_executor.py` - 执行器实现
- `backend/app/services/execution_service.py` - 执行服务
- `backend/scripts/recreate_login_cases.py` - 用例创建脚本

### 8.2 参考资料
- [Playwright等待策略](https://playwright.dev/python/docs/api/class-page#page-goto)
- [Element Plus选择器规范](https://element-plus.org/)

---

**文档版本：** v1.0  
**创建日期：** 2026-07-12  
**创建人：** Claude
