---
source_url: "https://docs.maestro.dev/get-started/quickstart"
title: "QuickStart | Maestro Docs"
mirrored_at: 2026-08-25T01:00:59.136Z
host: docs.maestro.dev
cited_in_42a: true
mirror_canonical: "https://index.42a.ai/docs.maestro.dev/get-started/quickstart"
---

> **Original source:** https://docs.maestro.dev/get-started/quickstart

⌘Ctrlk

-   [Introduction](https://docs.maestro.dev/)
-   [Maestro Studio](https://docs.maestro.dev/maestro-studio)
-   [Maestro CLI](https://docs.maestro.dev/maestro-cli)
-   [Maestro Cloud](https://docs.maestro.dev/maestro-cloud)
-   [Flows](https://docs.maestro.dev/maestro-flows)
-   [API Reference](https://docs.maestro.dev/reference)
-   [Examples](https://docs.maestro.dev/examples)
-   [Resources](https://docs.maestro.dev/extra-materials)

1.  [Introduction](https://docs.maestro.dev/)
2.  [Get Started](https://docs.maestro.dev/get-started)

## 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](https://docs.maestro.dev/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.

1.  Download the latest version of Android Studio from the [official site](https://developer.android.com/studio) and install it.
    
2.  Open Android Studio, click **More Actions**, and select **Virtual Device Manager**.
    
3.  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.

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

2.  Open Xcode, go to `Settings > Locations`, and ensure the **Command Line Tools** are selected.
    
3.  Open Xcode and go to `Xcode > Open Developer Tool > Simulator` to launch the simulator.
    
4.  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`](https://github.com/XcodesOrg/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.

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

![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F1411608689-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FCbCMt5C3rawmE9oIus7f%252Fuploads%252F8xc84a6h1ogLkSlHhMTf%252Fquickstart-1.png%3Falt%3Dmedia%26token%3D598e81f0-bff7-4dda-a8b0-cd0e90eeb611&width=768&dpr=3&quality=100&sign=5d116d03&sv=2)

1.  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.
    
2.  Click **Create a new test** to open the setup window.
    

![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F1411608689-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FCbCMt5C3rawmE9oIus7f%252Fuploads%252Fjbu6uWVXKRcqPXrqw0u5%252Fquickstart-create-a-new-test.png%3Falt%3Dmedia%26token%3D0ebb93d0-e7f3-4c7e-8ca7-1d390d0cb14d&width=768&dpr=3&quality=100&sign=a8b5618b&sv=2)

1.  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.
    

![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F1411608689-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FCbCMt5C3rawmE9oIus7f%252Fuploads%252FdjmIiLY8CHGHo2E2eIny%252Fimage.png%3Falt%3Dmedia%26token%3D19c5920e-0532-476f-94b4-62ea7c4b1604&width=768&dpr=3&quality=100&sign=584c27dd&sv=2)

-   **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.
    

![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F1411608689-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FCbCMt5C3rawmE9oIus7f%252Fuploads%252FzDBD9RNEdqNoOUT3y824%252Fimage.png%3Falt%3Dmedia%26token%3Dfd7b7193-a8b3-4ab2-98b1-84fd23907472&width=768&dpr=3&quality=100&sign=4af7ffeb&sv=2)

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.

1.  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 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 [API Reference](https://docs.maestro.dev/reference/)page.

To learn about how you can structure tests, also referred to in Maestro as Flows, access the [Flows](https://docs.maestro.dev/maestro-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.

![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F1411608689-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FCbCMt5C3rawmE9oIus7f%252Fuploads%252F5KsyREgrX1Xea97egCqd%252F2026-02-15_18-41-27.gif%3Falt%3Dmedia%26token%3D10b208a1-b4f3-4296-9d25-3f28e644c786&width=768&dpr=3&quality=100&sign=c1500849&sv=2)

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 [API Reference](https://docs.maestro.dev/reference/) page.

To learn about how you can structure tests, also referred to in Maestro as Flows, access the [Flows](https://docs.maestro.dev/maestro-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.

![](https://docs.maestro.dev/~gitbook/image?url=https%3A%2F%2F1411608689-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FCbCMt5C3rawmE9oIus7f%252Fuploads%252FtGa2Qii9wZNxzJqniVjJ%252F2026-02-15_18-26-33.gif%3Falt%3Dmedia%26token%3Ddc0a0d94-2635-4ca2-87b0-b849cfcc7055&width=768&dpr=3&quality=100&sign=88470b6f&sv=2)

**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.
    

### 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](https://docs.maestro.dev/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](https://docs.maestro.dev/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](https://docs.maestro.dev/maestro-flows/).
    

Last updated 1 month ago

-   [Video walkthrough](#video-walkthrough)
-   [Next steps](#next-steps)

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

```
appId: com.apple.MobileAddressBook 
---
- launchApp:
    clearState: true
```

```
appId: com.apple.MobileAddressBook 
---
- launchApp
- 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
```