Effective in 2026, to align with our trunk stable development model and ensure platform stability for the ecosystem, we will publish source code to AOSP in Q2 and Q4. For building and contributing to AOSP, we recommend utilizing android-latest-release instead of aosp-main. The android-latest-release manifest branch will always reference the most recent release pushed to AOSP. For more information, see Changes to AOSP.

InstrumentationTest

public class InstrumentationTest
extends Object implements IAbiReceiver, IConfigurationReceiver, IDeviceTest, IMetricCollectorReceiver, IRemoteTest, ITestCollector

java.lang.Object
↳	com.android.tradefed.testtype.InstrumentationTest

Known direct subclasses

AndroidJUnitTest, CodeCoverageTest

AndroidJUnitTest	A Test that runs an instrumentation test package on given device using the android.support.test.runner.AndroidJUnitRunner.
CodeCoverageTest	A Test that runs an instrumentation test package on a given device and generates the code coverage report.

A Test that runs an instrumentation test package on given device.

Summary

Constants
`String`	`RUN_TESTS_AS_USER_KEY`
`String`	`RUN_TESTS_ON_SDK_SANDBOX`

Fields
`protected boolean`	`mDebug`
`protected boolean`	`mInstrumentInPcc`
`protected boolean`	`mInstrumentSdkInSandbox`
`protected boolean`	`mInstrumentSdkSandbox`

Public constructors
`InstrumentationTest()`

