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.

For a more complete how-to guide for writing tests, see Testing apps on Android.

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.

The Gradle build interprets these test source sets in the same manner as it does for your project's app source sets, which allows you to create tests based on build variants.

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.

Figure 1. Your project's (1) instrumented tests and (2) local JVM tests are visible in either the Project view (left) or Android view (right).

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:

  1. Open the Java file containing the code you want to test.
  2. Click the class or method you want to test, then press Ctrl+Shift+T (⇧⌘T).
  3. In the menu that appears, click Create New Test.
  4. In the Create Test dialog, edit any fields and select any methods to generate, and then click OK.
  5. 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:

  1. In the Project window on the left, click the drop-down menu and select the Project view.
  2. 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.
  3. Right-click on the Java package directory and select New > Java Class.
  4. Name the file and then click OK.

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

dependencies {
    // Required for local unit tests (JUnit 4 framework)
    testImplementation 'junit:junit:4.12'

    // Required for instrumented tests
    androidTestImplementation 'com.android.support:support-annotations:24.0.0'
    androidTestImplementation 'com.android.support.test:runner:0.5'
}

For other optional library dependencies and more information about how to write your tests, see Building local unit tests and Building instrumented unit tests.

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.

To learn more, read Fix dependency resolution errors.

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:

  1. In the Project window on the left, click the drop-down menu and select the Project view.
  2. Within the appropriate module folder, right-click the src folder and click New > Directory.
  3. 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.
  4. Right-click on the new directory and click New > Directory.
  5. 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.

Groovy

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
    }
}
...

Kotlin

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.

Groovy

android {
    ...
    // Encapsulates options for running tests.
    testOptions {
        // Changes the directory where Gradle saves test reports. By default, Gradle saves test reports
        // in the path_to_your_project/module_name/build/outputs/reports/ directory.
        // '$rootDir' sets the path relative to the root directory of the current project.
        reportDir "$rootDir/test-reports"
        // Changes the directory where Gradle saves test results. By default, Gradle saves test results
        // in the path_to_your_project/module_name/build/outputs/test-results/ directory.
        // '$rootDir' sets the path relative to the root directory of the current project.
        resultsDir "$rootDir/test-results"
    }
}

Kotlin

android {
    ...
    // Encapsulates options for running tests.
    testOptions {
        // Changes the directory where Gradle saves test reports. By default, Gradle saves test reports
        // in the path_to_your_project/module_name/build/outputs/reports/ directory.
        // '$rootDir' sets the path relative to the root directory of the current project.
        reportDir = "$rootDir/test-reports"
        // Changes the directory where Gradle saves test results. By default, Gradle saves test results
        // in the path_to_your_project/module_name/build/outputs/test-results/ directory.
        // '$rootDir' sets the path relative to the root directory of the current project.
        resultsDir = "$rootDir/test-results"
    }
}

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

Groovy

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'
                }
                ...
            }
        }
    }
}

Kotlin

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 = listOf("-XX:MaxPermSize=256m")

                // You can also check the task name to apply options to only the tests you specify.
                if (it.name == "testDebugUnitTest") {
                    systemProperty = mapOf("debug" to "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:

  1. Create a library module.
  2. In the module level build file, apply the com.android.test plugin instead of com.android.library.
  3. Sync your project.

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:

Groovy

android {
    variantFilter { variant ->
        if (variant.buildType.name.equals('debug')) {
            variant.setIgnore(true);
        }
    }
}

Kotlin

android {
    variantFilter {
        if (buildType.name == "debug") {
            ignore = true
        }
    }
}

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:

  1. Be sure your project is synchronized with Gradle by clicking Sync Project in the toolbar.
  2. 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:

  1. Double-click the unit test you want to run.
  2. 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.
  3. Right-click the line where you placed your cursor.
  4. In the context menu, choose Run test-name with coverage.

    The coverage tool window appears.

Figure 2 shows the coverage tool window for a calculator unit test that tests for addition, subtraction, multiplication, and division.

Figure 2. See the code coverage percentages for your application.

For more information about local unit tests, see Building local unit tests.

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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:

  1. Click the cog icon .
  2. 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:

  1. In the output pane, click the Click to see difference link.
  2. In the Differences viewer, explore the differences as described on the IntelliJ page, Differences viewer for files.

Export test results

You can export your test results in XML or HTML format, as follows:

  1. Click Export Test Results .
  2. In the Export Test Results dialog, provide format and output information, and click OK.

    The exported test results save to the specified folder.

Import test results

You can import your exported test results, as follows:

  1. Click Import Test Results .
  2. In the drop-down menu, select the file you want to import.

    The imported tests results appear in the Run window.