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.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

Constants

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

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.

addMonitor

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.

callApplicationOnCreate

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

Parameters

app

Application: The application being created.

checkMonitorHit

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

finish

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.

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.

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.

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.

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

onCreate

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

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

onException

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

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.

sendCharacterSync

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.

sendKeySync

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

KeyEvent: The event to send to the current focus.

sendPointerSync

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.

sendTrackballEventSync

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.

startActivitySync

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

Intent: Description of the activity to start.

This value must never 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.

startActivitySync

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.

waitForMonitor

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

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.