> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Android

> Set up Momentic for an Android app and run your first mobile test.

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

## Install via the wizard

Run the onboarding wizard in your terminal. It signs you in through the browser,
then gets you to a passing Android test in about two minutes: install, sample
test run against a remote emulator, and editor MCP setup, all in one flow.

```bash theme={null}
npx @momentic/wizard@latest
```

### Have a coding agent set it up

A coding agent can't complete the browser sign-in, so the agent path uses an API
key and runs the wizard non-interactively. Copy the prompt below into Cursor,
Claude, or another agent:

<Prompt description="Set up Momentic for an Android project end to end via the onboarding wizard, non-interactively." actions={["copy", "cursor", "claude"]}>
  Set up Momentic for Android testing in this project by running the onboarding
  wizard non-interactively.

  First, get an API key. Check whether one is already available:

  * If `MOMENTIC_API_KEY` is set in the environment, or `~/.momentic/auth.json`
    exists from a previous sign-in, reuse it and skip ahead to running the wizard.
  * Otherwise, you cannot sign in through the browser yourself. Ask me to sign up
    at [https://app.momentic.ai](https://app.momentic.ai), create an API key at
    [https://app.momentic.ai/settings/api-keys](https://app.momentic.ai/settings/api-keys), and paste it back. Wait for the
    key, then export it:

  ```bash theme={null}
  export MOMENTIC_API_KEY=<the key I give you>
  ```

  Then run the wizard non-interactively. `npx --yes` auto-confirms the one-time
  package download, and the wizard's own `-y` flag resolves every prompt from
  flags, env, and defaults (reading the API key from `MOMENTIC_API_KEY`), so the
  command never blocks on input:

  ```bash theme={null}
  npx --yes @momentic/wizard@latest -y --platform android --editor-tools skills
  ```

  This installs `momentic-mobile` as a dev dependency, scaffolds
  `momentic.config.yaml` plus a sample test under `android/`, installs Chromium
  for WebView automation, and runs the sample test end to end against a remote
  emulator (no local Android Studio required). `--editor-tools` controls
  coding-agent setup: pass a comma-separated list to register the Momentic MCP
  server and install skills (for example `cursor,skills` or `claude-code,skills`),
  `all` to configure every detected agent, or `none` to skip. Omit the flag to
  auto-detect installed agents.

  The sample run uses a remote emulator, so it needs no local Java or Android SDK.
  To run tests against local emulators later, you'll need Java JDK 24+, Android
  Studio, and `ANDROID_HOME`; the wizard prints a prereq check that surfaces
  install commands for anything missing.

  When it finishes, confirm the sample test passed and that `momentic.config.yaml`
  (plus the sample `android/contacts.test.yaml`) was created in the project.
</Prompt>

Or, to install manually, continue with the rest of this guide.

## 1. Prerequisites

* **Node.js** 22.12.0+ in the 22.x line, 24.x, or 26.x. See the
  [Node.js release list](https://nodejs.org/en/about/previous-releases/) for
  supported release lines.
* **Java JDK** 24 (or later)
* **Android Studio** with platform tools and emulator components
* An APK of your app (see [App setup](/platforms/android/app-setup))
* A Momentic account, [sign up](https://app.momentic.ai) to generate an API key

```bash theme={null}
node -v          # need 22.12.0+ in 22.x, 24.x, or 26.x
java --version   # JDK 24
echo $ANDROID_HOME
```

See [App setup](/platforms/android/app-setup) for a full walkthrough of
installing Java, Android Studio, and setting `ANDROID_HOME`.

## 2. Install

```bash theme={null}
npm install --save-dev momentic-mobile
```

## 3. Authenticate

**Option A**: sign in with your browser (recommended):

```bash theme={null}
npx momentic-mobile login
```

This opens a browser-based login flow and saves credentials to
`~/.momentic/auth.json`. The CLI automatically uses this file when
`MOMENTIC_API_KEY` is not set.

**Option B**: use an API key:

Create an API key in the [dashboard](https://app.momentic.ai/settings/api-keys),
then export it:

```bash theme={null}
export MOMENTIC_API_KEY=your-api-key-here
```

## 4. Initialize

```bash theme={null}
npx momentic-mobile init
```

This writes `momentic.config.yaml` to your project root. `init` does not
scaffold any tests; author your first one in the editor below. (For
pre-scaffolded sample tests, use the
[onboarding wizard](#install-via-the-wizard) instead.)

## 5. Build your app

Momentic installs an `.apk`. Build it with the tab that matches your stack. Full
instructions are in [Android app setup](/platforms/android/app-setup); for more
cross-platform detail see
[Cross-platform frameworks](/quickstart/cross-platform-frameworks).

<Tabs>
  <Tab title="Native (Kotlin/Java)">
    ```bash theme={null}
    ./gradlew assembleRelease
    # APK in app/build/outputs/apk/release/
    ```
  </Tab>

  <Tab title="React Native">
    ```bash theme={null}
    cd android && ./gradlew assembleRelease
    # APK in android/app/build/outputs/apk/release/
    ```
  </Tab>

  <Tab title="Expo">
    Generate the native project, then build it like a React Native app:

    ```bash theme={null}
    npx expo prebuild
    ```

    Or build directly with EAS:

    ```bash theme={null}
    eas build --platform android --profile preview --local
    ```
  </Tab>

  <Tab title="Flutter">
    ```bash theme={null}
    flutter build apk   # APK in build/app/outputs/flutter-apk/
    ```
  </Tab>
</Tabs>

## 6. Install browsers

Momentic uses a headless browser to automate Android WebViews:

```bash theme={null}
npx momentic-mobile install-browsers chromium
```

<Info>
  If your app renders content inside an Android `WebView`, enable WebView
  debugging so Momentic can attach:
  `WebView.setWebContentsDebuggingEnabled(true)`. See [Android app
  setup](/platforms/android/app-setup) for details.
</Info>

## 7. Upload your APK (remote emulators)

Remote emulators are the fastest way to get started, no Android Studio VM
required. Upload your APK to a channel:

```bash theme={null}
npx momentic-mobile assets upload ./path/to/app.apk \
  --channel dev \
  --tag 1.0.0
```

Prefer local emulators? See [Android emulators](/platforms/android/emulators)
for the `LOCAL_AVD_ID` / `LOCAL_APK_PATH` setup.

## 8. Write and run your first test

Open the local editor:

```bash theme={null}
npx momentic-mobile app
```

<Note>
  Mobile tests are authored in this local editor (`momentic-mobile app`), not in
  the web app. The cloud dashboard at [app.momentic.ai](https://app.momentic.ai)
  is for viewing results, a browser-based creator for mobile tests isn't
  available yet.
</Note>

Create a test, pick the `dev` channel and `1.0.0` tag, and author a single
natural-language step (for example, `Tap the Sign in button`). Save it (the
editor writes the `.test.yaml` to your project), run it from the editor to
verify, then run it from the CLI by name:

```bash theme={null}
npx momentic-mobile run <your-test-name>
```

## 9. Verify

* Check the `.test.yaml` you just authored exists in your project root
* Open the [dashboard](https://app.momentic.ai) and check **Runs** for the
  result

## 10. Next steps

<CardGroup cols={3}>
  <Card title="Android app setup" icon="mobile" href="/platforms/android/app-setup">
    WebView debugging, APK packaging, environment tooling
  </Card>

  <Card title="Emulators" icon="tablet-screen-button" href="/platforms/android/emulators">
    Local vs. remote emulators and regions
  </Card>

  <Card title="CI/CD" icon="play" href="/running-tests/ci/github-actions">
    Run mobile tests on every pull request
  </Card>
</CardGroup>

Need a full working example? Clone
[momentic-ai/examples](https://github.com/momentic-ai/examples/tree/main/android).