移动端 App 自动化

Skill 标识
mobile-app-autotest

把 App 自动化从零散脚本变成可交接的工程:围绕 Android、iOS 和 WebView,先做环境体检与流程清单,再生成 Screen、Flow 和中文交付摘要,定位与排障都有章可循。

扫码添加辅导员,发送 Skill 名称领取源码
本文目录
  1. Skill 概览
  2. 适合谁、用在什么场景
  3. 需要准备什么、能得到什么
  4. 核心能力与使用边界
  5. 实战教程与使用说明
  6. 一、为什么需要这样一个 Skill?
  7. 二、这个 Skill 是什么?
  8. 三、适用场景与输入输出
  9. 3.1 适用场景
  10. 3.2 输入
  11. 3.3 输出(保存在项目根目录)
  12. 四、核心能力
  13. 4.1 定位金字塔
  14. 4.2 质量评分五维度
  15. 五、如何使用:操作步骤(从 0 跟做)
  16. 5.0 前置准备
  17. 5.1 步骤 1–2,环境体检
  18. 5.2 步骤 3–4,生成测试清单
  19. 5.3 步骤 5–6,启动 Appium 并生成测试工程
  20. 5.4 步骤 7–8,自检与中文交付
  21. 六、输出与保存的约定
  22. 6.1 JSON 与中文摘要分工
  23. 七、适合谁用
  24. 八、Skill 目录结构
  25. 8.1 可扩展点
  26. 九、整体架构与数据流
  27. 9.1 运行面决策
  28. 9.2 平台与驱动映射
  29. 十、SKILL.md 设计要点
  30. 十一、scripts 详细设计
  31. 11.1 check_mobile_env.sh
  32. 11.2 scaffold_manifest.py
  33. 十二、references 索引与契约
  34. 十三、给测试工程师的几点建议
  35. 十四、常见问题
  36. 附录: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 输出(保存在项目根目录)

文件/目录

阶段

用途

app-test-manifest.json

步骤 4

Screen / Flow / 风险清单

mobile-tests/config/

步骤 6

SessionFactory、capabilities

mobile-tests/screens/

步骤 6

页面对象(Screen Object)

mobile-tests/flows/

步骤 6

跨页面业务流程用例

mobile-tests/utils/

步骤 6

手势、等待、截图工具

mobile-tests/reports/

步骤 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

  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 质量评分五维度

维度

权重

看什么

可运行性

25

起服务即可跑通 P0;无硬编码本机路径

定位健壮性

25

P0 无裸 XPath;关键控件有 accessibility / id

可维护性

20

Screen/Flow 分层;capabilities 集中配置

稳定性

15

无 sleep;失败自动截图;超时合理

覆盖透明度

15

有 manifest;报告标风险

满分 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
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,生成测试清单

bash
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 前必须与业务方确认。

json
{
  "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 并生成测试工程

bash
npm i -g appium
appium driver install uiautomator2
appium driver install xcuitest   # 仅 macOS + iOS
appium --port 4723

在 Cursor 对话中说:

text
按 mobile-app-autotest 为包名 com.shop.demo 的 Android App 生成 mobile-tests 工程,
基于 app-test-manifest.json,先覆盖加购 P0 流程,用 Java + TestNG。
java
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/上下文 → 重跑冒烟 → 刷新摘要。


六、输出与保存的约定

text
你的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 目录结构

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

扩展需求

改哪里

换语言栈

references/stacks/ 对应文件 + SKILL.md 语言选型表

改 POM 风格

delivery-guide 中 Screen 模式 + stacks 示例

增加质量评分规则

quality-rubric.md

接入 GitHub Actions / GitLab CI

ci-pipeline-snippets.md

支持 RN / Flutter 定位

cross-framework-notes.md


九、整体架构与数据流

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

node -v 可用

Appium CLI

appium -v 可用

uiautomator2 驱动

driver list --installed 含 uiautomator2

xcuitest 驱动

macOS 上已安装(iOS 需要)

adb

有在线设备或给出 WARN

Xcode

macOS 上 xcodebuild 可用

端口 4723

已监听或提示启动 appium

云凭证 LT_*

可选;未设置则 WARN

11.2 scaffold_manifest.py

参数

默认值

说明

--app-id

com.example.app

包名 / bundleId

--platforms

android,ios

逗号分隔平台列表

--out

stdout

输出路径

--pretty

—

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

按语言栈生成用例代码时


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

  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。


十四、常见问题

现象

原因

处理

会话创建失败

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 触发语速查

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

扫码添加辅导员,发送 Skill 名称,领取源码与配套资料。

同类 Skills