First steps with UI Automator

Posted on by Olivier PHILIPPOT
Reading Time: 4 minutes

UI Auto…what ?

Like its name states it, UI Automator is a framework provided by Android allowing to execute User Interface (UI) functional tests in an automated way.

This framework lets you interact with visible elements of a smartphone screen: click a button, fill a text field, scroll down, etc.
Thanks to UI Automator, you can, for instance, launch an application, fill a login field, navigate in menus…

Let’s write together a first test scenario with UI Automator !
Our objective here is humble: launching a video from the Youtube application on Android.

UI Automator, Espresso, Appium…

In the Android framework, you can also find Espresso: but what is the difference?

UI Automator is more “black box” oriented: you can test any application (even without knowing the code) or even access Android systems settings (like the configuration panel).
Espresso is more “white box” oriented: it requires having the code of the application you want to test, you can conduct finer assertions (for instance on activity creation in the application).

It also exists tools such as Appium, but they aren’t integrated in the Android framework. They offer more features and additional bastraction layers. However, this implies a certain level of implementation complexity.

You would have probably guessed it by now, UI Automator is, for us, the simplest and most-suited framework to begin with!

First step: implementing the work environment

UI Automator tests belong to the instrumented tests group: they must be executed on a smartphone or on an Android emulator.
During a test, two APKs run in a same process; a first APK for the application to be tested and a second one for the test itself.

Thus you need an application (and a scenario) to test!

The source code of an Android application is usually organized as exposed here below:

module
|---src
    |---androidTest
    |---main
    |---test

First case: you are the developer of the application to test.
The simplest solution consists in developing tests in the same module as the application.
The main file contains your application source code and the androidTest file has your UI Automator tests.

Second case: you don’t have access to the source code of the application to test.
You need to create a new module: the main file will be empty and the androidTest file will contain your UI Automator tests.

In the module’s build.gradle file, add the following settings (UI Automator works with AndroidJUnitRunner) :

android {
    ...
    defaultConfig {
        ...
        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
    }
    ...
}
dependencies {
    ...
    androidTestCompile 'com.android.support.test.uiautomator:uiautomator-v18:2.1.2'
    androidTestCompile 'com.android.support.test:runner:0.5'
}

After making sure the project compiles correctly, it is time to add a new class in module/src/androidTest:

@RunWith(AndroidJUnit4.class)
public class YouTubeTest {
    @Test
    public void watchVideo() throws Exception {
        // TODO
    }
}

Everything is now ready for the test scenario implementation!

Second step: writing tests

A few precisions before getting started…

UI Automator allows to interact with visible elements of the screen.
Each element owns a certain amount of characteristics, including: content-description, class, resource-id, text.

UI Automator enables you to look for an element including a given characteristic.
For instance, to access the validate button displayed on the screen, you can look for the element which characteristic text means validate.
You can also get more specific, for example: the element which class is android.widget.EditText and which content-description is text_name.

The characteristic(s) used to find an element is/are rather important.
For example, watch out for names, particularly if your application is available in several languages!

In order to know the characteristics of elements visible on the screen, the Android tool uiautomatorviewer (that you can find under the tools file of your SDK Android) is very convenient.
Once it is launched, this tool allows you to screenshot screens of an Android smartphone.
Each screenshot is associated with a tree represesenting the hierarchy of visible elements, with their respective characteristics.

But let’s go back to our test scenario, for which we propose the following actions:

  • launch the Youtube application;
  • click on the magnifying glass icon to initiate a search;
  • indicate the text “greenspector” in the search field;
  • launch the video “Power Test Cloud – Greenspector (FR)” ;
  • watch the first 20 seconds of the video.

Before initiating any interaction with elements on the screen, you should instantiate a UiDevice object which will represent the current state of the smartphone’s screen.

UiDevice mDevice = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());

Let’s start by launching the Youtube application, like described in the Android documentation.
The purpose of this article being to demonstrate some of the most simple UI Automator features, this step isn’t detailed.

The next step consists in clicking on the magnifying glass icon to initiate the search.
After spotting the magnifying glass resource-id thanks to uiautomatorviewer, we use the waitForExists method which makes the element clickable only from the moment it is displayed.

UiObject icon = mDevice.findObject(new UiSelector().resourceId("com.google.android.youtube:id/menu_search"));
icon.waitForExists(TIMEOUT);
icon.click();

We then use the setText method to enter the desired search keyword.

UiObject editText = mDevice.findObject(new UiSelector().text("Search YouTube"));
editText.waitForExists(TIMEOUT);
editText.setText("greenspector");
mDevice.pressEnter();

Previously, we only used one criteria to search elements on the screen.
But it is possible to combine a few (if different characteristics have the same values for several elements), for instance:

UiObject video = mDevice.findObject(new UiSelector()
        .resourceId("com.google.android.youtube:id/title")
        .text("Power Test Cloud - Greenspector (FR)"));

Finally, let’s wait a few seconds and watch the beginning of the video.

synchronized (mDevice) {
    mDevice.wait(20000);
}

Third step: executing tests

In order to execute tests, it is necessary to be connected via ADB to a smartphone (either a “real” physical smartphone, or an Android emulator). Launch can be executed directly from Android Studio, or in command-line with ADB.

First case : Android Studio.

Go on the Run menu, then Edit Configurations.
Click on the + sign to add a configuration, select the Android Instrumented Tests model.
Adapt configuration with the module name to be tested, the test type, the smartphone (real or emulator).

Second case : command-line with ADB.

First off, compile the application and the tests, for example by using the Wrapper Gradle assemble and assembleAndroidTest tasks:

$ ./gradlew clean assemble assembleAndroidTest

Then install the generated .apk files on the smartphone:

$ adb install module/build/outputs/apk/module-debug.apk
$ adb install module/build/outputs/apk/module-debug-androidTest.apk

Lastly, launch a test:

$ adb shell am instrument com.package.test/android.test.InstrumentationTestRunner

Conclusion

Voilà! Our goal is reached for this easy first UI Automator test, now it is your turn!

Go further

Android Documentation on UI Automator.

Android Documentation on ADB.