momentic-mobile-test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Momentic Mobile Background

Momentic移动测试背景

Execution model

执行模型

Momentic Mobile drives real Android emulators and iOS simulators. Tests are ordered lists of structured mobile steps.

Interactive steps such as taps, typing, swipes, and scrolls use AI to resolve natural-language targets into concrete device actions.
Assertions can evaluate visible screen state, native hierarchy, and webview state when available.
Goal-based AI actions can perform broader tasks, but native mobile steps are more stable and should be preferred.

Momentic Mobile驱动真实的Android模拟器和iOS模拟器。测试是结构化移动步骤的有序列表。

点击、输入、滑动、滚动等交互式步骤使用AI将自然语言目标解析为具体的设备操作。
断言可评估可见屏幕状态、原生层级结构，以及可用时的webview状态。
基于目标的AI操作可以完成更广泛的任务，但原生移动步骤更稳定，应优先使用。

Cache and memory

缓存与内存

Momentic caches resolved mobile step metadata such as native selectors, XML nodes, visible text, webview state, and coordinates so most runs avoid repeated AI calls. This is critical for speed, but stale cache is a real debugging possibility: a step may hit the wrong element. AI checks may also use past-result memory to stay consistent across runs; bad memory can explain repeated borderline failures.

Caches are scoped by git metadata, including branch. Cache writes are skipped on protected branches, including the configured main branch, unless cache saving is forced with

--save-cache

or the

CI

environment variable is set. Cache reads can still happen on protected branches. Use

--disable-cache

to bypass cache entirely.

Ways to force fresh behavior:

Change the step description/assertion when the intent has changed; this changes the step identity used for cache matching. In v1, splicing a changed step also creates fresh internal UUIDs.
Use
```
--disable-cache
```
for dynamic targets that should resolve fresh every run, such as today's date or the next available slot.
Preserve good previewed cache by carrying
```
CacheId
```
into splice with
```
--cache-id <CacheId>
```
.
Change assertion wording and add disambiguation when previous AI memory is now misleading.

Momentic会缓存已解析的移动步骤元数据，例如原生选择器、XML节点、可见文本、webview状态和坐标，因此大多数运行可避免重复调用AI。这对提升速度至关重要，但缓存过期是实际调试中可能遇到的问题：步骤可能命中错误元素。AI检查也可能使用过往结果的内存来保持跨运行的一致性；错误的内存可能导致重复的边界性失败。

缓存范围由git元数据（包括分支）限定。在受保护分支（包括配置的主分支）上会跳过缓存写入，除非使用

--save-cache

强制保存缓存，或设置了

CI

环境变量。受保护分支仍可读取缓存。使用

--disable-cache

可完全绕过缓存。

强制获取全新行为的方法：

当意图改变时，修改步骤描述/断言；这会更改用于缓存匹配的步骤标识。在v1版本中，修改步骤还会生成新的内部UUID。
对于每次运行都需要重新解析的动态目标（如当日日期或下一个可用时段），使用
```
--disable-cache
```
。
通过
```
--cache-id <CacheId>
```
将
```
CacheId
```
带入修改操作，以保留已预览的有效缓存。
当之前的AI内存产生误导时，修改断言措辞并添加消歧义内容。

Timing

计时

Momentic uses smart waiting before targeting steps. It waits up to the configured smart-waiting timeout, which defaults to 5 seconds, for device state to settle or the target to appear. Within that window, do not add manual waits. For slower or more semantic readiness, use a targeted element/screen check, an AI check, or a native wait only when the test genuinely needs fixed time.

Momentic在执行目标步骤前会使用智能等待机制。它会等待最长至配置的智能等待超时时间（默认5秒），直到设备状态稳定或目标出现。在此窗口内，无需添加手动等待。对于较慢或更具语义性的就绪状态，仅当测试确实需要固定等待时间时，才使用目标元素/屏幕检查、AI检查或原生等待。

Settings precedence

设置优先级

momentic.config.yaml

sets project defaults, but many mobile settings can be overridden at the test level: platform, default app asset channel/tag, emulator provider, local device/app overrides, locale/timezone, geolocation, timeouts, headers, and environment. Always check the test's own metadata before assuming the project default applies.

For managed mobile assets, treat

channels

from

momentic_get_artifacts()

as the source of truth.

settings.defaultChannel

must be a real channel for the test platform.

settings.defaultTag

is optional; omit it to use the most recent uploaded tag for that channel. Do not assume

"latest"

is special unless that literal tag exists.

momentic.config.yaml

设置项目默认值，但许多移动设置可在测试层面覆盖：平台、默认应用资产渠道/标签、模拟器提供商、本地设备/应用覆盖、区域/时区、地理位置、超时时间、请求头和环境变量。在假设项目默认值适用前，务必检查测试自身的元数据。

对于托管的移动资产，将

momentic_get_artifacts()

返回的

channels

视为权威来源。

settings.defaultChannel

必须是测试平台的真实渠道。

settings.defaultTag

为可选参数；省略该参数将使用该渠道最近上传的标签。除非存在字面意义上的

"latest"

