Android - An Open Handset Alliance Project

android.app
public class

android.app.Instrumentation

java.lang.Object
	android.app.Instrumentation

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.

Nested Classes

Instrumentation.ActivityMonitor	Information about a particular kind of Intent that is being monitored in execStartActivity(ApplicationContext, IBinder, Activity, Intent, int).
Instrumentation.ActivityResult	Description of a Activity execution result to return to the original activity.

Summary

Public Constructors

Instrumentation()

Public Methods

				ActivityMonitor	addMonitor(IntentFilter filter, ActivityResult result, boolean block)
					A convenience wrapper for addMonitor(ActivityMonitor) that creates an intent filter matching Instrumentation.ActivityMonitor for you and returns it.
				void	addMonitor(ActivityMonitor monitor)
					Add a new Instrumentation.ActivityMonitor that will be checked whenever an activity is started in execStartActivity(ApplicationContext, IBinder, Activity, Intent, int).
				ActivityMonitor	addMonitor(String cls, ActivityResult result, boolean block)
					A convenience wrapper for addMonitor(ActivityMonitor) that creates a class matching Instrumentation.ActivityMonitor for you and returns it.
				void	callActivityOnCompleteThaw(Activity activity, Bundle icicle)
					Perform calling of an activity's onCompleteThaw(Bundle) method.
				void	callActivityOnCreate(Activity activity, Bundle icicle)
					Perform calling of an activity's onCreate(Bundle) method.
				void	callActivityOnFreeze(Activity activity, Bundle outState)
					Perform calling of an activity's onPause() method.
				void	callActivityOnNewIntent(Activity activity, Intent intent)
					Perform calling of an activity's onNewIntent(Intent) method.
				void	callActivityOnPause(Activity activity)
					Perform calling of an activity's onPause() method.
				void	callActivityOnPostCreate(Activity activity, Bundle icicle)
					Perform calling of an activity's onPostCreate(Bundle) method.
				void	callActivityOnRestart(Activity activity)
					Perform calling of an activity's onRestart() method.
				void	callActivityOnResume(Activity activity)
					Perform calling of an activity's onResume() method.
				void	callActivityOnStart(Activity activity)
					Perform calling of an activity's onStart() method.
				void	callApplicationOnCreate(Application app)
					Perform calling of the application's onCreate() method.
				boolean	checkMonitorHit(ActivityMonitor monitor, int minHits)
					Test whether an existing Instrumentation.ActivityMonitor has been hit.
				Bitmap	dupWindowBitmapSync(Activity activity)
					Return a copy of the bitmap holding the overall contents of the Activity's window.
				ActivityResult	execStartActivity(ApplicationContext who, IBinder token, Activity target, Intent intent, int requestCode)
					Execute a startActivity() call made by the application.
				void	finish(int resultCode, Bundle results)
					Terminate instrumentation of the application.
				void	getAllocCounts(Bundle results)
					Puts the current results from the allocation counting into results.
				void	getBinderCounts(Bundle results)
					Puts the counts for various binder counts for this process.
				Context	getContext()
					Return the Context of this instrumentation's package.
				void	getCpuTime(Bundle result)
					Puts the cpu time for this process in results.
				Context	getTargetContext()
					Return a Context for the target application being instrumented.
				void	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(ClassLoader cl, String className, Intent intent)
					Perform instantiation of the process's Activity object.
				Application	newApplication(ClassLoader cl, String className)
					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(ActivityMonitor monitor)
					Remove an Instrumentation.ActivityMonitor that was previously added with addMonitor(Instrumentation.ActivityMonitor).
				void	runOnMainSync(Runnable runner)
					Execute a call on the application's main thread, blocking until it is complete.
				void	sendCharacterSync(int keyCode)
					Higher-level method for sending both the down and up key events for a particular character key code.
				void	sendKeyDownUpSync(int key)
					Sends an up and down key event sync to the currently focused window.
				void	sendKeySync(KeyEvent event)
					Send a key event to the currently focused window/view and wait for it to be processed.
				void	sendPointerSync(MotionEvent event)
					Dispatch a pointer event.
				void	sendStringSync(String text)
					Sends the key events corresponding to the text to the app being instrumented.
				void	sendTrackballEventSync(MotionEvent event)
					Dispatch a trackball event.
				void	start()
					Create and start a new thread in which to run instrumentation.
				Activity	startActivitySync(Intent intent)
					Start a new activity and wait for it to begin running before returning.
				void	startAllocCounting()
				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(ActivityMonitor monitor)
					Wait for an existing Instrumentation.ActivityMonitor to be hit.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

	Object	clone()
		Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
	boolean	equals(Object o)
		Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
	void	finalize()
		Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
