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

# App setup

> Install the tools Android testing needs, package your APK, and enable WebView debugging.

Momentic supports Android apps running on **local** and **remote emulators**.
Real devices are not supported.

## Prerequisites

For **remote emulators**:

* **Node.js** 22.12.0+ or 24.0.0+
* **Android SDK platform-tools** (adb), with `ANDROID_HOME` exported and
  pointing at the SDK directory that contains `platform-tools/adb`
* An APK to upload

Remote emulators connect through a local adb tunnel, so adb is required even
though the emulator itself runs on Momentic's infrastructure. Only the
platform-tools are needed: Android Studio, Java, and a local emulator image are
not.

<Warning>
  adb on your `PATH` alone is not enough. Export `ANDROID_HOME` as well, or the
  run fails at driver startup with `Neither ANDROID_HOME nor ANDROID_SDK_ROOT
      environment variable was exported`.
</Warning>

For **local emulators**, add:

* **Java JDK** 24 (or later)
* **Android Studio** (latest stable) with platform-tools and emulator components

### Install Node.js

Download from [nodejs.org](https://nodejs.org/en/download).

```bash theme={null}
node -v  # v22.12.0 or higher
```

### Install adb

Download the
[Android SDK platform-tools](https://developer.android.com/tools/releases/platform-tools)
and unzip them into an SDK directory, then export `ANDROID_HOME` at that
directory (not at `platform-tools` itself):

```bash theme={null}
mkdir -p "$HOME/Android/sdk"
unzip platform-tools-latest-darwin.zip -d "$HOME/Android/sdk" # or -linux / -windows
echo 'export ANDROID_HOME="$HOME/Android/sdk"' >> ~/.zshrc
echo 'export PATH="$ANDROID_HOME/platform-tools:$PATH"' >> ~/.zshrc
source ~/.zshrc
adb --version
```

If you already have Android Studio, platform-tools come with its SDK; export
`ANDROID_HOME` at that SDK instead (see
[Set `ANDROID_HOME`](#set-android_home)).

<Warning>
  `brew install --cask android-platform-tools` puts adb on your `PATH` but
  creates no SDK directory, so `ANDROID_HOME` has nothing valid to point at. Use
  the zip above, or pair the cask with an SDK layout.
</Warning>

### Install Java

Java is only needed for local emulators. Download
[JDK 24](https://www.oracle.com/java/technologies/downloads/) from Oracle.

```bash theme={null}
java --version  # JDK 24
```

<Info>
  If `java --version` isn't found, re-open your terminal or make sure
  `JAVA_HOME/bin` is on your `PATH`.
</Info>

### Install Android Studio

Android Studio is only needed for local emulators. Download
[Android Studio](https://developer.android.com/studio) and complete the
first-run setup. Include:

* Android SDK Platform-Tools (ADB)
* Android Emulator

### Set `ANDROID_HOME`

Point `ANDROID_HOME` at your Android SDK install. Typical locations:

* macOS: `/Users/<username>/Library/Android/sdk`
* Linux: `/home/<username>/Android/Sdk`
* Windows: `C:\Users\<username>\AppData\Local\Android\Sdk`

<Tabs>
  <Tab title="macOS (zsh)">
    ```bash theme={null}
    echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc
    echo 'export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="Linux (bash/zsh)">
    ```bash theme={null}
    echo 'export ANDROID_HOME="$HOME/Android/Sdk"' >> ~/.bashrc
    echo 'export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Windows">
    Follow the [official guide](https://developer.android.com/tools/variables) to
    set `ANDROID_HOME` in System Properties, then restart your shell.
  </Tab>
</Tabs>

### Verify

```bash theme={null}
node -v              # v22.12.0 or higher
adb --version        # required for remote and local emulators
echo $ANDROID_HOME   # must print an SDK path containing platform-tools/adb
java --version       # JDK 24, local emulators only
```

## Enable WebView debugging

If your app renders content inside an Android `WebView`, enable WebView
debugging so Momentic can attach and interact with elements inside the WebView.

Add this to your app's startup code, before the `WebView` is used:

```java theme={null}
WebView.setWebContentsDebuggingEnabled(true);
```

<Warning>
  Without this, interactions against WebView elements fail with
  `InternalWebAgentError: No browser controller is attached to the requested
      webview.`
</Warning>

## APK requirements

* Debug builds with `debuggable=true` work without extra configuration.
* Release builds must enable WebView debugging as above if they contain WebView
  content.
* Both ARM64 and x86\_64 APKs are supported. Remote emulators use x86\_64.

## Next steps

<CardGroup cols={2}>
  <Card title="Emulators" icon="tablet-screen-button" href="/docs/platforms/android/emulators">
    Local vs. remote emulators and regions
  </Card>

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