Instrumentation

REPORT_KEY_IDENTIFIER

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

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"

Instrumentation

Instrumentation ()

addMonitor

Instrumentation.ActivityMonitor addMonitor (String cls, 
                Instrumentation.ActivityResult result, 
                boolean block)

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

addMonitor

Instrumentation.ActivityMonitor addMonitor (IntentFilter filter, 
                Instrumentation.ActivityResult result, 
                boolean block)

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

addMonitor

void addMonitor (Instrumentation.ActivityMonitor monitor)

Add a new Instrumentation.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.

callActivityOnCreate

void callActivityOnCreate (Activity activity, 
                Bundle icicle)

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

callActivityOnCreate

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

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

callActivityOnDestroy

void callActivityOnDestroy (Activity activity)

callActivityOnNewIntent

void callActivityOnNewIntent (Activity activity, 
                Intent intent)

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

callActivityOnPause

void callActivityOnPause (Activity activity)

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

callActivityOnPostCreate

void callActivityOnPostCreate (Activity activity, 
                Bundle icicle, 
                PersistableBundle persistentState)

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

callActivityOnPostCreate

void callActivityOnPostCreate (Activity activity, 
                Bundle icicle)

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

callActivityOnRestart

void callActivityOnRestart (Activity activity)

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

callActivityOnRestoreInstanceState

void callActivityOnRestoreInstanceState (Activity activity, 
                Bundle savedInstanceState)

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

callActivityOnRestoreInstanceState

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

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

callActivityOnResume

void callActivityOnResume (Activity activity)

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

callActivityOnSaveInstanceState

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

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

callActivityOnSaveInstanceState

void callActivityOnSaveInstanceState (Activity activity, 
                Bundle outState)

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

callActivityOnStart

void callActivityOnStart (Activity activity)

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

callActivityOnStop

void callActivityOnStop (Activity activity)

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

callActivityOnUserLeaving

void callActivityOnUserLeaving (Activity activity)

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

callApplicationOnCreate

void callApplicationOnCreate (Application app)

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

Note: This method will be called immediately after onCreate(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

boolean checkMonitorHit (Instrumentation.ActivityMonitor monitor, 
                int minHits)

Test whether an existing Instrumentation.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

void endPerformanceSnapshot ()

finish

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.

getAllocCounts

Bundle getAllocCounts ()

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

getBinderCounts

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.

getComponentName

ComponentName getComponentName ()

Returns complete component name of this instrumentation.

getContext

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.

getTargetContext

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.

getUiAutomation

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, sendPointerSync(MotionEvent) will not allow you to inject the event in an app different from the instrumentation target, while 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.

getUiAutomation

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, sendPointerSync(MotionEvent) will not allow you to inject the event in an app different from the instrumentation target, while 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.

invokeContextMenuAction

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

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

invokeMenuActionSync

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

Execute a particular menu item.

isProfiling

boolean isProfiling ()

Check whether this instrumentation was started with profiling enabled.

newActivity

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

newActivity

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

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

newApplication

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

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

newApplication

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

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

onCreate

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

onDestroy

void onDestroy ()

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

onException

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.

onStart

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

void removeMonitor (Instrumentation.ActivityMonitor monitor)

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

runOnMainSync

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.

sendCharacterSync

void sendCharacterSync (int keyCode)

Higher-level method for sending both the down and up key events for a particular character key code. Equivalent to creating both KeyEvent objects by hand and calling sendKeySync(KeyEvent). The event appears as if it came from keyboard 0, the built in one.

sendKeyDownUpSync

void sendKeyDownUpSync (int key)

Sends an up and down key event sync to the currently focused window.

sendKeySync

void sendKeySync (KeyEvent event)

Send a key event to the currently focused window/view and wait for it to be processed. Finished at some point after the recipient has returned from its event processing, though it may not have completely finished reacting from the event -- for example, if it needs to update its display as a result, it may still be in the process of doing that.

sendPointerSync

void sendPointerSync (MotionEvent event)

Dispatch a pointer event. Finished at some point after the recipient has returned from its event processing, though it may not have completely finished reacting from the event -- for example, if it needs to update its display as a result, it may still be in the process of doing that.

sendStatus

void sendStatus (int resultCode, 
                Bundle results)

Provide a status report about the application.

sendStringSync

void sendStringSync (String text)

Sends the key events corresponding to the text to the app being instrumented.

sendTrackballEventSync

void sendTrackballEventSync (MotionEvent event)

Dispatch a trackball event. Finished at some point after the recipient has returned from its event processing, though it may not have completely finished reacting from the event -- for example, if it needs to update its display as a result, it may still be in the process of doing that.

setAutomaticPerformanceSnapshots

void setAutomaticPerformanceSnapshots ()

setInTouchMode

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.

start

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

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

startAllocCounting

void startAllocCounting ()

startPerformanceSnapshot

void startPerformanceSnapshot ()

startProfiling

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

void stopAllocCounting ()

stopProfiling

void stopProfiling ()

Stops profiling if isProfiling() returns true.

waitForIdle

void waitForIdle (Runnable recipient)

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

waitForIdleSync

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

Activity waitForMonitor (Instrumentation.ActivityMonitor monitor)

Wait for an existing Instrumentation.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

Activity waitForMonitorWithTimeout (Instrumentation.ActivityMonitor monitor, 
                long timeOut)

Wait for an existing Instrumentation.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.