IRemoteAndroidTestRunner

public interface IRemoteAndroidTestRunner

com.android.ddmlib.testrunner.IRemoteAndroidTestRunner

Interface for running a Android test command remotely and reporting result to a listener.

Summary

Public methods

abstract void addBooleanArg(String name, boolean value)

Adds a boolean argument to include in instrumentation command.

abstract void addInstrumentationArg(String name, String value)

Adds a argument to include in instrumentation command.

abstract void cancel()

Requests cancellation of this test run.

abstract IRemoteAndroidTestRunner.CoverageOutput getCoverageOutputType()

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

abstract String getPackageName()

Returns the application package name.

abstract String getRunnerName()

Returns the runnerName.

abstract void removeInstrumentationArg(String name)

Removes a previously added argument.

abstract void run(ITestRunListener... listeners)

Execute this test run.

abstract void run( listeners)

Execute this test run.

abstract void setAdditionalTestOutputLocation(String additionalTestDataPath)

Sets the location of the additional test output to be copied to host before the test app is uninstalled.

abstract void setClassName(String className)

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

abstract void setClassNames(String[] classNames)

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

abstract void setCoverage(boolean coverage)

Sets this code coverage mode of this test run.

abstract void setCoverageReportLocation(String reportPath)

Sets the location of the generated coverage reports.

abstract void setDebug(boolean debug)

Sets this debug mode of this test run.

abstract void setLogOnly(boolean logOnly)

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

abstract void setMaxTimeToOutputResponse(long maxTimeToOutputResponse, TimeUnit maxTimeUnits)

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

abstract void setMaxTimeout(long maxTimeout, TimeUnit maxTimeUnits)

Sets the maximum time allowed for the instrumentation to finish.

abstract void setMaxtimeToOutputResponse(int maxTimeToOutputResponse)

This method is deprecated. Use ERROR(/#setMaxTimeToOutputResponse(long,java.util.concurrent.TimeUnit)).

abstract void setMethodName(String className, String testName)

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

abstract void setRunName(String runName)

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

If unspecified, will use package name

abstract void setTestCollection(boolean collection)

Sets this test run to test collection mode.

abstract void setTestPackageName(String packageName)

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

abstract void setTestSize(IRemoteAndroidTestRunner.TestSize size)

Sets to run only tests of given size.

Public methods

addBooleanArg

public abstract 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 abstract 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 abstract void cancel ()

Requests cancellation of this test run.

getCoverageOutputType

public abstract IRemoteAndroidTestRunner.CoverageOutput getCoverageOutputType ()

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

Returns
IRemoteAndroidTestRunner.CoverageOutput

getPackageName

public abstract String getPackageName ()

Returns the application package name.

Returns
String

getRunnerName

public abstract String getRunnerName ()

Returns the runnerName.

Returns
String

removeInstrumentationArg

public abstract void removeInstrumentationArg (String name)

Removes a previously added argument.

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

run

public abstract void run (ITestRunListener... listeners)

Execute this test run.

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

Parameters
listeners ITestRunListener: 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.
if connection to device was lost.

run

public abstract void run ( listeners)

Execute this test run.

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.
if connection to device was lost.

setAdditionalTestOutputLocation

public abstract 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 abstract 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 abstract 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 abstract void setCoverage (boolean coverage)

Sets this code coverage mode of this test run.

Parameters
coverage boolean

setCoverageReportLocation

public abstract void setCoverageReportLocation (String reportPath)

Sets the location of the generated coverage reports.

Parameters
reportPath String

setDebug

public abstract 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 abstract void setLogOnly (boolean logOnly)

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

Parameters
logOnly boolean

setMaxTimeToOutputResponse

public abstract 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 abstract 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 abstract void setMaxtimeToOutputResponse (int maxTimeToOutputResponse)

This method is deprecated.
Use ERROR(/#setMaxTimeToOutputResponse(long,java.util.concurrent.TimeUnit)).

Parameters
maxTimeToOutputResponse int

setMethodName

public abstract 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 abstract void setRunName (String runName)

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

If unspecified, will use package name

setTestCollection

public abstract void setTestCollection (boolean collection)

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
collection boolean

setTestPackageName

public abstract 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 abstract 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.