Android - Momentic

Fetch the complete documentation index

Use this file to discover all available pages before exploring further.

Prerequisites

Momentic supports local and remote Android emulators. Real devices are not supported. Local emulators use your Android Studio install; remote emulators run from any host.

All setup methods need:

Android also needs the Android SDK platform-tools (adb), with ANDROID_HOME or ANDROID_SDK_ROOT set to the SDK directory. Remote emulators connect through a local adb tunnel, so you need the SDK even when no emulator runs on your machine. The platform-tools alone are enough; you do not need Android Studio for this. See Install adb.

adb --version        # required for remote emulators too
echo $ANDROID_HOME   # or ANDROID_SDK_ROOT: must print an SDK directory

The manual setup also needs an APK. See Android app setup. To build the APK or to use a local emulator, you also need Java JDK 24+ and Android Studio with the emulator components. The wizard uses a remote emulator, so its sample run needs no local Java, Android Studio, or APK.

Setup with coding agent

Open Claude Code, Cursor, Codex, Copilot, or another coding agent in your project directory and paste the prompt below. It uses the wizard’s noninteractive API-key setup, then writes your first test.

Copy the setup prompt

Help me set up Momentic Android testing in this project.

What to do

  1. Check that adb --version works and that ANDROID_HOME or ANDROID_SDK_ROOT points to an SDK directory — remote emulators need the SDK too. If either check fails, install the Android platform-tools yourself if you can (sudo apt install adb, or brew install --cask android-platform-tools, or https://developer.android.com/tools/releases/platform-tools) then set ANDROID_HOME or ANDROID_SDK_ROOT to the SDK root and rerun both checks before continuing; otherwise ask me to install them and stop.
  2. Find an API key. If MOMENTIC_API_KEY is set or npx --yes momentic-mobile whoami prints your user and Org ID, use it. If not, ask me to create a key at https://app.momentic.ai/settings/api-keys and run export MOMENTIC_API_KEY=<the key I give you> — if your shell drops env vars between commands, prefix each npx command with MOMENTIC_API_KEY=<the key> instead.
  3. Install the CLI. If momentic.config.yaml already exists, skip to step 4. Otherwise run npx --yes @momentic/wizard@latest -y --platform android in the project root — it needs a package.json, so run npm init -y first if there is none.
    • It installs momentic-mobile, writes momentic.config.yaml, android/contacts.test.yaml, and AGENTS.md, runs the sample test on a remote emulator (which produces test-results/; no local Java, Android Studio, or APK needed — a 'JAVA_HOME is not set' warning during the sample run is expected, ignore it), and installs the Momentic skills. npm may print audit warnings during install — expected noise, keep going. It may also print 'Opening this run in your browser' or 'skipping editor validation' — both no-ops on headless agents.
    • If it fails MWZ_ARGS_MISSING_CREDENTIALS even with a key set, the env var didn't reach that shell — prefix the same command with MOMENTIC_API_KEY=<key> and re-run.
    • Pass --editor-tools to pick agent integrations — all, none, or a comma list like claude-code,cursor (skills forces the skill install).
  4. Install the skills and MCP server: the wizard already installed the skills — confirm .agents/skills/momentic-mobile-test/SKILL.md exists (re-run npx momentic-mobile skills -y --target codex if not). For MCP, list your tools for names starting with momentic_ and try calling one — if you cannot list MCP tools, none are configured, or every call fails to initialize, count them absent and do not try to repair a broken server. Then run npx momentic-mobile install-mcp -y to set it up — 'Error: No coding agent detected' with a non-zero exit means auto-detection missed you, not that your agent is unsupported: if your client is in the supported list (claude-code, cursor, vscode, codex, opencode, windsurf, devin, zed, gemini-cli, antigravity, claude-desktop), re-run with --client <name>; if it isn't, skip MCP and drive the Momentic CLI per the skill instead.
  5. Confirm the sample test passed and momentic.config.yaml + android/contacts.test.yaml exist. If you skipped the wizard, confirm npx --yes momentic-mobile whoami prints my user and Org ID.
  6. Ask me for an APK of my app and which user flow to test first. If I have no APK, the sample test already proved the pipeline — point me to the Android app setup link below and stop; setup is done. Do not author or run a test without an APK. Upload APKs with npx momentic-mobile assets upload ./build/app.apk --channel dev --tag 1.0.0.
  7. Load the momentic-mobile-test skill and write the test as android/<flow-slug>.test.yaml alongside android/contacts.test.yaml — leave the sample untouched. Set defaultChannel: dev and defaultTag: 1.0.0 on the new test. Assert only what is visible on screen when the action finishes — multi-step flows split fields across screens, so one assert for everything will fail. Author with the Momentic MCP tools if they are wired, otherwise write the *.test.yaml directly per the skill and validate with npx momentic-mobile lint. Run it with npx momentic-mobile run <path-to-test.yaml> --upload-results — a single test can take several minutes, allow a long timeout; it prints 'Uploaded to Momentic. ' when it finishes, keep that link. Fixing the test and re-running is the loop, not a violation — only a retry with no changes, or hiding a failure, is off-limits. When a run fails, unzip its .zip file under test-results/runs/ — it has screenshots, the screen XML snapshot, and device logs, the fastest way to see what went wrong before editing. If it keeps failing after real fixes, report the failure with the uploaded run link and stop, and show me the result.

Critical rules

Set up with the wizard

Run the wizard in your terminal:

npx @momentic/wizard@latest

The wizard signs you in through the browser, installs momentic-mobile, writes momentic.config.yaml plus a sample test under android/, runs the sample test on a remote emulator, and asks which coding agents to set up. A passing sample verifies setup. To test your own app, provide an APK and continue at Build your app. The wizard has already completed the install, authentication, and configuration steps.

Manual setup

  1. Install

npm

pnpm

yarn

npm install --save-dev momentic-mobile

pnpm add --save-dev momentic-mobile

yarn add --dev momentic-mobile

The examples below use npx. With pnpm, use pnpm exec momentic-mobile; with yarn, use yarn momentic-mobile.

  1. Authenticate

Sign in with your browser:

npx momentic-mobile login

The CLI saves the credentials to ~/.momentic/auth.json and uses them when MOMENTIC_API_KEY is not set. In CI, or in a shell without a browser, use an API key instead. Create one in the dashboard and export it:

export MOMENTIC_API_KEY=your-api-key-here

Check which account and organization the CLI uses:

npx momentic-mobile whoami
  1. Initialize
npx momentic-mobile init

This writes momentic.config.yaml to your project root. In an interactive terminal, it also offers to install the coding agent skills and the MCP server. init --yes accepts the defaults without prompts, so it works in agent shells and CI. init does not create tests. You write your first one in the editor below. For a sample test, use the wizard above instead.

  1. Build your app

Momentic installs an .apk. Build it with the tab that matches your stack. See Android app setup for full instructions.

   ./gradlew assembleRelease
   # APK in app/build/outputs/apk/release/

cd android && ./gradlew assembleRelease
# APK in android/app/build/outputs/apk/release/

Generate the native project, then build it like a React Native app:

npx expo prebuild

Or build with EAS:

eas build --platform android --profile preview --local

   flutter build apk   # APK in build/app/outputs/flutter-apk/

If your app shows content in an Android WebView, enable WebView debugging so Momentic can attach: WebView.setWebContentsDebuggingEnabled(true). See Android app setup for details.

  1. Upload your APK (remote emulators)

Remote emulators need no local emulator image or Android Studio. Upload your APK to a channel:

npx momentic-mobile assets upload ./path/to/app.apk \
  --channel dev \
  --tag 1.0.0

For local emulators, see Android emulators for the LOCAL_AVD_ID and LOCAL_APK_PATH setup.

  1. Write and run your first test

Open the local editor:

npx momentic-mobile app

You write mobile tests in this local editor, not in the web app. The dashboard at app.momentic.ai shows results. A browser-based editor for mobile tests is not available yet.

Create a test, select the dev channel and the 1.0.0 tag, and add an action followed by an assertion. For example, tap Sign in, then assert that the sign-in form is visible. Choose an outcome that matches your app. Save the test. The editor writes the .test.yaml file to your project. Run it from the editor, then run the saved file from the CLI. Replace <test-file> with its path relative to your current directory:

npx momentic-mobile run "<test-file>" --upload-results

--upload-results sends the result artifacts to the dashboard. Without it, those artifacts stay on your machine. See AI data use for the data sent to Momentic while a test runs. If the run fails, inspect its failed step and screenshot in the dashboard. Check the selected build, sign-in state, and assertion, then rerun. See Common problems for setup errors.

  1. Verify
  1. Connect your coding agent (optional)

Skip this step if init already did it. The two commands are independent: skills are local instruction files. The MCP server is a live process that gives the agent a device and Momentic tools.

npx momentic-mobile skills

npx momentic-mobile install-mcp

Both commands detect the coding agents on your machine and ask which ones to configure. Pass --yes to skip the prompt. See Building with AI for what each command does.

Android versions

Remote emulators run Android 15 by default. Android 14 is the other supported version. Set it in momentic.config.yaml, or per test in the test’s settings:

momentic.config.yaml

emulator:
  remoteEmulatorSettings:
    androidVersion: "14"

Local emulators run the Android version of the AVD you name. Pass --local-avd-id to pick one for a run:

npx momentic-mobile run --local-avd-id Pixel_9_API_35

To pin the AVD for a whole environment, set LOCAL_AVD_ID instead. The flag overrides the environment variable. See Android emulators for the environment setup.

Next steps

Clone momentic-ai/examples for a full working example.