momentic-mobile-test

Momentic Mobile Background

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.

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.

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.

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.

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.

JavaScript context

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.

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 or 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 ./... or ../...; 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.

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.

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.

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.

Working With Mobile 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:

1. Confirm fileType and platform.
2. Inspect nearby tests/modules for local command style.
3. Edit the smallest YAML range.
4. 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.

MCP Device-Validation Workflow

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.

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 }.

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.

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 s

...