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.
Sample
Codelabs