Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.

RemoteAndroidTestRunner

public class RemoteAndroidTestRunner
extends Object implements IRemoteAndroidTestRunner

java.lang.Object
↳	com.android.ddmlib.testrunner.RemoteAndroidTestRunner

Runs a Android test command remotely and reports results.

Summary

Public constructors
`RemoteAndroidTestRunner(String packageName, IShellEnabledDevice remoteDevice)` Alternate constructor.
`RemoteAndroidTestRunner(String packageName, String runnerName, IShellEnabledDevice remoteDevice)` Alternate constructor.
`RemoteAndroidTestRunner(String packageName, String runnerName, IShellEnabledDevice remoteDevice, RemoteAndroidTestRunner.StatusReporterMode statusReporterMode)` Creates a remote Android test runner.

Public methods
`void`	`addBooleanArg(String name, boolean value)` Adds a boolean argument to include in instrumentation command.
`void`	`addInstrumentationArg(String name, String value)` Adds a argument to include in instrumentation command.
`void`	`cancel()` Requests cancellation of this test run.
`IInstrumentationResultParser`	`createParser(String runName, listeners)` Create the `InstrumentationResultParser` that will be used to parse the instrumentation output.
`String`	`getAmInstrumentCommand()`
`IRemoteAndroidTestRunner.CoverageOutput`	`getCoverageOutputType()` Returns the type of the test coverage produces by the runner.
`String`	`getPackageName()` Returns the application package name.
`String`	`getRunOptions()` Returns options for the am instrument command.
`String`	`getRunnerName()` Returns the runnerName.
`void`	`removeInstrumentationArg(String name)` Removes a previously added argument.
`void`	`run(ITestRunListener... listeners)` Execute this test run.
`void`	`run( listeners)` Execute this test run.
`void`	`setAdditionalTestOutputLocation(String additionalTestDataPath)` Sets the location of the additional test output to be copied to host before the test app is uninstalled.
`void`	`setClassName(String className)` Sets to run only tests in this class Must be called before 'run'.
`void`	`setClassNames(String[] classNames)` Sets to run only tests in the provided classes Must be called before 'run'.
`void`	`setCoverage(boolean coverage)` Sets this code coverage mode of this test run.
`void`	`setCoverageReportLocation(String reportPath)` Sets the location of the generated coverage reports.
`void`	`setDebug(boolean debug)` Sets this debug mode of this test run.
`void`	`setLogOnly(boolean logOnly)` Sets this test run to log only mode - skips test execution.
`void`	`setMaxTimeToOutputResponse(long maxTimeToOutputResponse, TimeUnit maxTimeUnits)` Sets the maximum time allowed between output of the shell command running the tests on the devices.
`void`	`setMaxTimeout(long maxTimeout, TimeUnit maxTimeUnits)` Sets the maximum time allowed for the instrumentation to finish.
`void`	`setMaxtimeToOutputResponse(int maxTimeToOutputResponse)`
`void`	`setMethodName(String className, String testName)` Sets to run only specified test method Must be called before 'run'.
`void`	`setRunName(String runName)` Set a custom run name to be reported to the `ITestRunListener` on `run()` If unspecified, will use package name
`void`	`setRunOptions(String options)` Sets options for the am instrument command.
`void`	`setTestCollection(boolean collect)` Sets this test run to test collection mode.
`void`	`setTestPackageName(String packageName)` Sets to run all tests in specified package Must be called before 'run'.
`void`	`setTestSize(IRemoteAndroidTestRunner.TestSize size)` Sets to run only tests of given size.

Protected methods
`String`	`getArgsCommand()` Returns the full instrumentation command line syntax for the provided instrumentation arguments.
`String`	`getRunnerPath()` Returns the complete instrumentation component path.

Public constructors

RemoteAndroidTestRunner

public RemoteAndroidTestRunner (String packageName, 
                IShellEnabledDevice remoteDevice)

Alternate constructor. Uses default instrumentation runner.

