Test your app

Android Studio is designed to make testing simple. With just a few clicks, you
can set up a JUnit test that runs on the local JVM or an instrumented test that
runs on a device. Of course, you can also extend your test capabilities by
integrating test frameworks such as
Mockito to test Android API calls in your
local unit tests, and
Espresso or
UI Automator
to exercise user interaction in your instrumented tests. You can generate
Espresso tests automatically using
Espresso Test Recorder.

This page provides the basic information about how to add new tests to your app
and run them from Android Studio.

Test types and location

The location of your test code depends on the type of test you are writing.
Android Studio provides source code directories (source sets), for the
following two types of tests:

Local unit tests

Located at module-name/src/test/java/.

These are tests that run on your machine's local Java Virtual Machine (JVM).
Use these tests to minimize execution time when your tests have no Android
framework dependencies or when you can mock the Android framework dependencies.

At runtime, these tests are executed against a modified version of
android.jar where all final modifiers have been
stripped off. This lets you use popular mocking libraries, like Mockito.

Instrumented tests

Located at module-name/src/androidTest/java/.

These are tests that run on a hardware device or emulator. These tests have
access to Instrumentation
APIs, give you access to information such as the
Context
of the app you are testing,
and let you control the app under test from
your test code. Use these tests when writing integration and functional UI
tests to automate user interaction, or when your tests have Android dependencies
that mock objects cannot satisfy.

Because instrumented tests are built into an APK (separate from your app
APK), they must have their own AndroidManifest.xml file. However, Gradle automatically
generates this file during the build so it is not visible in your project
source set. You can add your own manifest file if necessary, such as to
specify a different value for `minSdkVersion` or register run listeners just
for your tests. When building your app, Gradle merges multiple manifest files
into one manifest.

When you create a new project or add an app module, Android Studio creates
the test source sets listed above and includes an example test file in each.
You can see them in the Project window as shown in figure 1.

Add a new test

To create either a local unit test or an instrumented test, you can create a
new test for a specific class or method by following these steps:

Open the Java file containing the code you want to test.

Click the class or method you want to test, then press Ctrl+Shift+T (⇧⌘T).

In the menu that appears, click Create New Test.

In the Create Test dialog, edit any fields and select any methods to
generate, and then click OK.

In the Choose Destination Directory dialog, click the source set
corresponding to the type of test you want to create: androidTest for an
instrumented test or test for a local unit test. Then click OK.

Alternatively, you can create a generic Java file in the appropriate test
source set as follows:

In the Project window on the left, click the drop-down menu and select
the Project view.

Expand the appropriate module folder and the nested src folder.
To add a local unit test, expand the test folder and the nested
java folder; to add an instrumented test, expand the androidTest
folder and the nested java folder.

Right-click on the Java package directory and select New > Java Class.

Name the file and then click OK.

Also be sure you specify the test library dependencies in
your app module's build.gradle file:

Resolve conflicts between the app and test APK

Both your app APK and its test APK share the same classpaths. So, you can get a
build error if both APKs depend on different versions of the same library. If
Gradle isn't able to detect this version conflict, your app may
behave unexpectedly or crash during runtime.

Create instrumented test for a build variant

If your project includes build variants
with unique source sets, then you might want corresponding instrumented test
source sets. Creating instrumented tests in source sets that correspond to your
build variants helps keep your test code organized and allows you to run only
the tests that apply to a given build variant.

To add a testing source set for your build variant, follow these steps:

In the Project window on the left, click the drop-down menu and select
the Project view.

Within the appropriate module folder, right-click the src folder
and click New > Directory.

For the directory name, enter "androidTestVariantName." For example, if
you have a build variant called "MyFlavor" then the directory name should be
"androidTestMyFlavor." Then click OK.

Right-click on the new directory and click New > Directory.

Enter "java" as the directory name, and then click OK.

Now you can add tests to this new source set by following the steps above to
add a new test. When you reach the Choose Destination Directory dialog,
select the new variant test source set.

The instrumented tests in src/androidTest/ source set are shared by all build
variants. When building a test APK for the "MyFlavor" variant of your app,
Gradle combines both the src/androidTest/ and src/androidTestMyFlavor/
source sets.

For example, the following table shows how instrumentation test files should
reside in source sets that correspond to the app's code source sets.

Path to app class

Path to matching instrumentation test class

src/main/java/Foo.java

src/androidTest/java/AndroidFooTest.java

src/myFlavor/java/Foo.java

src/androidTestMyFlavor/java/AndroidFooTest.java

Just as it does for your app source sets, the Gradle build merges and
overrides files from different test source sets. In this case, the
AndroidFooTest.java file in the "androidTestMyFlavor" source
set overrides the version in the "androidTest" source set. For more information
about how source sets are merged, see
Configure your build.

Another reason you should use build variants for your app and test source sets
is to create hermetic tests through mock dependencies. That is, you can create
a product flavor for your app that contains fake implementations of
dependencies (such as network requests or device sensor data that is ordinarily
flaky), and then add a corresponding mock test source set. For more
information, see the blog post about leveraging product flavors for hermetic
testing.

Configure instrumentation manifest settings

When Gradle builds your test APK, it automatically generates the AndroidManifest.xml
file and configures it with the <instrumentation>
node. One of the reasons Gradle configures this node for you is to make sure
that the targetPackage
property specifies the correct package name of the app under test. You can change some
of the other settings for this node by either creating another manifest
file in the test source set or configuring your module-level
build.gradle file, as shown in the following code sample.

