Automatic Android* Testing with UiAutomator

Introduction

I want to tell you about a wonderful tool to automatically test the UI of Android* applications. The name of this tool is UiAutomator. You can find all the latest documentation here: http://developer.android.com/tools/help/uiautomator/index.html and http://developer.android.com/tools/testing/testing_ui.html

UiAutomator has some strengths and weaknesses.

Advantages:

• Can be used on device displays with different resolution
• Events can be linked with Android UI controls. For example, click on a button with text that says “Ok,” instead of clicking a coordinate location (x=450, y=550).
• Can reproduce a complex sequence of user actions
• Always performs the same sequence of actions, allowing us to collect performance metrics on different devices.
• Can run several times and on different devices without changing any Java* code
• Can use hardware buttons on devices

Disadvantages:

• Hard to use with OpenGL* and HTML5 applications because these apps have no Android UI components.
• Time consuming to write JavaScript*

Script development

To introduce working with UiAutomator, I want to show a simple program. This program is the standard Android Messaging application and sends SMS messages to any phone number.

Here's a short description of the actions that we implemented:

1. Find and run application
2. Create and send SMS messages

As you can see it’s very easy.

Preparation for the test

To analyze the UI interface we will use uiautomatorviewer.

uiautomatorviewer shows a split screenshot of all the UI components in the Node Detail so you can see their different properties. From the properties you can find a desired element.

Customizing the Development Environment

If you use Eclipse*:

1. Create a new Java project in Eclipse. We will call our project: SendMessage
2. Right click on your project in the Project Explorer and click on the Properties item
3. In Properties, select Java Build Path and add the required libraries:

• Click on the Add Library > JUnit and there JUnit3 choose to add support for JUnit
• Click Add External JARs ...
• In the <android-sdk>/platforms/directory, select the latest version of the SDK. Also in this directory, select the files: uiautomator.jar and android.jar

If you are using a different development environment, make sure that the android.jar and uiautomator.jar files are added to the project settings.

Create a script

Create a project in a previously created new file with the Java class. Call it SendMessage. This class is inherited from class UiAutomatorTestCase and using keys Ctrl + Shift + o (for Eclipse), add the required libraries.

Create three functions to test this application:

1. Search and run the application
2. Send SMS messages
3. Exit to the main menu of the application

Create a function from which we will run all these features—a kind of main function:

public void test() {
    // Here will be called for all other functions
    }

Function to find and run the application

This function is simple. We press the Home button and once on the main window, open the menu and look for the icon with the application. Click on it and start the application.

private void findAndRunApp() throws UiObjectNotFoundException {
        // Go to main screen
        getUiDevice().pressHome();
        // Find menu button
        UiObject allAppsButton = new UiObject(new UiSelector()
        .description("Apps"));
        // Click on menu button and wait new window
        allAppsButton.clickAndWaitForNewWindow();
        // Find App tab
        UiObject appsTab = new UiObject(new UiSelector()
        .text("Apps"));
        // Click on app tab
        appsTab.click();
        // Find scroll object (menu scroll)
        UiScrollable appViews = new UiScrollable(new UiSelector()
        .scrollable(true));
        // Set the swiping mode to horizontal (the default is vertical)
        appViews.setAsHorizontalList();
        // Find Messaging application
        UiObject settingsApp = appViews.getChildByText(new UiSelector()
        .className("android.widget.TextView"), "Messaging");
        // Open Messaging application
        settingsApp.clickAndWaitForNewWindow();
        
        // Validate that the package name is the expected one
        UiObject settingsValidation = new UiObject(new UiSelector()
        .packageName("com.android.mms"));
        assertTrue("Unable to detect Messaging",
                settingsValidation.exists());
    }

All of the class names, the text on the buttons, etc. came from uiautomatorviewer.

Send SMS messages

This function finds and presses the button for writing a new application, enters a phone number for whom to send a text message to, and presses the send button. The phone number and text pass through the function arguments:

private void sendMessage(String toNumber, String text) throws UiObjectNotFoundException {
        // Find and click New message button
        UiObject newMessageButton = new UiObject(new UiSelector()
        .className("android.widget.TextView").description("New message"));
        newMessageButton.clickAndWaitForNewWindow();
        
        // Find to box and enter the number into it
        UiObject toBox = new UiObject(new UiSelector()
        .className("android.widget.MultiAutoCompleteTextView").instance(0));
        toBox.setText(toNumber);
        // Find text box and enter the message into it
        UiObject textBox = new UiObject(new UiSelector()
        .className("android.widget.EditText").instance(0));
        textBox.setText(text);
        
        // Find send button and send message
        UiObject sendButton = new UiObject(new UiSelector()
        .className("android.widget.ImageButton").description("Send"));
        sendButton.click();
    }

