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
Summary
Constants
|
|
|
Value |
|
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. |
"id" |
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. |
"stream" |
Public Constructors
Public Methods
|
|
|
|
|
void |
addMonitor(Instrumentation.ActivityMonitor monitor) |
|
|
|
|
|
Instrumentation.ActivityMonitor |
addMonitor(IntentFilter filter, Instrumentation.ActivityResult result, boolean block) |
|
|
|
|
|
Instrumentation.ActivityMonitor |
addMonitor(String cls, Instrumentation.ActivityResult result, boolean block) |
|
|
|
|
|
void |
callActivityOnCreate(Activity activity, Bundle icicle) |
|
|
|
|
|
void |
callActivityOnDestroy(Activity activity) |
|
|
|
|
|
void |
callActivityOnNewIntent(Activity activity, Intent intent) |
|
|
|
|
|
void |
callActivityOnPause(Activity activity) |
|
|
|
|
|
void |
callActivityOnPostCreate(Activity activity, Bundle icicle) |
|
|
|
|
|
void |
callActivityOnRestart(Activity activity) |
|
|
|
|
|
void |
callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState) |
|
|
|
|
|
void |
callActivityOnResume(Activity activity) |
|
|
|
|
|
void |
callActivityOnSaveInstanceState(Activity activity, Bundle outState) |
|
|
|
|
|
void |
callActivityOnStart(Activity activity) |
|
|
|
|
|
void |
callActivityOnStop(Activity activity) |
|
|
|
|
|
void |
callApplicationOnCreate(Application app) |
|
|
|
|
|
boolean |
checkMonitorHit(Instrumentation.ActivityMonitor monitor, int minHits) |
|
|
|
|
|
void |
endPerformanceSnapshot() |
|
|
|
|
|
Instrumentation.ActivityResult |
execStartActivity(Context who, IApplicationThread whoThread, IBinder token, Activity target, Intent intent, int requestCode) |
|
|
|
|
|
void |
finish(int resultCode, Bundle results) |
|
|
|
|
|
Bundle |
getAllocCounts() |
|
|
|
|
|
Bundle |
getBinderCounts() |
|
|
|
|
|
ComponentName |
getComponentName() |
|
|
|
|
|
Context |
getContext() |
|
|
|
|
|
Context |
getTargetContext() |
|
|
|
|
|
boolean |
invokeContextMenuAction(Activity targetActivity, int id, int flag) |
|
|
|
|
|
boolean |
invokeMenuActionSync(Activity targetActivity, int id, int flag) |
|
|
|
|
|
boolean |
isProfiling() |
|
|
|
|
|
Activity |
newActivity(ClassLoader cl, String className, Intent intent) |
|
|
|
|
|
Activity |
newActivity(Class<?> clazz, Context context, IBinder token, Application application, Intent intent, ActivityInfo info, CharSequence title, Activity parent, String id, Object lastNonConfigurationInstance) |
|
|
|
static |
|
Application |
newApplication(Class<?> clazz, Context context) |
|
|
|
|
|
Application |
newApplication(ClassLoader cl, String className, Context context) |
|
|
|
|
|
void |
onCreate(Bundle arguments) |
|
|
|
|
|
void |
onDestroy() |
|
|
|
|
|
boolean |
onException(Object obj, Throwable e) |
|
|
|
|
|
void |
onStart() |
|
|
|
|
|
void |
removeMonitor(Instrumentation.ActivityMonitor monitor) |
|
|
|
|
|
void |
runOnMainSync(Runnable runner) |
|
|
|
|
|
void |
sendCharacterSync(int keyCode) |
|
|
|
|
|
void |
sendKeyDownUpSync(int key) |
|
|
|
|
|
void |
sendKeySync(KeyEvent event) |
|
|
|
|
|
void |
sendPointerSync(MotionEvent event) |
|
|
|
|
|
void |
sendStatus(int resultCode, Bundle results) |
|
|
|
|
|
void |
sendStringSync(String text) |
|
|
|
|
|
void |
sendTrackballEventSync(MotionEvent event) |
|
|
|
|
|
void |
setAutomaticPerformanceSnapshots() |
|
|
|
|
|
void |
setInTouchMode(boolean inTouch) |
|
|
|
|
|
void |
start() |
|
|
|
|
|
Activity |
startActivitySync(Intent intent) |
|
|
|
|
|
void |
startAllocCounting() |
|
|
|
|
|
void |
startPerformanceSnapshot() |
|
|
|
|
|
void |
startProfiling() |
|
|
|
|
|
void |
stopAllocCounting() |
|
|
|
|
|
void |
stopProfiling() |
|
|
|
|
|
void |
waitForIdle(Runnable recipient) |
|
|
|
|
|
void |
waitForIdleSync() |
|
|
|
|
|
Activity |
waitForMonitor(Instrumentation.ActivityMonitor monitor) |
|
|
|
|
|
Activity |
waitForMonitorWithTimeout(Instrumentation.ActivityMonitor monitor, long timeOut) |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Constants
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"
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
Public Methods
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
proceed. |
Returns
- The newly created and added activity monitor.
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
proceed. |
Returns
- The newly created and added activity monitor.
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
callActivityOnDestroy(Activity activity)
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
callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState)
Perform calling of an activity's
onRestoreInstanceState(Bundle)
method. The default implementation simply calls through to that method.
Parameters
activity
| The activity being restored. |
savedInstanceState
| The previously saved state being restored.
|
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
callActivityOnSaveInstanceState(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 saved. |
outState
| The bundle to pass to the call.
|
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
callActivityOnStop(Activity activity)
Perform calling of an activity's
onStop()
method. The default implementation simply calls through to that method.
Parameters
activity
| The activity being stopped.
|
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.
|
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
void
endPerformanceSnapshot()
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. |
whoThread
| The main thread of 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
Bundle
getAllocCounts()
Returns a bundle with the current results from the allocation counting.
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 complete component name of this instrumentation.
Returns
- Returns the complete component name for this instrumentation.
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
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
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
| The activity in question. |
id
| The identifier associated with the context menu item. |
flag
| Additional flags, if any. |
Returns
- Whether the invocation was successful (for example, it could be
false if item is disabled).
public
boolean
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. |
Returns
- Whether the invocation was successful (for example, it could be
false if item is disabled).
public
boolean
isProfiling()
Check whether this instrumentation was started with profiling enabled.
Returns
- Returns true if profiling was enabled when starting, else false.
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.
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.
Parameters
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(). |
Returns
- Returns the instantiated activity
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
| The class used to create an Application object from. |
context
| The context to initialize the application with |
Returns
- The newly instantiated Application object.
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. |
context
| The context to initialize the application with |
Returns
- The newly instantiated Application object.
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, BroadcastReceiver, 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
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.
public
void
sendStatus(int resultCode, Bundle results)
Provide a status report about the application.
Parameters
resultCode
| Current success/failure of instrumentation. |
results
| Any results to send back to the code that started the instrumentation.
|
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.
public
void
setAutomaticPerformanceSnapshots()
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.
Parameters
inTouch
| Set to true to be in touch mode, false to be in
focus mode.
|
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
startPerformanceSnapshot()
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.
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.
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.
Parameters
monitor
| The ActivityMonitor to wait for. |
timeOut
| The timeout value in secs. |
Returns
- The Activity object that matched the monitor.