标签，否则不要假设它具有特殊含义。

Test context

测试上下文

Each run has a test-scoped

env

context that persists across steps, including modules. Later steps can read values written by earlier steps.

v2: use
```
saveAs
```
on steps with return values.
v1/MCP CLI strings: use
```
--env-key
```
.
JavaScript: prefer
```
return
```
plus
```
saveAs
```
/
```
--env-key
```
; use
```
setVariable(name, value)
```
when setting multiple variables.
Use
```
env.NAME
```
in JavaScript and module input expressions.
Use
```
{{ env.NAME }}
```
in string fields.
```
{{ ... }}
```
can evaluate JavaScript, but do not use it inside JavaScript step source because
```
env
```
is already in scope there.

Module inputs are JavaScript fragments as strings. Quote literal strings and use

env.X

for variables; they are not

{{ }}

templates.

每次运行都有一个测试范围的

env

上下文，该上下文会跨步骤（包括模块）持久化。后续步骤可读取前期步骤写入的值。

v2版本：在有返回值的步骤上使用
```
saveAs
```
。
v1/MCP CLI字符串：使用
```
--env-key
```
。
JavaScript：优先使用
```
return
```
搭配
```
saveAs
```
/
```
--env-key
```
；设置多个变量时使用
```
setVariable(name, value)
```
。
在JavaScript和模块输入表达式中使用
```
env.NAME
```
。
在字符串字段中使用
```
{{ env.NAME }}
```
。
```
{{ ... }}
```
可执行JavaScript，但不要在JavaScript步骤代码中使用它，因为
```
env
```
已在该作用域内。

模块输入是字符串形式的JavaScript片段。字符串字面量需加引号，变量使用

env.X

；它们不是

{{ }}

模板。

JavaScript context

JavaScript上下文

Mobile JavaScript steps run in the mobile execution sandbox. Use them for short one-off data prep, API checks, assertions, or context writes that native mobile steps cannot express.

The sandbox commonly provides

env

setVariable

axios

assert

, and other Momentic-provided helpers. If exact JS support matters, check the JavaScript command docs or the Step Authoring Guide from

momentic_session_start

Keep short one-off JavaScript inline. In v2 YAML, reusable utilities and long scripts can live in a project script file, following existing project conventions. Prefer locations such as

$MOMENTIC_PROJECT_ROOT/scripts/mobile-utilities/setup.js

when the project already has a

scripts/

pattern. Read nearby scripts first and match their module style, helper naming, env usage, and error style.

移动JavaScript步骤在移动执行沙箱中运行。可将其用于原生移动步骤无法实现的短期一次性数据准备、API检查、断言或上下文写入。

沙箱通常提供

env

、

setVariable

、

axios

、

assert

及其他Momentic提供的辅助工具。如果需要明确的JS支持情况，请查看JavaScript命令文档或

momentic_session_start

返回的《步骤编写指南》。

短期一次性JavaScript代码保持内联。在v2 YAML中，可复用工具和长脚本可存储在项目脚本文件中，遵循现有项目约定。如果项目已有

scripts/

目录结构，优先选择

$MOMENTIC_PROJECT_ROOT/scripts/mobile-utilities/setup.js

这类路径。先阅读附近的脚本，匹配它们的模块风格、辅助工具命名、环境变量用法和错误处理风格。

Project State On Disk

磁盘上的项目状态

Mobile tests are

*.test.yaml

files. Mobile modules are reusable step collections stored as

*.module.yaml

files. Test IDs are authoritative and live on the test file's

id

field.

There are two major mobile file formats:

```
fileType: momentic/mobile-test/v2
```
or
```
fileType: momentic/mobile-module/v2
```
-> mobile v2. Direct YAML editing is preferred for high-confidence localized changes when live device discovery is not needed.
Missing
```
fileType
```
, or any other value -> v1. Never edit v1 YAML directly; persist changes only through
```
momentic_test_splice_steps
```
.

Mobile v2 tests include a required

platform

value:

ANDROID

IOS

. Platform-specific command availability matters. Do not add Android-only commands to iOS tests.

momentic.config.yaml

is the project root config. It stores project defaults for agents, AI features, emulator settings, file globs, environments, mobile assets, cache behavior, and advanced settings.

Mobile v2 steps can reference local files by relative path:

Module invocations:
```
module: ./modules/login.module.yaml
```
JavaScript steps:
```
javascript: ./scripts/setup.js
```
File injection: command-specific local file paths

Relative paths resolve from the YAML file containing the step, not from the project root or importing test. Use

./...

../...

; do not use absolute paths or

. If you move, rename, or delete a referenced file, grep for the old path and update every reference.

v1 YAML should still be edited only through MCP. Do not use file-backed JavaScript in v1 YAML or MCP CLI step strings; v1 JavaScript steps should carry executable code in

code

--code

. Use JavaScript file references only in mobile v2 YAML.

Do not add internal or auto-generated fields to v2 YAML.

移动测试文件为

*.test.yaml

。移动模块是可复用的步骤集合，存储为

*.module.yaml

文件。测试ID是权威标识，位于测试文件的

id