The fields for the phone number and text message display do not have any special features, as neither the text nor any description of these fields is available. Therefore, I can find them by using in this instance an element in its ordinal position in the hierarchy of the interface.

To add the ability to pass parameters to the script we can specify the number of where we want to send the message, as well as text messages. The function test () initializes the default settings, and if any of the parameters were sent messages via the command line, the substitution of the default settings would be:

// Default parameters
        String toNumber = "123456"; 
        String text = "Test message";
        
        String toParam = getParams().getString("to");
        String textParam = getParams().getString("text");
if (toParam != null) {
// Remove spaces
            toNumber = toParam.trim();
        }
        if (textParam != null) {
            text = textParam.trim();
        }

Thus we will be able to pass parameters from the command line in the script using the small key -e, the first name of the parameter, and the second value. For example, my application sends the number to send " 777777 »:-e to 777777

There are some pitfalls. For example, this application doesn’t understand some characters and fails. It is impossible to convey just text with some characters , it does not perceive them and fails. Here are some of them: space, &, <, > , (,) , ", ' , as well as some Unicode characters. I replace these characters when applying them to script a string, such as a space line : blogspaceblog. So when the script starts UiAutomator, we use a script that will handle our input parameters. We add the function test (), where we check whether there are options, parse parameters, and replace them with real characters. Here is a sample code along with demonstrating what we inserted earlier:

if (toParam != null) {
            toParam = toParam.replace("blogspaceblog", " ");
            toParam = toParam.replace("blogamperblog", "&");
            toParam = toParam.replace("bloglessblog", "<");
            toParam = toParam.replace("blogmoreblog", ">");
            toParam = toParam.replace("blogopenbktblog", "(");
            toParam = toParam.replace("blogclosebktblog", ")");
            toParam = toParam.replace("blogonequoteblog", "'");
            toParam = toParam.replace("blogtwicequoteblog", "\"");
            toNumber = toParam.trim();
        }
        if (textParam != null) {
            textParam = textParam.replace("blogspaceblog", " ");
            textParam = textParam.replace("blogamperblog", "&");
            textParam = textParam.replace("bloglessblog", "<");
            textParam = textParam.replace("blogmoreblog", ">");
            textParam = textParam.replace("blogopenbktblog", "(");
            textParam = textParam.replace("blogclosebktblog", ")");
            textParam = textParam.replace("blogonequoteblog", "'");
            textParam = textParam.replace("blogtwicequoteblog", "\"");
            text = textParam.trim();
        }

Exit to the main menu of the application

This function is the simplest of all those that we have implemented. I simply press a button in a loop back until it shows the button to create a new message.

private void exitToMainWindow() {
        // Find New message button
        UiObject newMessageButton = new UiObject(new UiSelector()
        .className("android.widget.TextView").description("New message"));
        
        // Press back button while new message button doesn't exist
        while(!newMessageButton.exists()) {
            getUiDevice().pressBack();
        }
    }

Source code

So here is our code:

package blog.send.message;
import com.android.uiautomator.core.UiObject;
import com.android.uiautomator.core.UiObjectNotFoundException;
import com.android.uiautomator.core.UiScrollable;
import com.android.uiautomator.core.UiSelector;
import com.android.uiautomator.testrunner.UiAutomatorTestCase;

