Installing Maestro and Running Your First Flow

Maestro is an open-source mobile UI testing framework by mobile.dev. It drives real iOS Simulators and Android Emulators by simulating actual user gestures — taps, swipes, typing — on the native UI. Because it tests the real app binary, it catches bugs that unit and component tests miss, like incorrect navigation wiring or platform-specific rendering issues.

Maestro tests are written in simple YAML files, making them accessible to developers who are not experts in testing frameworks. Each YAML file describes a flow: a sequence of commands that the Maestro CLI executes against a running app.

Install Maestro via a shell script on macOS and Linux. It downloads the CLI binary and adds it to your PATH. On Windows, Maestro runs inside WSL2 with an Android emulator. Verify the installation by running maestro --version.

Maestro requires Java 11 or higher on macOS (for the underlying test runner). If you do not have Java, Maestro's installer suggests installing it via Homebrew. iOS testing requires Xcode and the Simulator app — standard requirements for any iOS development.

A Maestro flow is a YAML file. The top-level appId specifies which app to test — use the bundle identifier for iOS (e.g., com.example.myapp) or the package name for Android. The --- separator begins the command list.

Start with the launchApp command to open the app fresh. Then add assertions and actions. The simplest first flow just launches the app and verifies the welcome screen appears.

Run a Maestro flow with maestro test path/to/flow.yaml. Make sure a simulator or emulator is running and the app is installed on it before executing the command. Maestro connects to the running simulator automatically — no device selection needed when there is only one.

Maestro prints each command as it executes. On success, each step shows a green checkmark. On failure, it shows the failing command, a screenshot of the UI at the point of failure, and an error message. The screenshot is invaluable for debugging why an assertion failed.

The tapOn command simulates a finger tap. You can tap by text (the visible label), by id (the element's testID), or by a percentage-based point on the screen. Tapping by text is the most readable and resilient to layout changes.

If multiple elements have the same text, add an index to specify which one (0-indexed). Use optional: true to make the tap conditional — it skips without failing if the element is not present, which is useful for dismissing optional permission dialogs.

Use inputText to type text into the currently focused input field. First tap on the TextInput to focus it, then use inputText to type. Maestro types the full string at once rather than character by character.

For fields that require clearing existing text first, use clearText before inputText. Use hideKeyboard after typing to dismiss the software keyboard, which may be covering other elements you need to interact with.

Maestro generates test results in several formats: plain text in the terminal, JUnit XML (for CI systems like GitHub Actions), or an interactive HTML report. The HTML report includes screenshots for each step, making it easy to visually review what happened at each point in the flow.

When a test fails, Maestro saves a screenshot of the screen at the moment of failure. Look for the failure screenshot in the output to understand why an assertion failed — often the screen shows a loading spinner instead of the expected content, revealing a timing issue.

Commands in a Maestro flow execute sequentially. Maestro automatically waits for each command to complete before moving to the next. Taps wait for the element to be visible and stable before interacting, and assertions retry until the element appears (with a configurable timeout).

The default timeout for assertVisible is 5 seconds. If your app takes longer to load a screen (for example, it fetches data from a slow API), increase the timeout with the timeout option or add a waitForAnimationToEnd command.

By default, launchApp brings the app to the foreground if it is already running (warm start). For tests that must start with a clean state — no logged-in user, empty database cache — use clearState: true to delete all app data before launching.

This is equivalent to uninstalling and reinstalling the app. Use it in your most critical test flows to ensure they start from a predictable baseline and do not depend on data left by previous flows.

For repetitive steps like logging in before every test, extract them into a subflow YAML file and reference it with runFlow. This keeps each test flow focused on its specific scenario and makes login setup a one-line reusable step.

Subflows work like function calls in code — they execute in-line with the parent flow. You can pass parameters to subflows using the env section to make them reusable with different data (different users, different input values).

Maestro Studio is an interactive web-based UI that streams your simulator screen and lets you record flows by clicking on elements. Run maestro studio and it opens a browser where you can click to generate YAML commands automatically.

This is the fastest way to create your first flows — record the happy path interactively, then review and edit the generated YAML to add assertions and handle edge cases. Studio also shows the element tree for each screen, helping you find the best testID or text to target.

Test your understanding of React Native Mobile Development concepts from this lesson.

In this lesson you learned: how to install Maestro and write a YAML flow file that launches the app and asserts on visible content, how to use tapOn, inputText, and assertVisible to drive user interactions in flows, and how to use subflows to share repetitive steps like login across multiple test flows. Next up we write more advanced Maestro assertions and handle dynamic UI states.