用 Momentic 编写和维护 Android/iOS…

当需要为 Android 模拟器或 iOS 模拟器创建、运行、调试 Momentic 移动端 E2E 测试（v2 YAML）和可复用模块时使用。

适用场景

解决思路

1. 确认目标、用户可见的成功标准、平台、应用来源、provider、认证和环境要求；在预览或运行任何可能提交、购买、删除、发送、创建或其他非幂等副作用的步骤或 AI 动作前先询问用户，获批后最多执行一次；使用本地设备覆盖、编辑共享模块、重启长流程或运行昂贵的完整测试前也要先询问。
2. 判断文件类型：移动测试用 `*.test.yaml`，模块用 `*.module.yaml`，测试 ID 在测试文件的 `id` 字段；`fileType: momentic/mobile-test/v2` 和 `fileType: momentic/mobile-module/v2` 表示移动 v2，缺失或不同则视为已弃用的 v1；绝不直接编辑 v1 YAML，改用 `momentic_test_splice_steps` 持久化变更。
3. 移动 v2 测试必须声明 `platform: ANDROID` 或 `platform: IOS`，命令按平台区分；测试自带默认值 `defaultEnv`（环境变量）、`defaultChannel`（应用渠道）、`defaultTag`（标签或如 `nightly` 的别名），`--env`、`--channel`、`--tag` 可覆盖；`defaultTag` 可选，缺省时安装渠道中最新标签；在 `local` 区域则安装 `defaultApkFilePath` 或 `defaultAppFilePath`。
4. v2 可用相对路径引用模块、JavaScript 和注入文件，路径从包含引用的 YAML 文件解析，使用 `./...` 或 `../...`，绝不用绝对路径或 `~`；移动、重命名或删除被引用文件前先 grep 其路径并更新或删除所有引用；文件型 JavaScript 仅 v2 支持，v1/MCP 步骤字符串内联代码；不要向 v2 YAML 添加内部或生成字段。
5. 按场景选择工作流：已知 v2 变更走「查看邻近模式 -> 编辑 YAML -> 语法或引用不确定时 lint -> 验证时 reload 或 restart -> 运行相关范围」；v1、未知 UI 或交互式验证走「启动 MCP 会话 -> 运行前置步骤 -> 预览逻辑检查点 -> splice -> 验证已保存范围 -> 终止」；新测试用 `momentic_test_create` 创建后一次性编写已知 v2 序列，或需要实时发现时用 MCP 逐步编写；`momentic_session_start` 只能打开已有测试。
6. 把 MCP 作为默认交互接口；预览和运行默认等待 30 秒后返回 `stepRunnerId` 并继续工作；大多数调用尤其单个预设步骤不要设置 `timeoutSeconds`，仅当编码代理工具超时更短时降低、仅在更大工具超时内提高；用 `momentic_poll_runner` 轮询返回的句柄。
7. 优先使用测试配置的远程设备和应用设置，仅在用户明确要求时使用本地设备或应用覆盖。
8. 初始设置以及启动、驱动、设备或连接失败时运行 `npx momentic-mobile doctor`，收集支持报告时加 `--json`；远程 Android 需要 adb 和 `ANDROID_HOME`，本地 Android 还需 Java 和 Android Studio；本地 iOS 需要 macOS 和 Xcode，远程 iOS 在模拟器构建可用后不需要；按官方 Android/iOS 设置指南处理缺失依赖，不要猜测。
9. Android WebView 自动化需要启用 WebView 调试的构建（debug 构建通常自带，release 构建须显式启用）；缺失调试常表现为 `No browser controller is attached to the requested webview`；移动 WebView 通过设备运行，不需要本地 Chromium。
10. 编写规则：优先自然语言目标，仅对 AI 不可见的界面（画布、地图、游戏、无语义自定义视图）使用坐标；设备动作和检查用原生移动步骤；除非测试必须切换应用或恢复应用状态，否则不加初始启动/打开应用步骤；断言保持最小且由用户驱动，依赖动作前验证实质状态变化；确定性状态优先元素或屏幕检查，语义视觉状态用 AI 检查，仅当条件完全可见且层级数据不可用、不可靠或不相关时才用纯视觉 AI 检查；仅在用户要求或现有测试已使用时才用 AI 动作；除非正确性需要，不加可选或默认值字段；保持改动最小，保留无关值、注释、顺序和步骤风格，不通过弱化测试掩盖应用、资源、权限、数据或后端故障；除非测试意图需要，保留现有 `before`/`steps`/`after` 结构。
11. 缓存与内存：Momentic 缓存原生选择器、XML 节点、可见文本、webview 状态、坐标等元数据，AI 检查还可能复用历史结果记忆；缓存按 git 元数据（含分支）隔离，受保护分支只读缓存，除非使用 `--save-cache` 或设置 `CI`；步骤意图变化时修改其描述，绝不为定位步骤添加 `DANGEROUS_FORCE_DYNAMIC` 或 `--disable-cache`；把成功预览的 `CacheId` 带入被 splice 的确切步骤；旧记忆不再匹配预期条件时改写断言。
12. 就绪与计时：`emulator.smartWaitingTimeoutMs` 为 AI 定位前的就绪、缓存元素重试和其他单次交互等待提供预算；`emulator.waitForStability` 在每个交互步骤后等待其效果落地再进入下一步，对增量加载、屏幕间动画或整体缓慢的应用开启，它不控制定位前等待；智能等待内不要加 sleep，需要更长或语义化就绪时用描述所需正向状态的元素、屏幕或 AI 检查，检查会重试到超时，应增加其超时而非用 JavaScript 轮询。
13. 常见执行陷阱：键盘和输入动画可能与输入竞争，慢速 iOS 输入用 TYPE 的键盘稳定选项，对移动光标的掩码或格式化字段显式定位输入并在需要时加按键延迟；scroll 描述要揭示的内容，swipe 描述手指手势，向下滚动找到下方内容，而向上滑动移动手指以揭示它。
14. 设备、应用与设置：测试级设置可覆盖项目平台、应用资源、模拟器、locale、时区、地理位置、超时、header 和环境默认值，修改行为前检查两个层级；托管资源以 `momentic_get_artifacts` 的 `channels` 产物为有效平台渠道、标签和别名的唯一来源，按当前工具描述处理 `defaultChannel` 和 `defaultTag`。
15. 测试上下文：每次运行有跨步骤和模块持久的测试级 `env`；v2 用 `saveAs` 保存返回值，MCP 步骤字符串用 `--env-key`，JavaScript 中保存多个值用 `setVariable(name, value)`；JavaScript 和模块输入表达式用 `env.NAME`，字符串字段用 `{{ env.NAME }}` 但不在 JavaScript 源码内使用；模块输入是存为字符串的 JavaScript 片段，字面字符串要加引号，变量用 `env.X`。
16. JavaScript：设备行为用原生 tap、type、swipe、scroll、wait 和 check 步骤，以保留 Momentic 的定位、智能等待、缓存和追踪；不要用 JavaScript 复现这些动作或在检查可重试时轮询 UI 状态；移动 JavaScript 用于测试准备、数据生成、API、数据库、OTP/邮件/短信、断言和原生步骤无法表达的上下文写入；一次性代码保持简短，可复用 v2 脚本遵循邻近项目约定。
17. 移动 v2 YAML 编辑：测试用 `before`、`steps`、`after`，模块用 `steps`；每个步骤只有一个命令键，时长单位为毫秒，可运行步骤 ID 不存于 YAML；做最小编辑并匹配邻近语法；避免常见陷阱：iOS 测试中出现 Android 专用命令、v2 YAML 坐标超出 `0..100` 或 MCP 步骤字符串超出 `0..1`、添加 ID、缓存 blob、产物或错误的详细目标字段；schema 或文件引用有风险时运行 `npx momentic-mobile lint`；磁盘编辑后若可用则 reload 活动 MCP 测试，否则终止并重启会话，`momentic_test_get` 读取持久状态但不刷新活动会话。
18. MCP 设备工作流：使用工具描述和会话启动返回的平台专用 Step Authoring Guide 获取当前参数和步骤语法，不要从本技能复制这些参考材料；不要把上下文工具当作会话启动样板，按需使用并遵循其描述；已知测试 ID 时单独启动 `momentic_session_start`，其 Test Content 提供活动步骤和可运行 ID，平台来自测试；仅在发现未知测试、模块、环境、本地设备、模拟器或托管资源渠道时用 `momentic_get_artifacts`，避免冗余刷新；用 `momentic_test_get` 在启动前检查持久状态或读取其他测试，之后优先用活动会话和 splice 响应；仅当步骤需要未知环境数据时用带过滤的 `momentic_get_environment_variables`；仅在评估复用时用 `momentic_module_recommend` -> `momentic_module_get`，推荐会调用 AI 且启动会话不必须；每个会话只能运行一个设备操作，不要对同一会话并发发起预览、运行、状态或 splice 操作。
19. 预览 -> splice -> 验证流程：测试中途工作时先运行到前一步一次并保持同一会话，使编写从正确屏幕开始；按逻辑检查点（登录完成、权限已处理、表单就绪、提交完成、确认可见）向前预览；先读返回的截图，仅当图像缺少足够定位或诊断上下文时请求模拟器状态，应用可能仍在稳定时可再请求一次；splice 成功的检查点，把每个返回的 `CacheId` 只附加到其确切步骤，然后读取 splice 响应获取当前步骤引用；运行下一个依赖的已保存步骤或范围；若预览或运行返回 `stepRunnerId`，轮询它而不是启动另一个设备操作；结束前在安全时运行覆盖前置条件、变更步骤和下一个依赖契约的最小已保存范围，仅当累积状态可能掩盖失败时才先重置；完成后终止会话。
20. 批量处理明显的低风险步骤，对不确定目标单独预览；对非幂等动作，先预览准备、splice 检查点，然后最多运行一次已批准的保存动作。
21. MCP 截图是默认信号；需要可访问名称、原生 XML、webview 结构、屏幕边界或屏外上下文时请求序列化模拟器状态；仅在诊断数据、启动或安装行为时读取环境和已安装应用产物。
22. 模块：对约四个或更多可复用步骤的逻辑流程，检查 `momentic_module_recommend` -> `momentic_module_get` -> 复用或内联；模块不能包含模块；修改共享模块前先询问；遵守声明的参数、默认值和枚举值；模块输入是 JavaScript 片段而非 `{{ }}` 模板。
23. 故障排查——设备状态与计时：屏幕错误或陈旧时检查最新截图或模拟器状态，应用稳定中可重试状态捕获一次；某检查点就绪慢时添加最窄的元素、屏幕或 AI 检查，或增加现有检查超时，检查本身会重试，不要用 JavaScript 轮询；项目范围定位普遍慢时考虑增加 `emulator.smartWaitingTimeoutMs`，不要用它掩盖单个慢断言；长任务或上传时用适当超时检查稳定的正向结果而非 sleep；权限对话框或系统弹窗先显式处理再继续；会话漂移时用 `resetSession: true` 重跑所需已保存范围。
24. 故障排查——基础设施与应用健康：把 WDA、Appium、adb、模拟器引导或死亡、provider 连接、webview 上下文丢失和反复设备状态捕获失败视为基础设施或应用环境信号，先用 doctor 检查、查看日志和设备健康，从干净会话重试后再编辑测试；应用永不空闲时，持续动画、视频或后台 UI 工作会阻塞 iOS 可访问性快照，优先用测试模式开关禁用它，更长等待无法让永久繁忙的应用空闲；不要弱化断言或夸大步骤超时来掩盖基础设施故障，把失败子系统及证据与测试逻辑分开报告。
25. 故障排查——定位与断言：元素缺失时调试前置条件或滚动状态，元素可见但未找到时用可见文本、角色/名称和邻近上下文；快速错误目标动作考虑陈旧缓存，然后修正描述；仅在语义定位不可用时用坐标目标，MCP 分数用 `0..1`，v2 YAML 用 `0..100` 百分比；搜索目标时用 `SCROLL_TO`，仅当无目标或不适合滚动时才手动 `SWIPE`；引号文本是字面量，仅当必须出现确切文本时才加引号，否则描述含义；断言要具体说明区域、对象、数量或状态，纯视觉检查无法检查屏外内容或层级；AI 检查会重试瞬时快照直到超时，优先稳定最终状态，当确定性元素或屏幕检查能表达契约时使用它们。
26. 故障排查——格式与数据：v2 加载失败时 lint 文件并检查平台和相对引用；模块失败时重新检查参数、默认值、枚举和输入表达式；环境值缺失时验证产生方的保存以及消费方的 `env.X` 与 `{{ env.X }}`；应用启动/安装问题时检查测试设置、渠道/标签、已安装应用产物以及会话是远程还是本地。
27. 同一失败尝试约三次后停止并询问用户方向。

适用边界 · 注意事项

• 需要特定工具/云厂商/付费服务：依赖 Momentic 平台、MCP 工具、`momentic-mobile` CLI 及其托管设备/资源渠道，非通用开发者方案。
• 不适用于非 Momentic 的移动端测试框架或非 Android/iOS 平台。
• v1 YAML 不可直接编辑，必须通过 `momentic_test_splice_steps` 持久化变更。