Maestro Tutorial: Mobile UI Tests in YAML
Learn Maestro from your first YAML flow to a tagged suite running in CI on real iOS and Android devices. Hands-on, free, with a knowledge check.
What you will learn
- Maestro Tutorial: Mobile UI Tests in YAML
- Install Maestro and Run Your First Flow
- Maestro Selectors and Core Commands
- Subflows, Conditions, Loops and JavaScript
- iOS vs Android: Permissions, State, Links
- Debugging Flaky Maestro Flows
- Organising a Maestro Suite
- Run Maestro Flows on TestingBot
- Running Maestro in CI Pipelines
- Knowledge check
On this page
Last reviewed November 2026 against Maestro CLI 2.12.1 and the TestingBot CLI (@testingbot/cli) 1.5.0.
Maestro is an open-source UI automation framework for Android and iOS apps (and, more recently, web apps). You describe a user journey, such as "log in" or "add an item to the basket", as a list of steps in a YAML file called a flow, and the Maestro CLI plays those steps on an emulator, a simulator or a device.
Here is a complete flow. It drives the TestingBot sample app, a tiny calculator that adds two numbers, and you will run it yourself in chapter 1:
appId: org.reactjs.native.example.SampleApp
---
- launchApp
- tapOn:
id: inputA
point: "90%,50%"
- eraseText
- inputText: "10"
- tapOn:
id: inputB
point: "90%,50%"
- eraseText
- inputText: "5"
- assertVisible: "15"
The part above --- is the flow's configuration: which app it targets, plus optional tags, variables and hooks. Below it is a list of commands. There is no compile step, no test runner to configure and no driver session to create. (The point lines are there for a reason; chapter 2 explains the bug they fix.)
How Maestro sees your app#
Maestro works "at arm's length". It does not link into your app or need its source code. It reads the screen through the platform's accessibility layer, the same view hierarchy that screen readers use, and it sends real touch events through the operating system. That has three practical consequences:
- It is framework-agnostic. A React Native, Flutter, Jetpack Compose, SwiftUI or UIKit app all look the same to Maestro: a tree of elements with text, ids and bounds.
-
Your selectors are what the user sees, or the ids you exposed for accessibility.
tapOn: "Login"finds an element whose text matchesLogin.id:matches the Android resource id or the iOS accessibility identifier. - It can leave your app. System permission dialogs, Settings, a browser opened by a link: Maestro pilots the device, not just your process.
Waiting and tolerance are built in#
The biggest day-to-day difference from older tools is timing. Maestro waits for the UI to settle after each action, and assertions poll instead of checking once. assertVisible keeps looking for its element for a few seconds before it fails, so the sum in the flow above can take a moment to render without any sleep. For genuinely slow screens, such as a payment that takes 20 seconds, there is extendedWaitUntil with an explicit timeout. Chapter 5 covers what to do when the defaults are not enough.
How it compares to Appium, Espresso and XCUITest#
Choosing a mobile framework is a set of tradeoffs, not a ranking. A short, honest comparison:
| Maestro | Appium | Espresso / XCUITest | |
|---|---|---|---|
| Test language | YAML, plus JavaScript for logic | Any WebDriver client (Java, JS, Python, ...) | Kotlin/Java (Espresso), Swift/Obj-C (XCUITest) |
| Platforms per test | Android and iOS from one flow, if ids match | Android and iOS, separate drivers | One platform each |
| Access to the app | Black box via accessibility | Black box via platform drivers | Runs inside or beside the app, with the platform's own synchronisation |
| Protocol | Its own; not W3C WebDriver | W3C WebDriver | Native test runners |
| Feedback loop | Edit and re-run, no build | Re-run the client code | Rebuild the test APK or test bundle |
Where Maestro is strong: end-to-end user journeys, cross-platform teams, QA engineers who do not want to maintain a Java or Swift test project, and suites that must survive UI refactors. Where it is weaker: anything that needs white-box access (mocking a class, reading app state directly), complex programmatic logic (you get a JavaScript sandbox, not a full language and its package ecosystem), and existing WebDriver tooling, which does not apply because Maestro does not speak WebDriver. Espresso and XCUITest remain the fastest feedback for component-level UI tests owned by app developers. Many teams run Maestro journeys alongside them rather than instead of them; if you are weighing the other options, the comparisons of Appium vs Espresso and Appium vs XCUITest cover that side.
What you'll build / prerequisites#
Over eight chapters you will build a small, tagged Maestro suite for the TestingBot sample app (Android .apk and iOS simulator build, both public downloads), run it locally, then run it unchanged on cloud devices and from a GitHub Actions workflow.
You need:
- Java 17 or newer (the Maestro CLI runs on the JVM).
- For Android: Android Studio with an emulator, or a USB device with debugging enabled.
- For iOS: a Mac with Xcode and the Xcode command line tools, for the iOS Simulator.
- For chapters 7 and 8: Node.js (for the TestingBot CLI) and a TestingBot account. The Maestro product overview explains what the cloud side offers.
No programming background is required for the first four chapters. Basic shell and YAML familiarity helps.