public class SendMessage extends UiAutomatorTestCase {
    public void test() throws UiObjectNotFoundException {
        // Default parameters
        String toNumber = "123456"; 
        String text = "Test message";
        
        String toParam = getParams().getString("to");
        String textParam = getParams().getString("text");
        if (toParam != null) {
            toParam = toParam.replace("blogspaceblog", " ");
            toParam = toParam.replace("blogamperblog", "&");
            toParam = toParam.replace("bloglessblog", "<");
            toParam = toParam.replace("blogmoreblog", ">");
            toParam = toParam.replace("blogopenbktblog", "(");
            toParam = toParam.replace("blogclosebktblog", ")");
            toParam = toParam.replace("blogonequoteblog", "'");
            toParam = toParam.replace("blogtwicequoteblog", "\"");
            toNumber = toParam.trim();
        }
        if (textParam != null) {
            textParam = textParam.replace("blogspaceblog", " ");
            textParam = textParam.replace("blogamperblog", "&");
            textParam = textParam.replace("bloglessblog", "<");
            textParam = textParam.replace("blogmoreblog", ">");
            textParam = textParam.replace("blogopenbktblog", "(");
            textParam = textParam.replace("blogclosebktblog", ")");
            textParam = textParam.replace("blogonequoteblog", "'");
            textParam = textParam.replace("blogtwicequoteblog", "\"");
            text = textParam.trim();
        }
        findAndRunApp();
            sendMessage(toNumber, text);
            exitToMainWindow();
    }
    // Here will be called for all other functions
    private void findAndRunApp() throws UiObjectNotFoundException {
        // Go to main screen
        getUiDevice().pressHome();
        // Find menu button
        UiObject allAppsButton = new UiObject(new UiSelector()
        .description("Apps"));
        // Click on menu button and wait new window
        allAppsButton.clickAndWaitForNewWindow();
        // Find App tab
        UiObject appsTab = new UiObject(new UiSelector()
        .text("Apps"));
        // Click on app tab
        appsTab.click();
        // Find scroll object (menu scroll)
        UiScrollable appViews = new UiScrollable(new UiSelector()
        .scrollable(true));
        // Set the swiping mode to horizontal (the default is vertical)
        appViews.setAsHorizontalList();
        // Find Messaging application
        UiObject settingsApp = appViews.getChildByText(new UiSelector()
        .className("android.widget.TextView"), "Messaging");
        // Open Messaging application
        settingsApp.clickAndWaitForNewWindow();
        
        // Validate that the package name is the expected one
        UiObject settingsValidation = new UiObject(new UiSelector()
        .packageName("com.android.mms"));
        assertTrue("Unable to detect Messaging",
                settingsValidation.exists());
    }
    
    private void sendMessage(String toNumber, String text) throws UiObjectNotFoundException {
        // Find and click New message button
        UiObject newMessageButton = new UiObject(new UiSelector()
        .className("android.widget.TextView").description("New message"));
        newMessageButton.clickAndWaitForNewWindow();
        
        // Find to box and enter the number into it
        UiObject toBox = new UiObject(new UiSelector()
        .className("android.widget.MultiAutoCompleteTextView").instance(0));
        toBox.setText(toNumber);
        // Find text box and enter the message into it
        UiObject textBox = new UiObject(new UiSelector()
        .className("android.widget.EditText").instance(0));
        textBox.setText(text);
        
        // Find send button and send message
        UiObject sendButton = new UiObject(new UiSelector()
        .className("android.widget.ImageButton").description("Send"));
        sendButton.click();
    }
    
    private void exitToMainWindow() {
        // Find New message button
        UiObject newMessageButton = new UiObject(new UiSelector()
        .className("android.widget.TextView").description("New message"));
        
        // Press back button while new message button doesn't exist
        while(!newMessageButton.exists()) {
            getUiDevice().pressBack();
            sleep(500);
        }
    }
}

Compile and run the test UiAutomator

1. To generate configuration files for test assembly, run the following command from the command line:
   <android-sdk>/tools/android create uitest-project -n <name> -t <target-id> -p <path>
   Where <name> is the name of the project that was created to test UiAutomator (in our case: SendMessage), <target-id> is the choice of device and Android API Level (you can get a list of installed devices, the team (<android-sdk> / tools / android list targets), and <path> is the path to the directory that contains the project.
2. You must export the environment variable ANDROID_HOME:
   • On Windows*:
     set ANDROID_HOME=<path_to_your_sdk>
   • On UNIX*:
     export ANDROID_HOME=<path_to_your_sdk>
3. Go to the directory with the project file, build.xml, which was generated in step 1, and run the command:
   ant build
4. Copy the compiled JAR file to the device using the adb push:
   adb push <path_to_output_jar> /data/local/tmp/
   In our case, it is:
   adb push <project_dir>/bin/SendMessage.jar /data/local/tmp/
5. And run the script:
   adb shell uiautomator runtest /data/local/tmp/SendMessage.jar –c blog.send.message.SendMessage

Related Articles and Resources

• HTML5 - Intel Developer Zone
• Android - Intel Developer Zone

To learn more about Intel tools for the Android developer, visit Intel® Developer Zone for Android.