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 Q1 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 > Simulatorto launch the simulator.If no device is available, go to
Xcode > Settings > Platformsand ensure an iOS runtime (iOS 16, 17, 18, or 24) is installed.
Installation
Download the appropriate installer for your operating system:
Windows: MaestroStudio.exe
macOS: MaestroStudio.dmg
Linux: MaestroStudio.AppImage
Follow the platform-specific installation prompts:
Windows: Double-click the
.exeand follow the setup wizard.macOS: Open the
.dmgand drag Maestro Studio to yourApplicationsfolder.Linux: Make the
.AppImageexecutable and run it with the--no-sandboxflag: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.
Name: Name for your YAML file.
App Id: From the dropdown menu, select the App Id for testing. For this QuickStart, select com.apple.MobileAddressBook 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.
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 ContactsThe 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 Commands overviewpage.
To learn about how you can structure tests, also referred to in Maestro as Flows, access the Maestro Flows overview.
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.
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 Commands overviewpage.
To learn about how you can structure tests, also referred to in Maestro as Flows, access the Maestro Flows overview.
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.
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 overview 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 overview.
To learn the best practices for logic, modularity, and nesting, or learn how to add JavaScript scripts to your tests check out the Maestro Flows overview.
Last updated