Install Maestro and Run Your First Flow
On this page
In this chapter you install the Maestro CLI, put the TestingBot sample app on an emulator or simulator, and run a flow against it. Everything here is local; the cloud comes in chapter 7.
Install Java 17+#
The Maestro CLI is a JVM application and needs Java 17 or higher, with JAVA_HOME pointing at that installation. Check what you have:
java -version
echo $JAVA_HOME
Any distribution works (Temurin, Oracle JDK, or one installed with SDKMAN). If java -version prints 11 or lower, install a newer JDK before continuing; an old Java is the most common reason a fresh install will not start.
Install the Maestro CLI#
On macOS and Linux the official install script downloads the latest release into ~/.maestro:
curl -fsSL "https://get.maestro.mobile.dev" | bash
On macOS you can use Homebrew instead:
brew tap mobile-dev-inc/tap
brew trust --formula mobile-dev-inc/tap/maestro
brew install mobile-dev-inc/tap/maestro
On Windows, download maestro.zip from the Maestro GitHub releases, extract it (for example to C:\maestro) and add its bin folder to your PATH. WSL works too but needs extra ADB port forwarding, so the Maestro docs recommend native Windows, macOS or Linux.
Open a new terminal and verify:
maestro --version
maestro --help
Pin the version your team uses#
The install script always fetches the newest release. To install an exact version, which you want on CI and across a team, set MAESTRO_VERSION first:
export MAESTRO_VERSION=2.12.1; curl -Ls "https://get.maestro.mobile.dev" | bash
Keep a note of the version you develop against. When you run flows in the cloud later, you will pin the same version there so that local and remote runs behave the same.
Your laptop and the CI runner both use the install script, and a flow behaves differently on each. How do you make them run the same Maestro?
The install script fetches the newest release unless MAESTRO_VERSION pins one. Installing on the same day is luck, not a pin.
Get a device running#
Maestro needs a running target. It does not boot one for every test.
Android: open Android Studio, go to the Virtual Device Manager and start an emulator (any recent Pixel image is fine). A physical phone with USB debugging enabled also works.
iOS: you need a Mac with Xcode and the command line tools (xcode-select --install). Boot a simulator from Xcode, or from the terminal:
xcrun simctl list devices available | grep iPhone
xcrun simctl boot "iPhone 16"
open -a Simulator
Maestro can also create and boot a device for you with maestro start-device --platform android (or ios). Whatever you choose, confirm Maestro can see it:
maestro list-devices
If more than one device is connected, Maestro has to pick one. Use the global --device option (an alias of --udid) to be explicit, for example maestro --device emulator-5554 test flow.yaml. Get into this habit early: running a flow against the wrong device is a confusing way to lose half an hour.
An emulator and a USB phone are both connected, and your flow seems to run on the wrong one. What do you do?
With more than one target Maestro has to pick one. --device (an alias of --udid) makes the choice explicit.
Install the sample app#
The TestingBot sample app is a one-screen calculator: two number fields, A and B, and a Total field. It is available as an Android .apk and as a zipped iOS simulator .app, and it is the same app the Maestro example flow in the TestingBot docs uses, so you can compare notes.
Android:
curl -LO https://testingbot.com/appium/sample.apk
adb install sample.apk
iOS Simulator:
curl -LO https://testingbot.com/appium/sample.zip
unzip sample.zip # produces SampleApp.app
xcrun simctl install booted SampleApp.app
The two builds have different app identifiers, which matters because the first line of every flow names the app:
| Platform | appId |
|---|---|
| Android | com.sampleapp |
| iOS | org.reactjs.native.example.SampleApp |
Write the flow#
Create a folder for your suite and a first flow file in it:
mkdir -p maestro-course/flows && cd maestro-course/flows
Save this as add_numbers.yaml (swap the appId for com.sampleapp on Android):
appId: org.reactjs.native.example.SampleApp
---
- launchApp:
clearState: true
- tapOn:
id: inputA
point: "90%,50%"
- eraseText
- inputText: "10"
- tapOn:
id: inputB
point: "90%,50%"
- eraseText
- inputText: "5"
- assertVisible: "15"
- takeScreenshot: sum-result
Line by line:
-
appIdtells Maestro which app this flow is about.launchAppwith no arguments uses it. -
clearState: trueresets the app's data before launch, so every run starts from a fresh install state. -
tapOnwithid: inputAfocuses field A. Thepointmakes the tap land on the right-hand side of the field; chapter 2 shows what goes wrong without it. -
eraseTextpresses backspace (up to 50 times by default) to remove the field's existing content. -
inputTexttypes into the focused field. -
assertVisible: "15"waits until an element with text15is on screen. That is the test. -
takeScreenshotsaves a PNG into the run's artifact folder.
Before running it, check the YAML is valid:
maestro check-syntax add_numbers.yaml
Run it#
maestro test add_numbers.yaml
Maestro installs its driver on the device the first time (this can take a while on iOS), launches the app and prints each step as it runs:
...
Tap on id: inputA at 90%,50%... COMPLETED
Erase text... COMPLETED
Input text 10... COMPLETED
...
Assert that "15" is visible... COMPLETED
On a failure, the CLI prints which step failed and the path to a debug folder with a screenshot of the screen at that moment. You will use that folder a lot in chapter 5.
To run every flow in a folder, pass the folder instead of a file: maestro test .. By default Maestro only picks up flow files at the top level of the folder, not in subfolders. That default matters once you add reusable subflows in chapter 3.
Iterate quickly#
Two habits make the edit-run loop fast:
-
Continuous mode.
maestro test -c add_numbers.yamlre-runs the flow whenever you save the file. -
Read the hierarchy.
maestro hierarchyprints the view tree of whatever is on screen as JSON, including each element'stext,resource-id,accessibilityTextand bounds. When you do not know what selector to use, look here first.
You now have a working flow on one platform. If you would rather not maintain local emulators and simulators at all, chapter 7 runs this exact file on real Android and iOS devices in the cloud. The Maestro documentation is the reference for every command; the next chapter goes through the ones you will use most, and why the point lines in this flow are there.