# app-ui-test-platform

**Repository Path**: aiagentdemo/app-ui-test-platform

## Basic Information

- **Project Name**: app-ui-test-platform
- **Description**: 基于 [agent-device](https://github.com/callstack/agent-device) 与鸿蒙官方 **hdc** 的智能 App UI 自动化测试平台，

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# App UI 自动化测试平台

基于 [agent-device](https://github.com/callstack/agent-device) 与鸿蒙官方 **hdc** 的智能 App UI 自动化测试平台，
支持 **Android / iOS / HarmonyOS（鸿蒙）** 三类真机与模拟器。
后端 **Python3 + FastAPI**，前端 **Vue3 + Vite**，大模型使用**火山方舟 ARK**（OpenAI 兼容接口）。

平台把 agent-device 的 `open → snapshot → act → re-snapshot → verify` 工作循环产品化，
让测试人员用自然语言的需求文档或手工用例，即可在真机 / 模拟器上自动执行、失败自愈、并生成分析报告。

> 平台通过「平台注册表 + 可替换设备驱动」把平台能力抽象出来：iOS/Android 由 agent-device 驱动，
> HarmonyOS 由内置的 `hdc + uitest` 驱动（`services/harmony.py`）。两条驱动暴露同名方法，
> 执行引擎、选择器映射、失败自愈、AI 报告等上层逻辑完全复用、与平台无关。

## 五大功能

1. **设备管理**：自动发现连接到本机的真机与模拟器——`agent-device devices` 扫描 Android/iOS，`hdc list targets` 扫描 HarmonyOS——展示平台、型号、系统、序列号、在线状态，并可查看设备上的应用列表。
2. **需求/用例 → 结构化步骤**：粘贴需求文档或手工用例，ARK 大模型结合（可选的）真机页面布局快照（Android/iOS 用 `snapshot -i`，鸿蒙用 `uitest dumpLayout`），生成结构化步骤；执行引擎在运行时把语义选择器（`text=/label=/id=/key=/role=`）实时映射为最新快照的元素引用，规避了引用每次快照失效的问题。
3. **智能优化（失败自愈）**：逐步执行，每步后校验；一旦动作或断言失败，自动截图 + 留存当前页面快照，交给大模型判断原因（文案不符 / 需等待 / 需滚动 / 弹窗遮挡）并给出修正后的步骤，自动重试（次数可配，默认 2 次）。
4. **单用例智能报告**：每条用例执行后，结合逐步命令、报错、自愈记录、截图生成 Markdown 执行分析。
5. **任务级智能分析与测试建议**：一次任务结束后聚合通过/失败/自愈数据，给出质量风险、用例质量、覆盖度、自动化流程建议与优先级行动清单。

## 三平台支持

| 平台 | 标识 | 设备驱动 | 设备发现 | UI 树/快照 | 应用标识 |
| --- | --- | --- | --- | --- | --- |
| Android | `android` | agent-device | `agent-device devices`（ADB） | `snapshot -i` 可访问性树 | 包名 `com.example.app` |
| iOS | `ios` | agent-device | `agent-device devices`（XCUITest） | `snapshot -i` 可访问性树 | Bundle ID |
| HarmonyOS | `harmonyos` | **hdc + uitest（内置）** | `hdc list targets` | `uitest dumpLayout` ArkUI 树 | Bundle Name，可带 `/Ability` |

鸿蒙侧由 `services/harmony.py::HdcDriver` 实现：设备/应用/启停/截图走 hdc（`list targets`、`bm dump -a`、`aa start`、`snapshot_display`），
界面操作走 `uitest`——先 `dumpLayout` 导出 ArkUI 控件树并压成与 agent-device 一致的快照行（`@hN [role] "文本" id=".." key=".."`），
再把命中元素的中心坐标交给 `uitest uiInput click/inputText/swipe/longClick`。因此鸿蒙用例与其它平台用例共用同一套语义选择器、断言与自愈流程。

## 架构

```
app-ui-test-platform/
├── backend/                FastAPI 服务
│   ├── app/
│   │   ├── main.py         入口 / 静态托管 / SPA
│   │   ├── config.py       .env 配置
│   │   ├── database.py     SQLAlchemy（默认 SQLite）
│   │   ├── models.py       设备/需求/用例/步骤/任务/结果
│   │   ├── schemas.py      Pydantic
│   │   ├── routers/        devices / cases(含生成) / tasks / config
│   │   └── services/
│   │       ├── platforms.py   平台注册表（android/ios/harmonyos，驱动选择）
│   │       ├── cli_client.py  agent-device 封装 + get_driver() 驱动工厂
│   │       ├── harmony.py     HarmonyOS 驱动（hdc + uitest）
│   │       ├── snapshot.py    快照解析与选择器→引用（兼容 @eN/@hN、id/key）
│   │       ├── llm_client.py  ARK /chat/completions
│   │       ├── config_store.py 三模型通道配置
│   │       ├── generator.py   需求→结构化用例
│   │       ├── executor.py    执行引擎（按平台选驱动，含自愈循环）
│   │       └── analyzer.py    自愈修复 / 用例报告 / 任务建议
│   ├── requirements.txt
│   └── .env.example
└── frontend/               Vue3 + Vite
    └── src/
        ├── platforms.js    前端平台清单（与后端注册表对应）
        └── pages/          Home / Devices / Generate / Cases / CaseEdit
                            Tasks / TaskDetail / ModelConfig
```

## 前置条件

- Node.js **22.12+**，并全局安装 agent-device：

  ```bash
  npm install -g agent-device@latest
  agent-device doctor        # 自检 iOS/Android 环境
  ```

- Python 3.10+
- Android：开启 USB 调试的真机（`adb devices` 可见）或模拟器；多设备用 serial 区分。
- iOS：Xcode + 模拟器，或配置好的真机。
- HarmonyOS：安装 **DevEco Studio** 或 HarmonyOS Command Line Tools，使 `hdc` 在 PATH 中（也可在 `.env` 用 `HDC_BIN` 指定绝对路径）；真机开启开发者模式与 USB 调试，或启动 DevEco 模拟器。可用以下命令自检：

  ```bash
  hdc list targets                 # 能列出设备序列号即可
  hdc shell uitest dumpLayout      # 前台打开 App 后能导出布局
  ```

  > 说明：agent-device 与 hdc 相互独立，只测其中一类平台时安装对应工具即可；后端在「全部平台」发现时会分别尝试两类驱动，任一缺失不影响另一类。

## 配置大模型

平台的三个智能环节使用**各自独立的大模型通道**，可在前端「🧠 模型配置」页分别设置
（保存在服务端数据库，支持在线连通性测试），也可用 `.env` 作为统一默认值：

| 通道 | 用途 | 建议 |
| --- | --- | --- |
| `case_generation` 需求生成用例模型 | 需求/手工用例 → agent-device 步骤 | 指令遵循、推理能力强 |
| `self_repair` 用例智能优化模型 | 失败步骤自愈改写 | 响应快、稳定 |
| `result_analysis` 执行结果分析模型 | 用例报告 + 任务级测试建议 | 长文本总结能力强 |

```bash
cd backend
cp .env.example .env
```

`.env` 中填入默认方舟 Key 与模型（推理接入点）ID，作为三个通道的初始/回退配置；
同时可配置两类设备驱动的可执行文件：

```ini
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/coding/v3
ARK_API_KEY=你的key
ARK_MODEL=你的模型ID或接入点ID

# iOS / Android 驱动
AGENT_DEVICE_BIN=agent-device
# HarmonyOS 驱动（hdc 不在 PATH 时填绝对路径）
HDC_BIN=hdc
```

启动后在「模型配置」页可为每个通道单独覆盖 base_url / api_key / model / temperature；
API Key 保存后脱敏显示，留空保存不会覆盖已有密钥。

## 启动

### 后端

```bash
cd backend
python3 -m venv .venv && source .venv/bin/activate   # 可选
pip install -r requirements.txt
cp .env.example .env      # 首次，填写 ARK_API_KEY / ARK_MODEL
bash run.sh               # 或 uvicorn app.main:app --port 8066 --reload
```

### 前端（开发模式）

```bash
cd frontend
npm install
npm run dev               # http://localhost:5173 ，已代理 /api 到后端
```

开发代理默认指向 `http://localhost:8000`。若后端运行在其它端口（如 8066），用环境变量覆盖：

```bash
VITE_BACKEND=http://localhost:8066 npm run dev
```

> 注意：修改 `vite.config.js` 或该环境变量后需**重启** `npm run dev` 才会生效。

### 前后端一体化部署

```bash
cd frontend && npm run build      # 产物在 frontend/dist
```

后端启动时若检测到 `frontend/dist`，会自动托管，直接访问 `http://<服务器>:8066` 即可。

## 使用流程

1. 设备连上电脑，打开 **设备管理 → 发现设备**（可在下拉中选 Android / iOS / HarmonyOS，或选「全部平台」同时扫描）。
2. 打开待测 App，进入 **用例生成**：选择平台（含 HarmonyOS）、填写应用标识（鸿蒙可填 Bundle Name 或 `BundleName/EntryAbility`），可先「解析当前页面布局」，再粘贴需求/手工用例，点「生成测试用例」。
3. 在 **测试用例** 中校对 / 微调步骤与断言。
4. 进入 **测试任务**，选设备、勾选用例（列表会按所选设备的平台自动过滤），创建并执行；详情页 2 秒轮询实时进度，可看每步命令、报错、页面快照与截图。
5. 任务结束后查看每条用例的智能分析，以及整任务的测试建议。

## 关于命令与选择器

- Android/iOS 使用 agent-device：新版点击命令为 `press`（兼容坐标与选择器），等待界面稳定用 `--settle`；断言统一为
  `is visible/exists/absent/hidden/editable/text`。执行引擎以本机安装的 CLI 实际行为为准，
  如版本差异导致参数不同，以 `agent-device help` 输出为准并调整 `services/cli_client.py`。
- HarmonyOS 使用内置 hdc 驱动：发现 `hdc list targets`、应用 `bm dump -a`、启动 `aa start -a Ability -b Bundle`、
  截图 `snapshot_display -f`、界面树 `uitest dumpLayout`、操作 `uitest uiInput click/inputText/swipe/longClick/keyEvent`。
  不同 hdc/uitest 版本的子命令与导出 JSON 字段可能有差异，解析层已做多形态兼容，真机首测建议以
  `hdc shell uitest --help` 与实际导出的布局 JSON 为准，必要时调整 `services/harmony.py`。
- 选择器示例：`text="登录"`、`label="邮箱"`、`id="login-btn"`（鸿蒙对应 ArkUI id，Android 也支持全限定 resource-id 后缀）、
  鸿蒙 `key="loginKey"`、`role="button" label="继续"`、`label~="正则"`。
- 自愈次数、CLI/hdc 超时、数据库、端口等均可在 `.env` 调整
  （`MAX_REPAIR_ATTEMPTS`、`CLI_TIMEOUT_MS`、`HDC_BIN`、`HDC_TIMEOUT_MS`、`DATABASE_URL`）。