final	Class	getClass()
		Answers the unique instance of java.lang.Class which represents the class of the receiver.
	int	hashCode()
		Answers an integer hash code for the receiver.
final	void	notify()
		Causes one thread which is `wait` ing on the receiver to be made ready to run.
final	void	notifyAll()
		Causes all threads which are `wait` ing on the receiver to be made ready to run.
	String	toString()
		Answers a string containing a concise, human-readable description of the receiver.
final	void	wait(long time, int frac)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait(long time)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait()
		Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by `notify` or `notifyAll`).

Details

Public Constructors

public Instrumentation()

Public Methods

public ActivityMonitor addMonitor(IntentFilter filter, ActivityResult result, boolean block)

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

Parameters

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

Returns

The newly created and added activity monitor.

public void addMonitor(ActivityMonitor monitor)

Add a new Instrumentation.ActivityMonitor that will be checked whenever an activity is started in execStartActivity(ApplicationContext, IBinder, Activity, Intent, int). 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	The new ActivityMonitor to see.

public ActivityMonitor addMonitor(String cls, ActivityResult result, boolean block)

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

Parameters

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

Returns

The newly created and added activity monitor.

public void callActivityOnCompleteThaw(Activity activity, Bundle icicle)

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

Parameters

activity	The activity being thawed.
icicle	The previously frozen state being thawed.

public void callActivityOnCreate(Activity activity, Bundle icicle)

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

Parameters

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

public void callActivityOnFreeze(Activity activity, Bundle outState)

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

Parameters

activity	The activity being frozen.

public void callActivityOnNewIntent(Activity activity, Intent intent)

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

Parameters

activity	The activity receiving a new Intent.
intent	The new intent being received.

public void callActivityOnPause(Activity activity)

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

Parameters

activity	The activity being paused.

public void callActivityOnPostCreate(Activity activity, Bundle icicle)

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

Parameters

activity	The activity being created.
icicle	The previously frozen state (or null) to pass through to onPostCreate().

public void callActivityOnRestart(Activity activity)

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

Parameters

activity	The activity being restarted.

public void callActivityOnResume(Activity activity)

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

Parameters

activity	The activity being resumed.

public void callActivityOnStart(Activity activity)

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

Parameters

activity	The activity being started.

public void callApplicationOnCreate(Application app)

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

Parameters

app	The application being created.

