AI驱动 + agent-device :重塑移动端UI自动化测试的全新范式

前言

上一篇文章，我们分享了基于 Claude Code + Playwright CLI 实现 Web 端 UI 自动化测试的方案。核心思路是"AI 做一次学习，脚本做重复执行"，用双层引擎把 Token 消耗降到最低。

这次，我们把目光转向移动端。很多测试团队的实际业务场景是：用例写在 XMind 或 Markdown 里，需要真机或模拟器上跑 Android App，手工点一遍又一遍，效率低、容易漏。

围绕这个痛点，我们基于 Claude Code + agent-device  做了一套移动端 UI 测试自动执行方案。方案继承了 Web 端的核心理念，同时针对移动端的特殊性（ADB 连接、中文输入、系统弹窗等）做了大量适配。

一、整体架构：用例 → Skill → 设备操作

整个方案的架构和 Web 端一脉相承：

用例层 — 测试用例放在 Markdown 文件里，用自然语言写操作步骤和预期结果。支持 XMind 打星标一键导出为 Markdown 用例。

调度层 — 一个叫 app-run-test-suite 的 Skill（Claude Code 自定义指令），负责解析用例、调度执行、生成报告。支持单条跑、批量跑、XMind 导入后自动跑。

执行层 — 核心引擎。通过 agent-device 驱动 Android 设备，LLM 逐步操作：每步先截图分析页面 → 找到目标元素 → 执行操作 → 验证结果。

二、agent-device ：移动端操控底座

底层设备驱动我们选的是 agent-device，一个专门为 AI Agent 设计的 Android 设备操控工具。主要看重几点：

• 语义定位器（find） — 不用写 XPath 或 resource-id，直接用自然语言找元素：find text "登录" click、find label "用户名" fill "admin"
• 快照机制 — snapshot -i 获取当前屏幕所有可交互元素，带 @eN 引用，AI 看一眼就知道页面上有什么
• 断言验证（is） — is visible 'text="登录成功"' 验证元素状态，断言失败直接返回非零退出码
• 全操作覆盖 — 点击、输入、滚动、长按、滑动、截图、系统弹窗处理、剪贴板操作……手工测试能做的它都能做

安装一行命令：

npm install -g agent-device

三、执行流程：五步闭环

整个执行流程分为五步，每一步都有明确的输入输出：

第一步：用例解析与准备

支持三种模式：

• 单条执行：传入具体用例文件，只跑这一条
• 批量执行：传入用例目录，读取用例列表后逐条跑
• XMind 导入：无参数时自动检测 .xmind 文件，解析生成用例后再执行（如图有带有⭐的用例）

解析完成后，系统会显示执行计划，标注哪些用例有之前执行成功的精简步骤（_refined.md），优先使用精简版本。

第二步：环境检查与启动

这一步确保设备和应用都就绪：

1. 检查 agent-device 是否已安装
2. 启动 ADB 守护进程（减少 Windows 下弹窗干扰）
3. 连接 ADB 设备（真机 USB 或模拟器 adb connect 127.0.0.1:7555）
4. 关闭系统动画（关键！Android UI 动画会导致快照超时）
5. 关闭残留会话，启动目标应用

环境检查通过后显示就绪信息，包含 agent-device 版本、设备序列号、应用包名等，一目了然。

第三步：LLM 逐步执行（核心）

这是整个方案最复杂的部分。每条用例的执行流程：

1. 快照分析 — snapshot -i 获取当前屏幕交互元素
2. 智能元素定位 — 根据"智能引用解析规则"分析快照，找到实际要操作的元素
3. 执行操作 — 用 find 语义定位器或 @eN 引用操作元素
4. 验证预期结果 — 用 is 断言命令验证页面状态
5. 持久化结果 — 写入 JSON 结果文件 + 生成精简步骤文件

其中，"智能引用解析规则"是一个非常关键的设计。举个最常见的例子：

页面上的输入框通常有一个标签（如"用户名"）紧挨着一个输入框。快照里长这样：

@e24 [group] "用户名"@e25 [text-field] "" [editable]

AI 看到"用户名"标签后，知道要操作的是紧邻的 @e25 这个 text-field，而不是标签本身。这个规则覆盖了标签+输入框、标签+按钮、标签+开关、标签+下拉框等几乎所有常见 UI 组合模式。

第四步：生成 HTML 报告

所有用例跑完后，调用报告脚本合并所有 JSON 结果：

python generate_html_report.py --merge "reports" --save-json

生成的 HTML 报告截图内嵌（base64），不依赖外部资源，打开就能看。每条用例的每步操作截图、预期结果和实际结果对比都一目了然。

第五步：输出控制台总结

