Maestro: YAML-driven UI testing for Android, iOS and web

The gap Maestro fills between compiled test frameworks and driver stacks

Most mobile E2E stacks ask you to pick a side. Espresso and XCTest keep tests inside the app's own build, which ties the test language to the platform and the test suite to the app repository. Appium and Selenium sit outside the app but need a driver, a server process and a client library before the first assertion runs. Maestro takes a third position: it talks to the app through the platform's accessibility layer, ships as a single binary, and treats a test as a flat list of YAML commands. The README names those three decisions directly, and lists Appium, Espresso, UIAutomator, XCTest, Selenium and Playwright as the predecessors it learned from.

The audience follows from that. If you write flows for React Native, Flutter, native iOS, native Android, Ionic or hybrid apps and want the same command vocabulary across all of them, Maestro is aimed at you. The README notes that Meta uses Maestro to test React Native itself and that Expo supports it as its preferred E2E platform. Those are claims from the project, not independent measurements, and they say nothing about how it will behave on your app.

How a Maestro flow is interpreted and executed

A flow file has two parts separated by a line of three hyphens. Above the separator sits the header, which carries keys such as appId. Below it sits the command list, one command per line. The README's contacts example uses launchApp, tapOn, inputText and assertVisible, with tapOn taking either a visible string or a field name.

There is no compilation step. Flows are interpreted, so the file you edit is the file that runs, and the runner resolves each command against the current screen at execution time rather than against a recorded element tree. That is the mechanism behind the README's claim of built-in flakiness tolerance and automatic waiting: instead of inserting sleep calls, the runner waits for the target to become actionable. The trade-off is real. Because commands are resolved by visible text or accessibility labels, a copy change in the app can break a flow that a selector-based framework would survive, and the failure appears at runtime rather than at build time.

The device side is a live target: an emulator, a simulator, a browser or a physical Android device. Maestro Viewer embeds that device inside a coding agent so each MCP command is visible as it runs. The MCP server ships inside the CLI itself, which the README frames as nothing else to install beyond the CLI.

Installing Maestro and running a first flow

Maestro requires Java 17 or higher. Check that before anything else, because the installer will not fix a missing or outdated JDK for you.

java -version

The output should report version 17 or later. On macOS, Linux or Windows under WSL, the documented install is a single piped script, which is the same line the README gives.

curl -fsSL "https://get.maestro.mobile.dev" | bash

For a regular Windows installation, the README points to the installing Maestro page in the docs rather than to this command. Once the CLI is on the PATH, a flow is just a file. Save this as flow_contacts_android.yaml, keeping the header, the separator and the command list in that order.

appId: com.android.contacts
---
- launchApp
- tapOn: "Create new contact"
- tapOn: "First Name"
- inputText: "John"
- tapOn: "Last Name"
- inputText: "Snow"
- tapOn: "Save"

Run it with the CLI against a booted emulator and the commands execute in order, each one waiting for its target to appear. If you would rather not hand-write the file, the README offers two other entry points: build flows visually in Maestro Studio, or add Maestro MCP to a coding agent and ask it for an end-to-end flow, which it writes as YAML, runs until it passes, and leaves in the repository.

Physical iOS devices and other places Maestro is the wrong tool

The README is explicit that physical iOS devices are not yet supported. Flows run on emulators, simulators, browsers and physical Android devices. If your QA process signs off on real iPhones, Maestro cannot be the only tool in that pipeline, and no amount of YAML will change it.

Two smaller constraints follow from the design. Text-based targeting couples flows to the visible interface, so an app with heavy custom drawing, canvas-rendered content or sparse accessibility labels gives the runner little to resolve against; the accessibility layer is the contract, and an app that does not expose itself through it is a poor fit. Second, the interpreted model means a broken flow is discovered when it runs. Teams used to a compiler catching a renamed page object will need that check to come from CI instead.

Finally, Maestro Studio is not in this repository. The README states plainly that Studio is free but not open source, so anyone evaluating the project for a fully open source toolchain should treat the visual IDE as a separate product with its own terms. Maestro Cloud is likewise a commercial service with a pricing page and a seven-day trial, not part of the Apache-2.0 code.

How Maestro differs from Appium and from in-app frameworks

Appium is the closest comparison in scope: both drive apps from outside the binary and both target multiple platforms. The difference is what sits between the test and the device. Appium routes commands through WebDriver and platform-specific drivers, which means a server process, driver versions and a client library in whatever language you choose. Maestro removes that layer entirely: one binary, no drivers, no SDK, no dependencies, and the test file is data rather than code. The cost of that simplification is control. Appium exposes the full WebDriver surface and lets you drop into native APIs when a flow needs it; Maestro gives you a fixed command vocabulary and expects the accessibility layer to carry the interaction.

Against Espresso and XCTest the split is different again. Those run inside the app process with direct access to its internals, which makes them fast and precise but platform-specific and awkward to reuse across a React Native or Flutter codebase. Maestro's framework-agnostic claim rests on the same commands working for native, React Native, Flutter, Ionic and hybrid apps. The honest framing is that Maestro trades depth of access for uniformity of syntax, and that trade is worth it only if you value one flow format across several app types.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-09-18, three days before this was written. Recent releases are cli-2.10.0 on 2026-08-31, cli-2.9.0 on 2026-08-26 and cli-2.8.0 on 2026-07-31, so the CLI is shipping on a roughly monthly cadence. The repository layout is a multi-module Gradle build: maestro-cli, maestro-android, maestro-ios, maestro-ios-driver, maestro-ios-xctest-runner, maestro-web, maestro-orchestra, maestro-orchestra-models, maestro-proto, maestro-client, maestro-ai, maestro-test and maestro-utils, alongside build.gradle.kts, settings.gradle.kts and the Gradle wrapper. That is a large surface for a tool whose flows are meant to be simple, and it explains why the CLI can bundle an MCP server and an iOS XCTest runner without extra installs.

Upgrade cost is mostly about the CLI version rather than your flow files, since flows are interpreted and there is no compile step to break. The README does not document rollback or a compatibility policy between CLI releases, so pinning a known version in CI is the practical way to keep a suite stable. The licence is Apache-2.0, which permits commercial and closed-source use with the usual notice and attribution conditions. That covers the code in this repository only. Maestro Studio and Maestro Cloud are separate offerings with their own terms, and the README does not state their licensing, so read those before assuming a single agreement covers everything you install.

Editorial conclusion

Adopt Maestro if your team writes E2E flows for Android emulators, iOS simulators or browsers and wants them stored as reviewable YAML rather than compiled test code, and if a single binary install with no drivers fits your CI image. Do not adopt it if your release process depends on physical iOS devices, since the README states those are not yet supported, or if you need Studio's visual editor under an open source licence, because Studio is not part of this repository. Before committing, verify two things on your own machines: that Java 17 or higher is present, and that the device target you care about appears in the list of supported targets in the README.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mobile-dev-inc/Maestro on GitHub
3. Project website
4. README
5. Releases