Momentic model

Momentic Mobile turns structured natural language into native and webview automation on Android emulators and iOS simulators. Interactive steps resolve targets into device actions; assertions can inspect screenshots, native hierarchies, and webview state.

Project files and formats

Mobile tests use *.test.yaml; modules use *.module.yaml. Test IDs live in the test file's id field. Check momentic.config.yaml and test-level metadata before assuming project defaults apply.

fileType: momentic/mobile-test/v2 and fileType: momentic/mobile-module/v2 identify mobile v2. Treat missing or different fileType as deprecated v1. Never edit v1 YAML directly; persist changes through momentic_test_splice_steps.

Mobile v2 tests require platform: ANDROID or platform: IOS. Commands are platform-specific.

A mobile v2 test carries its own defaults: defaultEnv for environment variables, defaultChannel for the app channel, and defaultTag for a tag or an alias such as nightly. --env, --channel and --tag override them. defaultTag is optional: without it, the run installs the latest tag in the channel. In the local region the test installs defaultApkFilePath or defaultAppFilePath instead.

V2 can reference modules, JavaScript, and injected files with relative paths. Paths resolve from the YAML file containing the reference. Use ./... or ../..., never absolute paths or ~. Before moving, renaming, or deleting a referenced file, grep its path and update or remove every reference. File-backed JavaScript is v2-only; v1/MCP step strings carry code inline. Do not add internal or generated fields to v2 YAML.

Choose the workflow

Prefer these compact workflows unless the user requests something else:

• Known v2 change: inspect nearby patterns -> edit YAML -> lint when syntax

or references are uncertain -> reload or restart if validating -> run the relevant range.

• V1, unknown UI, or interactive validation: start MCP session -> run any

prerequisites -> preview a logical checkpoint -> splice it -> validate the saved range -> terminate.

• New test: create with momentic_test_create -> author a known v2 sequence

in one YAML edit, or use MCP step-by-step when live discovery is needed. momentic_session_start only opens an existing test.

Use MCP as the default interactive interface. Preview and run wait 30 seconds by default, then return a stepRunnerId while work continues. Leave timeoutSeconds unset for most calls, especially single preset steps. Lower it only when the coding agent's tool timeout is shorter; raise it only within a larger tool timeout. Poll returned handles with momentic_poll_runner.

Prefer the test's configured remote device and app settings. Use local device or app overrides only when the user explicitly requests them.

Setup prerequisites

Run npx momentic-mobile doctor for initial setup and launch, driver, device, or connectivity failures. Use --json when collecting a support report. See the doctor reference.

Remote Android requires adb and ANDROID_HOME; local Android also requires Java and Android Studio. Local iOS requires macOS and Xcode; remote iOS does not once a simulator build is available. Follow the Android or iOS setup guide rather than guessing at missing dependencies.

Android WebView automation requires a build with WebView debugging enabled. Debug builds usually provide it; release builds must enable it explicitly. Missing debugging commonly appears as No browser controller is attached to the requested webview. Mobile WebViews run through the device and do not need a local Chromium installation.

Before editing

Confirm the goal, user-visible success criteria, platform, app source, provider, auth, and env requirements. Ask before previewing or running any step or AI action that may submit, purchase, delete, send, create, or cause another non-idempotent side effect. If approved, execute it at most once. Also ask before using local device overrides, editing a shared module, restarting a long flow, or running an expensive full test.

Authoring rules

• Prefer natural-language targets. Use coordinates only for surfaces the AI

cannot see, such as canvases, maps, games, or non-semantic custom views.

• Use native mobile steps for device actions and checks. See JavaScript under

Test execution behavior for the exceptions.

• Do not add an initial launch/open-app step unless the test must switch apps or

recover app state.

• Keep assertions minimal and user-driven. Validate material state changes

before dependent actions.

• Prefer element or screen checks for deterministic state and AI checks for

semantic visual state. Use visual-only AI checks only when the condition is fully visible and hierarchy data is unavailable, unreliable, or irrelevant.

• Use AI actions only when the user requests one or the existing test already

uses one.

• AI actions are cached by default: a successful flow is saved and replayed,

self-healing failed replay steps. Add --disable-cache to an AI_ACTION to run the agent fresh each time; prefer this for chats, agentic workflows, exploratory tests, and other dynamic or nondeterministic behavior.

• Do not add optional or default-valued fields unless correctness requires them.
• Keep changes narrow. Preserve unrelated values, comments, ordering, and step

