Write UI Tests Without the Pain: Maestro Uses YAML Flows and Eliminates Sleep Calls

You've probably written a mobile UI test that looks reasonable, only to watch it fail because a button hadn't finished animating before your test tried to tap it. The fix? Sprinkle in some sleep(2000) calls and hope for the best. It works until it doesn't—and then you're debugging flaky tests at 11 PM. Maestro is an open-source framework that takes a different approach: you write your tests in YAML, and its execution engine handles the waiting automatically. No sleep calls, no flaky timing issues, just straightforward test flows that work across Android, iOS, and web.

What It Does

Maestro is a cross-platform UI testing framework that lets you write end-to-end tests for mobile and web applications using YAML files. It works on Android, iOS, and web apps—including React Native, Flutter, and hybrid apps—and runs on emulators, simulators, or physical devices. The tests are "flows" composed of simple commands like launchApp, tapOn, inputText, and assertVisible.

The architecture is straightforward: you write a YAML file describing the steps a user would take, and Maestro's interpreted execution engine runs those steps against your app. Because the flows are interpreted rather than compiled, you can iterate quickly without waiting for builds. Installation is a single curl command, and the only prerequisite is Java 17 or higher.

The key design decision here is that Maestro handles waiting internally. Instead of you guessing how long an element will take to appear, the framework watches the UI and proceeds when conditions are met. This is built into the execution engine, not bolted on as an afterthought.

Why It's Cool

The most immediately useful feature is the elimination of sleep calls. If you've ever maintained a test suite with hardcoded waits, you know the pain: too short and tests fail intermittently, too long and your suite takes forever. Maestro's smart waiting means tests are both faster and more reliable without you having to tune timing values.

The YAML format is surprisingly practical. A test that might take twenty lines of Java or Kotlin becomes five lines of YAML:

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

This readability matters when non-engineers need to understand what a test does, or when you're reviewing test coverage with the team. The flow is the documentation.

Cross-platform coverage is another strong point. You write one test and run it on Android and iOS. The same YAML file works for both platforms because Maestro abstracts away the platform-specific testing APIs. This is particularly valuable for teams building with React Native or Flutter, where you're already sharing code across platforms—now you can share tests too.

The project was built on learnings from its predecessors (Appium, Espresso, UIAutomator, XCTest, Selenium, Playwright) and it shows. The install is a single command, the test format is human-readable, and the execution engine handles the complexity that other frameworks force you to manage yourself.

There's also Maestro Studio, a free desktop IDE that lets you design and run tests visually without touching the terminal. It's not open-source, but it's free and integrates with the open-source CLI.

How to Try It

Getting started takes about five minutes. First, make sure you have Java 17 or higher:

java -version

Then install the CLI with a single command:

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

From there, the documentation guides you through building and installing your app, running a sample flow, and writing your first test. The repository is at github.com/mobile-dev-inc/Maestro if you want to browse the source or contribute.

Final Thoughts

Maestro is a practical tool for a common problem. If you're building mobile apps and spending too much time maintaining flaky UI tests, it's worth a look. The YAML approach won't suit every testing scenario—complex conditional logic is easier in a general-purpose language—but for the common case of testing user flows, it's cleaner than the alternatives. The project is Apache 2.0 licensed, and the community is active on Slack if you run into issues.

Follow @githubprojects for more developer tools and open source projects.