Exit course
Chapter 1 of 10 Beginner 5 min read Updated

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

  1. Maestro Tutorial: Mobile UI Tests in YAML
  2. Install Maestro and Run Your First Flow
  3. Maestro Selectors and Core Commands
  4. Subflows, Conditions, Loops and JavaScript
  5. iOS vs Android: Permissions, State, Links
  6. Debugging Flaky Maestro Flows
  7. Organising a Maestro Suite
  8. Run Maestro Flows on TestingBot
  9. Running Maestro in CI Pipelines
  10. Knowledge check
On this page
  1. How Maestro sees your app
  2. Waiting and tolerance are built in
  3. How it compares to Appium, Espresso and XCUITest
  4. What you'll build / prerequisites

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 matches Login. 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.