to top
Android APIs
public class

InstrumentationTestRunner

extends Instrumentation
implements TestSuiteProvider
java.lang.Object
   ↳ android.app.Instrumentation
     ↳ android.test.InstrumentationTestRunner

Class Overview

An Instrumentation that runs various types of TestCases against an Android package (application).

Developer Guides

For more information about application testing, read the Testing developer guide.

Typical Usage

  1. Write TestCases that perform unit, functional, or performance tests against the classes in your package. Typically these are subclassed from:
  2. In an appropriate AndroidManifest.xml, define the this instrumentation with the appropriate android:targetPackage set.
  3. Run the instrumentation using "adb shell am instrument -w", with no optional arguments, to run all tests (except performance tests).
  4. Run the instrumentation using "adb shell am instrument -w", with the argument '-e func true' to run all functional tests. These are tests that derive from InstrumentationTestCase.
  5. Run the instrumentation using "adb shell am instrument -w", with the argument '-e unit true' to run all unit tests. These are tests that do notderive from InstrumentationTestCase (and are not performance tests).
  6. Run the instrumentation using "adb shell am instrument -w", with the argument '-e class' set to run an individual TestCase.

Running all tests: adb shell am instrument -w com.android.foo/android.test.InstrumentationTestRunner

Running all small tests: adb shell am instrument -w -e size small com.android.foo/android.test.InstrumentationTestRunner

Running all medium tests: adb shell am instrument -w -e size medium com.android.foo/android.test.InstrumentationTestRunner

Running all large tests: adb shell am instrument -w -e size large com.android.foo/android.test.InstrumentationTestRunner

Filter test run to tests with given annotation: adb shell am instrument -w -e annotation com.android.foo.MyAnnotation com.android.foo/android.test.InstrumentationTestRunner

If used with other options, the resulting test run will contain the union of the two options. e.g. "-e size large -e annotation com.android.foo.MyAnnotation" will run only tests with both the LargeTest and "com.android.foo.MyAnnotation" annotations.

Filter test run to tests without given annotation: adb shell am instrument -w -e notAnnotation com.android.foo.MyAnnotation com.android.foo/android.test.InstrumentationTestRunner

Running a single testcase: adb shell am instrument -w -e class com.android.foo.FooTest com.android.foo/android.test.InstrumentationTestRunner

Running a single test: adb shell am instrument -w -e class com.android.foo.FooTest#testFoo com.android.foo/android.test.InstrumentationTestRunner

Running multiple tests: adb shell am instrument -w -e class com.android.foo.FooTest,com.android.foo.TooTest com.android.foo/android.test.InstrumentationTestRunner

Running all tests in a java package: adb shell am instrument -w -e package com.android.foo.subpkg com.android.foo/android.test.InstrumentationTestRunner

Including performance tests: adb shell am instrument -w -e perf true com.android.foo/android.test.InstrumentationTestRunner

To debug your tests, set a break point in your code and pass: -e debug true

To run in 'log only' mode -e log true This option will load and iterate through all test classes and methods, but will bypass actual test execution. Useful for quickly obtaining info on the tests to be executed by an instrumentation command.

To generate EMMA code coverage: -e coverage true Note: this requires an emma instrumented build. By default, the code coverage results file will be saved in a /data/ /coverage.ec file, unless overridden by coverageFile flag (see below)

To specify EMMA code coverage results file path: -e coverageFile /sdcard/myFile.ec
in addition to the other arguments.

Summary

Constants
String REPORT_KEY_NAME_CLASS If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the name of the current test class.
String REPORT_KEY_NAME_TEST If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the name of the current test.
String REPORT_KEY_NUM_CURRENT If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the sequence number of the current test.
String REPORT_KEY_NUM_TOTAL If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the total number of tests that are being run.
String REPORT_KEY_STACK If included in the status bundle sent to an IInstrumentationWatcher, this key identifies a stack trace describing an error or failure.
String REPORT_VALUE_ID This value, if stored with key REPORT_KEY_IDENTIFIER, identifies InstrumentationTestRunner as the source of the report.
int REPORT_VALUE_RESULT_ERROR The test completed with an error.
int REPORT_VALUE_RESULT_FAILURE The test completed with a failure.
int REPORT_VALUE_RESULT_OK The test completed successfully.
int REPORT_VALUE_RESULT_START The test is starting.
[Expand]
Inherited Constants
From class android.app.Instrumentation
Public Constructors

