momentic-mobile-test

Momentic 模型

Momentic Mobile 可将结构化自然语言转换为 Android 模拟器和 iOS 模拟器上的原生及 WebView 自动化。交互步骤会将目标解析为设备操作；断言可以检查屏幕截图、原生层级结构和 WebView 状态。

项目文件和格式

移动测试使用 *.test.yaml；模块使用 *.module.yaml。测试 ID 位于测试文件的 id 字段中。请先检查 momentic.config.yaml 和测试级元数据，再判断项目默认设置是否适用。

fileType: momentic/mobile-test/v2 和 fileType: momentic/mobile-module/v2 用于标识移动端 v2。缺少 fileType 或其值不同，则视为已弃用的 v1。切勿直接编辑 v1 YAML；应通过 momentic_test_splice_steps 保存更改。

移动端 v2 测试必须包含 platform: ANDROID 或 platform: IOS。命令因平台而异。

移动端 v2 测试包含自身默认设置：用于环境变量的 defaultEnv、用于应用渠道的 defaultChannel，以及用于标签或 nightly 等别名的 defaultTag。--env、--channel 和 --tag 会覆盖这些设置。defaultTag 为可选项：若未设置，运行时会安装该渠道中的最新标签版本。在 local 区域中，测试会改为安装 defaultApkFilePath 或 defaultAppFilePath 指定的文件。

v2 可以通过相对路径引用模块、JavaScript 和注入文件。路径相对于包含该引用的 YAML 文件解析。请使用 ./... 或 ../...，切勿使用绝对路径或 ~。移动、重命名或删除被引用的文件前，请先搜索其路径，并更新或移除所有引用。基于文件的 JavaScript 仅适用于 v2；v1/MCP 步骤字符串会将代码内联。请勿向 v2 YAML 添加内部字段或生成的字段。

选择工作流

除非用户另有要求，否则优先采用以下精简工作流：

• 已知的 v2 更改： 检查附近的模式 -> 编辑 YAML -> 语法或引用不确定时进行 lint -> 验证时重新加载或重启 -> 运行相关范围。
• v1、未知 UI 或交互式验证： 启动 MCP 会话 -> 运行所需前置步骤 -> 预览逻辑检查点 -> 插入步骤 -> 验证已保存的范围 -> 终止会话。
• 新测试： 使用 momentic_test_create 创建 -> 通过一次 YAML 编辑编写已知的 v2 步骤序列，或在需要实时探索时逐步使用 MCP。 momentic_session_start 只会打开现有测试。

默认使用 MCP 作为交互界面。预览和运行默认等待 30 秒，然后会在工作继续时返回 stepRunnerId。大多数调用都应省略 timeoutSeconds，尤其是单个预设步骤。只有当编码 Agent 的工具超时时间更短时才调低；只有在工具超时时间更长时才调高。使用 momentic_poll_runner 轮询返回的句柄。

优先使用测试中配置的远程设备和应用设置。仅当用户明确要求时，才使用本地设备或应用覆盖设置。

设置前置条件

首次设置，或启动、驱动程序、设备或连接失败时，请运行 npx momentic-mobile doctor。收集支持报告时使用 --json。请参阅 doctor 参考。

远程 Android 需要 adb 和 ANDROID_HOME；本地 Android 还需要 Java 和 Android Studio。本地 iOS 需要 macOS 和 Xcode；如果已有模拟器构建版本，远程 iOS 则不需要这些条件。请参阅 Android 或 iOS 设置指南，不要猜测缺少哪些依赖项。

Android WebView 自动化需要启用了 WebView 调试功能的构建版本。调试构建通常默认启用；发布构建必须显式启用。缺少调试功能时，通常会出现 No browser controller is attached to the requested webview。移动端 WebView 通过设备运行，无需本地安装 Chromium。

编辑前

确认目标、面向用户的成功标准、平台、应用来源、提供方、 身份验证和环境要求。在预览或执行任何可能提交、购买、删除、发送、创建或 产生其他非幂等副作用的步骤或 AI 操作之前，先征求确认。获批后，最多执行一次。还要在 使用本地设备覆盖项、编辑共享模块、重启长流程或 运行耗时较长的完整测试之前征求确认。

编写规则

• 优先使用自然语言描述目标。只有在 AI 无法查看的界面（如画布、地图、游戏或非语义自定义视图）中才使用坐标。
• 设备操作和检查使用原生移动端步骤。例外情况见 测试执行行为 中的 JavaScript。
• 除非测试必须切换应用或恢复应用状态，否则不要添加初始启动／打开应用步骤。
• 断言应尽量精简，并以用户需求为导向。在执行依赖后续状态的操作前，先验证重要的状态变化。
• 确定性状态优先使用元素或屏幕检查，语义视觉状态使用 AI 检查。仅当条件完全可见，且层级数据不可用、不可靠或无关时，才使用纯视觉 AI 检查。
• 只有在用户要求使用 AI 操作，或现有测试已使用 AI 操作时，才添加 AI 操作。
• AI 操作默认会缓存：成功的流程会被保存并重放，失败的重放步骤会进行自愈。向 AI_ACTION 添加 --disable-cache，可在每次运行时启动全新的 Agent；聊天、Agent 工作流、探索性测试及其他动态或非确定性行为优先使用此选项。
• 除非正确性要求，否则不要添加可选字段或带默认值的字段。
• 修改范围应尽量小。保留无关值、注释、顺序和步骤风格。不要通过弱化测试来掩盖应用、资源、权限、数据或后端故障。
• 除非测试意图要求修改，否则保留现有的 before / steps / after 结构。