字段。

有两种主要的移动文件格式：

```
fileType: momentic/mobile-test/v2
```
或
```
fileType: momentic/mobile-module/v2
```
-> 移动v2版本。当无需实时设备发现时，直接编辑YAML是高可信度本地化变更的首选方式。
缺少
```
fileType
```
或为其他值 -> v1版本。切勿直接编辑v1 YAML；仅通过
```
momentic_test_splice_steps
```
持久化变更。

移动v2测试包含必填的

platform

值：

ANDROID

或

IOS

。平台特定命令的可用性至关重要。不要将仅支持Android的命令添加到iOS测试中。

momentic.config.yaml

是项目根配置文件。它存储代理、AI功能、模拟器设置、文件通配符、环境、移动资产、缓存行为和高级设置的项目默认值。

移动v2步骤可通过相对路径引用本地文件：

模块调用：
```
module: ./modules/login.module.yaml
```
JavaScript步骤：
```
javascript: ./scripts/setup.js
```
文件注入：命令特定的本地文件路径

相对路径从包含该步骤的YAML文件所在位置解析，而非项目根目录或导入测试的位置。使用

./...

或

../...

；不要使用绝对路径或

。如果移动、重命名或删除了被引用文件，请搜索旧路径并更新所有引用。

v1 YAML仍只能通过MCP编辑。不要在v1 YAML或MCP CLI步骤字符串中使用基于文件的JavaScript；v1 JavaScript步骤应在

code

--code

中包含可执行代码。仅在移动v2 YAML中使用JavaScript文件引用。

不要向v2 YAML添加内部或自动生成的字段。

Before You Edit

编辑前准备

Gather only what you need:

Test goal and user-visible mobile success criteria.
Platform: Android or iOS.
App source: managed channel/tag, local APK/.app, or an already-installed app.
Provider: remote by default; local only when the user explicitly asks for a local emulator/simulator.
Auth requirements and required env vars.
Risky actions that must not run twice: submit, purchase, delete, send, create.

For long tasks, inspect nearby mobile tests and modules before authoring. Reusing an existing module is usually better than rebuilding a common flow inline.

Ask before long-running checks, starting over from scratch, destructive actions, local device overrides, or editing a shared module.

仅收集所需信息：

测试目标和用户可见的移动成功标准。
平台：Android或iOS。
应用来源：托管渠道/标签、本地APK/.app文件，或已安装的应用。
提供商：默认使用远程；仅当用户明确要求时才使用本地模拟器/模拟器。
认证要求和所需环境变量。
不得重复执行的风险操作：提交、购买、删除、发送、创建。

对于长任务，在编写前先查看附近的移动测试和模块。复用现有模块通常比重新构建通用流程更好。

在执行长时间检查、从头开始重建、破坏性操作、本地设备覆盖或编辑共享模块前，请先确认。

Choose The Workflow

选择工作流

If the user requests a specific workflow, respect it unless it is unsafe or impossible. Otherwise, use direct mobile v2 YAML editing when the file is v2, the change is localized, the step sequence is known, and live device discovery is not required. Good examples: reword an assertion, adjust a target, update an env key, fix a file reference, or insert a small known step from a nearby pattern.

Use the MCP device-validation workflow when the file is v1 or unknown, live UI state must be discovered, target timing is flaky, the flow is multi-step and unclear, the change depends on platform behavior, or the user asks to build/validate interactively.

Use

momentic_test_create

for new mobile tests; search for the tool if it is not visible. It requires

name

platform

, and valid mobile settings. Only pass folder/path fields when requested.

momentic_session_start

requires an existing

testId

; it does not create tests.

如果用户要求特定工作流，除非不安全或不可行，否则请遵循。否则，当文件为v2版本、变更为本地化、步骤序列已知且无需实时设备发现时，使用直接移动v2 YAML编辑。适用场景示例：修改断言措辞、调整目标、更新环境变量键、修复文件引用，或从附近模式插入少量已知步骤。

当文件为v1版本或未知、需要发现实时UI状态、目标计时不稳定、流程多步且不清晰、变更依赖平台行为，或用户要求交互式构建/验证时，使用MCP设备验证工作流。

使用

momentic_test_create

创建新的移动测试；如果工具不可见，请搜索它。它需要

name

、

platform

和有效的移动设置。仅在被要求时才传入文件夹/路径字段。

momentic_session_start

需要已有的

testId

；它不会创建测试。

Universal Authoring Rules

通用编写规则

Prefer natural-language element descriptions. Use coordinate targets only as a last resort for cases the AI cannot see, such as canvas-like surfaces, non-semantic custom views, maps, games, or a user-requested coordinate target.
Prefer native mobile steps over JavaScript. Use JS only when no native step expresses the behavior.
Do not add launch/open-app steps at the start unless the test actually needs to switch apps or recover app state.
Keep assertions minimal and user-driven. Add readiness checks only when they are needed to make the next dependent action reliable.
After an action that should materially change screen state, add an immediate validation before dependent actions. Prefer
```
ELEMENT_CHECK
```
or
```
SCREEN_CHECK
```
for deterministic text/state, and
```
AI_CHECK
```
for semantic visual state.
Do not use AI actions unless the user asks or the existing test already uses one.
Do not add optional/default fields unless needed for correctness.
Keep the delta small. Preserve unrelated params, request bodies, env keys, literal values, quoting, comments, ordering, and step style.
Do not work around real app failures. If the app is broken, data is missing, permissions are blocked, the app asset is wrong, or a backend is down, report the failure instead of weakening the test.
Do not reorganize
```
before
```
/
```
steps
```
/
```
after
```
or setup / main / teardown unless the test intent requires it.

