Testing on simulators and emulators with Maestro¶
Maestro is an open-source tool (Apache 2.0) for automating mobile apps. It can launch the app on an iOS simulator or Android emulator, tap buttons by their text, type, swipe, check what is on screen and take screenshots. Steps are written as short YAML files called flows.
It is useful for checking native behaviour that a browser preview can't show (safe areas, pop-ups, orientation, platform differences), and for repeating the same checks after each change. Maestro also has a built-in MCP server, so an AI coding assistant can drive the app too: "run the app on the iOS simulator and check X" becomes a single request.
Maestro runs on your own machine against local simulators and emulators. It needs no account, and nothing about it is built into the app. iOS is supported on simulators only, not real devices.
Install¶
Maestro needs Java 17 or newer. See also Maestro's own installation guide.
With [Homebrew](https://brew.sh/), which also installs Java:
```sh
brew tap mobile-dev-inc/tap
brew install mobile-dev-inc/tap/maestro
To opt out of Maestro's usage analytics, add export MAESTRO_CLI_NO_ANALYTICS=1 to your shell profile.
=== "Windows (untested)"
- Install Java 17 or newer (Android Studio's bundled JDK works) and set
JAVA_HOMEto it. - Download maestro.zip
and extract it to a stable location, e.g.
C:\maestro. -
Add its
binfolder to your userPATH, in PowerShell:[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\maestro\bin", "User") -
Open a new terminal and check with
maestro --help.
To opt out of usage analytics, set the user environment variable MAESTRO_CLI_NO_ANALYTICS to 1.
=== "Linux (untested)"
JAVA_HOME set:
curl -fsSL "https://get.maestro.mobile.dev" | bash
This installs to ~/.maestro/bin; add that to your PATH. To opt out of usage analytics, add
export MAESTRO_CLI_NO_ANALYTICS=1 to your shell profile.
You also need what native builds need:
- **iOS (macOS only):** Xcode and CocoaPods, as in
[Building and deploying to iOS](./building-and-deploying-to-ios.md).
- **Android:** the Android SDK and an emulator (from Android Studio's device manager), and JDK 21 for Gradle.
The build also expects the deployment's `google-services.json` in `android/app/` (download it from the
Firebase console). Without it, the build still succeeds but leaves out Firebase.
## Build the app
Maestro tests an installed app, so every change to the web code needs a full native rebuild. Use **debug
builds** (see [Known issues](#known-issues) for why this matters on Android).
!!! note "Debug builds vs the `debug` deployment"
assembleDebug, an APK that can be installed directly and inspected with developer tools, like
the one the on-device testing workflow produces) and release (bundleRelease,
signed for the Play Store). iOS has matching Debug and Release configurations in Xcode.
The debug deployment is a set of content (app-debug-content) used to try out components and
features. Any deployment can be built as a debug or a release build, and the debug deployment can be
built either way too.
```sh
yarn workflow deployment set <name>
yarn workflow android configure && yarn workflow ios configure # after switching deployment
yarn build
npx cap sync
```sh
cd android && JAVA_HOME=$(/usr/libexec/java_home -v 21) ./gradlew :app:assembleDebug && cd ..
adb -s emulator-5554 install -r android/app/build/outputs/apk/debug/app-debug.apk
You can also build the debug APK from Android Studio's Build menu.
=== "iOS simulator"
xcodebuild -workspace ios/App/App.xcworkspace -scheme App -configuration Debug \
-destination 'generic/platform=iOS Simulator' -derivedDataPath /tmp/oab-ios \
CODE_SIGNING_ALLOWED=NO build
xcrun simctl install <simulator-udid> "/tmp/oab-ios/Build/Products/Debug-iphonesimulator/<App name>.app"
No signing is needed for a simulator build. maestro list-devices shows the udid.
## Run flows
Flows depend on a deployment's content (the text on its buttons, its launch pop-ups), so they live in the
**deployment's repo**, in a `.maestro/` folder. For example, the `debug` deployment
([app-debug-content](https://github.com/IDEMSInternational/app-debug-content)) has a smoke flow,
`.maestro/smoke.yaml`: it launches the app fresh, uses the launch pop-up, closes it and opens the Templates
page, taking a screenshot at each stage.
From the open-app-builder root:
```sh
# Android
maestro --device emulator-5554 test .idems_app/deployments/debug/.maestro/smoke.yaml
# iOS: the app id differs between platforms, so pass it in
maestro --device <simulator-udid> test -e APP_ID=international.idems.debug-app \
.idems_app/deployments/debug/.maestro/smoke.yaml
--deviceis needed whenever more than one simulator or emulator is running;maestro list-devicesshows their ids.- Screenshots go to
~/.maestro/tests/<timestamp>/<flow>/takeScreenshot/, or to the folder given by--test-output-dir. - The app ids are
android.app_idandios.app_idin the deployment'sconfig.ts. Flows default to the Android one:appId: ${APP_ID || "<android app id>"}. Avoid anenv:block for this default, as it overrides values passed in through the MCP server.
To write a flow, see Maestro's commands reference.
Target elements by their visible text (tapOn: "Templates"); the text must match in full. The MCP server's
inspect_screen tool (below) is a good way to find the exact text.
Use it from an AI assistant (MCP)¶
Maestro's MCP server comes with the CLI. Register it once with your assistant, for example in Claude Code:
claude mcp add --scope user maestro -- maestro mcp
Other MCP clients use the same command (maestro mcp). The assistant then has these tools:
| Tool | What it does |
|---|---|
list_devices |
Lists local simulators and emulators (and their ids) |
inspect_screen |
Returns the elements on screen, with their text and positions |
take_screenshot |
Takes a screenshot of the current screen |
run |
Runs Maestro commands (inline YAML) or flow files |
cheat_sheet |
Maestro command reference |
The repo's assistant skill (.claude/skills/maestro/SKILL.md) covers the build steps and the issues below,
so an assistant can build, install and drive the app on request.
Don't mix the CLI and the MCP server on one device
Running the `maestro` CLI on a device replaces the driver the MCP server installed there. After that,
every MCP call on that device fails ("Device server died", or "Device became unreachable") until the MCP
server is reconnected in your assistant.
When the MCP server runs a flow, any takeScreenshot files are saved in the server's working directory,
usually the repo root. Delete them rather than committing them.
Known issues¶
Verified with Maestro 2.12.1 in November 2026.
Android: taps on a pop-up opened during app launch miss. If the Android WebView builds its accessibility information while Ionic's pop-up animation is running (pop-ups slide up from 40px below), it keeps those positions after the animation ends. Maestro then sees the pop-up's buttons about 40 CSS pixels below where they are drawn, and taps land below them. Waiting does not help. Page navigation and pop-ups opened later by a tap were not affected.
The app works around this in debug builds on Android only: after a pop-up opens, it briefly changes the
pop-up's layout, which makes the WebView recompute positions (refreshAndroidModalAccessibilityBounds in
src/app/app.component.ts). Release builds don't include it, so run Maestro against debug builds.
iOS: content is visible behind the splash screen. Maestro sees the app's content while the native splash
screen is still covering it, so a flow can find text and then tap the splash. After launchApp, wait for
the splash to go:
- extendedWaitUntil:
notVisible:
id: "Splash"
timeout: 30000
iOS simulator: "Apple Account Verification" alert. The simulator may show this system alert over the app. Dismiss it with an optional tap:
- tapOn:
text: "Not Now"
optional: true
maestro hierarchy doesn't show web content on Android. The standalone command only shows the native
views. Flows and the MCP server's inspect_screen do see the web content.