Instrumented tests run on Android devices, whether physical or emulated. As such, they can take advantage of the Android framework APIs. Instrumented tests therefore provide more fidelity than local tests, though they run much more slowly.
We recommend using instrumented tests only in cases where you must test against the behavior of a real device. AndroidX Test provides several libraries that make it easier to write instrumented tests when necessary.
Set up your testing environment
In your Android Studio project, you store the source files for instrumented
tests in module-name/src/androidTest/java/
. This directory already exists when
you create a new project and contains an example instrumented test.
Before you begin, you should add AndroidX Test APIs, which allow you to quickly
build and run instrumented test code for your apps. AndroidX Test includes a
JUnit 4 test runner ,AndroidJUnitRunner
, and APIs for functional UI tests
such as Espresso, UI Automator and Compose test.
You also need to configure the Android testing dependencies for your project to use the test runner and the rules APIs provided by AndroidX Test.
In your app's top-level build.gradle
file, you need to specify these libraries
as dependencies:
dependencies {
androidTestImplementation "androidx.test:runner:$androidXTestVersion"
androidTestImplementation "androidx.test:rules:$androidXTestVersion"
// Optional -- UI testing with Espresso
androidTestImplementation "androidx.test.espresso:espresso-core:$espressoVersion"
// Optional -- UI testing with UI Automator
androidTestImplementation "androidx.test.uiautomator:uiautomator:$uiAutomatorVersion"
// Optional -- UI testing with Compose
androidTestImplementation "androidx.compose.ui:ui-test-junit4:$compose_version"
}
You can find the latest versions in the AndroidX Release Notes and Compose UI Release Notes.
To use JUnit 4 test classes and have access to features such as test filtering,
make sure to specify AndroidJUnitRunner as the default test instrumentation
runner in your project by including the following setting in your app's
module-level build.gradle
file:
android {
defaultConfig {
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
}
}
Create an instrumented test class
Your instrumented test class should be a JUnit 4 test class that's similar to the class described in the section on how to build local tests.
To create an instrumented JUnit 4 test class, specify AndroidJUnit4
as your
default test runner.
The following example shows how you might write an instrumented test to verify
that the Parcelable interface is implemented correctly for the
LogHistory
class:
Kotlin
import android.os.Parcel import android.text.TextUtils.writeToParcel import androidx.test.filters.SmallTest import androidx.test.runner.AndroidJUnit4 import com.google.common.truth.Truth.assertThat import org.junit.Before import org.junit.Test import org.junit.runner.RunWith const val TEST_STRING = "This is a string" const val TEST_LONG = 12345678L // @RunWith is required only if you use a mix of JUnit3 and JUnit4. @RunWith(AndroidJUnit4::class) @SmallTest class LogHistoryAndroidUnitTest { private lateinit var logHistory: LogHistory @Before fun createLogHistory() { logHistory = LogHistory() } @Test fun logHistory_ParcelableWriteRead() { val parcel = Parcel.obtain() logHistory.apply { // Set up the Parcelable object to send and receive. addEntry(TEST_STRING, TEST_LONG) // Write the data. writeToParcel(parcel, describeContents()) } // After you're done with writing, you need to reset the parcel for reading. parcel.setDataPosition(0) // Read the data. val createdFromParcel: LogHistory = LogHistory.CREATOR.createFromParcel(parcel) createdFromParcel.getData().also { createdFromParcelData: List<Pair<String, Long>> -> // Verify that the received data is correct. assertThat(createdFromParcelData.size).isEqualTo(1) assertThat(createdFromParcelData[0].first).isEqualTo(TEST_STRING) assertThat(createdFromParcelData[0].second).isEqualTo(TEST_LONG) } } }
Java
import android.os.Parcel; import android.util.Pair; import androidx.test.runner.AndroidJUnit4; import com.google.common.truth.Truth.assertThat; import java.util.List; import org.junit.Before; import org.junit.Test; import org.junit.runner.RunWith; // @RunWith is required only if you use a mix of JUnit3 and JUnit4. @RunWith(AndroidJUnit4.class) public class LogHistoryAndroidUnitTest { public static final String TEST_STRING = "This is a string"; public static final long TEST_LONG = 12345678L; private LogHistory mLogHistory; @Before public void createLogHistory() { mLogHistory = new LogHistory(); } @Test public void logHistory_ParcelableWriteRead() { // Set up the Parcelable object to send and receive. mLogHistory.addEntry(TEST_STRING, TEST_LONG); // Write the data. Parcel parcel = Parcel.obtain(); mLogHistory.writeToParcel(parcel, mLogHistory.describeContents()); // After you're done with writing, you need to reset the parcel for reading. parcel.setDataPosition(0); // Read the data. LogHistory createdFromParcel = LogHistory.CREATOR.createFromParcel(parcel); List<Pair<String, Long>> createdFromParcelData = createdFromParcel.getData(); // Verify that the received data is correct. assertThat(createdFromParcelData.size()).isEqualTo(1); assertThat(createdFromParcelData.get(0).first).isEqualTo(TEST_STRING); assertThat(createdFromParcelData.get(0).second).isEqaulTo(TEST_LONG); } }
Run instrumented tests
Instrumented tests can be run on real devices or emulators. In the Android Studio guide you can learn how to:
Additional resources
UI tests are usually Instrumented tests that verify the correct behavior of the UI. They use frameworks such as Espresso or Compose Test. To learn more, read the UI testing guide.
For more information about using Instrumentation tests, consult the following resources.