style. Do not weaken a test to hide an app, asset, permission, data, or backend failure.

• Preserve the existing before / steps / after structure unless the test

intent requires a change.

Test execution behavior

Cache and memory

Momentic caches native selectors, XML nodes, visible text, webview state, coordinates, and other metadata. AI checks may also reuse past-result memory. Stale cache or memory can explain a fast wrong-target action or a repeated borderline verdict.

Cache is scoped by git metadata, including branch. Protected branches read cache but do not write it unless --save-cache is used or CI is set.

• Change a step description when its intent changes. In general, do not add

DANGEROUS_FORCE_DYNAMIC or --disable-cache to locator steps; built-in cache validation refinds changing targets. Disabling the cache is not a substitute for clarifying a vague description or fixing a timing or race condition. Add it only when told to, or when a cached locator already caused a failure that neither fix resolves.

• Carry a successful preview's CacheId into the exact step being spliced.
• Reword an assertion when old memory no longer matches its intended condition.

Readiness and timing

emulator.smartWaitingTimeoutMs budgets readiness before AI locate, cached element retries, and other single-interaction waits. emulator.waitForStability instead waits after each interactive step so its effects land before the next step begins. Turn on waitForStability for apps that load incrementally, animate between screens, or are broadly slow. It does not control pre-targeting waits.

Within smart waiting, do not add sleeps. For longer or semantic readiness, use an element, screen, or AI check that describes the required positive state. Checks retry until their timeout; increase that timeout instead of polling with JavaScript. See mobile configuration for project-wide timing settings.

Common execution pitfalls

• Keyboard and input animations can race with typing. For slow iOS inputs, use

TYPE's keyboard-settling option. For masked or formatted fields that move the cursor, target the input explicitly and add a keypress delay when needed.

• Scroll describes the content to reveal; swipe describes the finger gesture.

Scrolling down finds lower content, while swiping up moves the finger up to reveal it.

Devices, apps, and settings

Test-level settings can override project platform, app asset, emulator, locale, timezone, geolocation, timeout, header, and environment defaults. Inspect both levels before changing behavior.

For managed assets, use the channels artifact from momentic_get_artifacts as the source of truth for valid platform channels, tags, and aliases. Follow the current tool description for defaultChannel and defaultTag behavior.

Test context

Each run has a test-scoped env that persists across steps and modules.

• In v2, save returned values with saveAs; in MCP step strings, use

--env-key. Use setVariable(name, value) in JavaScript when saving several values.

• Use env.NAME in JavaScript and module input expressions. Use

{{ env.NAME }} in string fields, but not inside JavaScript source.

• Module inputs are JavaScript fragments stored as strings. Quote literal

strings and use env.X for variables.

JavaScript

Use native tap, type, swipe, scroll, wait, and check steps for device behavior. They retain Momentic's targeting, smart waiting, cache, and traces. Do not use JavaScript to reproduce those actions or poll UI state when a check can retry.

Use mobile JavaScript for test setup, data generation, APIs, databases, OTP/email/SMS, assertions, and context writes that no native step expresses. Keep one-off code short; for reusable v2 scripts, follow nearby project conventions. See the mobile JavaScript command for current syntax.

Working with mobile v2 YAML

Mobile v2 is human-editable. Tests use before, steps, and after; modules use steps. Each step has one command key, durations are milliseconds, and runnable step IDs are not stored in YAML.

Make the smallest edit and match nearby syntax. Common pitfalls:

• Android-only commands in iOS tests.
• Coordinates outside 0..100 in v2 YAML or 0..1 in MCP step strings.
• Adding IDs, cache blobs, artifacts, or the wrong detailed target field.

Consult File format for top-level structure and Steps for step syntax. Run npx momentic-mobile lint when schema or file-reference risk warrants it.

After a disk edit, reload the active MCP test if available; otherwise terminate and restart the session. momentic_test_get reads persisted state but does not refresh an active session.

MCP device workflow

Use tool descriptions and the platform-specific Step Authoring Guide returned by session start for current arguments and step syntax. Do not duplicate that reference material from this skill.

Start and fetch context

Do not call context tools as session-start boilerplate. Use them on demand and follow their descriptions, especially when they offer filters or return large project data.

• If the test ID is known, start momentic_session_start by itself. Its Test

Content provides active steps and runnable IDs; the platform comes from the test.

• Use momentic_get_artifacts only to discover unknown tests, modules,

