Maestro Testing: Mobile UI Automation With YAML Flows

What Is Maestro?

Maestro is an open-source UI automation framework for mobile and web apps. The Maestro documentation says it tests apps built with React Native, Flutter, or native code, runs tests without compilation, and waits for animations and network content on its own, so flows need no manual sleep() calls.

A flow is a declarative document. It names the application, lists the steps in order, and the runtime interprets that file against a connected device, emulator, simulator, or browser. Removing the programming language removes the project scaffolding with it.

Platform coverage is uneven, and the Maestro repository states the gap plainly: Android, iOS, and web apps are supported, but physical iOS devices are not yet supported. On your own machine that means Android phones and emulators, iOS simulators, and browsers.

Maestro sits at the end-to-end layer of mobile UI testing. It checks what a user sees and taps, so unit and API tests still cover internal state and backend logic.

Other Products Called Maestro

Search results for Maestro also return unrelated enterprise products that share the name:

Everything below refers to the testing framework.

How to Install Maestro

The Maestro CLI runs flows from a terminal or a CI job. Maestro Studio is a desktop app, with installers for Windows, macOS, and Linux, for building and running flows locally.

On macOS and Linux, the Maestro CLI install guide installs the CLI with one curl command and requires Java 17 or higher:

# Install the Maestro CLI
curl -fsSL "https://get.maestro.mobile.dev" | bash

# Confirm the CLI works and Java 17+ is on the path
maestro --help
java -version

On Windows, the same guide prefers the native route over WSL: download maestro.zip from the GitHub releases page, extract it, and add its bin folder to your PATH.

Local runs cost nothing. According to Maestro's pricing page, the free Local plan covers the CLI and Maestro Studio on your own devices, while paid plans add hosted devices and parallel runs on Maestro Cloud. If you are comparing hosted options, the Maestro alternative page sets them side by side.

Your First Flow

A flow has two parts separated by a document break (---): a header naming the application, and an ordered list of commands. This flow, taken from TestMu AI's Maestro sample repository, walks the Wikipedia Android app through its onboarding screens:

appId: org.wikipedia
---
- launchApp
- tapOn:
    id: "org.wikipedia:id/fragment_onboarding_forward_button"
- tapOn:
    id: "org.wikipedia:id/fragment_onboarding_forward_button"
- tapOn:
    id: "org.wikipedia:id/fragment_onboarding_forward_button"
- tapOn:
    id: "org.wikipedia:id/fragment_onboarding_done_button"

There are no imports, no driver configuration, and no build in that file. A flow that matches visible text instead of view ids reads even more plainly, which is what makes these files reviewable by people who never open an IDE:

appId: com.example.contacts
---
- launchApp
- tapOn: "Create new contact"
- tapOn: "First Name"
- inputText: "John"
- tapOn: "Last Name"
- inputText: "Snow"
- tapOn: "Save"
- assertVisible: "Add Phone Number"

Install the app on the device or emulator first, because Maestro launches it by appId but does not install it. Then run the file:

maestro test flow_contacts_android.yaml

Selectors and Commands

A small set of commands covers most flows:

Selector choice is where flows become durable or brittle. Matching by visible text is the fastest to write and breaks on the first copy change or the first localized build. Matching by view id survives both, and requires the application to expose meaningful identifiers, which is a development decision rather than a testing one. The same trade runs through software testability: how easily a system can be automated is decided before any test is written.

Conditions, Loops, and JavaScript in Maestro

Conditions attach to runFlow through a when block, and the Maestro conditions documentation lists visible, notVisible, platform, and true (a JavaScript expression) as the supported keys. This block dismisses a popup only when it appears:

- runFlow:
    when:
      visible: "Dismiss"
    commands:
      - tapOn: "Dismiss"

The platform key lets one file carry Android and iOS selectors side by side instead of maintaining two copies. Loops use repeat, which runs a block a fixed number of times or while a condition holds:

- repeat:
    times: 3
    commands:
      - tapOn: Button
      - scroll

JavaScript handles whatever YAML cannot express. runScript runs a .js file and evalScript runs an inline expression, both inside a sandbox with no file system access and no npm packages. The sandbox rules and the flow-ordering behavior that trips up larger suites are covered in depth in the Maestro mobile testing guide.

Maestro scripts can still reach your backend through a built-in HTTP client. The Maestro HTTP requests guide recommends seeding test data through your API before the UI steps, because setting it up through the UI is slow and flaky:

// seed_contact.js: create the contact through your API before the UI steps run
const response = http.post('https://staging-api.your-app.test/contacts', {
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ firstName: 'John', lastName: 'Snow' })
});
const contact = json(response.body);
output.contactName = contact.firstName;

appId: com.example.contacts
---
- runScript: seed_contact.js
- launchApp:
    clearState: true
- tapOn: "Search contacts"
- inputText: ${output.contactName}
- assertVisible: ${output.contactName}

The json() helper parses the response body, and any value stored on output is available to later commands as an expression. clearState wipes only the app's local data, so the contact created on the server is still there when the search runs.

Maestro vs Appium

Maestro testing and Appium both drive real mobile apps. The difference is how much of each test is code.

Maestro is faster to start and reaches its ceiling sooner. A team with no mobile automation gets more from ten Maestro flows written this week than from an Appium framework still being designed, while a team with a mature Appium suite gains little by porting it.

HyperExecute runs both frameworks, so the choice can be made per suite instead of once for the whole organization. For the wider field, see the roundup of Appium alternatives.

How to Run Maestro Tests on Real Devices

Locally, Maestro drives one device configuration at a time. Mobile defects cluster in the gaps between device models, OS versions, and screen sizes, so a suite that only runs on the handset on your desk tests the least interesting configuration you have.

TestMu AI runs Maestro on HyperExecute through its raw framework mode. One YAML config uploads the app, picks the devices, installs Maestro on the runner, and calls maestro test once per discovered flow. The HyperExecute Maestro documentation covers Android real devices, Android emulators, and iOS simulators, plus a dedicated runner script for iOS real devices.

This is the Android real-device config from TestMu AI's Maestro sample repository, with only the build name changed:

version: "0.2"
autosplit: true
concurrency: 2
runson: android
dynamicAllocation: true

runtime:
  - language: java
    version: "21"

framework:
  name: raw
  args:
    devices: ["Pixel 6-14"]
    video: true
    deviceLog: true
    appPath: maestro-test/sample.apk
    buildName: maestro-real-device
    queueTimeout: 600
    region: ap
    disableReleaseDevice: true
    isRealMobile: true
    reservation: false
    network: true
    platformName: android

env:
  MAESTRO: true
  MAESTRO_LOGS_DIR: MaestroLogs

pre:
  - chmod +x ./maestro-test/setup-script.sh
  - chmod +x ./maestro-test/runTest.sh
  - ./maestro-test/setup-script.sh

testDiscovery:
  command: cat ./maestro-test/discover.txt
  mode: static
  type: raw

testRunnerCommand: ./maestro-test/runTest.sh $test

frameworkStatusOnly: true

report: true
partialReports:
  - location: .
    type: xml
    frameworkName: junit

The pre step runs setup-script.sh, which updates adb and installs Maestro on the runner (the script pins Maestro 2.6.1). testRunnerCommand then hands each flow listed in discover.txt to runTest.sh, which stays deliberately thin:

#!/bin/bash
adb devices
/home/ltuser/.maestro/bin/maestro -v
/home/ltuser/.maestro/bin/maestro test $1 --debug-output ./MaestroLogs --format junit

Trigger the job from the repository root with the HyperExecute CLI:

./hyperexecute --user USERNAME --key ACCESS_KEY --config hyperexecute.yaml

Run it against the sample and the CLI prints the execution plan, uploads the APK, and reports each stage as it finishes. Trimmed output from a passing run on the requested Pixel 6:

Execution Plan
Mode:    autosplit
Runson:    android
Concurrency:    2
Unique Id for App - lt://APP10160161391793000247554808
Test Discovery Result: 2
yaml/android/android-swipe1.yaml
yaml/android/android-launch.yaml
Job e6e456c9-7e48-468f-b3a8-72876b84526f has INITIATED
✔ [2]  pre (14s)
✔ [2]  discovery (2s)
✔ [2]  yaml/android/android-swipe1.yaml (59s)
✔ [2]  yaml/android/android-launch.yaml (32s)
✔ [1]  pre (2m25s)
✔ [1]  discovery (1s)
COMPLETED
Test Execution Time:                  1m6s
Job Duration Time:                    3m4s
Total Tasks:                          2
Failed Tasks:                         0

Each flow's own log shows the device adb sees, the Maestro version the setup script installed, and the result:

List of devices attached
19041FDF60006W	device
2.6.1
Waiting for flows to complete...
[Passed] android-swipe1 (15s)
1/1 Flow Passed in 15s

Autosplit sends each flow to whichever task is ready first. Task 2 finished its pre stage in 14 seconds and ran both flows while task 1 was still installing Maestro, so on a small suite one device can end up doing all the work. Extra concurrency only pays off once the suite takes longer to run than the pre stage.

For emulators, the sample's emulator config sets isRealMobile: false and switches the runner to runTest_android_emulator.sh. To launch an app that is already on the device instead of an uploaded build, set appId: stock under framework.args and name the package in the flow.

Reports and Debugging

The --format junit flag in runTest.sh makes Maestro write a JUnit XML report, the format every CI system and most test management tools already read. On HyperExecute, partialReports collects those files into the job report. When one task runs several flows, each run overwrites report.xml, so rename the file after every flow in testRunnerCommand. Without it, the sample run's job report lists only android-launch, the last flow that task executed:

testRunnerCommand: ./maestro-test/runTest.sh $test && mv report.xml $test.xml

Debugging a mobile failure needs more than a stack trace, because the useful question is what was on screen. --debug-output keeps Maestro's logs and screenshots, and with video and deviceLog switched on, every HyperExecute task also carries a screen recording and the device log. That is what turns a failure that only reproduces on one device model into something a developer without that handset can act on.

When a flow fails, HyperExecute's AI root cause analysis reads Maestro flow execution logs and device interaction logs alongside the command logs, and separates the primary cause from the failures that cascade from it. Feed the JUnit output into a test management platform to keep history across runs: a single failing flow is a defect, while the same flow failing on one device family for three weeks is a pattern worth its own ticket.

Maestro Limitations

• Physical iPhones - The open-source CLI does not run flows on physical iOS devices, so local iOS coverage stops at simulators.
• Sandboxed JavaScript - Scripts cannot read fixture files or import npm packages, so data-driven suites pass data in through HTTP calls or environment variables.
• Flow order - Maestro runs discovered flows in a non-deterministic order by default, so flows that depend on each other need an explicit execution order in the workspace config.
• Cross-platform selectors - Commands are shared between Android and iOS, but view ids and accessibility identifiers usually are not, so one flow rarely runs on both without platform conditions.
• Deep assertions - A flow sees only the screen. Checking that a value persisted correctly in the backend stays the job of API-level tests.

Teams that get the most from Maestro use it for the journeys that must never break and keep a programmable framework for suites that need heavy data setup and custom logic.

Conclusion

Pick the one journey whose breakage would hurt most and write it as a flow today: launch, navigate, and assert one thing that proves the journey worked. If that takes longer than an hour, the obstacle is your app's selectors, and that is worth knowing on its own.

Then run it on hardware your users hold. TestMu AI's real device cloud supplies the Android devices, and the HyperExecute getting started guide sets up the CLI and credentials the sample config needs.

Testing from the terminal? Kane CLI by TestMu AI lets SDETs and developers plan, write, run and debug tests from the command line.

To run your first test, start free, or

book a demo

for a full walkthrough of the product.