Testing UI for Multiple Apps | Android Developers

Dependencies and Prerequisites

Android 4.3 (API level 18) or higher
Android Testing Support Library

This lesson teaches you to

Set Up UI Automator
Create a UI Automator Test Class
Run UI Automator Tests on a Device or Emulator

You should also read

UI Automator API Reference

Try it out

UI Automator Code Samples

A user interface (UI) test that involves user interactions across multiple apps lets you verify that your app behaves correctly when the user flow crosses into other apps or into the system UI. An example of such a user flow is a messaging app that lets the user enter a text message, launches the Android contact picker so that the users can select recipients to send the message to, and then returns control to the original app for the user to submit the message.

This lesson covers how to write such UI tests using the UI Automator testing framework provided by the Android Testing Support Library. The UI Automator APIs let you interact with visible elements on a device, regardless of which Activity is in focus. Your test can look up a UI component by using convenient descriptors such as the text displayed in that component or its content description. UI Automator tests can run on devices running Android 4.3 (API level 18) or higher.

The UI Automator testing framework is an instrumentation-based API and works with the AndroidJUnitRunner test runner.

Set Up UI Automator

Before you begin using UI Automator, you must:

Install the Android Testing Support Library. The UI Automator API is located under the com.android.support.test.uiautomator package. These classes allow you to create tests that use the Espresso testing framework. To learn how to install the library, see Testing Support Library Setup.
Set up your project structure. In your Gradle project, the source code for the target app that you want to test is typically placed under the app/src/main folder. The source code for instrumentation tests, including your UI Automator tests, must be placed under the app/src/androidTest folder. To learn more about setting up your project directory, see Managing Projects.
Specify your Android testing dependencies. In order for the Android Plug-in for Gradle to correctly build and run your UI Automator tests, you must specify the following libraries in the build.gradle file of your Android app module:
```
dependencies {
    androidTestCompile 'com.android.support.test:runner:0.3'
    androidTestCompile 'com.android.support.test:rules:0.3'
    androidTestCompile 'com.android.support.test.uiautomator:uiautomator-v18:2.1.1'
}
```

To optimize your UI Automator testing, you should first inspect the target app’s UI components and ensure that they are accessible. These optimization tips are described in the next two sections.

Inspecting the UI on a device

Before designing your test, inspect the UI components that are visible on the device. To ensure that your UI Automator tests can access these components, check that these components have visible text labels, android:contentDescription values, or both.

The uiautomatorviewer tool provides a convenient visual interface to inspect the layout hierarchy and view the properties of UI components that are visible on the foreground of the device. This information lets you create more fine-grained tests using UI Automator. For example, you can create a UI selector that matches a specific visible property.

To launch the uiautomatorviewer tool:

Launch the target app on a physical device.
Connect the device to your development machine.
Open a terminal window and navigate to the <android-sdk>/tools/ directory.
Run the tool with this command:
```
$ uiautomatorviewer
```

To view the UI properties for your application:

In the uiautomatorviewer interface, click the Device Screenshot button.
Hover over the snapshot in the left-hand panel to see the UI components identified by the uiautomatorviewertool. The properties are listed in the lower right-hand panel and the layout hierarchy in the upper right-hand panel.
Optionally, click on the Toggle NAF Nodes button to see UI components that are non-accessible to UI Automator. Only limited information may be available for these components.

To learn about the common types of UI components provided by Android, see User Interface.

Ensuring your Activity is accessible

The UI Automator test framework depends on the accessibility features of the Android framework to look up individual UI elements. As a developer, you should implement these minimum optimizations in your Activity to support UI Automator:

Use the android:contentDescription attribute to label the ImageButton, ImageView, CheckBox and other user interface controls.
Provide an android:hint attribute instead of a content description for EditText fields.
Associate an android:hint attribute with any graphical icons used by controls that provide feedback to the user (for example, status or state information).
Use the uiautomatorviewer tool to ensure that the UI component is accessible to the testing framework. You can also test the application by turning on accessibility services like TalkBack and Explore by Touch, and try using your application using only directional controls.

Generally, app developers get accessibility support for free, courtesy of the View and ViewGroup classes. However, some apps use custom view elements to provide a richer user experience. Such custom elements won't get the accessibility support that is provided by the standard Android UI elements. If this applies to your app, make sure that it exposes the custom-drawn UI element to Android accessibility services by implementing the AccessibilityNodeProvider class.