Parameters
`packageName`	`String`: the Android application package that contains the tests to run
`remoteDevice`	`IShellEnabledDevice`: the Android device to execute tests on

RemoteAndroidTestRunner

public RemoteAndroidTestRunner (String packageName, 
                String runnerName, 
                IShellEnabledDevice remoteDevice)

Alternate constructor. Uses default statusReporterMode.

Parameters
`packageName`	`String`: the Android application package that contains the tests to run
`runnerName`	`String`: the instrumentation test runner to execute. If null, will use default runner
`remoteDevice`	`IShellEnabledDevice`: the Android device to execute tests on

RemoteAndroidTestRunner

public RemoteAndroidTestRunner (String packageName, 
                String runnerName, 
                IShellEnabledDevice remoteDevice, 
                RemoteAndroidTestRunner.StatusReporterMode statusReporterMode)

Creates a remote Android test runner.

Parameters
`packageName`	`String`: the Android application package that contains the tests to run
`runnerName`	`String`: the instrumentation test runner to execute. If null, will use default runner
`remoteDevice`	`IShellEnabledDevice`: the Android device to execute tests on
`statusReporterMode`	`RemoteAndroidTestRunner.StatusReporterMode`: the status reporter mode to be used for am instrument command

Public methods

addBooleanArg

public void addBooleanArg (String name, 
                boolean value)

Adds a boolean argument to include in instrumentation command.

Parameters
`name`	`String`: the name of the instrumentation bundle argument
`value`	`boolean`: the value of the argument

addInstrumentationArg

public void addInstrumentationArg (String name, 
                String value)

Adds a argument to include in instrumentation command.

Must be called before 'run'. If an argument with given name has already been provided, its value will be overridden.

Parameters
`name`	`String`: the name of the instrumentation bundle argument
`value`	`String`: the value of the argument

cancel

public void cancel ()

Requests cancellation of this test run.

createParser

public IInstrumentationResultParser createParser (String runName, 
                 listeners)

Create the InstrumentationResultParser that will be used to parse the instrumentation output.

Parameters
`runName`	`String`: The name of the run to use.
`listeners`	: The listeners where to report the results.

Returns
`IInstrumentationResultParser`	An instance of `InstrumentationResultParser`.

getAmInstrumentCommand

public String getAmInstrumentCommand ()

Returns
`String`

getCoverageOutputType

public IRemoteAndroidTestRunner.CoverageOutput getCoverageOutputType ()

Returns the type of the test coverage produces by the runner. See CoverageOutput.

Returns
`IRemoteAndroidTestRunner.CoverageOutput`

getPackageName

public String getPackageName ()

Returns the application package name.

Returns
`String`

getRunOptions

public String getRunOptions ()

Returns options for the am instrument command.

Returns
`String`

getRunnerName

public String getRunnerName ()

Returns the runnerName.

Returns
`String`

removeInstrumentationArg

public void removeInstrumentationArg (String name)

Removes a previously added argument.

Parameters
`name`	`String`: the name of the instrumentation bundle argument to remove

run

public void run (ITestRunListener... listeners)

Execute this test run.