优先使用自然语言描述元素。仅当AI无法识别时（如类画布界面、非语义自定义视图、地图、游戏，或用户要求的坐标目标），才将坐标目标作为最后手段。
优先使用原生移动步骤而非JavaScript。仅当没有原生步骤可实现所需行为时才使用JS。
除非测试确实需要切换应用或恢复应用状态，否则不要在开头添加启动/打开应用的步骤。
保持断言简洁且以用户为导向。仅当需要确保后续依赖操作可靠时，才添加就绪检查。
在应显著改变屏幕状态的操作后，添加即时验证再执行依赖操作。对于确定性文本/状态，优先使用
```
ELEMENT_CHECK
```
或
```
SCREEN_CHECK
```
；对于语义视觉状态，优先使用
```
AI_CHECK
```
。
除非用户要求或现有测试已使用AI操作，否则不要添加AI操作。
除非正确性需要，否则不要添加可选/默认字段。
保持变更范围最小。保留无关参数、请求体、环境变量键、字面量值、引号、注释、顺序和步骤风格。
不要规避真实的应用故障。如果应用损坏、数据缺失、权限被阻止、应用资产错误或后端宕机，请报告故障而非削弱测试。
除非测试意图需要，否则不要重新组织
```
before
```
/
```
steps
```
/
```
after
```
或设置/主流程/清理部分。

Working With Mobile V2 YAML

处理移动v2 YAML

Mobile v2 is the human-editable format. Steps are compact: each step has one top-level command key, such as

tap: Continue

, or a detailed map under that key. Tests use

before

steps

after

; modules use

steps

. Durations are always milliseconds. No visible step/command IDs.

Direct-edit loop:

Confirm
```
fileType
```
and
```
platform
```
.
Inspect nearby tests/modules for local command style.
Edit the smallest YAML range.
Run lint or MCP validation when syntax or behavior is uncertain.

Common mistakes:

Using Android-only commands in iOS tests.
Using percent coordinates outside
```
0..100
```
in v2 YAML or outside
```
0..1
```
in MCP CLI-style step strings.
Confusing swipe direction with scroll intent.
```
SCROLL_TO --direction down
```
searches lower content;
```
SWIPE --direction up
```
moves the finger up and reveals lower content.
Adding step IDs, command IDs, cache blobs, or execution artifacts to YAML.
Using the wrong detailed target-field name for a command.

npx momentic-mobile lint

validates mobile v2 schemas and file references. Run it when you are unsure of syntax after edits or after moving/renaming referenced files.

State refresh after disk edits:

Active MCP session: use reload if available, otherwise restart the session and run the edited range.
No active MCP session: start a fresh session when ready to validate.
```
momentic_test_get
```
inspects persisted state; it does not refresh an active session after disk edits.

移动v2是可人工编辑的格式。步骤简洁：每个步骤有一个顶级命令键，例如

tap: Continue

，或该键下的详细映射。测试使用

before

steps

after

；模块使用

steps

。持续时间始终以毫秒为单位。无可见的步骤/命令ID。

直接编辑流程：

确认
```
fileType
```
和
```
platform
```
。
查看附近的测试/模块以了解本地命令风格。
编辑最小范围的YAML。
当语法或行为不确定时，运行lint或MCP验证。

常见错误：

在iOS测试中使用仅支持Android的命令。
在v2 YAML中使用超出
```
0..100
```
的百分比坐标，或在MCP CLI风格的步骤字符串中使用超出
```
0..1
```
的百分比坐标。
将滑动方向与滚动意图混淆。
```
SCROLL_TO --direction down
```
用于搜索下方内容；
```
SWIPE --direction up
```
表示向上滑动手指并显示下方内容。
向YAML添加步骤ID、命令ID、缓存 blob 或执行工件。
为命令使用错误的详细目标字段名称。

npx momentic-mobile lint

可验证移动v2模式和文件引用。编辑后或移动/重命名被引用文件后，若对语法不确定，请运行该命令。

磁盘编辑后的状态刷新：

活跃MCP会话：如果可用则使用重载，否则重启会话并运行编辑后的范围。
无活跃MCP会话：准备好验证时启动新会话。
```
momentic_test_get
```
检查持久化状态；磁盘编辑后不会刷新活跃会话。

MCP Device-Validation Workflow

MCP设备验证工作流

Use this for every v1 edit and for mobile v2 work that needs live discovery. The tool surface is shared; persistence differs: v1 uses splice, while v2 can use splice or direct YAML edit plus reload/restart.

