to top
public class

InstrumentationTest

extends Object
implements IDeviceTest IResumableTest @OptionClass(alias = "instrumentation")
java.lang.Object
   ↳ com.android.tradefed.testtype.InstrumentationTest
Known Direct Subclasses

Class Overview

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

Summary

Constants
String DELAY_MSEC_ARG
String TEST_TIMEOUT_INST_ARGS_KEY instrumentation test runner argument key used for individual test timeout
Fields
private BugreportCollector.Freq mBugreportFrequency @Option(name = "bugreport-on-failure", description = "Sets which failed testcase events cause a bugreport to be collected. a bugreport after failed testcases. Note that there is _no feedback mechanism_ between the test runner and the bugreport collector, so use the EACH setting with due caution.")
private boolean mFallbackToSerialRerun @Option(name = "fallback-to-serial-rerun", description = "Rerun tests serially after rerun from file failed.")
private String mForceAbi @Option(name = "force-abi", description = "The abi to use, can be either 32 or 64.", importance = com.android.tradefed.config.Option.Importance.IF_UNSET)
private File mInstallFile @Option(name = "install-file", description = "Optional file path to apk file that contains the tests.")
private Map<String, String> mInstrArgMap @Option(name = "instrumentation-arg", description = "Additional instrumentation arguments to provide.")
private boolean mIsRerunMode @Option(name = "rerun", description = "Rerun unexecuted tests individually on same device if test run fails to complete.")
private boolean mIsResumeMode @Option(name = "resume", description = "Schedule unexecuted tests for resumption on another device if first device becomes unavailable.")
private boolean mLogcatOnFailure @Option(name = "logcat-on-failure", description = "take a logcat snapshot on every test failure.")
private int mMaxLogcatBytes @Option(name = "logcat-on-failure-size", description = "The max number of logcat data in bytes to capture when --logcat-on-failure is on. Should be an amount that can comfortably fit in memory.")
private String mPackageName @Option(name = "package", shortName = 112, description = "The manifest package name of the Android test application to run.", importance = com.android.tradefed.config.Option.Importance.IF_UNSET)
private boolean mReRunUsingTestFile @Option(name = "rerun-from-file", description = "Use test file instead of separate adb commands for each test when re-running instrumentations for tests that failed to run in previous attempts. ")
private int mReRunUsingTestFileAttempts @Option(name = "rerun-from-file-attempts", description = "Max attempts to rerun tests from file. -1 means rerun from file infinitely.")
private boolean mRebootBeforeReRun @Option(name = "reboot-before-rerun", description = "Reboot a device before re-running instrumentations.")
private String mRunName @Option(name = "run-name", description = "Optional custom test run name to pass to listener. If unspecified, will use package name.")
private String mRunnerName @Option(name = "runner", description = "The instrumentation test runner class name to use.")
private boolean mScreenshotOnFailure @Option(name = "screenshot-on-failure", description = "Take a screenshot on every test failure")
private long mShellTimeout @Option(name = "shell-timeout", description = "The defined timeout (in milliseconds) is used as a maximum waiting time when expecting the command output from the device. At any time, if the shell command does not output anything for a period longer than defined timeout the TF run terminates. For no timeout, set to 0.")
private String mTestClassName @Option(name = "class", shortName = 99, description = "The test class name to run.")
private int mTestDelay @Option(name = "log-delay", description = "Delay in msec between each test when collecting test information.")
private String mTestMethodName @Option(name = "method", shortName = 109, description = "The test method name to run.")
private String mTestPackageName @Option(name = "test-package", description = "Only run tests within this specific java package. Will be ignored if --class is set.")
private String mTestSize @Option(name = "size", description = "Restrict test to a specific test size.")
private int mTestTimeout @Option(name = "test-timeout", description = "Sets timeout (in milliseconds) that will be applied to each test. In the event of a test timeout it will log the results and proceed with executing the next test. For no timeout, set to 0.")
private Integer mTimeout @Option(name = "timeout", description = "Deprecated - Use \"shell-timeout\" or \"test-timeout\" instead.")
Public Constructors
InstrumentationTest()
Public Methods
void addInstrumentationArg(String key, String value)
Add an argument to provide when running the instrumentation tests
String getCoverageTarget()
Get the coverageTarget previously set via setCoverageTarget(String).
ITestDevice getDevice()
Get the device under test.
String getForceAbi()
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 isResumable()
void run(ITestInvocationListener listener)
Runs the tests, and reports result to the listener.
void setBugreportFrequency(BugreportCollector.Freq freq)
Set the frequency with which to automatically collect bugreports after test failures.
void setClassName(String testClassName)
Optionally, set the test class name to run.
void setCollectsTestsShellTimeout(int timeout)
Set the max time in ms to allow for the 'max time to shell output response' when collecting tests.
void setCoverageTarget(String coverageTarget)
Set the coverage target of this test.
void setDevice(ITestDevice device)
Inject the device under test.
void setFallbackToSerialRerun(boolean reRunSerially)
void setForceAbi(String abi)
Sets force-abi option.
void setInstallFile(File installFile)
Set the optional file to install that contains the tests.
void setLogcatOnFailure(boolean logcatOnFailure)
void setLogcatOnFailureSize(int logcatOnFailureSize)
void setMethodName(String testMethodName)
Optionally, set the test method to run.
void setPackageName(String packageName)
Set the Android manifest package to run.
void setReRunUsingTestFile(boolean reRunUsingTestFile)
void setRebootBeforeReRun(boolean rebootBeforeReRun)
void setRerunMode(boolean rerun)
Optionally, set the rerun mode.
void setResumeMode(boolean resume)
Optionally, set the resume mode.
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 setScreenshotOnFailure(boolean screenshotOnFailure)
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(int timeout)
Optionally, set the maximum time (in milliseconds) for each individual test run.
void setTestsToRun(Collection<TestIdentifier> tests, boolean forceBatchMode)
Set the collection of tests that should be executed by this InstrumentationTest.
Protected Methods
void setRunnerArgs(IRemoteAndroidTestRunner runner)
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.android.tradefed.testtype.IDeviceTest
From interface com.android.tradefed.testtype.IResumableTest
From interface com.android.tradefed.testtype.IRemoteTest