environments, local devices, simulators, or managed asset channels. Avoid redundant refreshes.

• Use momentic_test_get to inspect persisted state before starting, or to read

a different test. Prefer active session and splice responses afterward.

• Use filtered momentic_get_environment_variables only when a step needs env

data that is not already known.

• Use momentic_module_recommend -> momentic_module_get only when evaluating

reuse; recommendation invokes AI and is not required to start a session.

Only one device operation may run per session. Do not issue concurrent preview, run, state, or splice operations against the same session.

Preview -> splice -> validate

1. For mid-test work, run through the preceding step once and keep the same

session so authoring starts from the correct screen.

1. Preview forward in logical checkpoints such as login complete, permission

handled, form ready, submission complete, or confirmation visible.

1. Read the returned screenshot first. Request emulator state only when the

image lacks enough targeting or diagnostic context; request it again once if the app may still be settling.

1. Splice the successful checkpoint. Attach each returned CacheId only to its

exact step, then read the splice response for current step refs.

1. Run the next dependent saved step or range. If a preview or run returns a

stepRunnerId, poll it instead of starting another device operation.

1. Before finishing, when safe, run the smallest saved range covering the

prerequisites, changed step, and next dependent contract. Reset first only when accumulated state could mask a failure.

1. Terminate the session when finished.

Batch obvious low-risk steps. Preview uncertain targets individually. For a non-idempotent action, preview setup, splice the checkpoint, then run the approved saved action at most once.

MCP screenshots are the default signal. Request serialized emulator state for accessible names, native XML, webview structure, screen bounds, or offscreen context. Read environment and installed-app artifacts only when diagnosing data, launch, or install behavior.

Modules

For a logical flow of roughly four or more reusable steps, check momentic_module_recommend -> momentic_module_get -> reuse or inline. Modules cannot contain modules. Ask before changing a shared module.

Respect declared parameters, defaults, and enum values. Module inputs are JavaScript fragments, not {{ }} templates.

Troubleshooting

Device state and timing

• Wrong or stale screen: inspect the latest screenshot or emulator state; retry

state capture once if the app is settling.

• Slow readiness at one checkpoint: add the narrowest element, screen, or AI

check, or increase the existing check's timeout. Checks already retry; do not poll with JavaScript.

• Broadly slow targeting across the project: consider increasing

emulator.smartWaitingTimeoutMs. Do not use it to mask one slow assertion.

• Long jobs or uploads: check for a stable positive result with an appropriate

timeout, not a sleep.

• Permission dialog or system sheet: handle it explicitly before continuing.
• Drifted session: rerun the required saved range with resetSession: true.

Infrastructure and app health

• Treat WDA, Appium, adb, emulator bootstrap or death, provider connectivity,

lost webview context, and repeated device-state capture failures as infrastructure or app-environment signals. Start with the doctor check above, inspect logs and device health, and retry from a clean session before editing the test.

• If the app never becomes idle, continuous animation, video, or background UI

work can block iOS accessibility snapshots. Prefer a test-mode switch that disables it; longer waits do not make a permanently busy app idle.

• Do not weaken assertions or inflate step timeouts to hide infrastructure

failures. Report the failing subsystem and supporting evidence separately from test logic.

Targeting and assertions

• Element absent: debug the prerequisite or scroll state. Element visible but

not found: use visible text, role/name, and nearby context.

• Fast wrong-target action: consider stale cache, then correct the description.
• Use coordinate targets only when semantic targeting is unavailable. MCP

fractions use 0..1; v2 YAML uses percentages from 0..100.

• Use SCROLL_TO when searching for a target. Use manual SWIPE only when no

target exists or scrolling is not appropriate.

• Quoted text is literal. Quote only when the exact text must appear; otherwise

describe meaning.

• Make assertions concrete about region, object, count, or state. Visual-only

checks cannot inspect offscreen content or hierarchy.

• AI checks retry instantaneous snapshots until timeout. Prefer stable final

state; use deterministic element or screen checks when they express the contract. See Writing assertions.

Format and data

• V2 load failure: lint the file and check platform and relative references.
• Module failure: re-check parameters, defaults, enums, and input expressions.
• Missing env value: verify the producing save and env.X versus

{{ env.X }} at the consumer.

• App launch/install issue: inspect test settings, channels/tags, installed-apps

artifacts, and whether the session is remote or local.

After about three attempts at the same failure, stop and ask the user for direction.