---
title: Install Maestro and Run Your First Flow | TestingBot
description: 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;…
source_url:
  html: https://testingbot.com/resources/courses/maestro/install-and-first-flow
  md: https://testingbot.com/resources/courses/maestro/install-and-first-flow.md
---

Course

[Maestro Mobile Testing](https://testingbot.com/resources/courses/maestro)

Chapter 2 of 10

1. [1 Maestro Tutorial: Mobile UI Tests in YAML](https://testingbot.com/resources/courses/maestro)
2. [2 Install Maestro and Run Your First Flow](https://testingbot.com/resources/courses/maestro/install-and-first-flow)
3. [3 Maestro Selectors and Core Commands](https://testingbot.com/resources/courses/maestro/selectors-and-commands)
4. [4 Subflows, Conditions, Loops and JavaScript](https://testingbot.com/resources/courses/maestro/flow-control-and-javascript)
5. [5 iOS vs Android: Permissions, State, Links](https://testingbot.com/resources/courses/maestro/ios-and-android-specifics)
6. [6 Debugging Flaky Maestro Flows](https://testingbot.com/resources/courses/maestro/debugging-and-flakiness)
7. [7 Organising a Maestro Suite](https://testingbot.com/resources/courses/maestro/organising-a-suite)
8. [8 Run Maestro Flows on TestingBot](https://testingbot.com/resources/courses/maestro/run-on-testingbot)
9. [9 Running Maestro in CI Pipelines](https://testingbot.com/resources/courses/maestro/ci-pipelines)
10. [10 Knowledge check](https://testingbot.com/resources/courses/maestro/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 2 of 10 Beginner 7 min read 2 quick checks Updated Nov 2026 

# Install Maestro and Run Your First Flow
On this page
1. [Install Java 17+](https://testingbot.com#install-java-17)
2. [Install the Maestro CLI](https://testingbot.com#install-the-maestro-cli)
3. [Get a device running](https://testingbot.com#get-a-device-running)
4. [Install the sample app](https://testingbot.com#install-the-sample-app)
5. [Write the flow](https://testingbot.com#write-the-flow)
6. [Run it](https://testingbot.com#run-it)
7. [Iterate quickly](https://testingbot.com#iterate-quickly)

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+[#](https://testingbot.com#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:

```bash
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[#](https://testingbot.com#install-the-maestro-cli)

On macOS and Linux the official install script downloads the latest release into `~/.maestro`:

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

On macOS you can use Homebrew instead:

```bash
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](https://github.com/mobile-dev-inc/maestro/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:

```bash
maestro --version
maestro --help
```

### Pin the version your team uses[#](https://testingbot.com#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:

```bash
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?

 Re-run the install script on both machines on the same day Set `MAESTRO_VERSION` to the version you develop against before running the install script Install with Homebrew on CI

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[#](https://testingbot.com#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:

```bash
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:

```bash
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?

 Pass the global `--device` option with the id from `maestro list-devices` Disconnect the phone every time Add `clearState: true` to `launchApp` Run `maestro start-device` before every test

With more than one target Maestro has to pick one. `--device` (an alias of `--udid`) makes the choice explicit.

## Install the sample app[#](https://testingbot.com#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](https://testingbot.com/support/app-automate/maestro#example) uses, so you can compare notes. **Android:**

```bash
curl -LO https://testingbot.com/appium/sample.apk
adb install sample.apk
```

**iOS Simulator:**

```bash
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[#](https://testingbot.com#write-the-flow)

Create a folder for your suite and a first flow file in it:

```bash
mkdir -p maestro-course/flows && cd maestro-course/flows
```

Save this as `add_numbers.yaml` (swap the `appId` for `com.sampleapp` on Android):

```yaml
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:

- `appId` tells Maestro which app this flow is about. `launchApp` with no arguments uses it.
- `clearState: true` resets the app's data before launch, so every run starts from a fresh install state.
- `tapOn` with `id: inputA` focuses field A. The `point` makes the tap land on the right-hand side of the field; chapter 2 shows what goes wrong without it.
- `eraseText` presses backspace (up to 50 times by default) to remove the field's existing content.
- `inputText` types into the focused field.
- `assertVisible: "15"` waits until an element with text `15` is on screen. That is the test.
- `takeScreenshot` saves a PNG into the run's artifact folder.

Before running it, check the YAML is valid:

```bash
maestro check-syntax add_numbers.yaml
```

## Run it[#](https://testingbot.com#run-it)

```bash
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[#](https://testingbot.com#iterate-quickly)

Two habits make the edit-run loop fast:

- **Continuous mode.** `maestro test -c add_numbers.yaml` re-runs the flow whenever you save the file.
- **Read the hierarchy.** `maestro hierarchy` prints the view tree of whatever is on screen as JSON, including each element's `text`, `resource-id`, `accessibilityText` and 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](https://testingbot.com/real-device-testing) in the cloud. The [Maestro documentation](https://docs.maestro.dev) 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.

[Previous · Chapter 1 Maestro Tutorial: Mobile UI Tests in YAML](https://testingbot.com/resources/courses/maestro) [Next · Chapter 3 Maestro Selectors and Core Commands](https://testingbot.com/resources/courses/maestro/selectors-and-commands)

On this page

1. [Install Java 17+](https://testingbot.com#install-java-17)
2. [Install the Maestro CLI](https://testingbot.com#install-the-maestro-cli)
3. [Get a device running](https://testingbot.com#get-a-device-running)
4. [Install the sample app](https://testingbot.com#install-the-sample-app)
5. [Write the flow](https://testingbot.com#write-the-flow)
6. [Run it](https://testingbot.com#run-it)
7. [Iterate quickly](https://testingbot.com#iterate-quickly)

Certification

Earn the free, resume-worthy TestingBot Maestro Certification for this course.

[How it works](https://testingbot.com/resources/courses/maestro/certification)