public boolean checkMonitorHit(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.

Parameters

monitor	The ActivityMonitor to check.
minHits	The minimum number of hits required.

Returns

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

public Bitmap dupWindowBitmapSync(Activity activity)

Return a copy of the bitmap holding the overall contents of the Activity's window. If the Activity's window is not attached to the window manager or not visible visible, null is returned.

This function uses runOnMainSync(Runnable) to have the main application thread retrieve the bitmap and wait for the result, so it can be used from any thread except the main thread. Code running in the main thread can directly call dupWindowBitmap().

Returns

A new Bitmap object holding a copy of the window's current contents.

public ActivityResult execStartActivity(ApplicationContext who, IBinder token, Activity target, Intent intent, int requestCode)

Execute a startActivity() call made by the application. The default implementation takes care of updating any active Instrumentation.ActivityMonitor objects and dispatches this call to the system activity manager; you can override this to watch for the application to start an activity, and modify what happens when it does.

This method returns an Instrumentation.ActivityResult object, which you can use when intercepting application calls to avoid performing the start activity action but still return the result the application is expecting. To do this, override this method to catch the call to start activity so that it returns a new ActivityResult containing the results you would like the application to see, and don't call up to the super class. Note that an application is only expecting a result if requestCode is >= 0.

This method throws ActivityNotFoundException if there was no Activity found to run the given Intent.

Parameters

who	The Context from which the activity is being started.
token	Internal token identifying to the system who is starting the activity; may be null.
target	Which activity is perform the start (and thus receiving any result); may be null if this call is not being made from an activity.
intent	The actual Intent to start.
requestCode	Identifier for this request's result; less than zero if the caller is not expecting a result.

Returns

To force the return of a particular result, return an ActivityResult object containing the desired data; otherwise return null. The default implementation always returns null.

Throws

	android.content.ActivityNotFoundException

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.

Parameters

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

public void getAllocCounts(Bundle results)

Puts the current results from the allocation counting into results.

Parameters

results	The allocation count results.

public void getBinderCounts(Bundle results)

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

Parameters

results	The binder count results.

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

The instrumentation's package context.

public void getCpuTime(Bundle result)

Puts the cpu time for this process in results.

Parameters

result	The cpu time result.

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

A Context in the target application.

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

Execute a particular menu item.

Parameters

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

public boolean isProfiling()

Check whether this instrumentation was started with profiling enabled.

Returns

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

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	The ClassLoader with which to instantiate the object.
className	The name of the class implementing the Activity object.
intent	The Intent object that specified the activity class being instantiated.

Returns

The newly instantiated Activity object.

Throws

InstantiationException
IllegalAccessException
ClassNotFoundException

public Application newApplication(ClassLoader cl, String className)

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

Parameters

cl	The ClassLoader with which to instantiate the object.
className	The name of the class implementing the Application object.

Returns

The newly instantiated Application object.

Throws

InstantiationException
IllegalAccessException
ClassNotFoundException

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

Parameters

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

public void onDestroy()

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

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	The client object that generated the exception. May be an Application, Activity, IntentReceiver, Service, or null.
e	The exception that was thrown.

Returns

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.

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.

public void removeMonitor(ActivityMonitor monitor)

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

Parameters

monitor	The monitor to remove.

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	The code to run on the main thread.

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

Parameters

keyCode	The key code of the character to send.

public void sendKeyDownUpSync(int key)

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

Parameters

key	The integer keycode for the event.

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

Parameters

event	The event to send to the current focus.

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

Parameters

event	The MotionEvent to dispatch

public void sendStringSync(String text)

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

Parameters

text	The text to be sent.

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

Parameters

event	The MotionEvent to dispatch

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.

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

Parameters

intent	Description of the activity to start.

public void startAllocCounting()

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.

public void stopAllocCounting()

public void stopProfiling()

Stops profiling if isProfiling() returns true.

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	Called the next time the thread's message queue is idle.

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.

public Activity waitForMonitor(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.

Parameters

monitor	The ActivityMonitor to wait for.

Returns

The Activity object that matched the monitor.


e.g. "intent" or "activity"

Android - An Open Handset Alliance Project

Documentation

Goodies

android.app.Instrumentation

Nested Classes

Summary

Public Constructors

Public Methods

Methods inherited from class java.lang.Object

Details

Public Constructors

public Instrumentation()

Public Methods

public ActivityMonitor addMonitor(IntentFilter filter, ActivityResult result, boolean block)

Parameters

Returns

See Also

public void addMonitor(ActivityMonitor monitor)

Parameters

See Also

public ActivityMonitor addMonitor(String cls, ActivityResult result, boolean block)

Parameters

Returns

See Also

public void callActivityOnCompleteThaw(Activity activity, Bundle icicle)

Parameters

public void callActivityOnCreate(Activity activity, Bundle icicle)

Parameters

public void callActivityOnFreeze(Activity activity, Bundle outState)

Parameters

public void callActivityOnNewIntent(Activity activity, Intent intent)

Parameters

public void callActivityOnPause(Activity activity)

Parameters

public void callActivityOnPostCreate(Activity activity, Bundle icicle)

Parameters

public void callActivityOnRestart(Activity activity)

Parameters

public void callActivityOnResume(Activity activity)

Parameters

public void callActivityOnStart(Activity activity)

Parameters

public void callApplicationOnCreate(Application app)

Parameters

public boolean checkMonitorHit(ActivityMonitor monitor, int minHits)

Parameters

Returns

See Also

public Bitmap dupWindowBitmapSync(Activity activity)

Returns

See Also

public ActivityResult execStartActivity(ApplicationContext who, IBinder token, Activity target, Intent intent, int requestCode)

Parameters

Returns

Throws

See Also

public void finish(int resultCode, Bundle results)

Parameters

public void getAllocCounts(Bundle results)

Parameters

public void getBinderCounts(Bundle results)

Parameters

public Context getContext()

Returns

See Also

public void getCpuTime(Bundle result)

Parameters

public Context getTargetContext()

Returns

See Also

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

Parameters

public boolean isProfiling()

Returns

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

Parameters

Returns

Throws

public Application newApplication(ClassLoader cl, String className)

Parameters