此工作流适用于所有v1版本编辑，以及需要实时发现的移动v2版本工作。工具界面共享；持久化方式不同：v1版本使用修改操作，而v2版本可使用修改操作或直接YAML编辑加重载/重启。

Discovery

发现

```
momentic_get_artifacts()
```
: project context, config path, cwd, tests, modules, environments, available AVDs, available iOS simulators, and managed mobile asset channels. Read only what you need.
```
momentic_test_get({ testId | testPath })
```
: inspect persisted mobile test state. Before a session, this is useful. During an active session after splicing, prefer the splice response or
```
returnTest: true
```
.

momentic_module_recommend({ userRequest })

: find reusable flows.

```
momentic_module_get({ selector })
```
: inspect module params, defaults, enums, and steps. Selector is exactly one of
```
{ id }
```
,
```
{ name }
```
, or
```
{ path }
```
.

```
momentic_get_artifacts()
```
：获取项目上下文、配置路径、当前工作目录、测试、模块、环境、可用AVD、可用iOS模拟器和托管移动资产渠道。仅读取所需内容。
```
momentic_test_get({ testId | testPath })
```
：检查持久化的移动测试状态。在会话开始前，此工具很有用。在修改后的活跃会话中，优先使用修改响应或
```
returnTest: true
```
。

momentic_module_recommend({ userRequest })

：查找可复用流程。

```
momentic_module_get({ selector })
```
：检查模块参数、默认值、枚举和步骤。选择器必须是
```
{ id }
```
、
```
{ name }
```
或
```
{ path }
```
中的其中一个。

Sessions

会话

```
momentic_session_start({ testId, ... })
```
: start a mobile session. It returns metadata, the Step Authoring Guide artifact, active Test Content with session step IDs, an initial screenshot, and installed-apps info. Required:
```
testId
```
. Call it by itself, not in parallel with other MCP tools.
The platform is inferred from the test. Prefer the test's default emulator settings. Omit provider/device/app overrides unless the user explicitly asks. If a provider must be chosen, prefer
```
remote
```
; use
```
local
```
only when requested.

Session start options include

provider

envName

localDeviceId

, and

localAppPath

Read the Step Authoring Guide before constructing CLI-style mobile steps.
```
momentic_run_step({ sessionId, fromStep, toStep?, targetSection?, resetSession? })
```
: run existing active-session steps. Use step IDs from Test Content or splice responses, never raw YAML. Use
```
parentStepIdChain: []
```
for top-level steps.
If state drifts, restart with
```
momentic_run_step
```
and
```
resetSession: true
```
on the same
```
sessionId
```
; do not reset between every micro-edit.

momentic_session_terminate({ sessionId })

: terminate when done.

```
momentic_session_start({ testId, ... })
```
：启动移动会话。返回元数据、《步骤编写指南》工件、带有会话步骤ID的活跃测试内容、初始截图和已安装应用信息。必填参数：
```
testId
```
。单独调用此工具，不要与其他MCP工具并行调用。
平台从测试中推断。优先使用测试的默认模拟器设置。除非用户明确要求，否则省略提供商/设备/应用覆盖。如果必须选择提供商，优先使用
```
remote
```
；仅在被要求时使用
```
local
```
。

会话启动选项包括

provider

、

envName

、

localDeviceId

和

localAppPath

。

在构建CLI风格的移动步骤前，请阅读《步骤编写指南》。
```
momentic_run_step({ sessionId, fromStep, toStep?, targetSection?, resetSession? })
```
：运行现有活跃会话中的步骤。使用测试内容或修改响应中的步骤ID，切勿使用原始YAML中的ID。顶级步骤使用
```
parentStepIdChain: []
```
。
如果状态偏离，使用
```
momentic_run_step
```
并设置
```
resetSession: true
```
重启同一
```
sessionId
```
；不要在每次微编辑后都重置。

momentic_session_terminate({ sessionId })

：完成后终止会话。

Test authoring loop

测试编写流程

Author MCP steps in checkpoint-sized chunks. Preview forward until a logical section works, then splice that checkpoint. Good checkpoints are natural mobile flow boundaries such as login complete, permission handled, form submitted, item created, or confirmation visible. Avoid splicing one step at a time unless each step is uncertain, risky, or affects shared module structure.

```
momentic_preview_step({ sessionId, step })
```
: execute one mobile step without persisting. It is stateful. If it returns
```
CacheId
```
, include
```
--cache-id <CacheId>
```
when splicing that step. The response screenshot shows device state after the step.
If a preview screenshot is not enough to target, call
```
momentic_get_session_state
```
with
```
returnBrowserState: true
```
, then inspect the emulator-state text or artifact for accessible names, visible text, XML nodes, webview structure, screen bounds, and nearby structure.
When the next several steps are obvious and low-risk, such as filling known fields, splice them together and run that saved range instead of previewing each field one by one.

momentic_test_splice_steps({ sessionId, startIndex, deleteCount, steps, targetSection?, parentStepIdChain?, returnTest? })

: insert, replace, or delete steps and persist.