跑完直接在终端看到结果：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  测试执行完毕━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  总计: 5 条  通过: 3 条  失败: 1 条  错误: 1 条  通过率: 60.0%  总耗时: 5m 12s━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  HTML报告: reports/test-report-2026-05-18.html━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

四、快照缓存策略：减少冗余操作

移动端快照（snapshot -i）是 IO 密集操作，每步都执行会拖慢速度。方案设计了"快照缓存策略"：

核心原则：只有纯文本输入（fill/type）和收起键盘后可以复用缓存，其他所有操作后都重新快照。

举个例子：

步骤1：snapshot -i（首次获取缓存）步骤2：fill 姓名 "张三" → 缓存仍有效步骤3：fill 电话 "13800138000" → 缓存仍有效（复用）步骤4：fill 地址 "北京市" → 缓存仍有效（复用）步骤5：click "提交" → 缓存失效（点击操作改变了页面）步骤6：snapshot -i（重新获取）→ 新缓存

一个表单页面，6 步只需要 2 次快照，而不是 6 次。

五、移动端特殊处理

移动端测试和 Web 端有不少差异，方案做了针对性适配：

中文输入问题 — Android 上 fill 和 type 输入中文可能报 NullPointerException。替代方案：如果目标文本在列表中可见，直接 find text "中文" click 选中；否则通过 ADB clipboard 设置剪贴板再粘贴。

系统弹窗处理 — 权限弹窗、系统对话框等，用 agent-device alert get 查看、alert accept 接受、alert dismiss 拒绝，不用手动处理。

智能等待 — 不盲目 sleep。页面跳转后用 find "目标文本" wait 5000 等待元素出现，比固定 sleep 更可靠也更快。

分级重读策略 — 批量执行时，每 5 条用例重读一次 Skill 指令文件，遇到异常也重读，防止长期任务中 AI "忘记"执行规范。

15 分钟超时熔断 — 单条用例执行超过 15 分钟自动终止，标记为失败，继续跑下一条。实际测试中，正常用例一般 1-3 分钟就能跑完，15 分钟基本意味着卡死了（比如页面白屏、弹窗阻塞、网络异常等），这时候及时止损比硬等更合理。每条用例的耗时都会精确记录（Unix 时间戳计算，不使用估算值），写进 JSON 结果文件里。

截图策略 — 不在每一步都截图，只在验证预期结果时截图（作为证据）和步骤失败时截图（用于排查）。普通操作步骤不截图，减少 IO 开销。

六、异常处理：8 种常见问题都有预案

实际跑设备测试，总会遇到各种意外。方案对 8 种常见异常都做了明确处理策略：

1. 用例文件不存在 → 跳过，标记 ERROR
2. 用例格式错误 → 跳过，标记 ERROR
3. agent-device 命令失败 → 记录错误，继续后续步骤
4. 页面加载超时 → sleep 5 后重试一次，仍失败则 FAIL
5. 设备无响应 → 检查 ADB 连接状态，尝试重连恢复
6. UI 快照超时 → 确认已关闭系统动画，sleep 2 后重试
7. 中文输入失败 → 回退到 ADB clipboard 方案
8. find 定位器失效 → 立即重新快照分析屏幕结构

核心原则：某条用例失败不影响后续用例执行，每条用例的结果独立持久化。

七、精简步骤（_refined.md）：越跑越聪明

和 Web 端方案类似，移动端也设计了"精简步骤"机制：

首次执行：AI 逐步摸索，快照分析、定位元素、执行操作，同时记录成功路径。

执行成功后：自动生成 _refined.md 文件，只记录"操作意图"（做什么），不记录定位方式（怎么找元素）。比如：

### 步骤 1：打开应用### 步骤 2：输入账号 15800336655### 步骤 3：输入密码 abc123### 步骤 4：勾选"已阅读并同意"### 步骤 5：点击登录

下次执行同一条用例：如果 _refined.md 存在，优先使用它作为执行参考。AI 不需要重新摸索，直接按步骤执行。

失败不覆盖：如果某次执行失败，不会覆盖之前成功的精简步骤。已有的 _refined.md 保持不动。

八、总结与展望

本方案基于 Claude Code Skill 机制 + agent-device，实现了从测试用例（Markdown/XMind）到 Android 设备自动化执行的完整闭环。核心亮点包括：自然语言用例驱动、语义定位器操作设备、智能引用解析、快照缓存优化、精简步骤自我进化、HTML 可视化报告。

和之前 Web 端方案搭配使用，基本覆盖了 Web + App 双端的 UI 自动化测试需求。

这个方案还有几个方向可以继续深入：

1. iOS 支持 — 目前只覆盖了 Android 端，下版本计划扩展到 iOS
2. 用例生成与执行彻底串联 — AI 生成用例 → 自动执行 → 自动出报告，整条链路零人工干预
3. 设备农场 — 多设备并行执行，进一步缩短回归测试时间