## 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: - **Node.js** 22.12.0 or later in the 22.x series, or 24.0.0 or later (`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](https://app.momentic.ai/) 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](https://developer.android.com/tools/releases/platform-tools) alone are enough; you do not need Android Studio for this. See [Install adb](/content/docs/platforms/android/app-setup#install-adb/index.html). ``` 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](/content/docs/platforms/android/app-setup/index.html). 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=` — if your shell drops env vars between commands, prefix each `npx` command with `MOMENTIC_API_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=` 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 `; 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/.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 --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 - 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. ## 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](/content/docs/quickstart/android#build-your-app/index.html). 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`. 2. **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](https://app.momentic.ai/settings/api-keys) and export it: ``` export MOMENTIC_API_KEY=your-api-key-here ``` Check which account and organization the CLI uses: ``` npx momentic-mobile whoami ``` 3. **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. 4. **Build your app** Momentic installs an `.apk`. Build it with the tab that matches your stack. See [Android app setup](/content/docs/platforms/android/app-setup/index.html) 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](/content/docs/platforms/android/app-setup/index.html) for details. 5. **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](/content/docs/platforms/android/emulators/index.html) for the `LOCAL_AVD_ID` and `LOCAL_APK_PATH` setup. 6. **Write and run your first test** Open the [local editor](/content/docs/local-app/index.html): ``` npx momentic-mobile app ``` You write mobile tests in this local editor, not in the web app. The dashboard at [app.momentic.ai](https://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](/content/docs/reference/mobile-commands/assert/index.html). 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 `` with its path relative to your current directory: ``` npx momentic-mobile run "" --upload-results ``` `--upload-results` sends the result artifacts to the dashboard. Without it, those artifacts stay on your machine. See [AI data use](/content/docs/account/ai-data-use/index.html) 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](/content/docs/account/common-problems/index.html) for setup errors. 7. **Verify** - Check that the `.test.yaml` file exists in your project. - Open the [dashboard](https://app.momentic.ai/) and check **Runs** for the result. - Confirm the run passed and inspect the screenshot at the assertion step to check that it matches the expected state. 8. **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](/content/docs/coding-agents/building-with-ai/index.html) 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](/content/docs/platforms/android/emulators/index.html) for the environment setup. ## Next steps - [**Android app setup** WebView debugging, APK packaging, environment tooling](/content/docs/platforms/android/app-setup/index.html) - [**Emulators** Local vs. remote emulators and regions](/content/docs/platforms/android/emulators/index.html) - [**Building with AI** Skills, the MCP server, and a prompt for your coding agent](/content/docs/coding-agents/building-with-ai/index.html) - [**CI/CD** Run mobile tests on every pull request](/content/docs/running-tests/ci/github-actions/index.html) Clone [momentic-ai/examples](https://github.com/momentic-ai/examples/tree/main/android) for a full working example.