Skip to main content
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.

​
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. 
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:

Set up Momentic for an Android project end to end via the onboarding wizard, non-interactively.

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

​
1. Prerequisites

  • Node.js 22.12.0+ or 24.0.0+
  • Java JDK 24 (or later)
  • Android Studio with platform tools and emulator components
  • An APK of your app (see App setup)
  • A Momentic account, sign up to generate an API key
node -v          # need 22.12.0+ or 24.0.0+
java --version   # JDK 24
echo $ANDROID_HOME
See App setup for a full walkthrough of installing Java, Android Studio, and setting ANDROID_HOME.

​
2. Install

npm install --save-dev momentic-mobile

​
3. Authenticate

Option A: sign in with your browser (recommended): 
npx @momentic/wizard login
This opens a browser-based login flow and saves credentials to ~/.momentic/auth.json. Both CLIs automatically use this file when MOMENTIC_API_KEY is not set. Option B: use an API key: Create an API key in the dashboard, then export it: 
export MOMENTIC_API_KEY=your-api-key-here

​
4. Initialize

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 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; for more cross-platform detail see Cross-platform frameworks. 
./gradlew assembleRelease
# APK in app/build/outputs/apk/release/

​
6. Install browsers

Momentic uses a headless browser to automate Android WebViews: 
npx momentic-mobile install-browsers chromium
If your app renders content inside an Android WebView, enable WebView debugging so Momentic can attach: WebView.setWebContentsDebuggingEnabled(true). See Android app setup for details.

​
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: 
npx momentic-mobile assets upload ./path/to/app.apk \
  --channel dev \
  --tag 1.0.0
Prefer local emulators? See Android emulators for the LOCAL_AVD_ID / LOCAL_APK_PATH setup.

​
8. Write and run your first test

Open the local editor: 
npx momentic-mobile app
Mobile tests are authored in this local editor (momentic-mobile app), not in the web app. The cloud dashboard at app.momentic.ai is for viewing results, a browser-based creator for mobile tests isn’t available yet.
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: 
npx momentic-mobile run <your-test-name>

​
9. Verify

  • Check the .test.yaml you just authored exists in your project root
  • Open the dashboard and check Runs for the result

​
10. Next steps

Android app setup

WebView debugging, APK packaging, environment tooling

Emulators

Local vs. remote emulators and regions

CI/CD

Run mobile tests on every pull request
Need a full working example? Clone momentic-ai/examples.