Added in API level 1
Deprecated in API level 24

InstrumentationTestRunner

Kotlin |Java

public class InstrumentationTestRunner
extends Instrumentation implements TestSuiteProvider

java.lang.Object
↳	android.app.Instrumentation
	↳	android.test.InstrumentationTestRunner

This class was deprecated in API level 24.
Use AndroidJUnitRunner instead. New tests should be written using the Android Testing Support Library.

An Instrumentation that runs various types of ERROR(/junit.framework.TestCase)s against an Android package (application).

Developer Guides

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

Typical Usage

Write ERROR(/junit.framework.TestCase)s that perform unit, functional, or performance tests against the classes in your package. Typically these are subclassed from:
- ActivityInstrumentationTestCase2
- ActivityUnitTestCase
- AndroidTestCase
- ApplicationTestCase
- InstrumentationTestCase
- ProviderTestCase
- ServiceTestCase
- SingleLaunchActivityTestCase
Set the android:targetPackage attribute of the <instrumentation> element in the test package's manifest. You should set the attribute value to the package name of the target application under test.
Run the instrumentation using "adb shell am instrument -w", with no optional arguments, to run all tests (except performance tests).
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.
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).
Run the instrumentation using "adb shell am instrument -w", with the argument '-e class' set to run an individual ERROR(/junit.framework.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 `Instrumentation.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.

Inherited constants

From class android.app.Instrumentation

`String`	`REPORT_KEY_IDENTIFIER` If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the class that is writing the report.
`String`	`REPORT_KEY_STREAMRESULT` If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies a string which can simply be printed to the output stream.

Public constructors
`InstrumentationTestRunner()`

Public methods
`TestSuite`	`getAllTests()` Override this to define all of the tests to run in your package.
`Bundle`	`getArguments()` Get the arguments passed to this instrumentation.
`ClassLoader`	`getLoader()` Override this to provide access to the class loader of your package.
`TestSuite`	`getTestSuite()`
`void`	`onCreate(Bundle arguments)` Called when the instrumentation is starting, before any application code has been loaded.
`void`	`onStart()` Method where the instrumentation thread enters execution.

Protected methods
`void`	`addTestListener(TestListener listener)` Add a `ERROR(/TestListener)`
`AndroidTestRunner`	`getAndroidTestRunner()`

Inherited methods

From class


        
          android.app.Instrumentation

`TestLooperManager`	`acquireLooperManager(Looper looper)` Takes control of the execution of messages on the specified looper until `TestLooperManager.release` is called.
`Instrumentation.ActivityMonitor`	`addMonitor(String cls, Instrumentation.ActivityResult result, boolean block)` A convenience wrapper for `addMonitor(android.app.Instrumentation.ActivityMonitor)` that creates a class matching `ActivityMonitor` for you and returns it.
`Instrumentation.ActivityMonitor`	`addMonitor(IntentFilter filter, Instrumentation.ActivityResult result, boolean block)` A convenience wrapper for `addMonitor(android.app.Instrumentation.ActivityMonitor)` that creates an intent filter matching `ActivityMonitor` for you and returns it.
`void`	`addMonitor(Instrumentation.ActivityMonitor monitor)` Add a new `ActivityMonitor` that will be checked whenever an activity is started.
`void`	`addResults(Bundle results)` Report some results in the middle of instrumentation execution.
`void`	`callActivityOnCreate(Activity activity, Bundle icicle)` Perform calling of an activity's `Activity.onCreate` method.
`void`	`callActivityOnCreate(Activity activity, Bundle icicle, PersistableBundle persistentState)` Perform calling of an activity's `Activity.onCreate` method.
`void`	`callActivityOnDestroy(Activity activity)`
`void`	`callActivityOnNewIntent(Activity activity, Intent intent, ComponentCaller caller)` Same as `callActivityOnNewIntent(android.app.Activity, android.content.Intent)`, but with an extra parameter for the `ComponentCaller` instance associated with the app that sent the intent.
`void`	`callActivityOnNewIntent(Activity activity, Intent intent)` Perform calling of an activity's `Activity.onNewIntent` method.
`void`	`callActivityOnPause(Activity activity)` Perform calling of an activity's `Activity.onPause` method.
`void`	`callActivityOnPictureInPictureRequested(Activity activity)` Perform calling of an activity's `Activity.onPictureInPictureRequested` method.
`void`	`callActivityOnPostCreate(Activity activity, Bundle savedInstanceState, PersistableBundle persistentState)` Perform calling of an activity's `Activity.onPostCreate` method.
`void`	`callActivityOnPostCreate(Activity activity, Bundle savedInstanceState)` Perform calling of an activity's `Activity.onPostCreate` method.
`void`	`callActivityOnRestart(Activity activity)` Perform calling of an activity's `Activity.onRestart` method.
`void`	`callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState)` Perform calling of an activity's `Activity.onRestoreInstanceState` method.
`void`	`callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState, PersistableBundle persistentState)` Perform calling of an activity's `Activity.onRestoreInstanceState` method.
`void`	`callActivityOnResume(Activity activity)` Perform calling of an activity's `Activity.onResume` method.
`void`	`callActivityOnSaveInstanceState(Activity activity, Bundle outState, PersistableBundle outPersistentState)` Perform calling of an activity's `Activity.onSaveInstanceState` method.
`void`	`callActivityOnSaveInstanceState(Activity activity, Bundle outState)` Perform calling of an activity's `Activity.onSaveInstanceState` method.
`void`	`callActivityOnStart(Activity activity)` Perform calling of an activity's `Activity.onStart` method.
`void`	`callActivityOnStop(Activity activity)` Perform calling of an activity's `Activity.onStop` method.
`void`	`callActivityOnUserLeaving(Activity activity)` Perform calling of an activity's `Activity.onUserLeaveHint` method.
`void`	`callApplicationOnCreate(Application app)` Perform calling of the application's `Application.onCreate` method.
`boolean`	`checkMonitorHit(Instrumentation.ActivityMonitor monitor, int minHits)` Test whether an existing `ActivityMonitor` has been hit.
`void`	`endPerformanceSnapshot()`
`void`	`finish(int resultCode, Bundle results)` Terminate instrumentation of the application.
`Bundle`	`getAllocCounts()` Returns a bundle with the current results from the allocation counting.
`Bundle`	`getBinderCounts()` Returns a bundle with the counts for various binder counts for this process.
`ComponentName`	`getComponentName()` Returns complete component name of this instrumentation.
`Context`	`getContext()` Return the Context of this instrumentation's package.
`String`	`getProcessName()` Return the name of the process this instrumentation is running in.
`Context`	`getTargetContext()` Return a Context for the target application being instrumented.
`UiAutomation`	`getUiAutomation(int flags)` Gets the `UiAutomation` instance with flags set.
`UiAutomation`	`getUiAutomation()` Gets the `UiAutomation` instance with no flags set.
`boolean`	`invokeContextMenuAction(Activity targetActivity, int id, int flag)` Show the context menu for the currently focused view and executes a particular context menu item.
`boolean`	`invokeMenuActionSync(Activity targetActivity, int id, int flag)` Execute a particular menu item.
`boolean`	`isProfiling()` Check whether this instrumentation was started with profiling enabled.
`Activity`	`newActivity(Class<?> clazz, Context context, IBinder token, Application application, Intent intent, ActivityInfo info, CharSequence title, Activity parent, String id, Object lastNonConfigurationInstance)` Perform instantiation of an `Activity` object.
`Activity`	`newActivity(ClassLoader cl, String className, Intent intent)` Perform instantiation of the process's `Activity` object.
`Application`	`newApplication(ClassLoader cl, String className, Context context)` Perform instantiation of the process's `Application` object.
`static Application`	`newApplication(Class<?> clazz, Context context)` Perform instantiation of the process's `Application` object.
`void`	`onCreate(Bundle arguments)` Called when the instrumentation is starting, before any application code has been loaded.
`void`	`onDestroy()` Called when the instrumented application is stopping, after all of the normal application cleanup has occurred.
`boolean`	`onException(Object obj, Throwable e)` This is called whenever the system captures an unhandled exception that was thrown by the application.
`void`	`onStart()` Method where the instrumentation thread enters execution.
`void`	`removeMonitor(Instrumentation.ActivityMonitor monitor)` Remove an `ActivityMonitor` that was previously added with `addMonitor(ActivityMonitor)`.
`void`	`resetInTouchMode()` Resets the `touch mode` to the device default.
`void`	`runOnMainSync(Runnable runner)` Execute a call on the application's main thread, blocking until it is complete.
`void`	`sendCharacterSync(int keyCode)` Sends up and down key events with the given key code to the currently focused window, and waits for it to be processed.
`void`	`sendKeyDownUpSync(int keyCode)` Sends up and down key events with the given key code to the currently focused window, and waits for it to be processed.
`void`	`sendKeySync(KeyEvent event)` Sends a key event to the currently focused window, and waits for it to be processed.
`void`	`sendPointerSync(MotionEvent event)` Dispatches a pointer event into a window owned by the instrumented application, and waits for it to be processed.
`void`	`sendStatus(int resultCode, Bundle results)` Provide a status report about the application.
`void`	`sendStringSync(String text)` Sends the key events that result in the given text being typed into the currently focused window, and waits for it to be processed.
`void`	`sendTrackballEventSync(MotionEvent event)` Dispatches a trackball event into the currently focused window, and waits for it to be processed.
`void`	`setAutomaticPerformanceSnapshots()`
`void`	`setInTouchMode(boolean inTouch)` Force the global system in or out of touch mode.
`void`	`start()` Create and start a new thread in which to run instrumentation.
`Activity`	`startActivitySync(Intent intent, Bundle options)` Start a new activity and wait for it to begin running before returning.
`Activity`	`startActivitySync(Intent intent)` Start a new activity and wait for it to begin running before returning.
`void`	`startAllocCounting()`
`void`	`startPerformanceSnapshot()`
`void`	`startProfiling()` This method will start profiling if isProfiling() returns true.
`void`	`stopAllocCounting()`
`void`	`stopProfiling()` Stops profiling if isProfiling() returns true.
`void`	`waitForIdle(Runnable recipient)` Schedule a callback for when the application's main thread goes idle (has no more events to process).
`void`	`waitForIdleSync()` Synchronously wait for the application to be idle.
`Activity`	`waitForMonitor(Instrumentation.ActivityMonitor monitor)` Wait for an existing `ActivityMonitor` to be hit.
`Activity`	`waitForMonitorWithTimeout(Instrumentation.ActivityMonitor monitor, long timeOut)` Wait for an existing `ActivityMonitor` to be hit till the timeout expires.

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

From interface


        
          android.test.TestSuiteProvider

abstract TestSuite getTestSuite()

Constants

REPORT_KEY_NAME_CLASS

Added in API level 1

public static final 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. This is sent with any status message describing a specific test being started or completed.

Constant Value: "class"

REPORT_KEY_NAME_TEST

Added in API level 1

public static final 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. This is sent with any status message describing a specific test being started or completed.

Constant Value: "test"

REPORT_KEY_NUM_CURRENT

Added in API level 1

public static final 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. This is sent with any status message describing a specific test being started or completed.

Constant Value: "current"

REPORT_KEY_NUM_TOTAL

Added in API level 1

public static final 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. This is sent with all status messages.

Constant Value: "numtests"

REPORT_KEY_STACK

Added in API level 1

public static final 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. This is sent with any status message describing a specific test being completed.

Constant Value: "stack"

REPORT_VALUE_ID

Added in API level 1

public static final String REPORT_VALUE_ID

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

Constant Value: "InstrumentationTestRunner"

REPORT_VALUE_RESULT_ERROR

Added in API level 1

public static final int REPORT_VALUE_RESULT_ERROR

The test completed with an error.

Constant Value: -1 (0xffffffff)

REPORT_VALUE_RESULT_FAILURE

Added in API level 1

public static final int REPORT_VALUE_RESULT_FAILURE

The test completed with a failure.

Constant Value: -2 (0xfffffffe)

REPORT_VALUE_RESULT_OK

Added in API level 1

public static final int REPORT_VALUE_RESULT_OK

The test completed successfully.

Constant Value: 0 (0x00000000)

REPORT_VALUE_RESULT_START

Added in API level 1

public static final int REPORT_VALUE_RESULT_START

The test is starting.

Constant Value: 1 (0x00000001)

Public constructors

InstrumentationTestRunner

public InstrumentationTestRunner ()

Public methods

getAllTests

Added in API level 1

public TestSuite getAllTests ()

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

Returns
`TestSuite`

getArguments

Added in API level 18
Deprecated in API level 24

public Bundle getArguments ()

Get the arguments passed to this instrumentation.

Returns
`Bundle`	the Bundle object

getLoader

Added in API level 1

public ClassLoader getLoader ()

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

Returns
`ClassLoader`

getTestSuite

Added in API level 1

public TestSuite getTestSuite ()

Returns
`TestSuite`

onCreate

Added in API level 1

public void onCreate (Bundle arguments)

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 Context.startActivity to begin the appropriate first activity of the application.

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

onStart

Added in API level 1

public void onStart ()

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

addTestListener

Added in API level 1

protected void addTestListener (TestListener listener)

Add a ERROR(/TestListener)

Parameters
`listener`	`TestListener`

getAndroidTestRunner

Added in API level 1

protected AndroidTestRunner getAndroidTestRunner ()

Returns
`AndroidTestRunner`