Public methods
`void`	`addDeviceListeners(Set<String> extraListeners)` Allows to add more custom listeners to the runner
`void`	`addInstrumentationArg(String key, String value)` Add an argument to provide when running the instrumentation tests.
`IAbi`	`getAbi()`
`IConfiguration`	`getConfiguration()` Gets the `IConfiguration` for this test.
`String`	`getCoverageTarget()` Get the coverageTarget previously set via `setCoverageTarget(String)`.
`boolean`	`getDebug()` Get the instrumentation debug setting.
`ITestDevice`	`getDevice()` Get the device under test.
`String`	`getForceAbi()`
`long`	`getMaxTimeout()` Returns the max timeout set for the instrumentation.
`String`	`getPackageName()` Get the Android manifest package to run.
`String`	`getRunName()` Get the custom test run name that will be provided to listener
`String`	`getRunnerName()` Gets the Android instrumentation runner to be used.
`boolean`	`isCollectTestsOnly()`
`boolean`	`isOrchestrator()` Returns the value of `ERROR(InstrumentationTest.mOrchestrator/#mOrchestrator InstrumentationTest.mOrchestrator)`
`void`	`run(TestInformation testInfo, ITestInvocationListener listener)` Runs the tests, and reports result to the listener.
`void`	`setAbi(IAbi abi)`
`void`	`setClassName(String testClassName)` Optionally, set the test class name to run.
`void`	`setCollectTestsOnly(boolean shouldCollectTest)` Enables or disables test collection mode
`void`	`setCollectsTestsShellTimeout(int timeout)` This method is deprecated. This method is a no-op
`void`	`setConfiguration(IConfiguration config)` Injects the `IConfiguration` in use.
`void`	`setCoverageTarget(String coverageTarget)` Set the coverage target of this test.
`void`	`setDebug(boolean debug)` Set the instrumentation debug setting.
`void`	`setDevice(ITestDevice device)` Inject the device under test.
`void`	`setEnforceFormat(boolean enforce)` Set True if we enforce the AJUR output format of instrumentation.
`void`	`setForceAbi(String abi)` Sets force-abi option.
`void`	`setInstallFile(File installFile)` Set the optional file to install that contains the tests.
`void`	`setIsolatedStorage(boolean isolatedStorage)` Set wether or not to use the isolated storage.
`void`	`setMethodName(String testMethodName)` Optionally, set the test method to run.
`void`	`setMetricCollectors(List<IMetricCollector> collectors)` Sets the list of `IMetricCollector`s defined for the test run.
`void`	`setOrchestrator(boolean useOrchestrator)` Sets the --orchestrator option
`void`	`setPackageName(String packageName)` Set the Android manifest package to run.
`void`	`setReRunUsingTestFile(boolean reRunUsingTestFile)` Sets the --rerun-from-file option.
`void`	`setRerunMode(boolean rerun)` Optionally, set the rerun mode.
`void`	`setRetryAttemptNumber(int attemptNumber)` Sets the retry attempt number for the test. Sets the retry attempt number by pushing it as a "retry_attempt" instrumentation argument to the device-side runner.
`void`	`setRunName(String runName)` Set the custom test run name that will be provided to listener
`void`	`setRunnerName(String runnerName)` Optionally, set the Android instrumentation runner to use.
`void`	`setShellTimeout(long timeout)` Optionally, set the maximum time (in milliseconds) expecting shell output from the device.
`void`	`setTestFilePathOnDevice(String testFilePathOnDevice)` Optionally, set the path to a file located on the device that should contain a list of line separated test classes and methods (format: com.foo.Class#method) to be run.
`void`	`setTestPackageName(String testPackageName)` Sets the test package filter.
`void`	`setTestSize(String size)` Optionally, set the test size to run.
`void`	`setTestTimeout(long timeout)` Optionally, set the maximum time (in milliseconds) for each individual test run.
`void`	`setTestsToRun(Collection<TestDescription> tests)` Set the collection of tests that should be executed by this InstrumentationTest.
`void`	`setWindowAnimation(boolean windowAnimation)`

Protected methods
`static Set<TestDescription>`	`excludeNonExecuted(TestRunResult results)` Filter out "NOT_EXECUTED" and Skipped for the purpose of tracking what needs to be rerun.
`String`	`getClassName()` Get the class name to run.
`ListInstrumentationParser`	`getListInstrumentationParser()` Get the `ListInstrumentationParser` used to parse 'pm list instrumentation' queries.
`String`	`getMethodName()` Get the test method to run.
`String`	`getTestPackageName()` Get the test java package to run.
`String`	`queryRunnerName()` Query the device for a test runner to use.
`void`	`setRunnerArgs(IRemoteAndroidTestRunner runner)`

Constants

RUN_TESTS_AS_USER_KEY

public static final String RUN_TESTS_AS_USER_KEY

Constant Value: "RUN_TESTS_AS_USER"

RUN_TESTS_ON_SDK_SANDBOX

public static final String RUN_TESTS_ON_SDK_SANDBOX

Constant Value: "RUN_TESTS_ON_SDK_SANDBOX"

Fields

mDebug

protected boolean mDebug

mInstrumentInPcc

protected boolean mInstrumentInPcc

mInstrumentSdkInSandbox

protected boolean mInstrumentSdkInSandbox

mInstrumentSdkSandbox

protected boolean mInstrumentSdkSandbox

Public constructors

InstrumentationTest

public InstrumentationTest ()

Public methods

addDeviceListeners

public void addDeviceListeners (Set<String> extraListeners)

Allows to add more custom listeners to the runner

Parameters
`extraListeners`	`Set`

addInstrumentationArg

public void addInstrumentationArg (String key, 
                String value)

Add an argument to provide when running the instrumentation tests.

Parameters
`key`	`String`: the argument name
`value`	`String`: the argument value

getAbi

public IAbi getAbi ()

Returns
`IAbi`

getConfiguration

public IConfiguration getConfiguration ()

Gets the IConfiguration for this test.

Returns
`IConfiguration`

getCoverageTarget

public String getCoverageTarget ()

Get the coverageTarget previously set via setCoverageTarget(String).

Returns
`String`

getDebug

public boolean getDebug ()

Get the instrumentation debug setting.

Returns
`boolean`	The boolean debug setting.

getDevice

public ITestDevice getDevice ()

Get the device under test.

Returns
`ITestDevice`	the `ITestDevice`

getForceAbi

public String getForceAbi ()

Returns
`String`

getMaxTimeout

public long getMaxTimeout ()

Returns the max timeout set for the instrumentation.

Returns
`long`

getPackageName

public String getPackageName ()

Get the Android manifest package to run.

Returns
`String`

getRunName

public String getRunName ()

Get the custom test run name that will be provided to listener

Returns
`String`

getRunnerName

public String getRunnerName ()

Gets the Android instrumentation runner to be used.

Returns
`String`

isCollectTestsOnly

public boolean isCollectTestsOnly ()

Returns
`boolean`	whether this test is in collect-tests-only mode.

isOrchestrator

public boolean isOrchestrator ()

Returns the value of ERROR(InstrumentationTest.mOrchestrator/#mOrchestrator InstrumentationTest.mOrchestrator)

Returns
`boolean`

run

public void run (TestInformation testInfo, 
                ITestInvocationListener listener)

Runs the tests, and reports result to the listener.

Parameters
`testInfo`	`TestInformation`: The `TestInformation` object containing useful information to run tests.
`listener`	`ITestInvocationListener`: the `ITestInvocationListener` of test results

Throws
`DeviceNotAvailableException`

setAbi

public void setAbi (IAbi abi)

Parameters
`abi`	`IAbi`

setClassName

public void setClassName (String testClassName)

Optionally, set the test class name to run.

Parameters
`testClassName`	`String`

setCollectTestsOnly

public void setCollectTestsOnly (boolean shouldCollectTest)

Enables or disables test collection mode

setCollectsTestsShellTimeout

public void setCollectsTestsShellTimeout (int timeout)

This method is deprecated.
This method is a no-op

Set the max time in ms to allow for the 'max time to shell output response' when collecting tests.

Parameters
`timeout`	`int`

setConfiguration

public void setConfiguration (IConfiguration config)

Injects the IConfiguration in use.

Parameters
`config`	`IConfiguration`

setCoverageTarget

public void setCoverageTarget (String coverageTarget)

Set the coverage target of this test.

Currently unused. This method is just present so coverageTarget can be later retrieved via getCoverageTarget()

Parameters
`coverageTarget`	`String`

setDebug

public void setDebug (boolean debug)

Set the instrumentation debug setting.

Parameters
`debug`	`boolean`: boolean value to set the instrumentation debug setting to.

setDevice

public void setDevice (ITestDevice device)

Inject the device under test.

Parameters
`device`	`ITestDevice`: the `ITestDevice` to use

setEnforceFormat

public void setEnforceFormat (boolean enforce)

Set True if we enforce the AJUR output format of instrumentation.

Parameters
`enforce`	`boolean`

setForceAbi

public void setForceAbi (String abi)

Sets force-abi option.

setInstallFile

public void setInstallFile (File installFile)

Set the optional file to install that contains the tests.

Parameters
`installFile`	`File`: the installable `File`

setIsolatedStorage

public void setIsolatedStorage (boolean isolatedStorage)

Set wether or not to use the isolated storage.

Parameters
`isolatedStorage`	`boolean`

setMethodName

public void setMethodName (String testMethodName)

Optionally, set the test method to run.

Parameters
`testMethodName`	`String`

setMetricCollectors

public void setMetricCollectors (List<IMetricCollector> collectors)

Sets the list of IMetricCollectors defined for the test run.

Parameters
`collectors`	`List`

setOrchestrator

public void setOrchestrator (boolean useOrchestrator)

Sets the --orchestrator option

Parameters
`useOrchestrator`	`boolean`

setPackageName

public void setPackageName (String packageName)

Set the Android manifest package to run.

Parameters
`packageName`	`String`

setReRunUsingTestFile

public void setReRunUsingTestFile (boolean reRunUsingTestFile)

Sets the --rerun-from-file option.

Parameters
`reRunUsingTestFile`	`boolean`

setRerunMode

public void setRerunMode (boolean rerun)

Optionally, set the rerun mode.

Parameters
`rerun`	`boolean`

setRetryAttemptNumber

public void setRetryAttemptNumber (int attemptNumber)

Sets the retry attempt number for the test. Default does nothing.

Sets the retry attempt number by pushing it as a "retry_attempt" instrumentation argument to the device-side runner.

Parameters
`attemptNumber`	`int`

setRunName

public void setRunName (String runName)

Set the custom test run name that will be provided to listener

Parameters
`runName`	`String`

setRunnerName

public void setRunnerName (String runnerName)

Optionally, set the Android instrumentation runner to use.

Parameters
`runnerName`	`String`

setShellTimeout

public void setShellTimeout (long timeout)

Optionally, set the maximum time (in milliseconds) expecting shell output from the device.

Parameters
`timeout`	`long`

setTestFilePathOnDevice

public void setTestFilePathOnDevice (String testFilePathOnDevice)

Optionally, set the path to a file located on the device that should contain a list of line separated test classes and methods (format: com.foo.Class#method) to be run. If set, will automatically attempt to re-run tests using this test file via InstrumentationFileTest instead of executing separate adb commands for each remaining test via rerun.

Parameters
`testFilePathOnDevice`	`String`

setTestPackageName

public void setTestPackageName (String testPackageName)

Sets the test package filter.

If non-null, only tests within the given java package will be executed.

Will be ignored if a non-null value has been provided to setClassName(String)

Parameters
`testPackageName`	`String`

setTestSize

public void setTestSize (String size)

Optionally, set the test size to run.

Parameters
`size`	`String`

setTestTimeout

public void setTestTimeout (long timeout)

Optionally, set the maximum time (in milliseconds) for each individual test run.

Parameters
`timeout`	`long`

setTestsToRun

public void setTestsToRun (Collection<TestDescription> tests)

Set the collection of tests that should be executed by this InstrumentationTest.

Parameters
`tests`	`Collection`: the tests to run

setWindowAnimation

public void setWindowAnimation (boolean windowAnimation)

Parameters
`windowAnimation`	`boolean`

Protected methods

excludeNonExecuted

protected static Set<TestDescription> excludeNonExecuted (TestRunResult results)

Filter out "NOT_EXECUTED" and Skipped for the purpose of tracking what needs to be rerun.

Parameters
`results`	`TestRunResult`

Returns
`Set<TestDescription>`

getClassName

protected String getClassName ()

Get the class name to run.

Returns
`String`

getListInstrumentationParser

protected ListInstrumentationParser getListInstrumentationParser ()

Get the ListInstrumentationParser used to parse 'pm list instrumentation' queries.

Returns
`ListInstrumentationParser`

getMethodName

protected String getMethodName ()

Get the test method to run.

Returns
`String`

getTestPackageName

protected String getTestPackageName ()

Get the test java package to run.

Returns
`String`

queryRunnerName

protected String queryRunnerName ()

Query the device for a test runner to use.

Returns
`String`	the first test runner name that matches the package or null if we don't find any.

Throws
	com.android.tradefed.device.DeviceNotAvailableException
`DeviceNotAvailableException`

setRunnerArgs

protected void setRunnerArgs (IRemoteAndroidTestRunner runner)

Parameters
`runner`	`IRemoteAndroidTestRunner`