从 0 到 1 打造移动端 App 自动化 Skill,架构、流程与实战全解析(附md文件)

学习路径四步

▲ 图注：从0开始学习的四步路径

教程总览

▲ 图注：教程总览封面——八步交付、Appium 技术栈与核心产物

一、为什么需要这样一个 Skill？

很多团队的 App 自动化困境，不是「不会写 Appium 脚本」，而是写了不敢长期维护。

• UI 小改，定位器成片失效，没人提前预警

• 用例条数不少，但不知道覆盖了哪些业务流程

• Android / iOS 各写一套，风格混乱、交接成本高

• 混合 App 里 WebView 切不对上下文，失败日志看不懂

• 本地能跑、真机就挂，云网格配置没人文档化

直接让 AI「帮我写 Appium 测试」，往往只能得到能跑一次的脚本，得不到可复查的测试工程。

二、这个 Skill 是什么？

mobile-app-autotest是安装在 Cursor 里的一个 Skill（工作说明书 + 辅助脚本 + 模板 + 参考文档），路径为 .cursor/skills/mobile-app-autotest/。

它不是一个独立运行的测试框架，而是指导 Cursor Agent 如何为你的 App 项目交付 Appium 自动化资产，并配套 Shell / Python 脚本做环境体检与测试清单生成。

Skill 三层架构

▲ 图注：Skill 三层架构总览

默认技术栈 Appium 3.x + UiAutomator2（Android）/ XCUITest（iOS）。默认语言仓库已有测试栈则跟随，否则 Java + TestNG。默认测试目录mobile-tests/。

三、适用场景与输入输出

3.1 适用场景

3.2 输入

• APK / IPA 路径，或云网格上传后的 lt://包地址

• 包名appPackage / bundleId

• 目标平台（Android / iOS / 双端）

• 可选：已有 Appium / WebdriverIO 项目约定（会优先沿用）

• 可选：要覆盖的 P0 业务流程描述（登录、加购、支付等）

3.3 输出（保存在项目根目录）

四、核心能力

八步交付闭环

▲ 图注：八步交付闭环与产物对应关系

4.1 定位金字塔

定位金字塔

▲ 图注：定位金字塔 L1-L5

1. L1 accessibility id / content-desc / label — 跨端首选

2. L2 Android resource-id / iOS name — 平台稳定属性

3. L3 iOS predicate / class chain — 结构查询

4. L4 Android UiAutomator — 列表滚动等场景

5. L5 XPath — 仅兜底，须注释原因

4.2 质量评分五维度

质量评分五维

满分 100，低于 70 需补全后再交付。

五、如何使用：操作步骤（从 0 跟做）

5.0 前置准备

1. 安装 Node.js、Python 3.8+；本地测 Android 需 JDK + Android SDK；测 iOS 需 macOS + Xcode

2. 确认 Skill 在 .cursor/skills/mobile-app-autotest/

3. 准备好 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 appiumappium driver install uiautomator2appium driver install xcuitest   # 仅 macOS + iOSappium --port 4723

在 Cursor 对话中说：

按 mobile-app-autotest 为包名 com.shop.demo 的 Android App 生成 mobile-tests 工程，基于 app-test-manifest.json，先覆盖加购 P0 流程，用 Java + TestNG。

Screen Object 代码

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/上下文 → 重跑冒烟 → 刷新摘要。

六、输出与保存的约定

mobile-tests 目录

你的App项目/├── app-test-manifest.json└── mobile-tests/    ├── config/              # SessionFactory、capabilities    ├── screens/             # CheckoutScreen 等页面对象    ├── flows/               # 跨页面业务流程用例    ├── utils/               # 手势、等待、截图    ├── fixtures/            # 测试账号与数据    └── reports/             # 失败截图、中文交付摘要

6.1 JSON 与中文摘要分工

七、适合谁用

八、Skill 目录结构

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 可扩展点

九、整体架构与数据流

9.1 运行面决策

9.2 平台与驱动映射

十、SKILL.md 设计要点

用途：定义 Agent 角色、八步交付工作流、定位策略、目录约定与完成定义。

十一、scripts 详细设计

11.1 check_mobile_env.sh

11.2 scaffold_manifest.py

输出 JSON 字段契约见 references/app-test-manifest-contract.md：appId、platforms、screens[]、flows[]、risks[]。

十二、references 索引与契约

十三、给测试工程师的几点建议

1. 先清单，后 case。不要跳过 manifest 阶段直接让 AI 堆用例，P0 流程错了后面全偏。

2. 把 accessibility id 当协作项。推动开发为关键控件设置 testID / content-desc。

3. Android / iOS 分开 caps。禁止混用定位器或 Options 类。

4. 混合 App 测完 H5 必回 NATIVE_APP。否则后续原生步骤静默失败。

5. 失败先走 fault-diagnosis。按症状改一项变量，不要同时改 caps 和定位器。

6. 云/本地 Hub 集中配置。写进 SessionFactory，不要散落在用例里。

7. 摘要给人看，JSON 给工具看。评审会上用中文摘要，脚本对比用 manifest。

十四、常见问题

附录：Cursor 触发语速查

按 mobile-app-autotest 为当前 App 做移动端自动化交付生成 app-test-manifest 和 mobile-tests 工程用 pytest 写 Android 加购流程 Appium 用例混合 App WebView 里点 H5 按钮怎么测移动端测试环境帮我检查一下配置 XCUITest 真机 capabilities