测试执行行为

缓存和记忆

Momentic 会缓存原生选择器、XML 节点、可见文本、WebView 状态、坐标和其他元数据。AI 检查也可能重用过往结果的记忆。缓存或记忆过期，可能导致快速执行的错误目标操作，或重复出现的临界判定。

缓存按 git 元数据（包括分支）进行作用域划分。受保护分支会读取缓存，但不会写入缓存，除非使用 --save-cache 或设置了 CI。

• 步骤意图发生变化时，更新步骤描述。通常不要向定位器步骤添加 DANGEROUS_FORCE_DYNAMIC 或 --disable-cache；内置缓存验证会重新查找发生变化的目标。禁用缓存不能替代澄清含糊的描述，也不能解决时序或竞态问题。只有在收到指示时，或缓存的定位器已导致故障且其他修复均无效时，才添加此选项。
• 将成功预览中的 CacheId 带入要插入的确切步骤。
• 旧记忆不再符合断言的预期条件时，重新措辞该断言。

就绪状态和时序

emulator.smartWaitingTimeoutMs 用于设置 AI 定位、缓存元素重试及其他单次交互等待的就绪等待时限。emulator.waitForStability 则在每个交互步骤后等待，确保其效果生效后再开始下一步。对于逐步加载、在屏幕间切换时带有动画或整体运行缓慢的应用，请启用 waitForStability。它不会控制目标定位前的等待。

在智能等待期间，不要添加休眠。对于较长时间或语义上的就绪状态，请使用描述所需正向状态的元素、屏幕或 AI 检查。检查会重试直到超时；与其使用 JavaScript 轮询，不如增加超时时间。请参阅 移动端配置，了解项目级时序设置。

常见执行问题

• 键盘和输入动画可能与输入操作发生竞态。对于输入较慢的 iOS，请使用 TYPE 的键盘稳定选项。对于会移动光标的掩码或格式化字段，请明确指定 输入目标，并在需要时增加按键延迟。
• Scroll 描述要显示的内容；swipe 描述手指手势。向下滚动可查找更靠下的内容， 而向上滑动会将手指向上移动，以显示相应内容。

设备、应用和设置

测试级设置可以覆盖项目的平台、应用资源、模拟器、区域设置、 时区、地理位置、超时、标头和环境默认值。更改行为前，请检查这两个层级。

对于托管资源，请使用 momentic_get_artifacts 返回的 channels 产物，作为有效平台通道、标签和别名的准确信息来源。关于 defaultChannel 和 defaultTag 的行为，请遵循当前工具说明。

测试上下文

每次运行都有一个测试作用域的 env，可在各步骤和模块之间持久保存。

• 在 v2 中，使用 saveAs 保存返回值；在 MCP 步骤字符串中，使用 --env-key。保存多个值时，在 JavaScript 中使用 setVariable(name, value)。
• 在 JavaScript 和模块输入表达式中使用 env.NAME。在字符串字段中使用 {{ env.NAME }}，但不要在 JavaScript 源代码中使用。
• 模块输入是以字符串形式存储的 JavaScript 代码片段。字面字符串需加引号，变量使用 env.X。

JavaScript

设备操作请使用原生点按、输入、滑动、滚动、等待和检查步骤。 这些步骤会保留 Momentic 的目标定位、智能等待、缓存和跟踪功能。不要用 JavaScript 重现这些操作；如果检查步骤可以重试，也不要用 JavaScript 轮询 UI 状态。

移动端 JavaScript 适用于测试设置、数据生成、API、数据库、 OTP/电子邮件/SMS、断言，以及无法通过原生步骤表达的上下文写入。 一次性代码应保持简短；对于可复用的 v2 脚本，请遵循项目中附近的惯例。有关当前语法，请参阅 移动端 JavaScript 命令。

使用移动端 v2 YAML

移动端 v2 YAML 可供人工编辑。测试使用 before、steps 和 after；模块使用 steps。每个步骤只有一个命令键，时长以毫秒为单位，可运行的步骤 ID 不会存储在 YAML 中。

尽量少做修改，并遵循附近的语法。常见问题：

• 在 iOS 测试中使用仅适用于 Android 的命令。
• 在 v2 YAML 中使用超出 0..100 范围的坐标，或在 MCP 步骤字符串中使用超出 0..1 范围的坐标。
• 添加 ID、缓存数据块、产物，或错误的详细目标字段。

有关顶层结构，请参阅文件格式；有关步骤语法，请参阅步骤。如果存在架构或文件引用方面的风险，请运行 npx momentic-mobile lint。