? Examples 		InstrumentationTestRunner()
Public Methods

? Examples 		TestSuite getAllTests()
Override this to define all of the tests to run in your package.

? Examples 		ClassLoader getLoader()
Override this to provide access to the class loader of your package.

? Examples 		TestSuite getTestSuite()

? Examples 		void onCreate( Bundle arguments)
Called when the instrumentation is starting, before any application code has been loaded.

? Examples 		void onStart()
Method where the instrumentation thread enters execution.
Protected Methods
AndroidTestRunner getAndroidTestRunner()
[Expand]
Inherited Methods
From class android.app.Instrumentation
From class java.lang.Object
From interface android.test.TestSuiteProvider

Constants

public static final String REPORT_KEY_NAME_CLASS

Added in API level 1

If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the name of the current test class. This is sent with any status message describing a specific test being started or completed.

Constant Value: "class"

public static final String REPORT_KEY_NAME_TEST

Added in API level 1

If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the name of the current test. This is sent with any status message describing a specific test being started or completed.

Constant Value: "test"

public static final String REPORT_KEY_NUM_CURRENT

Added in API level 1

If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the sequence number of the current test. This is sent with any status message describing a specific test being started or completed.

Constant Value: "current"

public static final String REPORT_KEY_NUM_TOTAL

Added in API level 1

If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the total number of tests that are being run. This is sent with all status messages.

Constant Value: "numtests"

public static final String REPORT_KEY_STACK

Added in API level 1

If included in the status bundle sent to an IInstrumentationWatcher, this key identifies a stack trace describing an error or failure. This is sent with any status message describing a specific test being completed.

Constant Value: "stack"

public static final String REPORT_VALUE_ID

Added in API level 1

This value, if stored with key REPORT_KEY_IDENTIFIER, identifies InstrumentationTestRunner as the source of the report. This is sent with all status messages.

Constant Value: "InstrumentationTestRunner"

public static final int REPORT_VALUE_RESULT_ERROR

Added in API level 1

The test completed with an error.

Constant Value: -1 (0xffffffff)

public static final int REPORT_VALUE_RESULT_FAILURE

Added in API level 1

The test completed with a failure.

Constant Value: -2 (0xfffffffe)

public static final int REPORT_VALUE_RESULT_OK

Added in API level 1

The test completed successfully.

Constant Value: 0 (0x00000000)

public static final int REPORT_VALUE_RESULT_START

Added in API level 1

The test is starting.

Constant Value: 1 (0x00000001)

Public Constructors

public InstrumentationTestRunner ()

Added in API level 1

Public Methods

public TestSuite getAllTests ()

Added in API level 1

Override this to define all of the tests to run in your package.

public ClassLoader getLoader ()

Added in API level 1

Override this to provide access to the class loader of your package.

public TestSuite getTestSuite ()

Added in API level 1

public void onCreate (Bundle arguments)

Added in API level 1

Called when the instrumentation is starting, before any application code has been loaded. Usually this will be implemented to simply call start() to begin the instrumentation thread, which will then continue execution in onStart().

If you do not need your own thread -- that is you are writing your instrumentation to be completely asynchronous (returning to the event loop so that the application can run), you can simply begin your instrumentation here, for example call startActivity(Intent) to begin the appropriate first activity of the application.

Parameters
arguments Any additional arguments that were supplied when the instrumentation was started.

public void onStart ()

Added in API level 1

Method where the instrumentation thread enters execution. This allows you to run your instrumentation code in a separate thread than the application, so that it can perform blocking operation such as sendKeySync(KeyEvent) or startActivitySync(Intent).

You will typically want to call finish() when this function is done, to end your instrumentation.

Protected Methods

protected AndroidTestRunner getAndroidTestRunner ()

Added in API level 1

No examples for this method.
Frequently called with: [Clear]
Portions of this page are reproduced from work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License. The original page is available here.