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 appI
d . 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.