移动端 App 自动化
- Skill 标识
mobile-app-autotest- 所属分类
- 软件测试 / 测试开发
把 App 自动化从零散脚本变成可交接的工程:围绕 Android、iOS 和 WebView,先做环境体检与流程清单,再生成 Screen、Flow 和中文交付摘要,定位与排障都有章可循。
本文目录
- Skill 概览
- 适合谁、用在什么场景
- 需要准备什么、能得到什么
- 核心能力与使用边界
- 实战教程与使用说明
- 一、为什么需要这样一个 Skill?
- 二、这个 Skill 是什么?
- 三、适用场景与输入输出
- 3.1 适用场景
- 3.2 输入
- 3.3 输出(保存在项目根目录)
- 四、核心能力
- 4.1 定位金字塔
- 4.2 质量评分五维度
- 五、如何使用:操作步骤(从 0 跟做)
- 5.0 前置准备
- 5.1 步骤 1–2,环境体检
- 5.2 步骤 3–4,生成测试清单
- 5.3 步骤 5–6,启动 Appium 并生成测试工程
- 5.4 步骤 7–8,自检与中文交付
- 六、输出与保存的约定
- 6.1 JSON 与中文摘要分工
- 七、适合谁用
- 八、Skill 目录结构
- 8.1 可扩展点
- 九、整体架构与数据流
- 9.1 运行面决策
- 9.2 平台与驱动映射
- 十、SKILL.md 设计要点
- 十一、scripts 详细设计
- 11.1 check_mobile_env.sh
- 11.2 scaffold_manifest.py
- 十二、references 索引与契约
- 十三、给测试工程师的几点建议
- 十四、常见问题
- 附录:Cursor 触发语速查
Skill 概览
适合谁、用在什么场景
希望建立或规范 Appium 自动化工程的移动测试工程师。
需要准备什么、能得到什么
- 输入材料:APK、IPA 或云端安装包地址、包名或 bundleId、目标平台及 P0 流程。
- 交付产物:测试 manifest、平台配置、Screen 对象、Flow 用例、截图及中文交付摘要。
核心能力与使用边界
- 核心能力:清单先行、定位分级、分平台配置、质量自评与失败诊断,支持本地及云真机运行面。
- 使用边界:Skill 不自带 Appium Server;实际设备、驱动、签名和运行环境仍需准备与验证。
实战教程与使用说明
本手册面向从零开始学习移动端 App 自动化的软件测试工程师。不要求你先精通 Appium,但建议你具备软件测试基础、会使用终端,并能在 Cursor 中与 AI 协作。
学习路径 先理解为什么 → 再认清 Skill 架构 → 跟着跑通八步交付 → 最后能独立维护和扩展。
预计用时 60–90 分钟。
▲ 图注:从0开始学习的四步路径
▲ 图注:教程总览封面——八步交付、Appium 技术栈与核心产物
一、为什么需要这样一个 Skill?
很多团队的 App 自动化困境,不是「不会写 Appium 脚本」,而是写了不敢长期维护。
UI 小改,定位器成片失效,没人提前预警
用例条数不少,但不知道覆盖了哪些业务流程
Android / iOS 各写一套,风格混乱、交接成本高
混合 App 里 WebView 切不对上下文,失败日志看不懂
本地能跑、真机就挂,云网格配置没人文档化
直接让 AI「帮我写 Appium 测试」,往往只能得到能跑一次的脚本,得不到可复查的测试工程。
mobile-app-autotest 要解决的,是把移动端自动化变成摸清现状 → 选定运行面 → 列清单 → 生成资产 → 自检 → 中文交付 的标准流程,让测试工程师有清晰的事实来源、质量门禁和排障回路。
普通 AI 生成 | mobile-app-autotest |
|---|---|
给几条能跑的 test case | 先出 manifest 清单,再生成 Screen / Flow |
XPath 满天飞,改版就挂 | 定位金字塔,优先 accessibility id |
Android / iOS 混写一套 caps | 分平台 Options + 跨端注解 Screen |
失败靠人工猜 | fault-diagnosis 决策树 + 自动截图 |
不知道环境缺什么 | check_mobile_env.sh 一键体检 |
二、这个 Skill 是什么?
mobile-app-autotest 是安装在 Cursor 里的一个 Skill(工作说明书 + 辅助脚本 + 模板 + 参考文档),路径为 .cursor/skills/mobile-app-autotest/。
它不是一个独立运行的测试框架,而是指导 Cursor Agent 如何为你的 App 项目交付 Appium 自动化资产,并配套 Shell / Python 脚本做环境体检与测试清单生成。
▲ 图注:Skill 三层架构总览
层级 | 组成 | 职责 |
|---|---|---|
协作层 | SKILL.md + Cursor | 定义何时触发、八步怎么推进、完成标准是什么 |
脚本层 | Shell + Python 脚本 | 环境体检、生成测试清单草稿(无第三方依赖) |
产物层 | JSON + 测试代码 + 中文摘要 | 机器可读清单 + 可执行 case + 人可读交付报告 |
默认技术栈 Appium 3.x + UiAutomator2(Android)/ XCUITest(iOS)。默认语言 仓库已有测试栈则跟随,否则 Java + TestNG。默认测试目录 mobile-tests/。
⚠️ 注意:Skill 不包含 Appium Server 安装包。本地执行前仍需 npm i -g appium 并安装 uiautomator2 / xcuitest 驱动。
三、适用场景与输入输出
3.1 适用场景
场景 | 是否适合 | 说明 |
|---|---|---|
项目尚无系统化 App 自动化 | ✅ 非常适合 | 从零搭 Appium 回归基础 |
已有零散 case,想梳理覆盖 | ✅ 适合 | 用 manifest + quality-rubric 量化缺口 |
Android / iOS 双端交付 | ✅ 适合 | 分平台 caps + 跨端 Screen 注解 |
混合 App(原生 + H5) | ✅ 适合 | WebView 上下文切换有专项 reference |
云真机碎片化回归 | ✅ 适合 | runtime-targets 配置 Hub 与 lt:// 包地址 |
需要给产品/领导中文简报 | ✅ 适合 | glossary-zh 交付摘要模板 |
团队已深度绑定 Detox / Maestro | ⚠️ 需审慎 | Skill 基于 Appium,非替代方案 |
纯游戏引擎自定义 UI | ⚠️ 需专项 | 需另行设计定位策略 |
3.2 输入
APK / IPA 路径,或云网格上传后的
lt://包地址包名
appPackage/bundleId目标平台(Android / iOS / 双端)
可选:已有 Appium / WebdriverIO 项目约定(会优先沿用)
可选:要覆盖的 P0 业务流程描述(登录、加购、支付等)
3.3 输出(保存在项目根目录)
文件/目录 | 阶段 | 用途 |
|---|---|---|
| 步骤 4 | Screen / Flow / 风险清单 |
| 步骤 6 | SessionFactory、capabilities |
| 步骤 6 | 页面对象(Screen Object) |
| 步骤 6 | 跨页面业务流程用例 |
| 步骤 6 | 手势、等待、截图工具 |
| 步骤 8 | 失败截图、中文交付摘要 |
四、核心能力
▲ 图注:八步交付闭环与产物对应关系
能力 1,清单先行
用 scaffold_manifest.py 产出 app-test-manifest.json,列 Screen / Flow / 风险,作为后续生成的事实来源。
能力 2,定位金字塔
L1 accessibility id 优先,L5 XPath 仅兜底;禁止 Thread.sleep 与写死坐标。
能力 3,多栈落地
支持 Java / Python / JS / TS;本地模拟器、USB 真机、云真机网格均可配置。
能力 4,质量评分 + 排障
quality-rubric 五维自评;fault-diagnosis 按症状决策树修复。
4.1 定位金字塔
▲ 图注:定位金字塔 L1-L5
L1 accessibility id / content-desc / label — 跨端首选
L2 Android resource-id / iOS name — 平台稳定属性
L3 iOS predicate / class chain — 结构查询
L4 Android UiAutomator — 列表滚动等场景
L5 XPath — 仅兜底,须注释原因
4.2 质量评分五维度
维度 | 权重 | 看什么 |
|---|---|---|
可运行性 | 25 | 起服务即可跑通 P0;无硬编码本机路径 |
定位健壮性 | 25 | P0 无裸 XPath;关键控件有 accessibility / id |
可维护性 | 20 | Screen/Flow 分层;capabilities 集中配置 |
稳定性 | 15 | 无 sleep;失败自动截图;超时合理 |
覆盖透明度 | 15 | 有 manifest;报告标风险 |
满分 100,低于 70 需补全后再交付。
五、如何使用:操作步骤(从 0 跟做)
5.0 前置准备
安装 Node.js、Python 3.8+;本地测 Android 需 JDK + Android SDK;测 iOS 需 macOS + Xcode
确认 Skill 在
.cursor/skills/mobile-app-autotest/准备好 APK / IPA 或云网格账号
5.1 步骤 1–2,环境体检
bash .cursor/skills/mobile-app-autotest/scripts/check_mobile_env.sh
检查点,确认 Node、Appium、uiautomator2 驱动、adb(或 Xcode)为 [OK];若 4723 未监听,后续需先 appium --port 4723。
5.2 步骤 3–4,生成测试清单
python3 .cursor/skills/mobile-app-autotest/scripts/scaffold_manifest.py \
--app-id com.shop.demo \
--platforms android,ios \
--pretty \
--out app-test-manifest.json
检查点,打开 manifest,人工校对 P0 flows 是否与真实业务一致;大规模生成 case 前必须与业务方确认。
{
"appId": "com.shop.demo",
"platforms": ["android", "ios"],
"flows": [{
"id": "guest_checkout",
"name": "访客加购至购物车",
"priority": "P0",
"steps": ["打开目录", "选首件商品", "加入购物车", "校验角标"]
}],
"risks": [{
"item": "优惠券 H5 页",
"reason": "WebView 上下文切换",
"mitigation": "见 hybrid-webview.md"
}]
}
5.3 步骤 5–6,启动 Appium 并生成测试工程
npm i -g appium
appium driver install uiautomator2
appium driver install xcuitest # 仅 macOS + iOS
appium --port 4723
在 Cursor 对话中说:
按 mobile-app-autotest 为包名 com.shop.demo 的 Android App 生成 mobile-tests 工程,
基于 app-test-manifest.json,先覆盖加购 P0 流程,用 Java + TestNG。
public class CheckoutScreen {
@AndroidFindBy(accessibility = "cart_checkout_btn")
@iOSXCUITFindBy(accessibility = "cart_checkout_btn")
WebElement checkoutBtn;
public CheckoutScreen(AppiumDriver driver) {
PageFactory.initElements(
new AppiumFieldDecorator(driver, Duration.ofSeconds(12)), this);
}
public PaymentScreen proceedToPay() {
checkoutBtn.click();
return new PaymentScreen(driver);
}
}
5.4 步骤 7–8,自检与中文交付
按 references/quality-rubric.md 逐项勾选质量门禁;输出中文摘要(模板见 glossary-zh.md),包含:覆盖范围、定位风险、环境缺口、补测建议。
修复循环:失败走 fault-diagnosis 决策树 → 修定位/caps/上下文 → 重跑冒烟 → 刷新摘要。
六、输出与保存的约定
你的App项目/
├── app-test-manifest.json
└── mobile-tests/
├── config/ # SessionFactory、capabilities
├── screens/ # CheckoutScreen 等页面对象
├── flows/ # 跨页面业务流程用例
├── utils/ # 手势、等待、截图
├── fixtures/ # 测试账号与数据
└── reports/ # 失败截图、中文交付摘要
6.1 JSON 与中文摘要分工
类型 | 读者 | 说明 |
|---|---|---|
app-test-manifest.json | 工具链 / Agent | 字段名稳定,便于自动对比覆盖 |
reports/ 中文摘要 | 产品、测试负责人 | 结论、缺口、待确认项 |
screens / flows 代码 | 测试开发 | 可独立运行,应纳入 Git 版本管理 |
⚠️ 安全约定,禁止把生产账号密码写入 case 或 fixtures。未知测试账号写在摘要「待确认」区。
七、适合谁用
推荐使用
测试开发 / SDET,从零搭 Appium 回归
负责 Android / iOS 双端交付的功能测试
需要混合 App(原生 + H5)自动化的同学
在 Cursor 里做 AI 测试工作流的团队
需要云真机碎片化回归、要写中文简报的 Tech Lead
需审慎
团队已深度绑定 Detox / Maestro 且不愿引入 Appium
无 APK/IPA、无模拟器、也不打算用云真机
纯游戏引擎自定义 UI(需专项方案)
期望 Skill 代替 Appium 本体安装与环境运维
八、Skill 目录结构
.cursor/skills/mobile-app-autotest/
├── SKILL.md # 八步工作流与触发词
├── 使用说明.md
├── scripts/
│ ├── check_mobile_env.sh # 环境体检
│ └── scaffold_manifest.py # 清单草稿生成
├── assets/templates/
│ ├── capability.android.json
│ └── capability.ios.json
└── references/
├── delivery-guide.md # 工程脚手架、并行、CI
├── runtime-targets.md # 本地 vs 云
├── platform-android.md
├── platform-ios.md
├── hybrid-webview.md
├── fault-diagnosis.md
├── app-test-manifest-contract.md
├── cross-framework-notes.md
├── glossary-zh.md
├── quality-rubric.md
├── ci-pipeline-snippets.md
└── stacks/
├── java-testng.md
├── python-pytest.md
├── js-wdio.md
└── ts-wdio.md
8.1 可扩展点
扩展需求 | 改哪里 |
|---|---|
换语言栈 |
|
改 POM 风格 | delivery-guide 中 Screen 模式 + stacks 示例 |
增加质量评分规则 |
|
接入 GitHub Actions / GitLab CI |
|
支持 RN / Flutter 定位 |
|
九、整体架构与数据流
9.1 运行面决策
用户线索 | 运行面 | 参考文档 |
|---|---|---|
云厂商 / 真机农场 / LT | 云网格 Hub + lt:// | runtime-targets.md |
模拟器 / USB 真机 / 本机 | 本地 Appium :4723 | SKILL.md |
多品牌多版本碎片化 | 云回归 + 本地冒烟 | runtime-targets.md |
未说明 | 默认本地模拟器冒烟 | — |
9.2 平台与驱动映射
线索词 | 平台 | automationName |
|---|---|---|
APK、Pixel、华为、小米 | Android | UiAutomator2 |
IPA、iPhone、iPad | iOS | XCUITest |
React Native / Flutter | 同上 | 同上;优先 accessibility |
十、SKILL.md 设计要点
用途:定义 Agent 角色、八步交付工作流、定位策略、目录约定与完成定义。
模块 | 设计意图 |
|---|---|
YAML frontmatter | name + description 供 Cursor 发现与触发 |
默认约定表 | 驱动、语言、目录一次说清,避免 Agent 即兴发挥 |
八步交付闭环 | 从现状调研到中文摘要的完整门禁 |
定位金字塔 L1–L5 | 生成代码时的硬性约束 |
质量门禁 checklist | 交付前逐项勾选,不可跳过 |
参考文档索引 | Agent 按需加载 references,避免 SKILL.md 过长 |
十一、scripts 详细设计
11.1 check_mobile_env.sh
检查项 | 通过标准 |
|---|---|
Node.js |
|
Appium CLI |
|
uiautomator2 驱动 | driver list --installed 含 uiautomator2 |
xcuitest 驱动 | macOS 上已安装(iOS 需要) |
adb | 有在线设备或给出 WARN |
Xcode | macOS 上 xcodebuild 可用 |
端口 4723 | 已监听或提示启动 appium |
云凭证 LT_* | 可选;未设置则 WARN |
11.2 scaffold_manifest.py
参数 | 默认值 | 说明 |
|---|---|---|
| com.example.app | 包名 / bundleId |
| android,ios | 逗号分隔平台列表 |
| stdout | 输出路径 |
| — | JSON 缩进格式化 |
输出 JSON 字段契约见 references/app-test-manifest-contract.md:appId、platforms、screens[]、flows[]、risks[]。
十二、references 索引与契约
文件 | 何时加载 |
|---|---|
delivery-guide.md | 生成工程脚手架、并行、设备交互时 |
runtime-targets.md | 配置本地 / 云 Hub、上传 APK/IPA 时 |
platform-android.md | Android 权限、ADB、UiAutomator 技巧 |
platform-ios.md | WDA、生物识别、iOS 专用定位 |
hybrid-webview.md | 混合 App WebView 上下文切换 |
fault-diagnosis.md | 用例失败、元素找不到、会话创建失败 |
app-test-manifest-contract.md | 编写或校验 manifest JSON |
cross-framework-notes.md | RN / Flutter 项目定位策略 |
glossary-zh.md | 撰写中文交付摘要 |
quality-rubric.md | 交付前质量自评 |
ci-pipeline-snippets.md | 接入 GitLab / Jenkins / pre-push 钩子时 |
stacks/*.md | 按语言栈生成用例代码时 |
十三、给测试工程师的几点建议
先清单,后 case。不要跳过 manifest 阶段直接让 AI 堆用例,P0 流程错了后面全偏。
把 accessibility id 当协作项。推动开发为关键控件设置 testID / content-desc。
Android / iOS 分开 caps。禁止混用定位器或 Options 类。
混合 App 测完 H5 必回 NATIVE_APP。否则后续原生步骤静默失败。
失败先走 fault-diagnosis。按症状改一项变量,不要同时改 caps 和定位器。
云/本地 Hub 集中配置。写进 SessionFactory,不要散落在用例里。
摘要给人看,JSON 给工具看。评审会上用中文摘要,脚本对比用 manifest。
十四、常见问题
现象 | 原因 | 处理 |
|---|---|---|
会话创建失败 | Appium 未启动或驱动未装 | 跑 check_mobile_env.sh;appium driver install |
元素找不到 | 定位器错或在 WebView 未切 context | Appium Inspector 重抓;读 hybrid-webview.md |
iOS WDA 超时 | Xcode / 签名问题 | 加大 wdaLaunchTimeout;读 platform-ios.md |
用例间歇失败 | sleep 或动画干扰 | 改显式等待;Android 关动画 |
云真机 lt:// 无效 | 包体未上传或过期 | 重新上传;读 runtime-targets.md |
并行多 Android 会话冲突 | systemPort 重复 | 每会话分配独立 systemPort |
学完本手册后,建议你用一个小型 Demo App 完整跑通环境体检 → 清单 → 生成 mobile-tests → 质量自评,并把中文摘要发给同事做一次评审。
附录:Cursor 触发语速查
按 mobile-app-autotest 为当前 App 做移动端自动化交付
生成 app-test-manifest 和 mobile-tests 工程
用 pytest 写 Android 加购流程 Appium 用例
混合 App WebView 里点 H5 按钮怎么测
移动端测试环境帮我检查一下
配置 XCUITest 真机 capabilities
扫码添加辅导员,发送 Skill 名称,领取源码与配套资料。