java.lang.Object | |
↳ | android.app.Instrumentation |
Known Direct Subclasses |
Known Indirect Subclasses |
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. | ||||||||||
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 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
A convenience wrapper for
addMonitor(ActivityMonitor) that
creates an intent filter matching Instrumentation.ActivityMonitor for you and
returns it. | |||||||||||
Add a new
Instrumentation.ActivityMonitor that will be checked whenever an
activity is started. | |||||||||||
A convenience wrapper for
addMonitor(ActivityMonitor) that
creates a class matching Instrumentation.ActivityMonitor for you and returns it. | |||||||||||
Perform calling of an activity's
onCreate(Bundle)
method. | |||||||||||
Perform calling of an activity's
onCreate(Bundle)
method. | |||||||||||
Perform calling of an activity's
onNewIntent(Intent)
method. | |||||||||||
Perform calling of an activity's
onPause() method. | |||||||||||
Perform calling of an activity's
onPostCreate(Bundle) method. | |||||||||||
Perform calling of an activity's
onPostCreate(Bundle) method. | |||||||||||
Perform calling of an activity's
onRestart()
method. | |||||||||||
Perform calling of an activity's
onRestoreInstanceState(Bundle)
method. | |||||||||||
Perform calling of an activity's
onRestoreInstanceState(Bundle)
method. | |||||||||||
Perform calling of an activity's
onResume() method. | |||||||||||
Perform calling of an activity's
onSaveInstanceState(Bundle)
method. | |||||||||||
Perform calling of an activity's
onSaveInstanceState(Bundle)
method. | |||||||||||
Perform calling of an activity's
onStart()
method. | |||||||||||
Perform calling of an activity's
onStop()
method. | |||||||||||
Perform calling of an activity's
onUserLeaveHint() method. | |||||||||||
Perform calling of the application's
onCreate()
method. | |||||||||||
Test whether an existing
Instrumentation.ActivityMonitor has been hit. | |||||||||||
Terminate instrumentation of the application.
| |||||||||||
Returns a bundle with the current results from the allocation counting.
| |||||||||||
Returns a bundle with the counts for various binder counts for this process.
| |||||||||||
Returns complete component name of this instrumentation.
| |||||||||||
Return the Context of this instrumentation's package.
| |||||||||||
Return a Context for the target application being instrumented.
| |||||||||||
Gets the
UiAutomation instance. | |||||||||||
Show the context menu for the currently focused view and executes a
particular context menu item.
| |||||||||||
Execute a particular menu item.
| |||||||||||
Check whether this instrumentation was started with profiling enabled.
| |||||||||||
Perform instantiation of the process's
Activity object. | |||||||||||
Perform instantiation of an
Activity object. | |||||||||||
Perform instantiation of the process's
Application object. | |||||||||||
Perform instantiation of the process's
Application object. | |||||||||||
Called when the instrumentation is starting, before any application code
has been loaded.
| |||||||||||
Called when the instrumented application is stopping, after all of the
normal application cleanup has occurred.
| |||||||||||
This is called whenever the system captures an unhandled exception that
was thrown by the application.
| |||||||||||
Method where the instrumentation thread enters execution.
| |||||||||||
Remove an
Instrumentation.ActivityMonitor that was previously added with
addMonitor(Instrumentation.ActivityMonitor) . | |||||||||||
Execute a call on the application's main thread, blocking until it is
complete.
| |||||||||||
Higher-level method for sending both the down and up key events for a
particular character key code.
| |||||||||||
Sends an up and down key event sync to the currently focused window.
| |||||||||||
Send a key event to the currently focused window/view and wait for it to
be processed.
| |||||||||||
Dispatch a pointer event.
| |||||||||||
Provide a status report about the application.
| |||||||||||
Sends the key events corresponding to the text to the app being
instrumented.
| |||||||||||
Dispatch a trackball event.
| |||||||||||
Force the global system in or out of touch mode.
| |||||||||||
Create and start a new thread in which to run instrumentation.
| |||||||||||
Start a new activity and wait for it to begin running before returning.
| |||||||||||
This method will start profiling if isProfiling() returns true.
| |||||||||||
Stops profiling if isProfiling() returns true.
| |||||||||||
Schedule a callback for when the application's main thread goes idle
(has no more events to process).
| |||||||||||
Synchronously wait for the application to be idle.
| |||||||||||
Wait for an existing
Instrumentation.ActivityMonitor to be hit. | |||||||||||
Wait for an existing
Instrumentation.ActivityMonitor to be hit till the timeout
expires. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
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.
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.
A convenience wrapper for addMonitor(ActivityMonitor)
that
creates an intent filter matching Instrumentation.ActivityMonitor
for you and
returns it.
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 proceed. |
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.
monitor | The new ActivityMonitor to see. |
---|
A convenience wrapper for addMonitor(ActivityMonitor)
that
creates a class matching Instrumentation.ActivityMonitor
for you and returns it.
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 proceed. |
Perform calling of an activity's onCreate(Bundle)
method. The default implementation simply calls through to that method.
activity | The activity being created. |
---|---|
icicle | The previously frozen state (or null) to pass through to onCreate(). |
Perform calling of an activity's onCreate(Bundle)
method. The default implementation simply calls through to that method.
activity | The activity being created. |
---|---|
icicle | The previously frozen state (or null) to pass through to |
persistentState | The previously persisted state (or null) |
Perform calling of an activity's onNewIntent(Intent)
method. The default implementation simply calls through to that method.
activity | The activity receiving a new Intent. |
---|---|
intent | The new intent being received. |
Perform calling of an activity's onPause()
method. The
default implementation simply calls through to that method.
activity | The activity being paused. |
---|
Perform calling of an activity's onPostCreate(Bundle)
method.
The default implementation simply calls through to that method.
activity | The activity being created. |
---|---|
icicle | The previously frozen state (or null) to pass through to onPostCreate(). |
Perform calling of an activity's onPostCreate(Bundle)
method.
The default implementation simply calls through to that method.
activity | The activity being created. |
---|---|
icicle | The previously frozen state (or null) to pass through to onPostCreate(). |
Perform calling of an activity's onRestart()
method. The default implementation simply calls through to that method.
activity | The activity being restarted. |
---|
Perform calling of an activity's onRestoreInstanceState(Bundle)
method. The default implementation simply calls through to that method.
activity | The activity being restored. |
---|---|
savedInstanceState | The previously saved state being restored. |
Perform calling of an activity's onRestoreInstanceState(Bundle)
method. The default implementation simply calls through to that method.
activity | The activity being restored. |
---|---|
savedInstanceState | The previously saved state being restored. |
persistentState | The previously persisted state (or null) |
Perform calling of an activity's onResume()
method. The
default implementation simply calls through to that method.
activity | The activity being resumed. |
---|
Perform calling of an activity's onSaveInstanceState(Bundle)
method. The default implementation simply calls through to that method.
activity | The activity being saved. |
---|---|
outState | The bundle to pass to the call. |
Perform calling of an activity's onSaveInstanceState(Bundle)
method. The default implementation simply calls through to that method.
activity | The activity being saved. |
---|---|
outState | The bundle to pass to the call. |
outPersistentState | The persistent bundle to pass to the call. |
Perform calling of an activity's onStart()
method. The default implementation simply calls through to that method.
activity | The activity being started. |
---|
Perform calling of an activity's onStop()
method. The default implementation simply calls through to that method.
activity | The activity being stopped. |
---|
Perform calling of an activity's onUserLeaveHint()
method.
The default implementation simply calls through to that method.
activity | The activity being notified that the user has navigated away |
---|
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.)
app | The application being created. |
---|
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.
monitor | The ActivityMonitor to check. |
---|---|
minHits | The minimum number of hits required. |
Terminate instrumentation of the application. This will cause the application process to exit, removing this instrumentation from the next time the application is started.
resultCode | Overall success/failure of instrumentation. |
---|---|
results | Any results to send back to the code that started the instrumentation. |
Returns a bundle with the current results from the allocation counting.
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 complete component name of this instrumentation.
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.
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.
Gets the UiAutomation
instance.
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.
Show the context menu for the currently focused view and executes a particular context menu item.
targetActivity | The activity in question. |
---|---|
id | The identifier associated with the context menu item. |
flag | Additional flags, if any. |
Execute a particular menu item.
targetActivity | The activity in question. |
---|---|
id | The identifier associated with the menu item. |
flag | Additional flags, if any. |
Check whether this instrumentation was started with profiling enabled.
Perform instantiation of the process's Activity
object. The
default implementation provides the normal system behavior.
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. |
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.
clazz | The Class of the desired Activity |
---|---|
context | The base context for the activity to use |
token | The token for this activity to communicate with |
application | The application object (if any) |
intent | The intent that started this Activity |
info | ActivityInfo from the manifest |
title | The title, typically retrieved from the ActivityInfo record |
parent | The parent Activity (if any) |
id | The embedded Id (if any) |
lastNonConfigurationInstance | Arbitrary object that will be
available via Activity.getLastNonConfigurationInstance() . |
InstantiationException | |
IllegalAccessException | |
InstantiationException |
Perform instantiation of the process's Application
object. The
default implementation provides the normal system behavior.
cl | The ClassLoader with which to instantiate the object. |
---|---|
className | The name of the class implementing the Application object. |
context | The context to initialize the application with |
Perform instantiation of the process's Application
object. The
default implementation provides the normal system behavior.
clazz | The class used to create an Application object from. |
---|---|
context | The context to initialize the application with |
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.
arguments | Any additional arguments that were supplied when the instrumentation was started. |
---|
Called when the instrumented application is stopping, after all of the normal application cleanup has occurred.
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.
obj | The client object that generated the exception. May be an Application, Activity, BroadcastReceiver, Service, or null. |
---|---|
e | The exception that was thrown. |
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.
Remove an Instrumentation.ActivityMonitor
that was previously added with
addMonitor(Instrumentation.ActivityMonitor)
.
monitor | The monitor to remove. |
---|
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.
runner | The code to run on the main thread. |
---|
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.
keyCode | The key code of the character to send. |
---|
Sends an up and down key event sync to the currently focused window.
key | The integer keycode for the 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.
event | The event to send to the current focus. |
---|
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.
event | A motion event describing the pointer action. (As noted in
obtain(long, long, int, float, float, int) , be sure to use
uptimeMillis() as the timebase.
|
---|
Provide a status report about the application.
resultCode | Current success/failure of instrumentation. |
---|---|
results | Any results to send back to the code that started the instrumentation. |
Sends the key events corresponding to the text to the app being instrumented.
text | The text to be sent. |
---|
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.
event | A motion event describing the trackball action. (As noted in
obtain(long, long, int, float, float, int) , be sure to use
uptimeMillis() as the timebase.
|
---|
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.
inTouch | Set to true to be in touch mode, false to be in focus mode. |
---|
Create and start a new thread in which to run instrumentation. This new
thread will call to onStart()
where you can implement the
instrumentation.
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.
intent | Description of the activity to start. |
---|
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.
Schedule a callback for when the application's main thread goes idle (has no more events to process).
recipient | Called the next time the thread's message queue is idle. |
---|
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.
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.
monitor | The ActivityMonitor to wait for. |
---|
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.
monitor | The ActivityMonitor to wait for. |
---|---|
timeOut | The timeout value in secs. |