Android UI Testing with uiautomatorviewer and uiautomator

Introduction

 There are two types of testing when it comes to Android UI testing. White box testing requires that the source code of the application to test to be accessible by the tester. For white box testing, the tester can use the Android Instrumentation framework in order to construct test case scenarios within an application. The second type is called black box testing, where the tester does not have access to the source code of the application but you need to test the behavior of an application when it runs on a device.

What is Android UI Testing?

In Android UI testing, you want to test how the application interacts with a user on a real device. UI testing ensures that the application returns the correct UI output in response to a sequence of user actions, such as entering keyboard input or pressing toolbars, menus, dialogs, images, and other UI controls. In order to achieve that goal, you have two options. The first is to play with the application on a real device by trying many paths and looking for misbehavior and bugs. This approach is obviously time-consuming, error-prone, and you can try limited scenarios.

The other solution is automated testing. Automated testing involves creating programs to perform testing tasks (test cases) to cover specific usage scenarios, and then using the testing framework to run the test cases automatically and in a repeatable manner.

How to use uiautomatorviewer to scan and analyze UI components

The first tool we are going to see is the uiautomatorviewer, a GUI tool to scan and analyze the UI components of an Android application. In order to useuiautomatorviewer, you must first download and install the SDK and the Eclipse IDE according to the instructions at Setting Up the ADT Bundle. After the installation, the tool exists in the /tools/ folder and you can start it by typing: uiautomatorviewer from the command line.

But what is the purpose of this tool? With uiautomatorviewer, you can inspect the UI of an application in order to find the layout hierarchy and view the properties of the individual UI components of an application. This is very important, particularly when you want to construct automation testing because, by knowing the layout hierarchy of the application and the IDs of the individual widgets, you can use them in theuiautomator (the API in the next section of this course) in order to create automation tests.

Step-by-step instructions using uiautomatorviewer 

Here are step-by-step instructions on how we can use the uiautomatorviewer to find the layout hierarchy and the IDs of some widgets for the Calculator application that exists in the most Android devices.

1. Connect your device to the PC using an USB cable and from “Settings -> Developer options” enable USB debugging.
   
2. Start the Calculator application. 
   
3. From the command line, type: uiautomatorviewer (if you have a path problem, you can type the command from the /tools/ folder). An empty uiautomatorviewer window should open.
   
4. From the top left of the uiautomatorviewer window click “Device screenshot” (see above.)
5. A screenshot of the Calculator” application opens.
   
6. Find the ID of the “7” button : click on “7” (first screenshot below) and look at the right bottom panel the “resource-id” value (second screenshot below). 
   

   
   Now you know that:

   • the id for the widget of number “7” ( “com.android.calculator2:id/digit7”).
   • In the same way we find the ID of “1” (“com.android.calculator2:id/digit1”) 
   • the ID of the symbol “+” (“com.android.calculator2:id/plus”) 
   • and the ID of the symbol “=” (“com.android.calculator2:id/equal”)
7. Also note that, when you hover the mouse over the screenshot of the application, the top right panel of uiautomatorviewer shows the hierarchy of the view under the mouse and the bottom right panel of uiautomatorviewer shows more infos for the widget under the mouse. 
   

   You now know how to create a simple functional UI test using uiautomator. In the following section, you will construct a functional UI test in which you will check how the applications works when you add the numbers “7” and “1”.

How to use uiautomator API to create customized functional UI tests

With uiautomator API, you can create functional UI tests without the need to have access to the source code of the application. The uiautomator is a Java library containing APIs to create customized functional UI tests, and an execution engine to automate and run the tests.

 To run uiautomator, you must:

