Added in API level 1

Summary: Nested Classes | Constants | Ctors | Methods | Inherited Methods

Instrumentation

---

Kotlin |Java

public class Instrumentation
extends Object

java.lang.Object
↳	android.app.Instrumentation

Known direct subclasses InstrumentationTestRunner, LaunchPerformanceBase InstrumentationTestRunner This class was deprecated in API level 24. Use AndroidJUnitRunner instead. New tests should be written using the Android Testing Support Library.  LaunchPerformanceBase Base class for all launch performance Instrumentation classes.

---

Base class for implementing application instrumentation code. When running with instrumentation turned on, this class will be instantiated for you before any of the application code, allowing you to monitor all of the interaction the system has with the application. An Instrumentation implementation is described to the system through an AndroidManifest.xml's <instrumentation> tag.

Summary

Nested classes
class	Instrumentation.ActivityMonitor Information about a particular kind of Intent that is being monitored.
class	Instrumentation.ActivityResult Description of a Activity execution result to return to the original activity.

Constants
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
Instrumentation()

Public methods
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.

Inherited methods

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.

Constants

REPORT_KEY_IDENTIFIER

Added in API level 1

public static final 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. This can be used to provide more structured logging or reporting capabilities in the IInstrumentationWatcher.

Constant Value: "id"

REPORT_KEY_STREAMRESULT

Added in API level 1

public static final 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. 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.

Constant Value: "stream"

Public constructors

Instrumentation

Added in API level 1

public Instrumentation ()

Public methods

acquireLooperManager

Added in API level 26

public TestLooperManager acquireLooperManager (Looper looper)

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

Parameters
looper	Looper

Returns
TestLooperManager

addMonitor

Added in API level 1

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

Parameters
cls	String: The activity class this monitor is responsible for.
result	Instrumentation.ActivityResult: A canned result to return if the monitor is hit; can be null.
block	boolean: Controls whether the monitor should block the activity start (returning its canned result) or let the call proceed.

Returns
Instrumentation.ActivityMonitor	The newly created and added activity monitor.

See also:

• addMonitor(ActivityMonitor)
• checkMonitorHit(ActivityMonitor, int)

addMonitor

Added in API level 1

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

Parameters
filter	IntentFilter: The set of intents this monitor is responsible for.
result	Instrumentation.ActivityResult: A canned result to return if the monitor is hit; can be null.
block	boolean: Controls whether the monitor should block the activity start (returning its canned result) or let the call proceed.

Returns
Instrumentation.ActivityMonitor	The newly created and added activity monitor.

See also:

• addMonitor(ActivityMonitor)
• checkMonitorHit(ActivityMonitor, int)

addMonitor

Added in API level 1

public void addMonitor (Instrumentation.ActivityMonitor monitor)

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.

Parameters
monitor	Instrumentation.ActivityMonitor: The new ActivityMonitor to see.

See also:

• addMonitor(IntentFilter, ActivityResult, boolean)
• checkMonitorHit(ActivityMonitor, int)

addResults

Added in API level 26

public void addResults (Bundle results)

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

Parameters
results	Bundle

callActivityOnCreate

Added in API level 1

public void callActivityOnCreate (Activity activity, 
                Bundle icicle)

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

Parameters
activity	Activity: The activity being created.
icicle	Bundle: The previously frozen state (or null) to pass through to onCreate().

callActivityOnCreate

Added in API level 21

public void callActivityOnCreate (Activity activity, 
                Bundle icicle, 
                PersistableBundle persistentState)

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

Parameters
activity	Activity: The activity being created.
icicle	Bundle: The previously frozen state (or null) to pass through to
persistentState	PersistableBundle: The previously persisted state (or null)

callActivityOnDestroy

Added in API level 1

public void callActivityOnDestroy (Activity activity)

Parameters
activity	Activity

callActivityOnNewIntent

Added in API level 35

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

Parameters
activity	Activity: The activity receiving a new Intent. This value cannot be null.
intent	Intent: The new intent being received. This value cannot be null.
caller	ComponentCaller: The ComponentCaller instance that launched the activity with the new intent. This value cannot be null.

callActivityOnNewIntent

Added in API level 1

public void callActivityOnNewIntent (Activity activity, 
                Intent intent)

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

Parameters
activity	Activity: The activity receiving a new Intent.
intent	Intent: The new intent being received.

callActivityOnPause

Added in API level 1

public void callActivityOnPause (Activity activity)

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

Parameters
activity	Activity: The activity being paused.