磁盘编辑后，如果可以，请重新加载当前活动的 MCP 测试；否则，请终止并重启会话。momentic_test_get 会读取持久化状态，但不会刷新活动会话。

MCP 设备工作流

请使用会话启动时返回的工具说明和平台专属步骤编写指南，了解当前参数和步骤语法。不要在本技能中重复这些参考资料。

启动并获取上下文

不要将上下文工具用作会话启动的例行步骤。按需使用这些工具，并遵循其说明，尤其是提供筛选条件或返回大量项目数据时。

• 如果已知测试 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 操作。

预览 -> splice -> 验证

1. 对于测试中途的工作，先运行到前置步骤，并保持同一会话，以便从正确的屏幕开始编写。
2. 在逻辑检查点向前预览，例如登录完成、权限已处理、表单就绪、提交完成或确认信息可见。
3. 首先读取返回的截图。只有当图像不足以提供定位或诊断上下文时，才请求模拟器状态；如果应用可能仍在加载，再请求一次。
4. splice 成功的检查点。每个返回的 CacheId 只能附加到对应的步骤，然后读取 splice 响应以获取当前步骤引用。
5. 运行下一个依赖的已保存步骤或范围。如果预览或运行返回 stepRunnerId，请轮询该 ID，而不是启动另一项设备操作。
6. 完成前，在安全的情况下，运行覆盖前置条件、已更改步骤和下一个依赖契约的最小已保存范围。只有当累积状态可能掩盖故障时，才先重置。
7. 完成后终止会话。

将明显低风险的步骤批量处理。对目标不确定的步骤逐个预览。对于非幂等操作，先预览设置，再 splice 检查点，然后最多运行一次已批准的已保存操作。

MCP 截图是默认信号。对于可访问名称、原生 XML、WebView 结构、屏幕边界或屏幕外上下文，请请求序列化模拟器状态。仅在诊断数据、启动或安装行为时，才读取环境和已安装应用的资产。

模块

对于包含大约四个或更多可复用步骤的逻辑流程，请检查 momentic_module_recommend -> momentic_module_get -> 复用或内联。模块不能包含其他模块。更改共享模块前请先征求同意。

遵守已声明的参数、默认值和枚举值。模块输入是 JavaScript 片段，不是 {{ }} 模板。

故障排查

设备状态和时序

• 屏幕错误或过时：检查最新截图或模拟器状态；如果应用仍在加载，再次捕获状态。
• 某个检查点的就绪速度较慢：添加范围最窄的元素、屏幕或 AI 检查，或延长现有检查的超时时间。检查已具备重试机制；不要使用 JavaScript 轮询。
• 项目范围内的定位普遍较慢：考虑增大 emulator.smartWaitingTimeoutMs。不要用它来掩盖单个断言缓慢的问题。
• 长时间运行的任务或上传：使用适当的超时时间检查稳定的成功结果，而不是休眠等待。
• 权限对话框或系统面板：继续之前应明确处理。
• 会话状态偏移：使用 resetSession: true 重新运行所需的已保存范围。

基础设施和应用健康状况

• 将 WDA、Appium、adb、模拟器启动或崩溃、提供方连接、webview 上下文丢失，以及反复捕获设备状态失败视为基础设施或应用环境信号。先执行上文的 doctor 检查，检查日志和设备健康状况，然后从干净的会话重新尝试，再修改测试。
• 如果应用始终无法进入空闲状态，持续动画、视频或后台 UI 工作可能会阻止 iOS 无障碍快照。优先使用测试模式开关将其禁用；延长等待时间无法让永久忙碌的应用进入空闲状态。
• 不要通过弱化断言或大幅延长步骤超时来掩盖基础设施故障。将故障子系统和支持证据与测试逻辑分开报告。

定位和断言

• 找不到元素：排查前置条件或滚动状态。元素可见但未找到：使用可见文本、角色/名称和附近上下文。
• 操作很快但目标错误：考虑缓存过期，再修正描述。
• 仅在无法进行语义定位时使用坐标目标。MCP 使用 0..1 的比例；v2 YAML 使用 0..100 的百分比。
• 搜索目标时使用 SCROLL_TO。只有在目标不存在或不适合滚动时，才使用手动 SWIPE。
• 引号中的文本会按字面匹配。只有必须出现确切文本时才加引号；否则描述其含义。
• 对区域、对象、数量或状态提出具体断言。仅检查视觉内容无法查看屏幕外的内容或层级结构。
• AI 检查会在超时前重试瞬时快照。优先使用稳定的最终状态；如果确定性元素或屏幕检查能够表达预期条件，则使用它们。参见 编写断言。

格式和数据

• V2 加载失败：检查文件格式，并核对平台和相对引用。
• 模块失败：重新检查参数、默认值、枚举和输入表达式。
• 缺少环境值：核实生成该值的保存操作，以及使用方处的 env.X 与 {{ env.X }}。
• 应用启动/安装问题：检查测试设置、渠道/标签、已安装应用产物，以及会话是远程还是本地。

对同一故障尝试约三次后，请停止并询问用户如何处理。