After splicing, read the response immediately; it is the source of truth for inserted/deleted refs and active-session step IDs.
If
```
returnTest: true
```
, verify the returned structure before continuing.
If downstream steps remain, run the immediate next step or small range to confirm the flow still connects.
For non-idempotent actions such as submit, purchase, delete, send, or create, avoid repeated previews. Preview the setup steps, splice the checkpoint before the risky action, then execute the risky saved step once only when validation requires it.
For obvious adjacent low-risk steps, batch them; do not checkpoint after every field unless target or device state is uncertain.
When the requested edit is complete, ask whether to validate from the start by running the relevant saved range with
```
momentic_run_step
```
.

以检查点大小的块编写MCP步骤。向前预览直到逻辑部分正常工作，然后修改该检查点。好的检查点是自然的移动流程边界，例如登录完成、权限处理完毕、表单提交、项目创建或确认信息可见。除非每个步骤都不确定、有风险或影响共享模块结构，否则避免每次修改一个步骤。

```
momentic_preview_step({ sessionId, step })
```
：执行一个移动步骤但不持久化。它是有状态的。如果返回
```
CacheId
```
，修改该步骤时需包含
```
--cache-id <CacheId>
```
。响应截图显示步骤执行后的设备状态。
如果预览截图不足以定位目标，调用
```
momentic_get_session_state
```
并设置
```
returnBrowserState: true
```
，然后检查模拟器状态文本或工件以获取可访问名称、可见文本、XML节点、webview结构、屏幕边界和附近结构。
当下几个步骤明显且低风险时（如填写已知字段），将它们一起修改并运行保存的范围，而非逐个预览每个字段。

momentic_test_splice_steps({ sessionId, startIndex, deleteCount, steps, targetSection?, parentStepIdChain?, returnTest? })

：插入、替换或删除步骤并持久化。

修改后立即读取响应；它是插入/删除引用和活跃会话步骤ID的权威来源。
如果设置
```
returnTest: true
```
，在继续前验证返回的结构。
如果仍有后续步骤，运行紧邻的下一个步骤或小范围步骤以确认流程仍连贯。
对于非幂等操作（如提交、购买、删除、发送或创建），避免重复预览。预览设置步骤，在风险操作前修改检查点，然后仅在验证需要时执行一次保存的风险步骤。
对于明显的相邻低风险步骤，批量处理；除非目标或设备状态不确定，否则不要在每个字段后都设置检查点。
当请求的编辑完成后，询问是否通过
```
momentic_run_step
```
运行相关保存范围以从头开始验证。

Reading tool output

读取工具输出

Sessions are live emulator/simulator processes. Screenshots and UI snapshots are transient. If the screenshot does not show expected state after an action, call

momentic_get_session_state

once more; the app may still be loading.

MCP tools may return artifact links under

.momentic-mcp/...

. Read linked files only when needed:

Emulator-state text: refine targeting or debug native/webview structure.
Screenshots: usually already returned inline as images.
Environment files: validate
```
envKey
```
, JavaScript/API outputs, or dependent env values.
Installed-apps reports: verify package/bundle state when app launch or install behavior is unclear.
```
momentic_get_session_state
```
returns serialized emulator state only with
```
returnBrowserState: true
```
; screenshots are returned by default.

会话是实时的模拟器/模拟器进程。截图和UI快照是临时的。如果操作后截图未显示预期状态，请再次调用

momentic_get_session_state

；应用可能仍在加载。

MCP工具可能在

.momentic-mcp/...

下返回工件链接。仅在需要时读取链接文件：

模拟器状态文本：优化定位或调试原生/webview结构。
截图：通常已作为图片内联返回。
环境文件：验证
```
envKey
```
、JavaScript/API输出或依赖的环境变量值。
已安装应用报告：当应用启动或安装行为不明确时，验证包/捆绑包状态。
```
momentic_get_session_state
```
仅在设置
```
returnBrowserState: true
```
时返回序列化的模拟器状态；默认返回截图。

CLI-style step strings

CLI风格步骤字符串

preview_step

and

splice_steps

use CLI-style strings:

--step-type <TYPE> [options]

. The platform-specific Step Authoring Guide returned by

momentic_session_start

is authoritative.

Common examples:

Tap:

--step-type TAP --description "the Continue button"

Type:

--step-type TYPE --description "Email field" --value "user@example.com" --clear-content

AI check:

--step-type AI_CHECK --assertion "the confirmation message is visible" --timeout-seconds 10

Scroll to:

--step-type SCROLL_TO --description "Settings" --direction down

Press:
```
--step-type PRESS --key HOME
```

Module:

--step-type MODULE --module-id <id> --inputs email=env.USER_EMAIL

Splice example:

json

{
  "sessionId": "SESSION_ID",
  "startIndex": 0,
  "deleteCount": 0,
  "steps": [
    "--step-type TAP --description \"the Continue button\" --cache-id UUID_FROM_PREVIEW",
    "--step-type AI_CHECK --assertion \"the next screen is visible\" --timeout-seconds 10"
  ],
  "targetSection": "main"
}

For mobile conditionals, create the

CONDITIONAL

step with

--assertion-type