callActivityOnPictureInPictureRequested

Added in API level 30

public void callActivityOnPictureInPictureRequested (Activity activity)

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

Parameters
activity	Activity: The activity being notified that picture-in-picture is being requested. This value cannot be null.

callActivityOnPostCreate

Added in API level 21

public void callActivityOnPostCreate (Activity activity, 
                Bundle savedInstanceState, 
                PersistableBundle persistentState)

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

Parameters
activity	Activity: The activity being created. This value cannot be null.
savedInstanceState	Bundle: The previously frozen state (or null) to pass through to onPostCreate().
persistentState	PersistableBundle: The previously persisted state (or null)

callActivityOnPostCreate

Added in API level 1

public void callActivityOnPostCreate (Activity activity, 
                Bundle savedInstanceState)

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

Parameters
activity	Activity: The activity being created. This value cannot be null.
savedInstanceState	Bundle: The previously saved state (or null) to pass through to onPostCreate().

callActivityOnRestart

Added in API level 1

public void callActivityOnRestart (Activity activity)

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

Parameters
activity	Activity: The activity being restarted.

callActivityOnRestoreInstanceState

Added in API level 1

public void callActivityOnRestoreInstanceState (Activity activity, 
                Bundle savedInstanceState)

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

Parameters
activity	Activity: The activity being restored. This value cannot be null.
savedInstanceState	Bundle: The previously saved state being restored. This value cannot be null.

callActivityOnRestoreInstanceState

Added in API level 21

public void callActivityOnRestoreInstanceState (Activity activity, 
                Bundle savedInstanceState, 
                PersistableBundle persistentState)

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

Parameters
activity	Activity: The activity being restored. This value cannot be null.
savedInstanceState	Bundle: The previously saved state being restored (or null).
persistentState	PersistableBundle: The previously persisted state (or null)

callActivityOnResume

Added in API level 1

public void callActivityOnResume (Activity activity)

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

Parameters
activity	Activity: The activity being resumed.

callActivityOnSaveInstanceState

Added in API level 21

public void callActivityOnSaveInstanceState (Activity activity, 
                Bundle outState, 
                PersistableBundle outPersistentState)

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

Parameters
activity	Activity: The activity being saved. This value cannot be null.
outState	Bundle: The bundle to pass to the call. This value cannot be null.
outPersistentState	PersistableBundle: The persistent bundle to pass to the call. This value cannot be null.

callActivityOnSaveInstanceState

Added in API level 1

public void callActivityOnSaveInstanceState (Activity activity, 
                Bundle outState)

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

Parameters
activity	Activity: The activity being saved. This value cannot be null.
outState	Bundle: The bundle to pass to the call. This value cannot be null.

callActivityOnStart

Added in API level 1

public void callActivityOnStart (Activity activity)

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

Parameters
activity	Activity: The activity being started.

callActivityOnStop

Added in API level 1

public void callActivityOnStop (Activity activity)

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

Parameters
activity	Activity: The activity being stopped.

callActivityOnUserLeaving

Added in API level 3

public void callActivityOnUserLeaving (Activity activity)

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

Parameters
activity	Activity: The activity being notified that the user has navigated away

callApplicationOnCreate

Added in API level 1

public void callApplicationOnCreate (Application app)

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.)

Parameters
app	Application: The application being created.

checkMonitorHit

Added in API level 1

public boolean checkMonitorHit (Instrumentation.ActivityMonitor monitor, 
                int minHits)

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.

Parameters
monitor	Instrumentation.ActivityMonitor: The ActivityMonitor to check.
minHits	int: The minimum number of hits required.

Returns
boolean	True if the hit count has been reached, else false.

See also:

• addMonitor(ActivityMonitor)

endPerformanceSnapshot

Added in API level 1

public void endPerformanceSnapshot ()

finish

Added in API level 1

public void finish (int resultCode, 
                Bundle results)

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.

Parameters
resultCode	int: Overall success/failure of instrumentation.
results	Bundle: Any results to send back to the code that started the instrumentation.

getAllocCounts

Added in API level 1

public Bundle getAllocCounts ()

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

Returns
Bundle

getBinderCounts

Added in API level 1

public Bundle getBinderCounts ()

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.

Returns
Bundle

getComponentName

Added in API level 1

public ComponentName getComponentName ()

Returns complete component name of this instrumentation.

Returns
ComponentName	Returns the complete component name for this instrumentation.

getContext

Added in API level 1

public Context getContext ()

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.

Returns
Context	The instrumentation's package context.

See also:

• getTargetContext()

getProcessName

Added in API level 26

public String getProcessName ()

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.

Returns
String

getTargetContext

Added in API level 1

public Context getTargetContext ()

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.

Returns
Context	A Context in the target application.

See also:

• getContext()

getUiAutomation

Added in API level 24

public UiAutomation getUiAutomation (int flags)

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.

Parameters
flags	int: The flags to be passed to the UiAutomation, for example UiAutomation.FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES, UiAutomation.FLAG_DONT_USE_ACCESSIBILITY. Value is 0, UiAutomation.FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES, or UiAutomation.FLAG_DONT_USE_ACCESSIBILITY

Returns
UiAutomation	The UI automation instance.

See also:

• UiAutomation

getUiAutomation

Added in API level 18

public UiAutomation getUiAutomation ()

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.

Returns
UiAutomation	The UI automation instance.

See also:

• UiAutomation

invokeContextMenuAction

Added in API level 1

public boolean invokeContextMenuAction (Activity targetActivity, 
                int id, 
                int flag)

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

Parameters
targetActivity	Activity: The activity in question.
id	int: The identifier associated with the context menu item.
flag	int: Additional flags, if any.

Returns
boolean	Whether the invocation was successful (for example, it could be false if item is disabled).

invokeMenuActionSync

Added in API level 1

public boolean invokeMenuActionSync (Activity targetActivity, 
                int id, 
                int flag)

Execute a particular menu item.

Parameters
targetActivity	Activity: The activity in question.
id	int: The identifier associated with the menu item.
flag	int: Additional flags, if any.

Returns
boolean	Whether the invocation was successful (for example, it could be false if item is disabled).

isProfiling

Added in API level 1

public boolean isProfiling ()

Check whether this instrumentation was started with profiling enabled.

Returns
boolean	Returns true if profiling was enabled when starting, else false.

newActivity

Added in API level 1

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

Parameters
clazz	Class: The Class of the desired Activity
context	Context: The base context for the activity to use
token	IBinder: The token for this activity to communicate with
application	Application: The application object (if any)
intent	Intent: The intent that started this Activity
info	ActivityInfo: ActivityInfo from the manifest
title	CharSequence: The title, typically retrieved from the ActivityInfo record
parent	Activity: The parent Activity (if any)
id	String: The embedded Id (if any)
lastNonConfigurationInstance	Object: Arbitrary object that will be available via Activity.getLastNonConfigurationInstance().

Returns
Activity	Returns the instantiated activity

Throws
	java.lang.InstantiationException
	java.lang.IllegalAccessException
IllegalAccessException
InstantiationException

newActivity

Added in API level 1

public Activity newActivity (ClassLoader cl, 
                String className, 
                Intent intent)

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

Parameters
cl	ClassLoader: The ClassLoader with which to instantiate the object.
className	String: The name of the class implementing the Activity object.
intent	Intent: The Intent object that specified the activity class being instantiated.

Returns
Activity	The newly instantiated Activity object.

Throws
ClassNotFoundException
IllegalAccessException
InstantiationException

newApplication

Added in API level 1

public Application newApplication (ClassLoader cl, 
                String className, 
                Context context)

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

Parameters
cl	ClassLoader: The ClassLoader with which to instantiate the object.
className	String: The name of the class implementing the Application object.
context	Context: The context to initialize the application with

Returns
Application	The newly instantiated Application object.

Throws
ClassNotFoundException
IllegalAccessException
InstantiationException

newApplication

Added in API level 1

public static Application newApplication (Class<?> clazz, 
                Context context)

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

Parameters
clazz	Class: The class used to create an Application object from.
context	Context: The context to initialize the application with

Returns
Application	The newly instantiated Application object.

Throws
ClassNotFoundException
IllegalAccessException
InstantiationException

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.

onDestroy

Added in API level 1

public void onDestroy ()

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

onException

Added in API level 1

public boolean onException (Object obj, 
                Throwable e)

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.

Parameters
obj	Object: The client object that generated the exception. May be an Application, Activity, BroadcastReceiver, Service, or null.
e	Throwable: The exception that was thrown.

Returns
boolean	To allow normal system exception process to occur, return false. If true is returned, the system will proceed as if the exception didn't happen.

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.

removeMonitor

Added in API level 1

public void removeMonitor (Instrumentation.ActivityMonitor monitor)

Remove an ActivityMonitor that was previously added with addMonitor(ActivityMonitor).

Parameters
monitor	Instrumentation.ActivityMonitor: The monitor to remove.

See also:

• addMonitor(ActivityMonitor)

resetInTouchMode

Added in API level 33

public void resetInTouchMode ()

Resets the touch mode to the device default.

runOnMainSync

Added in API level 1

public void runOnMainSync (Runnable runner)

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.

Parameters
runner	Runnable: The code to run on the main thread.

sendCharacterSync

Added in API level 1

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

Equivalent to sendKeyDownUpSync(int).

Parameters
keyCode	int: The key code of the character to send.

See also:

• sendKeySync(KeyEvent)

sendKeyDownUpSync

Added in API level 1

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

Parameters
keyCode	int: The key code for the events to send.

See also:

• sendKeySync(KeyEvent)

sendKeySync

Added in API level 1

public void sendKeySync (KeyEvent event)

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.

Parameters
event	KeyEvent: The event to send to the current focus.

sendPointerSync

Added in API level 1

public void sendPointerSync (MotionEvent event)

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.

Parameters
event	MotionEvent: A motion event describing the pointer action. (As noted in MotionEvent.obtain(long, long, int, float, float, int), be sure to use SystemClock.uptimeMillis() as the timebase.

sendStatus

Added in API level 1

public void sendStatus (int resultCode, 
                Bundle results)

Provide a status report about the application.

Parameters
resultCode	int: Current success/failure of instrumentation.
results	Bundle: Any results to send back to the code that started the instrumentation.

sendStringSync

Added in API level 1

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

Parameters
text	String: The text to be sent.

See also:

• sendKeySync(KeyEvent)

sendTrackballEventSync

Added in API level 1

public void sendTrackballEventSync (MotionEvent event)

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.

Parameters
event	MotionEvent: A motion event describing the trackball action. (As noted in MotionEvent.obtain(long, long, int, float, float, int), be sure to use SystemClock.uptimeMillis() as the timebase.

setAutomaticPerformanceSnapshots

Added in API level 1

public void setAutomaticPerformanceSnapshots ()

setInTouchMode

Added in API level 1

public void setInTouchMode (boolean inTouch)

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).

Parameters
inTouch	boolean: Set to true to be in touch mode, false to be in focus mode.

start

Added in API level 1

public void start ()

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

Added in API level 28

public Activity startActivitySync (Intent intent, 
                Bundle options)

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 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 Activity.onCreate. Generally this means it has gone through the full initialization including Activity.onResume and drawn and displayed its initial window.

Parameters
intent	Intent: Description of the activity to start. This value cannot be null.
options	Bundle: Additional options for how the Activity should be started. May be null if there are no options. See ActivityOptions for how to build the Bundle supplied here; there are no supported definitions for building it manually.

Returns
Activity	This value cannot be null.

See also:

• Context.startActivity(Intent, Bundle)

startActivitySync

Added in API level 1

public Activity startActivitySync (Intent intent)

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 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 Activity.onCreate. Generally this means it has gone through the full initialization including Activity.onResume and drawn and displayed its initial window.

Parameters
intent	Intent: Description of the activity to start.

Returns
Activity

See also:

• Context.startActivity(Intent)
• startActivitySync(Intent, Bundle)

startAllocCounting

Added in API level 1
Deprecated in API level 23

public void startAllocCounting ()

startPerformanceSnapshot

Added in API level 1

public void startPerformanceSnapshot ()

startProfiling

Added in API level 1

public void startProfiling ()

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

Added in API level 1
Deprecated in API level 23

public void stopAllocCounting ()

stopProfiling

Added in API level 1

public void stopProfiling ()

Stops profiling if isProfiling() returns true.

waitForIdle

Added in API level 1

public void waitForIdle (Runnable recipient)

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

Parameters
recipient	Runnable: Called the next time the thread's message queue is idle.

waitForIdleSync

Added in API level 1

public void waitForIdleSync ()

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

Added in API level 1

public Activity waitForMonitor (Instrumentation.ActivityMonitor monitor)

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.

Parameters
monitor	Instrumentation.ActivityMonitor: The ActivityMonitor to wait for.

Returns
Activity	The Activity object that matched the monitor.

waitForMonitorWithTimeout

Added in API level 1

public Activity waitForMonitorWithTimeout (Instrumentation.ActivityMonitor monitor, 
                long timeOut)

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.

Parameters
monitor	Instrumentation.ActivityMonitor: The ActivityMonitor to wait for.
timeOut	long: The timeout value in milliseconds.

Returns
Activity	The Activity object that matched the monitor.