很多测开朋友不是不会写 Appium，而是写完不敢长期维护。这篇分享一套装在 Cursor 里的 mobile-app-autotest Skill，把「摸清现状 → 清单 → 生成工程 → 自检 → 中文交付」做成标准流程。附完整说明文档与资料包。
一、测开人真正头疼的，不是「写不出」
坦率的讲，App 自动化这几年最常见的困境，不是「完全不会写脚本」，而是写了之后，没人愿意长期背锅维护。
UI 小改一下，定位器成片失效。用例条数看着不少，却说不清覆盖了哪些业务流程。Android / iOS 各写一套，风格混乱，交接成本直接拉满。混合 App 里 WebView 切错上下文，失败日志看半天也看不懂。本地能跑，真机就挂，云网格配置更是没人愿意写清楚。
你如果直接跟 AI 说「帮我写 Appium 测试」，往往只能拿到能跑一次的脚本，拿不到可复查的测试工程。
我是真的觉得，测开需要的不是又一个「临时 Prompt」，而是一套能把交付过程钉死的工作说明书。mobile-app-autotest 干的，就是这件事。
二、这套 Skill 到底是什么
它不是独立运行的测试框架，而是装在 Cursor 里的 Skill，路径一般在 .cursor/skills/mobile-app-autotest/。
你可以把它理解成三层。
协作层，SKILL.md 定义何时触发、八步怎么推进、完成标准是什么
脚本层，Shell / Python 做环境体检和测试清单草稿，尽量少依赖第三方包
产物层，JSON 清单 + 可执行用例 + 给人看的中文摘要
默认技术栈是 Appium 3.x，Android 走 UiAutomator2，iOS 走 XCUITest。语言优先跟随仓库已有测试栈，没有的话默认 Java + TestNG。测试工程默认落到 mobile-tests/。
这块需要注意一下，Skill 本身不打包 Appium Server。本地执行前，你还是得自己装好 Appium 和对应驱动。
目录里大概会看到这些东西，SKILL.md 管八步闭环和触发语，scripts 下放环境体检和清单脚手架，assets/templates 放双端 capabilities 模板，references 则按需加载，比如 hybrid-webview、fault-diagnosis、quality-rubric、各语言栈示例。Agent 不会一次性把所有参考文档塞进上下文，而是遇到对应场景再读，这样既稳又省 token。
三、它解决什么问题，适合谁用
跟普通过一轮对话生成脚本相比，它更在意「事实来源」和「质量门禁」。
普通 AI 生成 | mobile-app-autotest |
|---|
直接给几条能跑的 case | 先出 manifest，再生成 Screen / Flow |
XPath 满天飞，改版就挂 | 定位金字塔，优先 accessibility id |
双端 caps 混写 | 分平台 Options + 跨端 Screen 注解 |
失败靠人猜 | fault-diagnosis 决策树 + 自动截图 |
环境缺啥不清楚 | check_mobile_env.sh 一键体检 |
特别适合这几类场景，项目还没有系统化 App 自动化、已有零散 case 想量化覆盖缺口、要做 Android / iOS 双端交付、混合 App 要切 WebView、需要云真机碎片化回归，以及要给产品和领导写中文简报。
如果团队已经深度绑定别的移动端方案，或者纯游戏引擎自定义 UI，就要更审慎，Skill 默认站在 Appium 这条路上。
输入也很克制，你通常只要准备好 APK / IPA（或云网格包地址）、包名、目标平台，再加上可选的 P0 业务流程描述，比如登录、加购、支付。仓库里如果已有 Appium / WebdriverIO 约定，Skill 会优先沿用，而不是强行推翻重写。
四、核心能力，记住这四件事就够
1. 清单先行
用 scaffold_manifest.py 产出 app-test-manifest.json，把 Screen / Flow / 风险列清楚，后面所有生成都以这份清单为事实来源。先清单，后 case，这是整条链路最重要的纪律。
清单里常见字段包括 appId、platforms、screens、flows、risks。flows 会写清优先级和步骤，risks 会标出像「优惠券 H5 页」这种 WebView 切换风险，并指向对应排障文档。你可以把这份 JSON 当成机器可读的测试地图，后面改版对比覆盖缺口时特别好用。
2. 定位金字塔
L1 优先 accessibility id / content-desc / label。L2 用平台稳定属性。L3、L4 再考虑结构查询和列表滚动场景。L5 的 XPath 只做兜底，而且必须注释原因。禁止 Thread.sleep，也禁止写死坐标。
3. 多栈落地
Java / Python / JS / TS 都能跟。本地模拟器、USB 真机、云真机网格都能配。运行面怎么选，Skill 里有对应参考文档。
4. 质量评分 + 排障
quality-rubric 按可运行性、定位健壮性、可维护性、稳定性、覆盖透明度五维自评，满分 100，低于 70 建议补全再交付。失败时走 fault-diagnosis，按症状改一项变量，不要同时改 caps 和定位器。
八步交付闭环也可以记成一条线，摸清现状、选定运行面、锁定语言栈、生成清单、启动服务、生成资产、环境自检与质量评分、输出中文交付摘要。中间任何一步跳过，后面都容易漂。
五、从 0 跟做，最小可用路径
前置准备
装好 Node.js、Python 3.8+。测 Android 需要 JDK 和 Android SDK，测 iOS 需要 macOS 和 Xcode。确认 Skill 已放到项目的 skills 目录，并准备好 APK / IPA，或者云网格账号。
第一步，环境体检
确认 Node、Appium、uiautomator2、adb（或 Xcode）都是 OK。如果 4723 没监听，后续先启动 Appium。
第二步，生成测试清单
打开 manifest，人工校对 P0 flows 是否跟真实业务一致。大规模生成 case 前，务必先跟业务方确认。
第三步，启动服务，让 Agent 生成工程
在 Cursor 里可以直接这样说。
生成出来的 Screen Object，典型长这样。
第四步，自检与中文交付
按 quality-rubric 逐项勾选，输出中文摘要，写清覆盖范围、定位风险、环境缺口和补测建议。失败就进排障决策树，修完再刷一遍冒烟，再刷新摘要。
Cursor 里也可以直接丢这些触发语，比如「按 mobile-app-autotest 为当前 App 做移动端自动化交付」「混合 App WebView 里点 H5 按钮怎么测」「移动端测试环境帮我检查一下」「配置 XCUITest 真机 capabilities」。触发词尽量带上 Skill 名，Agent 更容易准确命中工作流。
六、你会得到什么产物
JSON 给工具和 Agent 做覆盖对比，中文摘要给人看，screens / flows 代码给测开维护并纳入版本管理。安全约定也很明确，禁止把生产账号密码写进 case 或 fixtures。未知测试账号就老实写在摘要的「待确认」区，别硬编码进仓库。
常见翻车点也顺便提一句。会话创建失败，多半是 Appium 没起或驱动没装。元素找不到，先怀疑定位器，再怀疑 WebView 没切 context。iOS WDA 超时，优先看签名和超时参数。用例间歇失败，通常是 sleep 或动画在捣乱，改成显式等待会稳很多。并行多 Android 会话冲突时，记得给每个会话分配独立 systemPort。
七、几个我愿意反复强调的建议
先清单，后 case。跳过 manifest 直接堆用例，P0 一错后面全偏。
把 accessibility id 当协作项，推动开发给关键控件补 testID / content-desc。
Android / iOS 分开 caps，禁止混用定位器和 Options 类。
混合 App 测完 H5，必须切回 NATIVE_APP，否则后面原生步骤会静默失败。
失败先走 fault-diagnosis，一次只改一个变量。
云 / 本地 Hub 写进 SessionFactory，别散落在用例里。
评审会上用中文摘要，脚本对比用 manifest。
怎么说呢，AI 时代测开真正值钱的，不是「能让模型吐出一段能跑的代码」，而是能把交付变成可复查、可交接、可排障的工程闭环。
这套 Skill，就是在帮你把这件事从「靠经验」变成「靠流程」。
八、资料自取
文末资料包里有完整 Skill 压缩包、配套 MD 说明文档，评论区留言666，无偿！
如果你正在从零搭 App 自动化，建议先拿一个小 Demo App 完整跑通「环境体检 → 清单 → 生成 mobile-tests → 质量自评」，再把中文摘要丢给同事做一次评审。跑通这一圈，比只收藏一篇文章有用得多。