Constants

static final String DELAY_MSEC_ARG

Constant Value: "delay_msec"

static final String TEST_TIMEOUT_INST_ARGS_KEY

instrumentation test runner argument key used for individual test timeout

Constant Value: "timeout_msec"

Fields

private BugreportCollector.Freq mBugreportFrequency

private boolean mFallbackToSerialRerun

private String mForceAbi

private File mInstallFile

private Map<String, String> mInstrArgMap

private boolean mIsRerunMode

private boolean mIsResumeMode

private boolean mLogcatOnFailure

private int mMaxLogcatBytes

private String mPackageName

private boolean mReRunUsingTestFile

private int mReRunUsingTestFileAttempts

private boolean mRebootBeforeReRun

private String mRunName

private String mRunnerName

private boolean mScreenshotOnFailure

private long mShellTimeout

private String mTestClassName

private int mTestDelay

private String mTestMethodName

private String mTestPackageName

private String mTestSize

private int mTestTimeout

private Integer mTimeout

Public Constructors

public InstrumentationTest ()

Public Methods

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

public String getCoverageTarget ()

Get the coverageTarget previously set via setCoverageTarget(String).

Returns
String

public ITestDevice getDevice ()

Get the device under test.

Returns
ITestDevice the ITestDevice

public String getForceAbi ()

Returns
String

public String getPackageName ()

Get the Android manifest package to run.

Returns
String

public String getRunName ()

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

Returns
String

public String getRunnerName ()

Gets the Android instrumentation runner to be used.

Returns
String

public boolean isResumable ()

Returns
boolean

public void run (ITestInvocationListener listener)

Runs the tests, and reports result to the listener.

Parameters
listener ITestInvocationListener: the ITestInvocationListener of test results
Throws
DeviceNotAvailableException

public void setBugreportFrequency (BugreportCollector.Freq freq)

Set the frequency with which to automatically collect bugreports after test failures.

Note that there is _no feedback mechanism_ between the test runner and the bugreport collector, so use the EACH setting with due caution: if a large quantity of failures happen in rapid succession, the bugreport for a given one of the failures could end up being collected tens of minutes or hours after the respective failure occurred.

Parameters
freq BugreportCollector.Freq

public void setClassName (String testClassName)

Optionally, set the test class name to run.

Parameters
testClassName String

public void setCollectsTestsShellTimeout (int timeout)

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

Exposed for testing.

Parameters
timeout int

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

public void setDevice (ITestDevice device)

Inject the device under test.

Parameters
device ITestDevice: the ITestDevice to use

public void setFallbackToSerialRerun (boolean reRunSerially)

Parameters
reRunSerially boolean

public void setForceAbi (String abi)

Sets force-abi option.

public void setInstallFile (File installFile)

Set the optional file to install that contains the tests.

Parameters
installFile File: the installable File

public void setLogcatOnFailure (boolean logcatOnFailure)

Parameters
logcatOnFailure boolean

public void setLogcatOnFailureSize (int logcatOnFailureSize)

Parameters
logcatOnFailureSize int

public void setMethodName (String testMethodName)

Optionally, set the test method to run.

Parameters
testMethodName String

public void setPackageName (String packageName)

Set the Android manifest package to run.

Parameters
packageName String

public void setReRunUsingTestFile (boolean reRunUsingTestFile)

Parameters
reRunUsingTestFile boolean

public void setRebootBeforeReRun (boolean rebootBeforeReRun)

Parameters
rebootBeforeReRun boolean

public void setRerunMode (boolean rerun)

Optionally, set the rerun mode.

Parameters
rerun boolean

public void setResumeMode (boolean resume)

Optionally, set the resume mode.

Parameters
resume boolean

public void setRunName (String runName)

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

Parameters
runName String

public void setRunnerName (String runnerName)

Optionally, set the Android instrumentation runner to use.

Parameters
runnerName String

public void setScreenshotOnFailure (boolean screenshotOnFailure)

Parameters
screenshotOnFailure boolean

public void setShellTimeout (long timeout)

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

Parameters
timeout long

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 InstrumentationSerialTest"

Parameters
testFilePathOnDevice String

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

public void setTestSize (String size)

Optionally, set the test size to run.

Parameters
size String

public void setTestTimeout (int timeout)

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

Parameters
timeout int

public void setTestsToRun (Collection<TestIdentifier> tests, boolean forceBatchMode)

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

Parameters
tests Collection: the tests to run
forceBatchMode boolean: if true, the first attempt to run the tests will proceed as normal with the InstrumentationTest attempting to run all tests in the package. If false, the given tests will be run one by one with separate adb commands.

Protected Methods

protected void setRunnerArgs (IRemoteAndroidTestRunner runner)

Parameters
runner IRemoteAndroidTestRunner