momentic-mobile-test

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: momentic-mobile-test
description: Create, run, and maintain Momentic mobile E2E tests and modules for Android and iOS. Use Momentic MCP tools for live device validation, and use direct v2 YAML edits only for high-confidence local mobile v2 changes.
---

# 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](https://momentic.ai/docs/cli-reference/momentic-mobile/commands/doctor).

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](https://momentic.ai/docs/platforms/android/app-setup) or
[iOS](https://momentic.ai/docs/platforms/ios/app-setup) 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 a