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.

This test runner supports several common testing tasks, including the following:

• Writing JUnit tests
• Accessing instrumentation information
• Filtering tests
• Sharding tests

Writing JUnit tests

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 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:

@RunWith(AndroidJUnit4.class)
@LargeTest
public class ChangeTextBehaviorTest {

    private static final String mStringToBeTyped = "Espresso";

    @Rule
    public ActivityTestRule<MainActivity> mActivityRule =
            new ActivityTestRule<>(MainActivity.class);

    @Test
    public void changeText_sameActivity() {
        // Type text and then press the button.
        onView(withId(R.id.editTextUserInput))
                .perform(typeText(mStringToBeTyped), closeSoftKeyboard());
        onView(withId(R.id.changeTextBt)).perform(click());

        // Check that the text was changed.
        onView(withId(R.id.textToBeChanged))
                .check(matches(withText(mStringToBeTyped)));
    }
}

Accessing instrumentation information

You can use the InstrumentationRegistry class to access information related to your test run. This class includes the Instrumentation object, the target app Context object, the 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.

Filtering tests

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 the following:

• @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 23 from running, use the annotation @SDKSupress(minSdkVersion=23).
• @SmallTest, @MediumTest, and @LargeTest: Classify how long a test should take to run, and consequently, how frequently you can run the test.

Sharding tests

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:

adb shell am instrument -w -e numShards 10 -e shardIndex 2

Resources

To learn more about using this test runner, see the API reference.

To use the AndroidJUnitRunner class, include it as one of your project's packages.