QuickStart

Install Maestro Studio, set up your environment, and run your first automated test in five minutes.

You are starting your journey with Maestro. This guide will help you install Maestro Studio, set up your environment, and execute your first automated test (called a Flow) in just five minutes.

Platform-specific setup

Maestro requires a running target device to execute your tests. Use the tabs below to configure your virtual environment.

Download the latest version of Android Studio from the official site and install it.
Open Android Studio, click More Actions, and select Virtual Device Manager.
Click Create Virtual Device (+), select a modern device (e.g., Pixel 8), and download a system image (API 31 or higher is recommended).

Maestro currently supports API Levels 29, 30, 31, 33, and 34. API 35 and 36 support is arriving in Q2 2026.

Finish the wizard and click the Play button to start the emulator.

Download Xcode from the Mac App Store and install it.
Open Xcode, go to Settings > Locations, and ensure the Command Line Tools are selected.
Open Xcode and go to Xcode > Open Developer Tool > Simulator to launch the simulator.
If no device is available, go to Xcode > Settings > Platforms and ensure an iOS runtime (iOS 16, 17, 18, or 24) is installed.

Xcode is installed but no iOS simulators appear?

If you installed Xcode without opening it (for example via xcodes or a scripted install), macOS may not have installed Xcode's required system components - so the CoreSimulator framework is missing and simulators won't load. In Maestro Studio this shows up as no iOS devices in the device list.

Complete the one-time component install:

xcodebuild -runFirstLaunch

# If you're prompted to accept the license first, run:

sudo xcodebuild -license accept

# Then restart Maestro Studio
# iOS simulators should now appear.

Installation

Download the appropriate installer for your operating system:

Follow the platform-specific installation prompts:

Windows: Double-click the .exe and follow the setup wizard.
macOS: Open the .dmg and drag Maestro Studio to your Applications folder.
Linux: Make the .AppImage executable and run it with the --no-sandbox flag:
```
chmod +x MaestroStudio.AppImage
./MaestroStudio.AppImage --no-sandbox
```

Create your first test

Once your device is running and Maestro Studio is open, you can create your first Flow.

Open Maestro Studio and click Choose new workspace location to define the directory on your computer to store your tests.

Click the No device connected button at the top. Select your running Android Emulator or iOS Simulator from the list. The virtual device will pop up.
Click Create a new test to open the setup window.

On the Add a new test to your workspace window, select Mobile Test and enter the following:

Name: Name for your YAML file.
App Id: From the dropdown menu, select the App Id for testing. For this QuickStart, select com.google.android.contacts from the dropdown menu.

You can also use the Scan file for App Id option to automatically detect the identifier from an .apk (Android) or .app/.zip (iOS) file.

You can also add tags to keep your tests organized.

Click Create Test. Maestro will generate a minimal YAML file to launch the app.

appId: com.google.android.contacts
---
- launchApp:
    clearState: true

Run your first test

With your first YAML file created, let's add a few commands to perform a search.

In the Maestro Studio editor, copy and paste the example below for your platform.

appId: com.google.android.contacts
---
- launchApp:
    clearState: true
- tapOn: Allow
- tapOn: Create contact
- tapOn: First name
- inputText: John
- tapOn: Last name
- inputText: Doe
- tapOn: Company
- inputText: Maestro
- tapOn: "+1"
- inputText: 111-111-1111
- tapOn: Save
- back
- takeScreenshot: All Contacts

The test launches the native Contacts app, creates a new entry, saves it, and captures a screenshot.

To learn more about the commands you can use to create tests, access the Commandspage.

To learn about how you can structure tests, also referred to in Maestro as Flows, access the Flows.

After pasting, click Run Locally. Watch your virtual device execute the steps automatically. Maestro Studio will highlight each step as it succeeds or provide a failure reason if an element cannot be found.

appId: com.apple.MobileAddressBook 
---
- launchApp:
    clearState: true
- tapOn: All iPhone
- tapOn: Add
- tapOn: First name
- inputText: John
- tapOn: Last name
- inputText: Doe
- tapOn: Company
- inputText: Maestro
- tapOn: John
- tapOn: add phone
- inputText: +1 111-111-1111
- tapOn: Done
- tapOn: Back
- takeScreenshot: All Contacts

The test launches the Address Book app, adds a new contact, and saves the result.

To learn more about the commands you can use to create tests, access the Commandspage.

To learn about how you can structure tests, also referred to in Maestro as Flows, access the Flows.

Interactive Flow authoring

While this QuickStart focuses on manual YAML, Maestro Studio offers three interactive ways to build your test:

Inspect Screen: Click the Inspect Screen button to select elements visually on the device and receive recommended commands.
Insert Command: Click the Insert Command button in the IDE to choose from a list of standard actions.
Manual Entry: Type commands directly into the YAML editor for precise control.

Access Run tests with Maestro Studio for more information.

Video walkthrough

Watch this step-by-step video to see the first test creation process in detail:

Next steps

Now that you’ve seen the power of "arm's length" automation, explore these resources to master the ecosystem:

Visit the Maestro Studio to learn how to use visual element inspection and the Live REPL to build tests without writing code from scratch.
If you prefer a programmatic approach or need to integrate tests into your CI/CD pipeline, head to the Maestro CLI.
To learn the best practices for logic, modularity, and nesting, or learn how to add JavaScript scripts to your tests check out the Flows.

PreviousHow Maestro works NextMaestro solutions

Last updated 11 days ago