momentic-mobile-test

What this skill does

# 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 Autho