1. 1. Prepare to test by installing the app on a test device.
      • Now, analyze the app’s UI components following the instructions in the previous section. Note the properties of the widget you want to test (for example, the resource-id, the text of the widget, etc).
   2. Create automated tests to simulate specific user interactions on your application.
      • Using Eclipse, create a new java project. (for example, “MyFirstTest” java project).
      • In that project you must include the libraries that are necessary in order to useuiautomator. Right click on the project and from “Properties” select “Java build path” -> “Libraries” -> “Add library” -> “JUnit” -> “Next” -> “Finish”.

        Also from “Properties” select “Java build path” -> “Libraries” -> “Add external JARs” and Under the platforms directory, select the latest SDK version and add both the uiautomator.jar and android.jar files.
        

      • Using the uiautomator API, write the code (CalculatorTest.java) to test the Calculator application. In the uiautomator API there are many java classes with which you can write your own testing cases and find out how the application works. Your java testing class (CalculatorTest.java in our example) must extentsUiAutomatorTestCase, a base class which provides useful methods. After that, you can use the classes in the API in order to construct your testing scenario.

      Note: There are many classes in the API but the three most important are:
      UiDevice - This class represents the device under testing and your testing program must start by acquiring a reference to that object calling the methodgetUiDevice() (a method that the UiAutomatorTestCase class provides). When you have a reference to the device, you can do many things with it. For example, you can take a screenshot of the device with the codegetUiDevice().takeScreenshot(storePath);, you can test the press of “Home” button with the code getUiDevice().pressHome(); or test the press of power button with the code getUiDevice().sleep();.

      UiSelector - With this class, you can specify the elements in the layout hierarchy you want to test, filtered by properties such as text value, content-description, class name, and state information. You can also target an element by its location in a layout hierarchy. For example, to get a reference to a view with the text “Bluetooth” you can write UiObject button = new UiObject(new UiSelector().text(“Bluetooth”)); You can also select a component by class name, by description, by ID, etc.

      UiObject - This class represents a simple UI element in the testing application and, once you have a reference to it, you can click on it with code likeUiObject seven = new UiObject(new UiSelector().resourceId(“com.android.calculator2:id/digit7″)); seven.click();, you can read the text of it with code like seven.getText();, or you can set the text in an editable field, after clearing the field’s content with code like seven.setText();.

   3. Compile your test cases into a JAR file and install it on your test device along with your app.

      After the writing the code for your testing scenario, you must follow the next steps in order to to compile your code, create a JAR file from it, and push that JAR file to the device.
      1. Go to your /sdk/tools/ folder. ( Example: cd /home/angelos/Desktop/adt-bundle-linux-x86-20131030/sdk/tools/ )
      2. Type /tools/android create uitest-project -n -t 5 -p 
      (Example: android create uitest-project -n MyFirstTest -t 5 -p /home/angelos/workspace/MyFirstTest/) NOTE: in order to find the correct value for the parameter -t, type android list targets.
      3. For Windows type : set ANDROID_HOME= <path_to_your_sdk>. 
      For Linux type: export ANDROID_HOME= <path_to_your_sdk>.
      (Example: export ANDROID_HOME=/home/angelos/Desktop/adt-bundle-linux-x86-20131030/sdk/ )
      4. Go to your project directory. (Example: cd /home/angelos/workspace/MyFirstTest/ )
      5. Type ant build.
      6. Go to platform-tools folder. (Example: cd /home/angelos/Desktop/adt-bundle-linux-x86-20131030/sdk/platform-tools )
      7. Push the JAR file to your Android device. (Example: adb push /home/angelos/workspace/MyFirstTest/bin/MyFirstTest.jar /data/local/tmp/ )

   4. Run the tests and view the test results.

      In order to run your testing scenario class type, adb shell uiautomator runtest MyFirstTest.jar -c nak.test.CalculatorTest. Note: Substitute MyFirstTest.jarand nak.test.CalculatorTest with your project name and your class name. Voila! The testing is running and you can see in your device what happens in the Calculator application when we add “7″ and “1″ and then press the back button.

       

      Presentation Help

   5. Note any bugs or defects discovered in testing.
      Now, it’s up to you to note misbehavior of the application under testing or to test the behavior of the application under extreme conditions. What you can write as a testing scenario is only limited by your imagination.

 

Source Code 

package nak.test;

//Import the uiautomator libraries

import com.android.uiautomator.core.UiObject;

import com.android.uiautomator.testrunner.UiAutomatorTestCase;

import com.android.uiautomator.core.UiSelector;

import com.android.uiautomator.core.UiObjectNotFoundException;

import com.android.uiautomator.core.UiScrollable;

public class CalculatorTest extends UiAutomatorTestCase {   

public void testingCalculator() throws UiObjectNotFoundException {   

// First we testing the press of the HOME button.

getUiDevice().pressHome();

 // using the uiautomatorviewer tool we found that the button for the "applications" has

 //the value “Apps” (screen9)

 // so we use this property to create a UiSelector to find the button. 

UiObject Applications = new UiObject(new UiSelector().description("Apps"));

// testing the click to bring up the All Apps screen.

Applications.clickAndWaitForNewWindow();

// In the All Apps screen, the "Calculator" application is located in 

// the Apps tab. So, we create a UiSelector to find a tab with the text 

// label “Apps”.

UiObject apps = new UiObject(new UiSelector().text("Apps"));

// and then testing the click to this tab in order to enter the Apps tab.

apps.click();

// All the applications are in a scrollable list 

// so first we need to get a reference to that list

UiScrollable ListOfapplications = new UiScrollable(new UiSelector().scrollable(true));

// and then trying to find the application    

// with the name Calculator

UiObject Calculator = ListOfapplications.getChildByText(new UiSelector().className(android.widget.TextView.class.getName()),"Calculator");

Calculator.clickAndWaitForNewWindow();

// now the Calculator app is open

// so we can test the press of button "7" using the ID "com.android.calculator2:id/digit7"

//we found by using uiautomatorviewer

UiObject seven = new UiObject(new UiSelector().resourceId("com.android.calculator2:id/digit7"));

seven.click();

// now we test the press of button "+"

UiObject plus = new UiObject(new UiSelector().resourceId("com.android.calculator2:id/plus"));

plus.click();

// and then the press of button "1"

UiObject one = new UiObject(new UiSelector().resourceId("com.android.calculator2:id/digit1"));

one.click();

// we test the press of button "="

UiObject result = new UiObject(new UiSelector().resourceId("com.android.calculator2:id/equal"));

result.click();

//and finally we test the press of "Back" button

getUiDevice().pressBack();

}   

}