Android

The wizard signs you in, installs Momentic, runs a sample test on a remote emulator, and connects your coding agent. The manual setup does the same steps one at a time.

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.

Prerequisites

The wizard and the manual setup both need:

Node.js 22.12.0+ or 24.0.0+ (node -v)
A package.json in your project. Run npm init -y if you do not have one. Commit it with the lockfile, so CI and local runs use the same Momentic version.
A Momentic account. Sign up to create one.

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.

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.

Setup with coding agent

Copy this prompt and paste it into Claude Code, Cursor, Codex, Copilot, or any other agent. It runs the wizard with an API key because an agent cannot complete the browser sign-in. Then it 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) and continue; 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` 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. 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. <url>' 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 folder under `test-results/runs/` — it has screenshots, the screen XML snapshot, and console output, 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

- If `MOMENTIC_API_KEY` disappears between shell commands, prefix each `npx` command with it instead of relying on `export`.
- Do not edit `momentic.config.yaml` unless I ask.
- Do not create an API key for me. Ask me for one when you need it.
- Write tests as `*.test.yaml` files. Do not write Playwright or Appium code.
- Do not place real orders, send emails, or touch shared data while testing.
- Run each new test before you tell me it is done.

## When done, point me to

- Building with AI: https://momentic.ai/docs/coding-agents/building-with-ai
- Android app setup: https://momentic.ai/docs/platforms/android/app-setup
- Run in CI: https://momentic.ai/docs/running-tests/ci/github-actions

Manual setup

Install

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.

Authenticate

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

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.

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.

Build your app

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

Native (Kotlin/Java)
React Native
Expo
Flutter

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

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.

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 write one natural-language step, for example Tap the Sign in button. Save the test. The editor writes the .test.yaml file to your project. Run it from the editor, then run it from the CLI by name:

npx momentic-mobile run <your-test-name> --upload-results

--upload-results sends the result to the dashboard. Without it, the run stays on your machine.

Verify

Check that the .test.yaml file exists in your project.
Open the dashboard and check Runs for the result.

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

Android app setup

WebView debugging, APK packaging, environment tooling

Emulators

Local vs. remote emulators and regions

Building with AI

Skills, the MCP server, and a prompt for your coding agent

CI/CD

Run mobile tests on every pull request

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

Get started

Building with AI

Author

Run

Learn

Platforms

Integrations

Account

Prerequisites

Set up with the wizard

Setup with coding agent

Manual setup

Android versions

Next steps

Android app setup

Emulators

Building with AI

CI/CD

​Prerequisites

​Set up with the wizard

​Setup with coding agent

​Manual setup

​Android versions

​Next steps

Android app setup

Emulators

Building with AI

CI/CD

Prerequisites

Set up with the wizard

Setup with coding agent

Manual setup

Android versions

Next steps