com.android.ddmlib.testrunner

Class RemoteAndroidTestRunner

java.lang.Object

com.android.ddmlib.testrunner.RemoteAndroidTestRunner

All Implemented Interfaces:

IRemoteAndroidTestRunner

Direct Known Subclasses:

AndroidTestOrchestratorRemoteAndroidTestRunner

public class RemoteAndroidTestRunner
extends java.lang.Object
implements IRemoteAndroidTestRunner

Runs a Android test command remotely and reports results.

Nested Class Summary

Nested classes/interfaces inherited from interface com.android.ddmlib.testrunner.IRemoteAndroidTestRunner

IRemoteAndroidTestRunner.CoverageOutput, IRemoteAndroidTestRunner.TestSize

Constructor Summary

Constructors

Constructor and Description
RemoteAndroidTestRunner(java.lang.String packageName, IShellEnabledDevice remoteDevice) Alternate constructor.
RemoteAndroidTestRunner(java.lang.String packageName, java.lang.String runnerName, IShellEnabledDevice remoteDevice) Creates a remote Android test runner.

Method Summary

Modifier and Type	Method and Description
void	addBooleanArg(java.lang.String name, boolean value) Adds a boolean argument to include in instrumentation command.
void	addInstrumentationArg(java.lang.String name, java.lang.String value) Adds a argument to include in instrumentation command.
void	cancel() Requests cancellation of this test run.
InstrumentationResultParser	createParser(java.lang.String runName, java.util.Collection<ITestRunListener> listeners) Create the InstrumentationResultParser that will be used to parse the instrumentation output.
java.lang.String	getAmInstrumentCommand()
protected java.lang.String	getArgsCommand() Returns the full instrumentation command line syntax for the provided instrumentation arguments.
IRemoteAndroidTestRunner.CoverageOutput	getCoverageOutputType() Returns the type of the test coverage produces by the runner.
java.lang.String	getPackageName() Returns the application package name.
java.lang.String	getRunnerName() Returns the runnerName.
protected java.lang.String	getRunnerPath() Returns the complete instrumentation component path.
java.lang.String	getRunOptions() Returns options for the am instrument command.
void	removeInstrumentationArg(java.lang.String name) Removes a previously added argument.
void	run(java.util.Collection<ITestRunListener> listeners) Execute this test run.
void	run(ITestRunListener... listeners) Execute this test run.
void	setClassName(java.lang.String className) Sets to run only tests in this class Must be called before 'run'.
void	setClassNames(java.lang.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(java.lang.String reportPath) Sets the location of the generated coverage reports.
void	setDebug(boolean debug) Sets this debug mode of this test run.
void	setEnforceTimeStamp(boolean timestamp) Sets this test to enforce expecting a final time stamp from the instrumentation otherwise the run will be considered failed.
void	setLogOnly(boolean logOnly) Sets this test run to log only mode - skips test execution.
void	setMaxTimeout(long maxTimeout, java.util.concurrent.TimeUnit maxTimeUnits) Sets the maximum time allowed for the instrumentation to finish.
void	setMaxtimeToOutputResponse(int maxTimeToOutputResponse) Deprecated.
void	setMaxTimeToOutputResponse(long maxTimeToOutputResponse, java.util.concurrent.TimeUnit maxTimeUnits) Sets the maximum time allowed between output of the shell command running the tests on the devices.
void	setMethodName(java.lang.String className, java.lang.String testName) Sets to run only specified test method Must be called before 'run'.
void	setRunName(java.lang.String runName) Set a custom run name to be reported to the ITestRunListener on IRemoteAndroidTestRunner.run(com.android.ddmlib.testrunner.ITestRunListener...)
void	setRunOptions(java.lang.String options) Sets options for the am instrument command.
void	setTestCollection(boolean collect) Sets this test run to test collection mode.
void	setTestPackageName(java.lang.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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RemoteAndroidTestRunner

public RemoteAndroidTestRunner(java.lang.String packageName,
                               java.lang.String runnerName,
                               IShellEnabledDevice remoteDevice)

Creates a remote Android test runner.

Parameters:

packageName - the Android application package that contains the tests to run

runnerName - the instrumentation test runner to execute. If null, will use default runner

remoteDevice - the Android device to execute tests on

RemoteAndroidTestRunner

public RemoteAndroidTestRunner(java.lang.String packageName,
                               IShellEnabledDevice remoteDevice)

Alternate constructor. Uses default instrumentation runner.

Parameters:

packageName - the Android application package that contains the tests to run

remoteDevice - the Android device to execute tests on

Method Detail

getPackageName

public java.lang.String getPackageName()

Description copied from interface: IRemoteAndroidTestRunner

Returns the application package name.

Specified by:

getPackageName in interface IRemoteAndroidTestRunner

getRunnerName

public java.lang.String getRunnerName()

Description copied from interface: IRemoteAndroidTestRunner

Returns the runnerName.

Specified by:

getRunnerName in interface IRemoteAndroidTestRunner

getRunnerPath

protected java.lang.String getRunnerPath()

Returns the complete instrumentation component path.

setClassName

public void setClassName(java.lang.String className)

Description copied from interface: IRemoteAndroidTestRunner

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

Specified by:

setClassName in interface IRemoteAndroidTestRunner

Parameters:

className - fully qualified class name (eg x.y.z)

setClassNames

public void setClassNames(java.lang.String[] classNames)

Description copied from interface: IRemoteAndroidTestRunner

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.

Specified by:

setClassNames in interface IRemoteAndroidTestRunner

Parameters:

classNames - array of fully qualified class names (eg x.y.z)

setMethodName

public void setMethodName(java.lang.String className,
                          java.lang.String testName)

Description copied from interface: IRemoteAndroidTestRunner

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

Specified by:

setMethodName in interface IRemoteAndroidTestRunner

Parameters:

className - fully qualified class name (eg x.y.z)

testName - method name

setTestPackageName

public void setTestPackageName(java.lang.String packageName)

Description copied from interface: IRemoteAndroidTestRunner

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

Specified by:

setTestPackageName in interface IRemoteAndroidTestRunner

Parameters:

packageName - fully qualified package name (eg x.y.z)

addInstrumentationArg

public void addInstrumentationArg(java.lang.String name,
                                  java.lang.String value)

Description copied from interface: IRemoteAndroidTestRunner

Adds a argument to include in instrumentation command.

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

Specified by:

addInstrumentationArg in interface IRemoteAndroidTestRunner

Parameters:

name - the name of the instrumentation bundle argument

value - the value of the argument

removeInstrumentationArg

public void removeInstrumentationArg(java.lang.String name)

Description copied from interface: IRemoteAndroidTestRunner

Removes a previously added argument.

Specified by:

removeInstrumentationArg in interface IRemoteAndroidTestRunner

Parameters:

name - the name of the instrumentation bundle argument to remove

addBooleanArg

public void addBooleanArg(java.lang.String name,
                          boolean value)

Description copied from interface: IRemoteAndroidTestRunner

Adds a boolean argument to include in instrumentation command.

Specified by:

addBooleanArg in interface IRemoteAndroidTestRunner

Parameters:

name - the name of the instrumentation bundle argument

value - the value of the argument

See Also:

addInstrumentationArg(java.lang.String, java.lang.String)

setLogOnly

public void setLogOnly(boolean logOnly)

Description copied from interface: IRemoteAndroidTestRunner

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

Specified by:

setLogOnly in interface IRemoteAndroidTestRunner

setDebug

public void setDebug(boolean debug)

Description copied from interface: IRemoteAndroidTestRunner

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.

Specified by:

setDebug in interface IRemoteAndroidTestRunner

setCoverage

public void setCoverage(boolean coverage)

Description copied from interface: IRemoteAndroidTestRunner

Sets this code coverage mode of this test run.

Specified by:

setCoverage in interface IRemoteAndroidTestRunner

setCoverageReportLocation

public void setCoverageReportLocation(java.lang.String reportPath)

Description copied from interface: IRemoteAndroidTestRunner

Sets the location of the generated coverage reports.

Specified by:

setCoverageReportLocation in interface IRemoteAndroidTestRunner

getCoverageOutputType

public IRemoteAndroidTestRunner.CoverageOutput getCoverageOutputType()

Description copied from interface: IRemoteAndroidTestRunner

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

Specified by:

getCoverageOutputType in interface IRemoteAndroidTestRunner

setEnforceTimeStamp

public void setEnforceTimeStamp(boolean timestamp)

Description copied from interface: IRemoteAndroidTestRunner

Sets this test to enforce expecting a final time stamp from the instrumentation otherwise the run will be considered failed.

Specified by:

setEnforceTimeStamp in interface IRemoteAndroidTestRunner

setTestSize

public void setTestSize(IRemoteAndroidTestRunner.TestSize size)

Description copied from interface: IRemoteAndroidTestRunner

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

Specified by:

setTestSize in interface IRemoteAndroidTestRunner

Parameters:

size - the IRemoteAndroidTestRunner.TestSize to run.

setTestCollection

public void setTestCollection(boolean collect)

Description copied from interface: IRemoteAndroidTestRunner

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.

Specified by:

setTestCollection in interface IRemoteAndroidTestRunner

setMaxtimeToOutputResponse

@Deprecated
public void setMaxtimeToOutputResponse(int maxTimeToOutputResponse)

Deprecated.

Specified by:

setMaxtimeToOutputResponse in interface IRemoteAndroidTestRunner

setMaxTimeToOutputResponse

public void setMaxTimeToOutputResponse(long maxTimeToOutputResponse,
                                       java.util.concurrent.TimeUnit maxTimeUnits)

Description copied from interface: IRemoteAndroidTestRunner

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.

Specified by:

setMaxTimeToOutputResponse in interface IRemoteAndroidTestRunner

Parameters:

maxTimeToOutputResponse - 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 - Units for non-zero maxTimeToOutputResponse and maxTimeout values.

See Also:

IShellEnabledDevice.executeShellCommand(String, com.android.ddmlib.IShellOutputReceiver, long, long, TimeUnit)

setMaxTimeout

public void setMaxTimeout(long maxTimeout,
                          java.util.concurrent.TimeUnit maxTimeUnits)

Description copied from interface: IRemoteAndroidTestRunner

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.

Specified by:

setMaxTimeout in interface IRemoteAndroidTestRunner

Parameters:

maxTimeout - 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 - Units for non-zero maxTimeToOutputResponse and maxTimeout values.

See Also:

IShellEnabledDevice.executeShellCommand(String, com.android.ddmlib.IShellOutputReceiver, long, long, TimeUnit)

setRunName

public void setRunName(java.lang.String runName)

Description copied from interface: IRemoteAndroidTestRunner

Set a custom run name to be reported to the ITestRunListener on IRemoteAndroidTestRunner.run(com.android.ddmlib.testrunner.ITestRunListener...)

If unspecified, will use package name

Specified by:

setRunName in interface IRemoteAndroidTestRunner

run

public void run(ITestRunListener... listeners)
         throws TimeoutException,
                AdbCommandRejectedException,
                ShellCommandUnresponsiveException,
                java.io.IOException

Description copied from interface: IRemoteAndroidTestRunner

Execute this test run.

Convenience method for IRemoteAndroidTestRunner.run(Collection).

Specified by:

run in interface IRemoteAndroidTestRunner

Parameters:

listeners - listens for test results

Throws:

TimeoutException - in case of a timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

ShellCommandUnresponsiveException - if the device did not output any test result for a period longer than the max time to output.

java.io.IOException - if connection to device was lost.

See Also:

IRemoteAndroidTestRunner.setMaxtimeToOutputResponse(int)

run

public void run(java.util.Collection<ITestRunListener> listeners)
         throws TimeoutException,
                AdbCommandRejectedException,
                ShellCommandUnresponsiveException,
                java.io.IOException

Description copied from interface: IRemoteAndroidTestRunner

Execute this test run.

Specified by:

run in interface IRemoteAndroidTestRunner

Parameters:

listeners - collection of listeners for test results

Throws:

TimeoutException - in case of a timeout on the connection.

AdbCommandRejectedException - if adb rejects the command

ShellCommandUnresponsiveException - if the device did not output any test result for a period longer than the max time to output.

java.io.IOException - if connection to device was lost.

See Also:

IRemoteAndroidTestRunner.setMaxtimeToOutputResponse(int)

createParser

@NonNull
public InstrumentationResultParser createParser(@NonNull
                                                         java.lang.String runName,
                                                         @NonNull
                                                         java.util.Collection<ITestRunListener> listeners)

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

Parameters:

runName - The name of the run to use.

listeners - The listeners where to report the results.

Returns:

An instance of InstrumentationResultParser.

getAmInstrumentCommand

@NonNull
public java.lang.String getAmInstrumentCommand()

getRunOptions

@NonNull
public java.lang.String getRunOptions()

Returns options for the am instrument command.

setRunOptions

public void setRunOptions(@NonNull
                          java.lang.String options)

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

cancel

public void cancel()

Description copied from interface: IRemoteAndroidTestRunner

Requests cancellation of this test run.

Specified by:

cancel in interface IRemoteAndroidTestRunner

getArgsCommand

protected java.lang.String getArgsCommand()

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