android {
...
// Each product flavor you configure can override properties in the
// defaultConfig {} block. To learn more, go to Configure product flavors.
defaultConfig {
...
// Specifies the application ID for the test APK.
testApplicationId "com.test.foo"
// Specifies the fully-qualified class name of the test instrumentation runner.
testInstrumentationRunner "android.test.InstrumentationTestRunner"
// If set to 'true', enables the instrumentation class to start and stop profiling.
// If set to false (default), profiling occurs the entire time the instrumentation
// class is running.
testHandleProfiling true
// If set to 'true', indicates that the Android system should run the instrumentation
// class as a functional test. The default value is 'false'
testFunctionalTest true
}
}
...

Change the test build type

By default, all tests run against the debug build type. You can change this to
another build type by using the testBuildType property in your module-level
build.gradle file. For example, if you want to run your tests against your
"staging" build type, edit the file as shown in the following snippet.

android {
...
testBuildType "staging"
}

Configure Gradle test options

The Android plugin for Gradle allows you
to specify certain options for all or just some of your unit tests. In the
module-level build.gradle file, use the testOptions
{}
block to specify options that change how Gradle runs all your tests.

To specify options for only local unit tests, configure the unitTests
{}
block inside testOptions {}.

android {
...
testOptions {
...
// Encapsulates options for local unit tests.
unitTests {
// By default, local unit tests throw an exception any time the code you are testing tries to access
// Android platform APIs (unless you mock Android dependencies yourself or with a testing
// framework like Mockito). However, you can enable the following property so that the test
// returns either null or zero when accessing platform APIs, rather than throwing an exception.
returnDefaultValues true
// Encapsulates options for controlling how Gradle executes local unit tests. For a list
// of all the options you can specify, read Gradle's reference documentation.
all {
// Sets JVM argument(s) for the test JVM(s).
jvmArgs '-XX:MaxPermSize=256m'
// You can also check the task name to apply options to only the tests you specify.
if (it.name == 'testDebugUnitTest') {
systemProperty 'debug', 'true'
}
...
}
}
}
}

Use separate test modules for instrumented tests

If you want to have a module dedicated for instrumented tests and isolate the
rest of your code from your tests, you can create a separate test module and
configure its build similar to that of a library module. To create a test module,
proceed as follows:

After you create your test module, you can include your test code in the main or
variant source set (for example, src/main/java or src/variant/java).
If your app module defines multiple product flavors, you can recreate those
flavors in your test module, and, using variant aware dependency management, the test module attempts to test the
matching flavor in the target module.

By default, test modules contain and test only a debug variant. However, you can
create new build types to match the tested app project. To make the test module
test a different build type, and not the debug one, use
VariantFilter to disable the debug variant in the test project, as shown below:

If you want a test module to target only certain flavors or build types of an
app, you can use the matchingFallbacks
property to target only the variants you want to test. This also prevents the
test module from having to configure those variants for itself.

Run a test

To run a test, proceed as follows:

Be sure your project is synchronized with Gradle by clicking
Sync Project
in the toolbar.

Run your test in one of the following ways:

In the Project window, right-click a test and click Run.

In the Code Editor, right-click a class or method in the test file and
click Run
to test all methods in the class.

To run all tests, right-click on the test directory and click Run
tests.

By default, your test runs using Android Studio's default run configuration. If
you'd like to change some run settings such as the instrumentation runner and
deployment options, you can edit the run configuration in the Run/Debug
Configurations dialog (click Run > Edit Configurations).

View test coverage

The test coverage tool is available for local unit tests to track the percentage
and areas of your app code that your unit tests have covered. Use the
test coverage tool to determine whether you have adequately tested the elements,
classes, methods, and lines of code that make up your app.

There are a number of ways to run a unit test, and they are described on the
IntelliJ
Running with Coverage page. The following procedure shows how to run
a unit test inline from the editor:

Double-click the unit test you want to run.

In the editor, place your cursor in the line you want to run with
coverage.

If you place your cursor in the class declaration, all test methods
in that class run.

If you place your cursor in a method declaration, all
code in that method runs.

If you place your cursor on a particular line within
a method, only that line runs.

View the test results

When you run a JUnit or instrumented test, the results appear in the
Run window. A green bar means all tests succeeded and a red bar means at
least one test failed. Figure 3 shows a successful test run.

Figure 3. Test results appear in the Run window.

The Run window displays the tests in a tree view on the left, and the
results and messages for the current test suite in the output pane on the right.
Use the toolbars, context menus, and status icons to manage the
test results, as follows:

Use the run toolbar to rerun the current test, stop the current test,
rerun failed tests (not shown because it is available for unit tests only),
pause output, and dump threads.

Use the testing toolbar to filter and sort test results. You can
also expand or collapse nodes, show test coverage, and import or export test
results.

Click the context menu to track the running test, show inline statistics, scroll to the
stacktrace, open the source code at an exception, auto scroll to the source,
and select the first failed test when the test run completes.

Test status icons indicate whether a test has an error, was
ignored, failed, is in progress, has passed, is paused, was terminated, or
was not run.

Right-click a line in the tree view to display a context menu that lets
you run the tests in debug mode, open the test source code file, or jump to
the line in the source code being tested.

For more information about the Run window, its toolbars, and context menus,
see the IntelliJ page,
Test
Runner Tab.

View inline statistics

To find out how long your tests took to run, do the
following:

Click the cog icon
.

In the drop-down list, select Show Inline Statistics.

The elapsed time in milliseconds displays to the right of the tests.

Compare strings

If a unit test contains assertEquals() failures from comparing
two string objects, you can see what the differences are between the two
string objects to find out what caused the failures, as follows: