Instrumentation

REPORT_KEY_IDENTIFIER

static val REPORT_KEY_IDENTIFIER: String

If included in the status or final bundle sent to an IInstrumentationWatcher, this key identifies the class that is writing the report. This can be used to provide more structured logging or reporting capabilities in the IInstrumentationWatcher.

Value: "id"

REPORT_KEY_STREAMRESULT

static val REPORT_KEY_STREAMRESULT: String

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. Using these streams provides a "pretty printer" version of the status & final packets. Any bundles including this key should also include the complete set of raw key/value pairs, so that the instrumentation can also be launched, and results collected, by an automated system.

Value: "stream"

Instrumentation

Instrumentation()

acquireLooperManager

open fun acquireLooperManager(looper: Looper!): TestLooperManager!

Takes control of the execution of messages on the specified looper until TestLooperManager#release is called.

addMonitor

open fun addMonitor(monitor: Instrumentation.ActivityMonitor!): Unit

Add a new ActivityMonitor that will be checked whenever an activity is started. The monitor is added after any existing ones; the monitor will be hit only if none of the existing monitors can themselves handle the Intent.

addMonitor

open fun addMonitor(
    filter: IntentFilter!, 
    result: Instrumentation.ActivityResult!, 
    block: Boolean
): Instrumentation.ActivityMonitor!

A convenience wrapper for addMonitor(android.app.Instrumentation.ActivityMonitor) that creates an intent filter matching ActivityMonitor for you and returns it.

addMonitor

open fun addMonitor(
    cls: String!, 
    result: Instrumentation.ActivityResult!, 
    block: Boolean
): Instrumentation.ActivityMonitor!

A convenience wrapper for addMonitor(android.app.Instrumentation.ActivityMonitor) that creates a class matching ActivityMonitor for you and returns it.

addResults

open fun addResults(results: Bundle!): Unit

Report some results in the middle of instrumentation execution. Later results (including those provided by finish) will be combined with android.os.Bundle#putAll.

callActivityOnCreate

open fun callActivityOnCreate(
    activity: Activity!, 
    icicle: Bundle!
): Unit

Perform calling of an activity's android.app.Activity#onCreate method. The default implementation simply calls through to that method.

callActivityOnCreate

open fun callActivityOnCreate(
    activity: Activity!, 
    icicle: Bundle!, 
    persistentState: PersistableBundle!
): Unit

Perform calling of an activity's android.app.Activity#onCreate method. The default implementation simply calls through to that method.

callActivityOnDestroy

open fun callActivityOnDestroy(activity: Activity!): Unit

callActivityOnNewIntent

open fun callActivityOnNewIntent(
    activity: Activity!, 
    intent: Intent!
): Unit

Perform calling of an activity's android.app.Activity#onNewIntent method. The default implementation simply calls through to that method.

callActivityOnNewIntent

open fun callActivityOnNewIntent(
    activity: Activity, 
    intent: Intent, 
    caller: ComponentCaller
): Unit

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.

callActivityOnPause

open fun callActivityOnPause(activity: Activity!): Unit

Perform calling of an activity's Activity#onPause method. The default implementation simply calls through to that method.

callActivityOnPictureInPictureRequested

open fun callActivityOnPictureInPictureRequested(activity: Activity): Unit

Perform calling of an activity's Activity#onPictureInPictureRequested method. The default implementation simply calls through to that method.

callActivityOnPostCreate

open fun callActivityOnPostCreate(
    activity: Activity, 
    savedInstanceState: Bundle?
): Unit

Perform calling of an activity's android.app.Activity#onPostCreate method. The default implementation simply calls through to that method.

callActivityOnPostCreate

open fun callActivityOnPostCreate(
    activity: Activity, 
    savedInstanceState: Bundle?, 
    persistentState: PersistableBundle?
): Unit

Perform calling of an activity's android.app.Activity#onPostCreate method. The default implementation simply calls through to that method.

callActivityOnRestart

open fun callActivityOnRestart(activity: Activity!): Unit

Perform calling of an activity's Activity#onRestart method. The default implementation simply calls through to that method.

callActivityOnRestoreInstanceState

open fun callActivityOnRestoreInstanceState(
    activity: Activity, 
    savedInstanceState: Bundle
): Unit

Perform calling of an activity's android.app.Activity#onRestoreInstanceState method. The default implementation simply calls through to that method.

callActivityOnRestoreInstanceState

open fun callActivityOnRestoreInstanceState(
    activity: Activity, 
    savedInstanceState: Bundle?, 
    persistentState: PersistableBundle?
): Unit

Perform calling of an activity's android.app.Activity#onRestoreInstanceState method. The default implementation simply calls through to that method.

callActivityOnResume

open fun callActivityOnResume(activity: Activity!): Unit

Perform calling of an activity's Activity#onResume method. The default implementation simply calls through to that method.

callActivityOnSaveInstanceState

open fun callActivityOnSaveInstanceState(
    activity: Activity, 
    outState: Bundle
): Unit

Perform calling of an activity's android.app.Activity#onSaveInstanceState method. The default implementation simply calls through to that method.

callActivityOnSaveInstanceState

open fun callActivityOnSaveInstanceState(
    activity: Activity, 
    outState: Bundle, 
    outPersistentState: PersistableBundle
): Unit

Perform calling of an activity's android.app.Activity#onSaveInstanceState method. The default implementation simply calls through to that method.

callActivityOnStart

open fun callActivityOnStart(activity: Activity!): Unit

Perform calling of an activity's Activity#onStart method. The default implementation simply calls through to that method.

callActivityOnStop

open fun callActivityOnStop(activity: Activity!): Unit

Perform calling of an activity's Activity#onStop method. The default implementation simply calls through to that method.

callActivityOnUserLeaving

open fun callActivityOnUserLeaving(activity: Activity!): Unit

Perform calling of an activity's Activity#onUserLeaveHint method. The default implementation simply calls through to that method.

callApplicationOnCreate

open fun callApplicationOnCreate(app: Application!): Unit

Perform calling of the application's Application#onCreate method. The default implementation simply calls through to that method.

Note: This method will be called immediately after onCreate(android.os.Bundle). Often instrumentation tests start their test thread in onCreate(); you need to be careful of races between these. (Well between it and everything else, but let's start here.)

checkMonitorHit

open fun checkMonitorHit(
    monitor: Instrumentation.ActivityMonitor!, 
    minHits: Int
): Boolean

Test whether an existing ActivityMonitor has been hit. If the monitor has been hit at least minHits times, then it will be removed from the activity monitor list and true returned. Otherwise it is left as-is and false is returned.

endPerformanceSnapshot

open fun endPerformanceSnapshot(): Unit

finish

open fun finish(
    resultCode: Int, 
    results: Bundle!
): Unit

Terminate instrumentation of the application. This will cause the application process to exit, removing this instrumentation from the next time the application is started. If multiple processes are currently running for this instrumentation, all of those processes will be killed.

getAllocCounts

open fun getAllocCounts(): Bundle!

Returns a bundle with the current results from the allocation counting.

getBinderCounts

open fun getBinderCounts(): Bundle!

Returns a bundle with the counts for various binder counts for this process. Currently the only two that are reported are the number of send and the number of received transactions.

getComponentName

open fun getComponentName(): ComponentName!

Returns complete component name of this instrumentation.

getContext

open fun getContext(): Context!

Return the Context of this instrumentation's package. Note that this is often different than the Context of the application being instrumentated, since the instrumentation code often lives is a different package than that of the application it is running against. See getTargetContext to retrieve a Context for the target application.

getProcessName

open fun getProcessName(): String!

Return the name of the process this instrumentation is running in. Note this should only be used for testing and debugging. If you are thinking about using this to, for example, conditionalize what is initialized in an Application class, it is strongly recommended to instead use lazy initialization (such as a getter for the state that only creates it when requested). This can greatly reduce the work your process does when created for secondary things, such as to receive a broadcast.

getTargetContext

open fun getTargetContext(): Context!

Return a Context for the target application being instrumented. Note that this is often different than the Context of the instrumentation code, since the instrumentation code often lives is a different package than that of the application it is running against. See getContext to retrieve a Context for the instrumentation code.

getUiAutomation

open fun getUiAutomation(): UiAutomation!

Gets the UiAutomation instance with no flags set.

Note: The APIs exposed via the returned UiAutomation work across application boundaries while the APIs exposed by the instrumentation do not. For example, Instrumentation#sendPointerSync(MotionEvent) will not allow you to inject the event in an app different from the instrumentation target, while UiAutomation#injectInputEvent(android.view.InputEvent, boolean) will work regardless of the current application.

A typical test case should be using either the UiAutomation or Instrumentation APIs. Using both APIs at the same time is not a mistake by itself but a client has to be aware of the APIs limitations.

Equivalent to getUiAutomation(0). If a UiAutomation exists with different flags, the flags on that instance will be changed, and then it will be returned.

Compatibility mode: This method is infallible for apps targeted for Build.VERSION_CODES#R and earlier versions; for apps targeted for later versions, it will return null if UiAutomation fails to connect. The caller can check the return value and retry on error.

getUiAutomation

open fun getUiAutomation(flags: Int): UiAutomation!

Gets the UiAutomation instance with flags set.

Note: The APIs exposed via the returned UiAutomation work across application boundaries while the APIs exposed by the instrumentation do not. For example, Instrumentation#sendPointerSync(MotionEvent) will not allow you to inject the event in an app different from the instrumentation target, while UiAutomation#injectInputEvent(android.view.InputEvent, boolean) will work regardless of the current application.

A typical test case should be using either the UiAutomation or Instrumentation APIs. Using both APIs at the same time is not a mistake by itself but a client has to be aware of the APIs limitations.

If a UiAutomation exists with different flags, the flags on that instance will be changed, and then it will be returned.

Compatibility mode: This method is infallible for apps targeted for Build.VERSION_CODES#R and earlier versions; for apps targeted for later versions, it will return null if UiAutomation fails to connect. The caller can check the return value and retry on error.

invokeContextMenuAction

open fun invokeContextMenuAction(
    targetActivity: Activity!, 
    id: Int, 
    flag: Int
): Boolean

Show the context menu for the currently focused view and executes a particular context menu item.

invokeMenuActionSync

open fun invokeMenuActionSync(
    targetActivity: Activity!, 
    id: Int, 
    flag: Int
): Boolean

Execute a particular menu item.

isProfiling

open fun isProfiling(): Boolean

Check whether this instrumentation was started with profiling enabled.

newActivity

open fun newActivity(
    clazz: Class<*>!, 
    context: Context!, 
    token: IBinder!, 
    application: Application!, 
    intent: Intent!, 
    info: ActivityInfo!, 
    title: CharSequence!, 
    parent: Activity!, 
    id: String!, 
    lastNonConfigurationInstance: Any!
): Activity!

Perform instantiation of an Activity object. This method is intended for use with unit tests, such as android.test.ActivityUnitTestCase. The activity will be useable locally but will be missing some of the linkages necessary for use within the system.

newActivity

open fun newActivity(
    cl: ClassLoader!, 
    className: String!, 
    intent: Intent!
): Activity!

Perform instantiation of the process's Activity object. The default implementation provides the normal system behavior.

newApplication

open fun newApplication(
    cl: ClassLoader!, 
    className: String!, 
    context: Context!
): Application!

Perform instantiation of the process's Application object. The default implementation provides the normal system behavior.

newApplication

open static fun newApplication(
    clazz: Class<*>!, 
    context: Context!
): Application!

Perform instantiation of the process's Application object. The default implementation provides the normal system behavior.

onCreate

open fun onCreate(arguments: Bundle!): Unit

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

onDestroy

open fun onDestroy(): Unit

Called when the instrumented application is stopping, after all of the normal application cleanup has occurred.

onException

open fun onException(
    obj: Any!, 
    e: Throwable!
): Boolean

This is called whenever the system captures an unhandled exception that was thrown by the application. The default implementation simply returns false, allowing normal system handling of the exception to take place.

onStart

open fun onStart(): Unit

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 or #startActivitySync.

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

removeMonitor

open fun removeMonitor(monitor: Instrumentation.ActivityMonitor!): Unit

Remove an ActivityMonitor that was previously added with #addMonitor.

resetInTouchMode

open fun resetInTouchMode(): Unit

Resets the touch mode to the device default.

runOnMainSync

open fun runOnMainSync(runner: Runnable!): Unit

Execute a call on the application's main thread, blocking until it is complete. Useful for doing things that are not thread-safe, such as looking at or modifying the view hierarchy.

sendCharacterSync

open fun sendCharacterSync(keyCode: Int): Unit

Sends up and down key events with the given key code to the currently focused window, and waits for it to be processed.

Equivalent to sendKeyDownUpSync(int).

sendKeyDownUpSync

open fun sendKeyDownUpSync(keyCode: Int): Unit

Sends up and down key events with the given key code to the currently focused window, and waits for it to be processed.

sendKeySync

open fun sendKeySync(event: KeyEvent!): Unit

Sends a key event to the currently focused window, and waits for it to be processed.

This method blocks until the recipient has finished handling the event. Note that the recipient may not have completely finished reacting from the event when this method returns. For example, it may still be in the process of updating its display or UI contents upon reacting to the injected event.

sendPointerSync

open fun sendPointerSync(event: MotionEvent!): Unit

Dispatches a pointer event into a window owned by the instrumented application, and waits for it to be processed.

If the motion event being injected is targeted at a window that is not owned by the instrumented application, the input injection will fail. See getUiAutomation() for injecting events into all windows.

This method blocks until the recipient has finished handling the event. Note that the recipient may not have completely finished reacting from the event when this method returns. For example, it may still be in the process of updating its display or UI contents upon reacting to the injected event.

sendStatus

open fun sendStatus(
    resultCode: Int, 
    results: Bundle!
): Unit

Provide a status report about the application.

sendStringSync

open fun sendStringSync(text: String!): Unit

Sends the key events that result in the given text being typed into the currently focused window, and waits for it to be processed.

sendTrackballEventSync

open fun sendTrackballEventSync(event: MotionEvent!): Unit

Dispatches a trackball event into the currently focused window, and waits for it to be processed.

This method blocks until the recipient has finished handling the event. Note that the recipient may not have completely finished reacting from the event when this method returns. For example, it may still be in the process of updating its display or UI contents upon reacting to the injected event.

setAutomaticPerformanceSnapshots

open fun setAutomaticPerformanceSnapshots(): Unit

setInTouchMode

open fun setInTouchMode(inTouch: Boolean): Unit

Force the global system in or out of touch mode. This can be used if your instrumentation relies on the UI being in one more or the other when it starts.

Note: Starting from Android Build.VERSION_CODES#TIRAMISU, this method will only take effect if the instrumentation was sourced from a process with MODIFY_TOUCH_MODE_STATE internal permission granted (shell already have it).

start

open fun start(): Unit

Create and start a new thread in which to run instrumentation. This new thread will call to onStart where you can implement the instrumentation.

startActivitySync

open fun startActivitySync(intent: Intent!): Activity!

Start a new activity and wait for it to begin running before returning. In addition to being synchronous, this method as some semantic differences from the standard android.content.Context#startActivity call: the activity component is resolved before talking with the activity manager (its class name is specified in the Intent that this method ultimately starts), and it does not allow you to start activities that run in a different process. In addition, if the given Intent resolves to multiple activities, instead of displaying a dialog for the user to select an activity, an exception will be thrown.

The function returns as soon as the activity goes idle following the call to its android.app.Activity#onCreate. Generally this means it has gone through the full initialization including Activity#onResume and drawn and displayed its initial window.

startActivitySync

open fun startActivitySync(
    intent: Intent, 
    options: Bundle?
): Activity

Start a new activity and wait for it to begin running before returning. In addition to being synchronous, this method as some semantic differences from the standard android.content.Context#startActivity call: the activity component is resolved before talking with the activity manager (its class name is specified in the Intent that this method ultimately starts), and it does not allow you to start activities that run in a different process. In addition, if the given Intent resolves to multiple activities, instead of displaying a dialog for the user to select an activity, an exception will be thrown.

The function returns as soon as the activity goes idle following the call to its android.app.Activity#onCreate. Generally this means it has gone through the full initialization including Activity#onResume and drawn and displayed its initial window.

startAllocCounting

open fun startAllocCounting(): Unit

Deprecated: Deprecated in Java.

startPerformanceSnapshot

open fun startPerformanceSnapshot(): Unit

startProfiling

open fun startProfiling(): Unit

This method will start profiling if isProfiling() returns true. You should only call this method if you set the handleProfiling attribute in the manifest file for this Instrumentation to true.

stopAllocCounting

open fun stopAllocCounting(): Unit

Deprecated: Deprecated in Java.

stopProfiling

open fun stopProfiling(): Unit

Stops profiling if isProfiling() returns true.

waitForIdle

open fun waitForIdle(recipient: Runnable!): Unit

Schedule a callback for when the application's main thread goes idle (has no more events to process).

waitForIdleSync

open fun waitForIdleSync(): Unit

Synchronously wait for the application to be idle. Can not be called from the main application thread -- use start to execute instrumentation in its own thread.

waitForMonitor

open fun waitForMonitor(monitor: Instrumentation.ActivityMonitor!): Activity!

Wait for an existing ActivityMonitor to be hit. Once the monitor has been hit, it is removed from the activity monitor list and the first created Activity object that matched it is returned.

waitForMonitorWithTimeout

open fun waitForMonitorWithTimeout(
    monitor: Instrumentation.ActivityMonitor!, 
    timeOut: Long
): Activity!

Wait for an existing ActivityMonitor to be hit till the timeout expires. Once the monitor has been hit, it is removed from the activity monitor list and the first created Activity object that matched it is returned. If the timeout expires, a null object is returned.