What Is Maestro and How to Set It Up to Run Tests Locally?

Hi, I’m Nadeem — an ISTQB-certified QA engineer with more than seven years of experience in mobile, web, and API testing. One of the most exciting tools I've worked with recently is Maestro, a fast and intuitive framework for mobile UI automation. In this maestro tutorial, I’ll explain exactly what Maestro is and provide a complete maestro setup guide to help you get started with testing on your local machine.

What Is Maestro?

If you're new to mobile testing with Maestro, think of it as a lightweight, open-source UI automation tool for Android and iOS apps. Maestro allows you to write user flows in simple YAML files that are easy to read, modify, and share. Unlike traditional test automation tools, Maestro is fast to set up and runs seamlessly across platforms with minimal configuration. It’s perfect for quick validations, smoke testing, or full maestro test automation suites.

Why Use Maestro for Mobile Testing?

Platform-Agnostic: Works on Android and iOS using the same test files.
Simple Syntax: Uses YAML instead of code-heavy frameworks.
Fast Feedback: Modify and re-run flows in seconds.
Open Source: Free to use with a growing community.

Maestro’s intuitive approach makes it easy for anyone—developers, testers, or product managers—to participate in mobile automation.

How to Set Up Maestro (Step-by-Step)

In this maestro setup guide, I’ll walk you through how to install the CLI, write your first test, and run it locally on macOS or other platforms.

1. Install Maestro CLI

On macOS, the fastest way is via Homebrew:

brew install maestro

Alternatively, you can use:

curl -Ls https://maestro.mobile.dev/install | bash

2. Confirm the Installation

maestro --version

This verifies that the CLI was installed correctly.

3. Initialize a New Project

mkdir maestro-tests
                            cd maestro-tests
                            maestro init

This creates a starter structure with sample flows.

4. Write a Test Flow

Here’s a basic example of a login flow for maestro test automation:

appId: com.example.app
                            ---
                            - launchApp
                            - tapOn: "Username"
                            - inputText: "test_user"
                            - tapOn: "Password"
                            - inputText: "secure123"
                            - tapOn: "Log In"

5. Run the Test Locally

maestro test flows/login.yaml

As long as a simulator or emulator is running, Maestro will execute the test steps and display results in the terminal.

Running Multiple Tests

You can run an entire suite of flows from a folder using:

maestro test flows/

This is ideal for CI pipelines and repetitive validations.

Troubleshooting Tips

Device not found? Make sure your Android emulator or iOS simulator is running.
Elements not tapping? Use maestro studio to inspect app elements and labels.
Installation errors? Reinstall Java or update your CLI to the latest version.

Best Practices for Using Maestro

Break down long flows into smaller YAML files for clarity.
Store screenshots and logs from failed tests for review.
Document flows clearly for collaboration with devs and PMs.

Summary

This guide covered what is Maestro, how it fits into modern mobile automation strategies, and how to run your first tests locally. By following this maestro tutorial, you’ll be ready to automate user flows on iOS and Android using one of the easiest tools available.

If you're looking for a clean, modern approach to mobile testing, maestro installation is quick and highly adaptable. Whether you're just experimenting or planning full regression runs, Maestro makes it simple to get started.

Connect with me on LinkedIn
Read more blogs at inadeem.me

What is Maestro? How to set up maestro on and run test locally?