Installation and First Script

In the first part, I tried to make a sense of what Maestro is and what are the pre-set up stuff you need to do before using the library.

In this part, I will install Maestro and try to run a simple script.

Installation

Since I’m trying to install this on a MacOS machine, I’ll follow the installation script given on the Maestro official documentation

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

Once this finishes, then you can directly run maestro test to run tests – but wait there is a caveat. If there is no installed virtual device or the Android Home is not set, then maestro will complain about it – see the red part in the screenshot below

In case you’re trying to run tests on iOS simulators ( Maestro doesn’t support running tests in iOS physical devices as of now), then you need to run these two commands after maestro installation

brew tap facebook/fb
brew install facebook/fb/idb-companion

Note: Before you start running any tests on Android or iOS simulators, I’d highly recommend you to install Xcode if you’re on a Mac machine, along with the command line tools.

Once you’re done with installation, to verify that maestro is installed, you can run this sample command to show the version you’ve installed

maestro -v

Once you’re done with this step check, you can run the following command to start a new AVD

maestro start-device --platform=android

If you see the second image, it tells you the command you need to run if the above command fails – this command will manually install the required system-image required by maestro

Now before we run the first script we have

• Android Installation and directory path set.
• Created a new AVD
• Installed maestro
• Started a device using maestro CLI.

First Script

Now let’s run a sample script – before and then we’ll deconstruct what are the essential components of the test flow.

Create a new directory and inside that create a new file named flow.yaml and copy paste this

# flow.yaml

appId: hibernate.v2.testyourandroid
---
- launchApp
- tapOn: "Flashlight"

Now before running this script, one thing to make sure is that the AVD that you want to run this test on should have the apk file or .zip file installed already, or maestro complains that the app cannot be found.

Maestro also gives you some pre-build samples if you want to run them before-hand to see how the workflow actually processes. In order to run those samples, do this

adb install sample.apk
maestro test android-flow.yaml

Explaining the First Test

The first thing to notice is that the tests are written in plain yaml files – and not in any code-specific language files like Java,Python etc. This is one of the most welcome feature that I see in maestro that if you know how yaml works, then it would be breeze for you and it is much easier to learn and has much lesser knowledge curve as compared to other programming languages – although maestro can use .js files to for other purposes – but most of the heavy lifting is done through yaml files.

Now lets break this down step by step

# flow.yaml

This is nothing but a simple comment in yaml file, that specifies the name of the file – you can write a comment in yaml using # some text

appId: hibernate.v2.testyourandroid

This is actually what tells maestro which app it needs to test. You need to tell it the appID or the app Package name so that it knows which app to target.

To get the app package name, open the .apk file in the Profile or Debug mode using Android Studio

Then open the AndroidManifest.xml file and check the package key

Now lets take a look at the next two statements

- launchApp
- tapOn: "Flashlight"

The first statement launchApp is one of the pre-defined ( in built) yaml keywords that means that the app needs to be launched. This is the command that you’ll use to launch the app under test. This will by default launch the app which has been defined in the appId . You can also define the appId under the launchApp key also

- launchApp : appId

or also like this with different option states like clearing the state before app launch

- launchApp:
    appId: "com.example.app"
    clearState: true

If you want to set some default permissions before the app launch, you can also do that under the launchApp key

- launchApp:
    appId: "com.example.app"
    clearState: true
    permissions:
        notifications: unset # notification permission is unset

Next the command that is being used is tapOn – which literally means tap on something – an equivalent of click event on the desktop.

In this command, I’ve simply mentioned to tap on an element with the text Flashlight. There are other options too like providing the amount of repeats or delays etc. If you want to wait for some time before the app UI settles, then you can also do that – however maestro by default waits for the UI to settle.

- tapOn:
    text: "Button"
    waitToSettleTimeoutMs: 500 # ms

Now let’s run the flow.yaml file. Before running the file, make sure that the AVD that you’re targeting is started – otherwise maestro will complain that there are no active devices

So we have successfully executed our first test – the logs generated are stored in the .maestro folder inside the user home directory in my case /Users/shrijanki – the generated path under which you can find logs/failures/screenshots etc is

/Users/{username}/.maestro/tests/{dir_created_for_that_test}

A sample screenshot of how that directory looks

If there is a failed test, then maestro will take a screenshot and store it – you can see in the screenshot below with (x) mark –

In the third part of the series , I’ll try to explain more about how we can use assertions, how we can take screenshots, waiting etc.