How to automate your UI testing using Maestro

This tutorial will teach you how to setup Maestro on your machine, in order to automate your UI testing. It will show you actions that are currently available, along with some examples of how tests on Maestro look like, so that you can write your own.

Maestro works on layouts written in both Android Views and Jetpack Compose. As a matter of fact, Maestro can pick up text and content descriptions specified in the layouts and uses that to perform actions on those views.

How Maestro looks like in action

Video taken from the official documentation:

How to install Maestro on your machine

Mac OS

Install it using Homebrew

brew tap mobile-dev-inc/tap
brew install maestro

Windows

• Download the latest release from Github (prefixed with CLI)
• Unzip it
• In PowerShell:

cd /path/to/unzipped/bin
maestro test flow.yaml

Linux

Install it via Homebrew

brew tap mobile-dev-inc/tap
brew install maestro

• By downloading the latest CLI release from Github

How to write your first test

In order to write a Maestro test, create a yaml file containing the steps your tests. This is similar to the @Test functions in Espresso tests.

A yaml file looks like this:

# flow.yaml
appId: com.app.id
---
- launchApp
- tapOn: 'Text on the screen'

once you are happy with the recipe run it on a connected device using:

maestro test flow.yaml

What actions are supported in Maestro

Tapping

Simulating a single tap on the screen is performed by using tapOn following parameters:

- tapOn:
    text: "Text"     # (optional) Finds text that matches regexp
    id: "id"         # (optional) Finds id that matches regexp
    width: 100       # (optional) Finds element of a given width
    height: 100      # (optional) Finds element of a given height
    tolerance: 10    # (optional) Tolerance to apply when comparing width and height
    optional: false  # (default: false) If set to true, test won't fail if view can't be found

There is also support for tapping on a specific part of the screen instead of a view:

- tapOn:
    point: 100,200    # This command will tap on point x:100 y:200 on the screen (in pixels)

Long pressing on a view

Simulating a long press is performed by using longPressOn following parameters:

- longPressOn: Text
- longPressOn:
    id: view_id
- longPressOn:
    point: 100,200

Scrolling

A simple vertical scroll can be performed using scroll.

For swiping from a specific part of the screen, you need to use swipe:

- swipe:                 # This command performs a swipe down gesture starting from (x=100, y=900) ending at (x=100, y=200)
    start: 100, 900
    end: 100, 200

Typing

You can emulate typing on a edit texts using inputText.

- inputText: "Hello World"

Pressing Back

Back button is emulated using back

- back

Asserting

Assertions are done using the assertVisible commands following parameters:

- assertVisible:
    # Same exact parameters as in Tap On View

- assertNotVisible:
    # Same exact parameters as in Tap On View

More commands are supported such as launching links, and apps. You can find everything on the official documentation official documentation.

A simple example

The example that comes with the official documentation launches the default Contacts app and creates a new contact. The recipe is fairly straightforward to go through:

# flow_contacts_android.yaml

appId: com.android.contacts
---
- launchApp
- tapOn: "Create new contact"
- tapOn: "First Name"
- inputText: "John"
- tapOn: "Last Name"
- inputText: "Snow"
- tapOn: "Save"

How can I use Maestro using Jetpack Compose

You can refer to your Composable functions in your Maestro flows by using their text or content descriptions. This is a similar to how you would write UI tests for Jetpack Compose. In order to apply a content description to your custom Composable functions use the semantics Modifier and pass a value to the contentDescription property:

CircleButton(
    modifier = Modifier.semantics { contentDescription = "Like" },
    icon = Icons.Rounded.Favorite
)

Conclusion

Maestro is the new open-source UI testing framework by mobile.dev. We saw how to setup Maestro on your local machine and how to create flows in order to automate your testing. There are a lot things about Maestro that are not covered in this tutorial, so make sure to check the full documentation and Github repository.