移动端自动化测试框架 (应用 App + 游戏 App)

当前 Windows 机器部署完成的完整框架：**Appium 3.x 驱动应用 UI** + **Airtest/Poco 驱动 Unity 游戏**，统一 pytest 调度，Allure 出报告。

## 环境状态

| 组件 | 版本 | 说明 |
|------|------|------|
| Node.js | v22.22.2 | Appium 运行时 |
| Java | 1.8.0_251 | Android 工具链 |
| ADB | 37.0.0 | 设备通信 (`D:\Program Files\android-sdk-windows`) |
| Appium | 3.4.2 + uiautomator2@7.5.1 | 已装驱动 |
| Python | 3.10.0 | `C:\Python310\python.exe` |
| airtest | 1.4.3 | 游戏图像识别 |
| pocoui | 1.0.94 | Unity 控件定位 |
| Allure | 2.30.0 | 报告生成 |

> 依赖冲突说明：airtest 固定了 websocket-client 0.48.0，与 selenium 声明的 ≥1.8 冲突。
> 已验证不影响 Appium/selenium 常规使用（仅 BiDi 特性受影响），**不要**单独升级 websocket-client，否则 airtest 会挂。

## 目录结构

```
mobile-automation/
├── base/
│   ├── base_driver.py      # Appium driver 工厂(Android/iOS)
│   ├── base_page.py        # POM 页面基类(定位/手势/截图)
│   ├── base_game.py        # 游戏基类(Poco优先+Airtest兜底)
│   └── device_manager.py   # 设备池(本地adb/STF农场)
├── pages/                  # 页面对象(每页一个类)
│   └── login_page.py       # 登录页示例(改定位器即可用)
├── testcase/
│   ├── app/                # 应用App用例
│   │   └── test_login.py   # 登录冒烟示例
│   └── game/               # 游戏App用例
│       └── test_game_smoke.py
├── data/accounts.yaml      # 测试账号池
├── config/config.yaml      # ★ 唯一需要改的配置文件
├── utils/                  # 日志/钉钉飞书通知
├── conftest.py             # fixtures: driver/game/失败自动截图
├── pytest.ini              # 标记(p0/p1/p2, app/game)与默认参数
├── start_appium.bat        # 一键启动 Appium Server
├── run_smoke.bat           # 一键跑冒烟+开报告
└── verify_env.py           # 环境自检
```

## 快速开始

### 1. 环境自检

```bash
cd mobile-automation
python verify_env.py
```

### 2. 修改配置 (config/config.yaml)

```yaml
app:
  android:
    app_package: "你的应用包名"        # adb shell dumpsys window | grep mCurrentFocus
    app_activity: ".MainActivity"
game:
  android:
    app_package: "你的游戏包名"
```

### 3. 连接手机 → 跑冒烟

```bash
# 手机开启USB调试并连接, 确认: adb devices
start_appium.bat          # 窗口1: 启动Appium
run_smoke.bat             # 窗口2: 跑P0用例并打开报告
```

### 4. 常用命令

```bash
python -m pytest testcase/app -m p0 -v            # 仅应用P0
python -m pytest testcase/game -m p0 -v           # 仅游戏P0
python -m pytest -m "p0 or p1" -n 2               # 2设备并行(xdist)
python -m pytest --device=serial123 testcase/app  # 指定设备
allure serve reports/allure-results               # 随时看报告
```

## 用例分级与触发策略

| 级别 | 含义 | 触发时机 |
|------|------|---------|
| `@pytest.mark.p0` | 冒烟(最稳定) | PR 提交 |
| `@pytest.mark.p1` | 核心回归 | 每日定时 |
| `@pytest.mark.p2` | 全量 | 发版前 |

## 游戏用例前置条件

1. **Poco 路线(推荐)**：游戏开发集成 pocoui Unity SDK，即可用 `game.poco_click("Canvas/BtnXxx")` 精准定位
2. **图像路线(兜底)**：用 AirtestIDE 截取模板图放入 `airtest_images/`，用 `game.img_touch("xx.png")`

## 待部署项 (Phase 3+, 需要额外环境)

- **STF 设备农场**：需安装 Docker Desktop，装好后将 `config.yaml → devices.mode` 改为 `stf` 并填 token
- **iOS 真机**：需要 macOS + Xcode，Windows 上只能覆盖 Android
- **CI/CD**：Jenkins/GitLab CI Runner 接入后，pipeline 末尾调用 `utils/notification.notify_result()` 推钉钉/飞书

## 常见问题

| 问题 | 解决 |
|------|------|
| `无可用设备` | `adb devices` 确认授权；手机装驱动；换USB线 |
| 启动App失败 | 检查 config.yaml 包名/Activity；`adb shell dumpsys window \| grep mCurrentFocus` 获取真实值 |
| Poco 连不上 | 游戏未接 SDK 或未启动；先跑纯图像用例验证 |
| 图像匹配失败 | 换截图(去掉特效帧)、降低分辨率差异、AirtestIDE 里调阈值 |
| element not found | 定位器优先 aid > id > text > xpath，避免深层级 xpath |