If the custom view element contains a single element, make it accessible by implementing accessibility API methods. If the custom view contains elements that are not views themselves (for example, a WebView, make sure it implements the AccessibilityNodeProvider class. For container views that extend an existing container implementation (for example, a ListView), implementing AccessibilityNodeProvider is not necessary.

For more information about implementing and testing accessibility, see Making Applications Accessible.

Create a UI Automator Test Class

To build a UI Automator test, create a class that extends InstrumentationTestCase. Implement the following programming model in your UI Automator test class:

Get a UiDevice object to access the device you want to test, by calling the getInstance() method and passing it an Instrumentation object as the argument.
Get a UiObject object to access a UI component that is displayed on the device (for example, the current view in the foreground), by calling the findObject() method.
Simulate a specific user interaction to perform on that UI component, by calling a UiObject method; for example, call performMultiPointerGesture() to simulate a multi-touch gesture, and setText() to edit a text field. You can call on the APIs in steps 2 and 3 repeatedly as necessary to test more complex user interactions that involve multiple UI components or sequences of user actions.
Check that the UI reflects the expected state or behavior, after these user interactions are performed.

These steps are covered in more detail in the sections below.

Accessing UI Components

The UiDevice object is the primary way you access and manipulate the state of the device. In your tests, you can call UiDevice methods to check for the state of various properties, such as current orientation or display size. Your test can use the UiDevice object to perform device-level actions, such as forcing the device into a specific rotation, pressing D-pad hardware buttons, and pressing the Home and Menu buttons.

It’s good practice to start your test from the Home screen of the device. From the Home screen (or some other starting location you’ve chosen in the device), you can call the methods provided by the UI Automator API to select and interact with specific UI elements.

The following code snippet shows how your test might get an instance of UiDevice and simulate a Home button press:

import android.test.InstrumentationTestCase;
import android.support.test.uiautomator.UiDevice;
import android.support.test.uiautomator.By;

public class CalculatorUiTest extends InstrumentationTestCase {

    private UiDevice mDevice;

    public void setUp() {
        // Initialize UiDevice instance
        mDevice = UiDevice.getInstance(getInstrumentation());

        // Start from the home screen
        mDevice.pressHome();
        mDevice.wait(Until.hasObject(By.pkg(getHomeScreenPackage()).depth(0)),
    }
}

Use the findObject() method to retrieve a UiObject which represents a view that matches a given selector criteria. You can reuse the UiObject instances that you have created in other parts of your app testing, as needed. Note that the UI Automator test framework searches the current display for a match every time your test uses a UiObject instance to click on a UI element or query a property.

The following snippet shows how your test might construct UiObject instances that represent a Cancel button and a OK button in an app.

UiObject cancelButton = mDevice.findObject(new UiSelector()
        .text("Cancel"))
        .className("android.widget.Button"));
UiObject okButton = mDevice.findObject(new UiSelector()
        .text("OK"))
        .className("android.widget.Button"));

// Simulate a user-click on the OK button, if found.
if(okButton.exists() && okButton.isEnabled()) {
    okButton.click();
}

Specifying a selector

If you want to access a specific UI component in an app, use the UiSelector class. This class represents a query for specific elements in the currently displayed UI.

If more than one matching element is found, the first matching element in the layout hierarchy is returned as the target UiObject. When constructing a UiSelector, you can chain together multiple properties to refine your search. If no matching UI element is found, a UiAutomatorObjectNotFoundException is thrown.

You can use the childSelector() method to nest multiple UiSelector instances. For example, the following code example shows how your test might specify a search to find the first ListView in the currently displayed UI, then search within that ListView to find a UI element with the text property Apps.

UiObject appItem = new UiObject(new UiSelector()
        .className("android.widget.ListView")
        .instance(1)
        .childSelector(new UiSelector()
        .text("Apps")));

As a best practice, when specifying a selector, you should use a Resource ID (if one is assigned to a UI element) instead of a text element or content-descriptor. Not all elements have a text element (for example, icons in a toolbar). Text selectors are brittle and can lead to test failures if there are minor changes to the UI. They may also not scale across different languages; your text selectors may not match translated strings.

It can be useful to specify the object state in your selector criteria. For example, if you want to select a list of all checked elements so that you can uncheck them, call the checked() method with the argument set to true.

Performing Actions

Once your test has obtained a UiObject object, you can call the methods in the UiObject class to perform user interactions on the UI component represented by that object. You can specify such actions as:

click() : Clicks the center of the visible bounds of the UI element.
dragTo() : Drags this object to arbitrary coordinates.
setText() : Sets the text in an editable field, after clearing the field's content. Conversely, the clearTextField() method clears the existing text in an editable field.
swipeUp() : Performs the swipe up action on the UiObject. Similarly, the swipeDown(), swipeLeft(), and swipeRight() methods perform corresponding actions.

The UI Automator testing framework allows you to send an Intent or launch an Activity without using shell commands, by getting a Context object through getContext().

The following snippet shows how your test can use an Intent to launch the app under test. This approach is useful when you are only interested in testing the calculator app, and don't care about the launcher.

public void setUp() {
    ...

    // Launch a simple calculator app
    Context context = getInstrumentation().getContext();
    Intent intent = context.getPackageManager()
            .getLaunchIntentForPackage(CALC_PACKAGE);
    intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK);
            // Clear out any previous instances
    context.startActivity(intent);
    mDevice.wait(Until.hasObject(By.pkg(CALC_PACKAGE).depth(0)), TIMEOUT);
}

Performing actions on collections

Use the UiCollection class if you want to simulate user interactions on a collection of items (for example, songs in a music album or a list of emails in an Inbox). To create a UiCollection object, specify a UiSelector that searches for a UI container or a wrapper of other child UI elements, such as a layout view that contains child UI elements.

The following code snippet shows how your test might construct a UiCollection to represent a video album that is displayed within a FrameLayout:

UiCollection videos = new UiCollection(new UiSelector()
        .className("android.widget.FrameLayout"));

// Retrieve the number of videos in this collection:
int count = videos.getChildCount(new UiSelector()
        .className("android.widget.LinearLayout"));

// Find a specific video and simulate a user-click on it
UiObject video = videos.getChildByText(new UiSelector()
        .className("android.widget.LinearLayout"), "Cute Baby Laughing");
video.click();

// Simulate selecting a checkbox that is associated with the video
UiObject checkBox = video.getChild(new UiSelector()
        .className("android.widget.Checkbox"));
if(!checkBox.isSelected()) checkbox.click();

Performing actions on scrollable views

Use the UiScrollable class to simulate vertical or horizontal scrolling across a display. This technique is helpful when a UI element is positioned off-screen and you need to scroll to bring it into view.

The following code snippet shows how to simulate scrolling down the Settings menu and clicking on an About tablet option:

UiScrollable settingsItem = new UiScrollable(new UiSelector()
        .className("android.widget.ListView"));
UiObject about = settingsItem.getChildByText(new UiSelector()
        .className("android.widget.LinearLayout"), "About tablet");
about.click();

Verifying Results

The InstrumentationTestCase extends TestCase, so you can use standard JUnit Assert methods to test that UI components in the app return the expected results.

The following snippet shows how your test can locate several buttons in a calculator app, click on them in order, then verify that the correct result is displayed.

private static final String CALC_PACKAGE = "com.myexample.calc";

public void testTwoPlusThreeEqualsFive() {
    // Enter an equation: 2 + 3 = ?
    mDevice.findObject(new UiSelector()
            .packageName(CALC_PACKAGE).resourceId("two")).click();
    mDevice.findObject(new UiSelector()
            .packageName(CALC_PACKAGE).resourceId("plus")).click();
    mDevice.findObject(new UiSelector()
            .packageName(CALC_PACKAGE).resourceId("three")).click();
    mDevice.findObject(new UiSelector()
            .packageName(CALC_PACKAGE).resourceId("equals")).click();

    // Verify the result = 5
    UiObject result = mDevice.findObject(By.res(CALC_PACKAGE, "result"));
    assertEquals("5", result.getText());
}

Run UI Automator Tests on a Device or Emulator

UI Automator tests are based on the Instrumentation class. The Android Plug-in for Gradle provides a default directory (src/androidTest/java) for you to store the instrumented test classes and test suites that you want to run on a device. The plug-in compiles the test code in that directory and then executes the test app using a test runner class. You are strongly encouraged to use the AndroidJUnitRunner class provided in the Android Testing Support Library as your default test runner.

To run UI Automator tests in your Gradle project:

Specify AndroidJUnitRunner as the default test instrumentation runner in your build.gradle file:

android {
    defaultConfig {
        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
    }
}

Run your tests from the command-line by calling the connectedCheck (or cC) task:
```
./gradlew cC
```