Convenience method for ERROR(/#run(Collection)).

Parameters
`listeners`	`ITestRunListener`: listens for test results

Throws
`AdbCommandRejectedException`
`ShellCommandUnresponsiveException`
`TimeoutException`

run

public void run ( listeners)

Execute this test run.

Parameters
`listeners`	: collection of listeners for test results

Throws
`AdbCommandRejectedException`
`ShellCommandUnresponsiveException`
`TimeoutException`

setAdditionalTestOutputLocation

public void setAdditionalTestOutputLocation (String additionalTestDataPath)

Sets the location of the additional test output to be copied to host before the test app is uninstalled. E.g., generated benchmark reports.

Parameters
`additionalTestDataPath`	`String`

setClassName

public void setClassName (String className)

Sets to run only tests in this class Must be called before 'run'.

Parameters
`className`	`String`: fully qualified class name (eg x.y.z)

setClassNames

public void setClassNames (String[] classNames)

Sets to run only tests in the provided classes Must be called before 'run'.

If providing more than one class, requires a InstrumentationTestRunner that supports the multiple class argument syntax.

Parameters
`classNames`	`String`: array of fully qualified class names (eg x.y.z)

setCoverage

public void setCoverage (boolean coverage)

Sets this code coverage mode of this test run.

Parameters
`coverage`	`boolean`

setCoverageReportLocation

public void setCoverageReportLocation (String reportPath)

Sets the location of the generated coverage reports.

Parameters
`reportPath`	`String`

setDebug

public void setDebug (boolean debug)

Sets this debug mode of this test run. If true, the Android test runner will wait for a debugger to attach before proceeding with test execution.

Parameters
`debug`	`boolean`

setLogOnly

public void setLogOnly (boolean logOnly)

Sets this test run to log only mode - skips test execution.

Parameters
`logOnly`	`boolean`

setMaxTimeToOutputResponse

public void setMaxTimeToOutputResponse (long maxTimeToOutputResponse, 
                TimeUnit maxTimeUnits)

Sets the maximum time allowed between output of the shell command running the tests on the devices.

This allows setting a timeout in case the tests can become stuck and never finish. This is different from the normal timeout on the connection.

By default no timeout will be specified.

Parameters
`maxTimeToOutputResponse`	`long`: the maximum amount of time during which the command is allowed to not output any response. A value of 0 means the method will wait forever (until the `receiver` cancels the execution) for command output and never throw.
`maxTimeUnits`	`TimeUnit`: Units for non-zero `maxTimeToOutputResponse` and `maxTimeout` values.

setMaxTimeout

public void setMaxTimeout (long maxTimeout, 
                TimeUnit maxTimeUnits)

Sets the maximum time allowed for the instrumentation to finish.

This allows setting a timeout in case the tests can become stuck and never finish. This is different from the normal timeout on the connection.

By default no timeout will be specified.

Parameters
`maxTimeout`	`long`: the maximum amount of time during which the command is allowed to not output any response. A value of 0 means the method will wait forever (until the `receiver` cancels the execution) for command output and never throw.
`maxTimeUnits`	`TimeUnit`: Units for non-zero `maxTimeToOutputResponse` and `maxTimeout` values.

setMaxtimeToOutputResponse

public void setMaxtimeToOutputResponse (int maxTimeToOutputResponse)

Parameters
`maxTimeToOutputResponse`	`int`

setMethodName

public void setMethodName (String className, 
                String testName)

Sets to run only specified test method Must be called before 'run'.

Parameters
`className`	`String`: fully qualified class name (eg x.y.z)
`testName`	`String`: method name

setRunName

public void setRunName (String runName)

Set a custom run name to be reported to the ITestRunListener on run()

If unspecified, will use package name

setRunOptions

public void setRunOptions (String options)

Sets options for the am instrument command. See com/android/commands/am/Am.java for full list of options.

Parameters
`options`	`String`

setTestCollection

public void setTestCollection (boolean collect)

Sets this test run to test collection mode. If true, will skip test execution and will set all appropriate runner arguments required for a successful test collection.

Parameters
`collect`	`boolean`

setTestPackageName

public void setTestPackageName (String packageName)

Sets to run all tests in specified package Must be called before 'run'.

Parameters
`packageName`	`String`: fully qualified package name (eg x.y.z)

setTestSize

public void setTestSize (IRemoteAndroidTestRunner.TestSize size)

Sets to run only tests of given size. Must be called before 'run'.

Parameters
`size`	`IRemoteAndroidTestRunner.TestSize`: the `TestSize` to run.

Protected methods

getArgsCommand

protected String getArgsCommand ()

Returns the full instrumentation command line syntax for the provided instrumentation arguments. Returns an empty string if no arguments were specified.

Returns
`String`

getRunnerPath

protected String getRunnerPath ()

Returns the complete instrumentation component path.

Returns
`String`