and the matching assertion fields, then splice nested steps with

parentStepIdChain: [conditionalStepId]

preview_step

和

splice_steps

使用CLI风格字符串：

--step-type <TYPE> [options]

。

momentic_session_start

返回的平台特定《步骤编写指南》是权威依据。

常见示例：

点击：

--step-type TAP --description "the Continue button"

输入：

--step-type TYPE --description "Email field" --value "user@example.com" --clear-content

AI检查：

--step-type AI_CHECK --assertion "the confirmation message is visible" --timeout-seconds 10

滚动到：

--step-type SCROLL_TO --description "Settings" --direction down

按键：
```
--step-type PRESS --key HOME
```

模块：

--step-type MODULE --module-id <id> --inputs email=env.USER_EMAIL

修改示例：

json

{
  "sessionId": "SESSION_ID",
  "startIndex": 0,
  "deleteCount": 0,
  "steps": [
    "--step-type TAP --description \"the Continue button\" --cache-id UUID_FROM_PREVIEW",
    "--step-type AI_CHECK --assertion \"the next screen is visible\" --timeout-seconds 10"
  ],
  "targetSection": "main"
}

对于移动条件判断，使用

--assertion-type

和匹配的断言字段创建

CONDITIONAL

步骤，然后使用

parentStepIdChain: [conditionalStepId]

修改嵌套步骤。

Modules

模块

Default to module-first for logical flows of 4+ steps such as login, permission handling, setup, navigation inside the app, or checkout. Call

momentic_module_recommend

, inspect strong candidates with

momentic_module_get

, then decide module vs inline.

Modules cannot contain modules. Splicing a

MODULE

step inside a module fails.

Editing a shared module requires user confirmation. To modify a module through MCP, replace the module step with a

MODULE

step carrying the needed metadata flags:

--parameters

--parameter-enum

--default-parameter

--module-name

--module-description

--disabled

. Keys in

defaultParameters

and

parameterEnums

must exist in

parameters

Module

inputs

values are JavaScript fragments as strings. Quote string literals, reference env as

env.X

, and respect enum constraints exactly.

对于包含4个及以上步骤的逻辑流程（如登录、权限处理、设置、应用内导航或结账），优先使用模块。调用

momentic_module_recommend

，使用

momentic_module_get

检查优质候选模块，然后决定使用模块还是内联步骤。

模块不能包含模块。在模块内修改

MODULE

步骤会失败。

编辑共享模块需要用户确认。要通过MCP修改模块，将模块步骤替换为带有所需元数据标志的

MODULE

步骤：

--parameters

、

--parameter-enum

、

--default-parameter

、

--module-name

、

--module-description

、

--disabled

。

defaultParameters

和

parameterEnums

中的键必须存在于

parameters

中。

模块

inputs

值是字符串形式的JavaScript片段。字符串字面量需加引号，环境变量引用为

env.X

，并严格遵循枚举约束。

Validation Strategy

验证策略

Direct mobile v2 edit with no live validation requested: summarize changes and ask whether to run.
Direct mobile v2 edit with active session: reload if available, otherwise restart the session, then run the edited range.
MCP-authored edit: preview forward, splice at logical checkpoints, then run the next downstream saved step or range.
Long full-test runs, local device overrides, and risky actions require confirmation.
Terminate MCP sessions when done.

直接移动v2编辑且未要求实时验证：总结变更并询问是否运行。
直接移动v2编辑且有活跃会话：如果可用则重载，否则重启会话，然后运行编辑后的范围。
MCP编写的编辑：向前预览，在逻辑检查点修改，然后运行下一个下游保存的步骤或范围。
长时间的全测试运行、本地设备覆盖和风险操作需要确认。
完成后终止MCP会话。

Troubleshooting

故障排除

Device state and timing

设备状态与计时

Wrong screen/UI: read latest emulator state or call
```
momentic_get_session_state
```
.
Screenshot not updated: call
```
momentic_get_session_state
```
once more.
Flaky timing: prefer
```
AI_CHECK
```
,
```
SCREEN_CHECK
```
,
```
ELEMENT_CHECK
```
, or a targeted
```
SCROLL_TO
```
over generic
```
WAIT
```
.
Long backend job/import/upload: use an assertion or screen/element wait with an appropriate timeout instead of sleeps.
Permission dialog or system sheet: handle it explicitly before continuing.
Weird session state: use
```
momentic_run_step
```
with
```
resetSession: true
```
.

错误的屏幕/UI：读取最新的模拟器状态或调用
```
momentic_get_session_state
```
。
截图未更新：再次调用
```
momentic_get_session_state
```
。
计时不稳定：优先使用
```
AI_CHECK
```
、
```
SCREEN_CHECK
```
、
```
ELEMENT_CHECK
```
或目标明确的
```
SCROLL_TO
```
，而非通用的
```
WAIT
```
。
长时间后端作业/导入/上传：使用断言或屏幕/元素等待并设置适当的超时时间，而非休眠。
权限对话框或系统面板：在继续前显式处理。
异常会话状态：使用
```
momentic_run_step
```
并设置
```
resetSession: true
```
。

