Testing Support Library

In this document

See also

The Android Testing Support Library provides an extensive framework for testing Android apps.
This library provides a set of APIs that allow you to quickly build and run test code for
your apps, including JUnit 4 and functional user interface (UI) tests. You can run tests
created using these APIs from the Android Studio IDE or from the command line.

AndroidJUnitRunner

The
AndroidJUnitRunner
class is a JUnit test runner that lets you
run JUnit 3 or JUnit 4-style test classes on Android devices, including those using the
Espresso and UI Automator testing frameworks.
The test runner handles loading your test package and the app under test
to a device, running your tests, and reporting test results. This class replaces the InstrumentationTestRunner class, which only supports JUnit 3 tests.

JUnit support

The test runner is compatible with your JUnit 3 and JUnit 4 (up to JUnit
4.10) tests. However, you should avoid mixing JUnit 3 and and JUnit 4 test code in the same
package, as this might cause unexpected results. If you are creating an instrumented JUnit 4
test class to run on a device or emulator, your test class must be prefixed with the
@RunWith(AndroidJUnit4.class) annotation.

The following code snippet shows how you might write an instrumented JUnit 4 test to validate
that the add operation in the CalculatorActivity class works correctly.

Access to instrumentation information

You can use the
InstrumentationRegistry
class to access information related to your
test run. This class includes the Instrumentation object, target app Context object, test app Context object, and the
command line arguments passed into your test. This data is useful when you are writing tests
using the UI Automator framework or when writing tests that have dependencies on the Instrumentation or Context objects.

Test filtering

In your JUnit 4.x tests, you can use annotations to configure the test run. This feature
minimizes the need to add boilerplate and conditional code in your tests. In addition to the
standard annotations supported by JUnit 4, the test runner also supports Android-specific
annotations, including:

@RequiresDevice:
Specifies that the test should run only on physical devices, not on emulators.

@SdkSupress:
Suppresses the test from running on a lower Android API level than the given level. For
example, to suppress tests on all API levels lower than 18 from running, use the annotation
@SDKSupress(minSdkVersion=18).

Test sharding

The test runner supports splitting a single test suite into multiple
shards, so you can easily run tests belonging to the same shard together as a group,
under the same Instrumentation instance. Each shard is identified by an
index number. When running tests, use the -e numShards option to specify the number
of separate shards to create and the -e shardIndex option to specify which shard to
run.

For example, to split the test suite into 10 shards and run only the tests grouped in the
second shard, use the following command:

Espresso

The Espresso testing framework provides a set of APIs to build UI tests to test user flows
within an app. These APIs let you write automated UI tests that are concise and that run
reliably. Espresso is well-suited for writing white box-style automated tests, where
the test code utilizes implementation code details from the app under test.

The key features of the Espresso testing framework include:

Flexible APIs for view and adapter matching in target apps.
For more information, see View matching.

An extensive set of action APIs to automate UI interactions.
For more information, see Action APIs.

View matching

The Espresso.onView()
method lets you access a UI component in the target app and
interact with it. The method accepts a
Matcher argument and searches the view
hierarchy to locate a corresponding View instance that meets some given
criteria. You can refine searches by specifying such criteria as:

The class name of the view

The content description of the view

The R.id of the view

Text displayed in the view

For example, to target a button that has the ID value of my_button, you can specify
a matcher like this:

onView(withId(R.id.my_button));

If the search is successful, the
onView()
method returns a reference which lets you
perform user actions and test assertions against the target view.

Adapter matching

In an AdapterView layout, the layout is dynamically populated with
children views at runtime. If the target view is inside a layout subclassed from AdapterView (such as a ListView or GridView), the
onView()
method might not work because only a subset of
the layout’s views may be loaded in the current view hierarchy.

Action APIs

Typically, you test an app by performing some user interactions against the app’s user
interface. You can easily automate these actions in your test by using the
ViewActions
API. You can perform such UI interactions as:

