# 智能测试执行器使用指南

## 🎯 功能概述

智能测试执行器让 Cursor AI 能够：
1. **自动规划执行** - 解析自然语言测试用例，自动规划执行步骤
2. **自动验证成功** - 每一步操作后自动验证是否成功（通过页面元素变化）
3. **自动解决问题** - 遇到问题自动分析并重试
4. **自动截图分析** - 找不到元素时自动截图并分析
5. **智能判断成功** - 通过页面元素出现/消失判断操作是否成功

## 🚀 快速开始

### 方式1：通过 MCP 工具（推荐）

直接在 Cursor 中告诉 AI：

```
帮我执行这个测试用例：
打开 com.im30.mind
点击底部云文档
点击我的空间
点击蓝色加号
点击云文档（新）
等待3秒
点击右上角三个点图标
弹出的弹窗内点击删除
之后会再有一个弹窗，点击删除
```

AI 会自动调用 `mobile_execute_test_case` 工具，然后：
- 解析测试用例
- 自动执行每一步
- 每一步后验证是否成功
- 失败时自动重试或截图分析

### 方式2：直接使用 Python 脚本

```python
import asyncio
from mobile_mcp.core.ai.smart_test_executor import SmartTestExecutor

async def main():
    executor = SmartTestExecutor()
    
    test_case = """
打开 com.im30.mind
点击底部云文档
点击我的空间
点击蓝色加号
点击云文档（新）
等待3秒
点击右上角三个点图标
弹出的弹窗内点击删除
之后会再有一个弹窗，点击删除
"""
    
    result = await executor.execute_test_case(test_case)
    print(f"执行完成：{result['success_count']}/{result['total_steps']} 成功")

if __name__ == "__main__":
    asyncio.run(main())
```

## ✨ 核心特性

### 1. 自动验证操作成功

每次点击后，执行器会：
- 等待页面响应（0.5秒）
- 获取新的页面快照
- 对比页面变化
- 检查期望元素是否出现
- 检查不期望元素是否消失

**示例：**
```python
# 点击"云文档"后，自动检查是否出现"我的空间"等元素
click_result = await executor.execute_click_with_verification(
    "底部云文档",
    expected_after=["云文档", "我的空间"]
)
```

### 2. 自动重试机制

如果操作失败，执行器会：
- 自动重试（默认最多2次）
- 每次重试前等待1秒
- 记录每次尝试的结果

### 3. 自动截图分析

如果定位失败，执行器会：
- 自动截图
- 保存截图路径
- 返回截图信息供 Cursor AI 分析

### 4. 智能推断期望变化

执行器会根据操作描述自动推断期望的页面变化：

- 点击"底部云文档" → 期望出现"我的空间"
- 点击"加号" → 期望出现"云文档"、"在线表格"等选项
- 点击"删除" → 期望"删除"按钮消失

## 📋 测试用例格式

### 基本格式

```
操作1描述
操作2描述
操作3描述
...
```

### 支持的操作类型

1. **打开应用**
   ```
   打开 com.im30.mind
   启动 com.im30.mind
   ```

2. **点击元素**
   ```
   点击底部云文档
   点击我的空间
   点击蓝色加号
   ```

3. **输入文本**
   ```
   输入用户名为 admin
   输入密码为 123456
   ```

4. **等待**
   ```
   等待3秒
   等待5秒
   ```

5. **验证/断言**
   ```
   验证页面包含"成功"
   检查是否出现"欢迎"
   ```

## 🔍 执行流程

```
1. 解析测试用例
   ↓
2. 执行步骤1
   ↓
3. 验证步骤1是否成功
   ├─ 成功 → 继续下一步
   └─ 失败 → 重试或截图分析
   ↓
4. 执行步骤2
   ↓
5. 验证步骤2是否成功
   ...
   ↓
6. 生成执行报告
```

## 📊 执行报告

执行完成后会返回详细的执行报告：

```json
{
  "total_steps": 9,
  "success_count": 8,
  "fail_count": 1,
  "success_rate": "88.9%",
  "results": [
    {
      "step_num": 1,
      "action": "launch_app",
      "description": "打开 com.im30.mind",
      "success": true,
      "details": {...}
    },
    ...
  ]
}
```

## 🎨 高级用法

### 自定义验证逻辑

```python
# 自定义期望的元素变化
click_result = await executor.execute_click_with_verification(
    "删除按钮",
    expected_after=["确认删除"],  # 期望出现"确认删除"
    unexpected_after=["删除按钮"],  # 期望"删除按钮"消失
    max_retries=3  # 最多重试3次
)
```

### 手动验证页面变化

```python
# 手动验证页面是否包含特定元素
verification = await executor.verify_page_change(
    expected_elements=["我的空间", "云文档"],
    unexpected_elements=["加载中"],
    min_wait=1.0  # 最小等待1秒
)

if verification['success']:
    print("验证成功")
else:
    print(f"缺少元素: {verification['expected_missing']}")
```

## 💡 最佳实践

1. **清晰的测试用例描述**
   - 使用明确的操作描述
   - 避免歧义的元素名称

2. **合理使用等待**
   - 页面加载慢时添加等待
   - 网络请求后等待响应

3. **验证关键步骤**
   - 重要操作后添加验证
   - 确保页面状态正确

4. **查看执行报告**
   - 分析失败原因
   - 优化测试用例

## 🔧 故障排查

### 问题：元素定位失败

**解决方案：**
- 执行器会自动截图
- 查看截图路径
- 使用 `mobile_analyze_screenshot` 分析

### 问题：点击后页面未变化

**解决方案：**
- 检查元素是否正确
- 增加等待时间
- 查看执行日志

### 问题：验证失败

**解决方案：**
- 检查期望元素是否正确
- 查看页面快照
- 调整验证逻辑

## 🎉 总结

智能测试执行器让测试自动化变得简单：
- ✅ **只需描述测试用例** - 不需要写代码
- ✅ **自动执行和验证** - AI 自动处理
- ✅ **自动解决问题** - 失败时自动重试
- ✅ **自动截图分析** - 找不到元素时自动截图

**这就是 Cursor AI + MCP 的强大之处！** 🚀