Targeting and cache

定位与缓存

Element not found: inspect screenshot/emulator state. If visible, improve the description using visible text, role/name, and nearby context; if absent, debug the prerequisite step or scroll state.
Wrong element was hit quickly or without any AI: suspect stale cache, especially when the screen structure is similar to a prior run.
Dynamic target: change the description to be stable, or disable cache for that step.
Coordinates: use
```
--x-fraction
```
/
```
--y-fraction
```
only when semantic targeting is not available. In MCP CLI strings, fractions are
```
0..1
```
.
Scroll direction: use
```
SCROLL_TO --direction down
```
for lower content and
```
SCROLL_TO --direction up
```
for earlier content. Use manual
```
SWIPE
```
when there is no specific target or
```
SCROLL_TO
```
is not appropriate.
Quoted text: quoted substrings in descriptions are treated literally by Momentic AI. Use quotes only when that exact text must appear on screen or in the element's name; omit quotes for semantic matching.

元素未找到：检查截图/模拟器状态。如果元素可见，使用可见文本、角色/名称和附近上下文优化描述；如果元素不存在，调试前置步骤或滚动状态。
快速命中错误元素或未调用任何AI：怀疑缓存过期，尤其是当屏幕结构与之前的运行相似时。
动态目标：修改描述使其稳定，或禁用该步骤的缓存。
坐标：仅当语义定位不可用时，才使用
```
--x-fraction
```
/
```
--y-fraction
```
。在MCP CLI字符串中，比例范围为
```
0..1
```
。
滚动方向：使用
```
SCROLL_TO --direction down
```
查看下方内容，使用
```
SCROLL_TO --direction up
```
查看上方内容。当没有特定目标或
```
SCROLL_TO
```
不适用时，使用手动
```
SWIPE
```
。
带引号的文本：描述中的带引号子字符串会被Momentic AI视为字面量。仅当屏幕上或元素名称中必须出现该确切文本时才使用引号；语义匹配时省略引号。

AI check performance

AI检查性能

Ambiguous assertion: make the expected visual/text condition concrete. Include the relevant screen region, object, count, or state.
Literal text mismatch: quoted strings are treated as text that must appear on screen. Remove quotes when semantic matching is intended.
Off-screen: visual conditions like color or shape can only be evaluated if the element is visible. Use scroll/gesture setup.
Repeated bad verdict: reword the assertion so the intended condition is clearer and old memory no longer applies.
Transient conditions: AI checks retry over the configured timeout, but each attempt is an instantaneous snapshot. Prefer stable final-state assertions; if necessary, use a deterministic element/screen check.

断言模糊：使预期的视觉/文本条件具体化。包含相关屏幕区域、对象、数量或状态。
字面文本不匹配：带引号的字符串被视为必须出现在屏幕上的文本。当需要语义匹配时，移除引号。
元素不在屏幕上：颜色或形状等视觉条件仅在元素可见时才可评估。使用滚动/手势操作设置。
重复错误判定：修改断言措辞，使预期条件更清晰，避免旧内存的影响。
临时条件：AI检查会在配置的超时时间内重试，但每次尝试都是即时快照。优先使用稳定的最终状态断言；如有必要，使用确定性的元素/屏幕检查。

Format and data

格式与数据

Env value missing: confirm the producing step used
```
saveAs
```
/
```
--env-key
```
or
```
setVariable
```
, and that the consuming syntax is
```
env.X
```
vs
```
{{ env.X }}
```
.
Module input error: inputs are JavaScript fragments as strings; quote string literals and match enum constraints exactly.
App launch/install issue: inspect test settings, managed channels/tags, installed-apps artifact, and whether the session is remote or local.
Platform mismatch: check the test
```
platform
```
and the Step Authoring Guide for platform-specific command availability.

环境变量值缺失：确认生成步骤使用了
```
saveAs
```
/
```
--env-key
```
或
```
setVariable
```
，且消费语法为
```
env.X
```
而非
```
{{ env.X }}
```
。
模块输入错误：输入是字符串形式的JavaScript片段；字符串字面量需加引号并严格匹配枚举约束。
应用启动/安装问题：检查测试设置、托管渠道/标签、已安装应用工件，以及会话是远程还是本地。
平台不匹配：检查测试的
```
platform
```
和《步骤编写指南》中平台特定命令的可用性。

Completion Checklist

完成检查清单

Identify v1 vs mobile v2 and choose MCP vs direct edit.
For MCP changes: preview forward to checkpoints, splice with cache IDs, read splice refs, and run the next saved step/range.
For v2 direct edits: lint or validate when syntax/behavior is uncertain.
Ask before full start-to-end validation unless the user already requested it.
End any MCP session you started.

区分v1版本与移动v2版本，并选择MCP或直接编辑方式。
对于MCP变更：向前预览至检查点，携带缓存ID进行修改，读取修改引用，并运行下一个保存的步骤/范围。
对于v2直接编辑：当语法/行为不确定时，运行lint或验证。
除非用户已要求，否则在进行从头到尾的完整验证前请先确认。
终止你启动的所有MCP会话。