// Type text into an EditText view, then close the soft keyboard
onView(withId(R.id.editTextUserInput))
.perform(typeText(STRING_TO_BE_TYPED), closeSoftKeyboard());
// Press the button to submit the text change
onView(withId(R.id.changeTextBt)).perform(click());

UI thread synchronization

Tests on Android devices can fail randomly because of timing issues. This testing issue is
referred to as test flakiness. Prior to Espresso, the workaround was to insert a
sufficiently long sleep or timeout period into a test or to add code to keep retrying the
failing operation. The Espresso testing framework handles synchronization between the
Instrumentation and the UI thread; this removes the need for the previous
timing workarounds and ensures that your test actions and assertions run more reliably.

UI Automator

The UI Automator testing framework provides a set of APIs to build UI tests that perform
interactions on user apps and system apps. The UI Automator APIs allows you to perform
operations such as opening the Settings menu or the app launcher in a test device. The UI
Automator testing framework is well-suited for writing black box-style automated
tests, where the test code does not rely on internal implementation details of the target
app.

An API to retrieve state information and perform operations on the target device.
For more information, see Access to device state.

APIs that support cross-app UI testing.
For more information, see UI Automator APIs .

Requires Android 4.3 (API level 18) or higher.

UI Automator Viewer

The uiautomatorviewer tool provides a convenient GUI to scan and analyze the UI
components currently displayed on an Android device. You can use this tool 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 by creating a UI selector that matches a specific visible property.

The uiautomatorviewer tool is located in the <android-sdk>/tools/
directory.

Access to device state

The UI Automator testing framework provides a
UiDevice
class to access and perform operations on the device on which the target app is running. You
can call its methods to access device properties such as current orientation or display size.
The UiDevice
class also let you perform actions such as:

Change the device rotation

Press a D-pad button

Press the Back, Home, or Menu buttons

Open the notification shade

Take a screenshot of the current window

For example, to simulate a Home button press, call the UiDevice.pressHome() method.

UI Automator APIs

The UI Automator APIs allow you to write robust tests without needing to know about the
implementation details of the app that you are targeting. You can use these APIs to capture
and manipulate UI components across multiple apps:

UiCollection:
Enumerates a container's UI elements for the purpose of counting,
or targeting sub-elements by their visible text or content-description property.

UiScrollable:
Provides support for searching for items in a scrollable UI container.

UiSelector:
Represents a query for one or more target UI elements on a device.

Configurator:
Allows you to set key parameters for running UI Automator tests.

For example, the following code shows how you can write a test script that brings up the
default app launcher in the device:

// Initialize UiDevice instance
mDevice = UiDevice.getInstance(getInstrumentation());
// Perform a short press on the HOME button
mDevice().pressHome();
// Bring up the default launcher by searching for
// a UI component that matches the content-description for the launcher button
UiObject allAppsButton = mDevice
.findObject(new UiSelector().description("Apps"));
// Perform a click on the button to bring up the launcher
allAppsButton.clickAndWaitForNewWindow();

In the SDK Manager window, scroll to the end of the Packages list, find the
Extras folder and, if necessary, expand to show its contents.

Select the Android Support Repository item.

Click the Install packages... button.

After downloading, the tool installs the Support Repository files to your existing Android
SDK directory. The library files are located in the following subdirectory of your SDK:
<sdk>/extras/android/m2repository directory.

The Android Testing Support Library classes are located under the
android.support.test package.

To use the Android Testing Support Library in your Gradle project, add these dependencies in
your build.gradle file:

dependencies {
androidTestCompile 'com.android.support.test:runner:0.3'
// Set this dependency to use JUnit 4 rules
androidTestCompile 'com.android.support.test:rules:0.3'
// Set this dependency to build and run Espresso tests
androidTestCompile 'com.android.support.test.espresso:espresso-core:2.2'
// Set this dependency to build and run UI Automator tests
androidTestCompile 'com.android.support.test.uiautomator:uiautomator-v18:2.1.1'
}

To set
AndroidJUnitRunner
as the default test instrumentation runner in your Gradle project, specify this dependency in
your build.gradle file: