Maestro Testing: Mobile UI Automation With YAML Flows

What Is Maestro?

Maestro testing is built on one idea: a test is a declarative YAML document rather than a program. You state which application the flow applies to, then list the steps in order. The runtime interprets that file against a connected device or emulator.

The design choice underneath is that mobile UI tests are mostly sequences of taps, inputs, and assertions, and that expressing those in a general-purpose language costs more than it returns for the common case. Removing the language removes the project scaffolding with it.

The second design choice matters more in practice. Every command waits for the interface to be ready before acting, rather than executing immediately and leaving the author to guess at sleeps. Hand-written mobile automation accumulates fixed waits precisely because that guessing is hard, and those waits are what make suites slow and flaky at the same time.

Which Maestro You Mean

Worth settling early, because searching for this tool returns two unrelated products and a great deal of music software.

The two share a word and nothing else. Everything below refers to the mobile testing framework.

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 one walks the Wikipedia 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"

That is the whole test. No imports, no driver configuration, no build. A flow using visible text instead of view ids reads even more plainly, which is what makes these files reviewable by people who will 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"

Run it against an attached device or emulator with a single command. The framework resolves the app, installs it if needed, and executes the steps in order.

maestro test flow_contacts_android.yaml

Selectors and Commands

The command vocabulary is deliberately small. These cover the overwhelming majority of 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 localised 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 trade is the same one covered in software testability: how easily a system can be automated is decided before any test is written.

Maestro vs Appium

Maestro testing and Appium both drive real mobile applications, and they suit different teams rather than ranking against each other.

The honest summary is that Maestro is faster to start and hits a ceiling sooner. A team with no mobile automation at all gets more value from ten Maestro flows written this week than from an Appium framework that is still being designed. A team already running a mature Appium suite gains little by porting it. Both frameworks execute on the same infrastructure, so the choice does not have to be made once and forever.

Running on Real Devices

Locally, Maestro drives whatever is plugged in or emulated, which is one device configuration. Mobile defects concentrate in the gaps between device models, OS versions, and screen sizes, so a suite that only ever runs on one handset is testing the least interesting configuration you have.

Running the same flows on TestMu AI covers that spread across 10,000+ real devices without owning any of them. Maestro executes through HyperExecute, and the whole run is described by one configuration file. Upload the build first and keep the returned identifier:

curl -u "USERNAME:AccessKey" -X POST \
  "https://manual-api.lambdatest.com/app/upload/realDevice" \
  -F "appFile=@/path/to/your/app.apk" \
  -F "name=sampleApp"

# Response contains an APP_ID you reference as lt://APP1234...

Then describe the run. The configuration below is from a working Maestro setup on HyperExecute, with autosplit distributing the discovered flows across the requested devices:

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

runtime:
  - language: java
    version: "21"

framework:
  name: raw
  args:
    devices: [".*-.*", ".*-.*", ".*-.*"]
    video: true
    deviceLog: true
    appPath: maestro-test/sample.apk
    buildName: maestro-t1
    queueTimeout: 600

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

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

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

The runner script is the part that actually invokes Maestro on the machine, and it is deliberately thin:

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

Then trigger the run. Each discovered flow is dispatched to a device, and the dashboard collects the results:

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

Both real devices and Android emulators are supported, and pre-installed system apps can be targeted by setting the app identifier to stock and naming the package in the flow. Full setup, including the iOS path, is in the HyperExecute Maestro documentation.

Reports and Debugging

The format flag in the runner above is doing more work than it looks. It makes Maestro emit JUnit XML, which is the interchange format every CI system and most test management tools already understand, so results land somewhere durable instead of scrolling past in a log.

Debugging a mobile failure needs more than a stack trace, because the interesting question is usually what was on screen. The debug output directory captures logs and screenshots locally. On a grid run, video and device logs attach to each execution, which is what turns a failure that only reproduces on one device model into something a developer without that handset can act on.

Feed the JUnit output into test management if you want history rather than a per-run verdict. A single failing flow is a defect; the same flow failing on one device family for three weeks is a different and more useful finding.

Where Maestro Struggles

Every account of Maestro testing should state these plainly, because the parts a framework is bad at decide whether it fits your suite more than the parts it is good at.

• Conditional logic. Declarative YAML has no natural way to express take this path if the user has a saved card, and flows that need it become several near-duplicate files.
• Data-driven runs. Testing twenty input combinations means twenty flows or an external generator, where a programming language would use a loop.
• Test data setup. There is no way to call your own code to seed an account, so setup either happens through the UI, which is slow, or outside the framework entirely.
• Cross-platform reuse. The commands are shared between Android and iOS but the selectors usually are not, so one flow rarely runs untouched on both.
• Deep assertions. Checking that a value persisted correctly to a backend is outside what a UI-level flow can see, and stays the job of API-level checks.

None of these are defects. They are the cost of the trade that makes a first flow take minutes. The teams that get the most from Maestro use it for the journeys that must never break and keep a programmable framework for the suites that need logic, which is a division of labour rather than a migration.

Conclusion

Pick the one journey whose breakage would be most embarrassing and write it as a flow this afternoon. Launch, navigate, assert one thing that proves the journey worked. If it takes longer than an hour, the obstacle is your app's selectors rather than the framework, and that is a finding worth having on its own.

Then decide the division of labour deliberately. Maestro for the flows that must never break and that non-engineers should be able to read; a programmable framework for suites that need loops, seeded data, and calls into your own code. Choosing one tool for everything is what forces the compromise.

Whichever mix you land on, run it on hardware your users actually hold. TestMu AI's real device cloud covers that spread, and the broader picture of what to test on mobile is in the mobile app testing guide.