public class Instrumentation extends Object
Modifier and Type | Class and Description |
---|---|
static class |
Instrumentation.ActivityMonitor
Information about a particular kind of Intent that is being monitored.
|
static class |
Instrumentation.ActivityResult
Description of a Activity execution result to return to the original
activity.
|
Modifier and Type | Field and Description |
---|---|
static 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.
|
static 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.
|
Constructor and Description |
---|
Instrumentation() |
Modifier and Type | Method and Description |
---|---|
void |
addMonitor(Instrumentation.ActivityMonitor monitor)
Add a new
Instrumentation.ActivityMonitor that will be checked whenever an
activity is started. |
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. |
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. |
void |
callActivityOnCreate(Activity activity,
Bundle icicle)
Perform calling of an activity's
Activity.onCreate(android.os.Bundle)
method. |
void |
callActivityOnDestroy(Activity activity) |
void |
callActivityOnNewIntent(Activity activity,
Intent intent)
Perform calling of an activity's
Activity.onNewIntent(android.content.Intent)
method. |
void |
callActivityOnPause(Activity activity)
Perform calling of an activity's
Activity.onPause() method. |
void |
callActivityOnPostCreate(Activity activity,
Bundle icicle)
Perform calling of an activity's
Activity.onPostCreate(android.os.Bundle) method. |
void |
callActivityOnRestart(Activity activity)
Perform calling of an activity's
Activity.onRestart()
method. |
void |
callActivityOnRestoreInstanceState(Activity activity,
Bundle savedInstanceState)
Perform calling of an activity's
Activity.onRestoreInstanceState(android.os.Bundle)
method. |
void |
callActivityOnResume(Activity activity)
Perform calling of an activity's
Activity.onResume() method. |
void |
callActivityOnSaveInstanceState(Activity activity,
Bundle outState)
Perform calling of an activity's
Activity.onPause() method. |
void |
callActivityOnStart(Activity activity)
Perform calling of an activity's
Activity.onStart()
method. |
void |
callActivityOnStop(Activity activity)
Perform calling of an activity's
Activity.onStop()
method. |
void |
callActivityOnUserLeaving(Activity activity)
Perform calling of an activity's
Activity.onUserLeaveHint() method. |
void |
callApplicationOnCreate(Application app)
Perform calling of the application's
Application.onCreate()
method. |
boolean |
checkMonitorHit(Instrumentation.ActivityMonitor monitor,
int minHits)
Test whether an existing
Instrumentation.ActivityMonitor has been hit. |
void |
endPerformanceSnapshot() |
void |
execStartActivities(Context who,
IBinder contextThread,
IBinder token,
Activity target,
Intent[] intents,
Bundle options)
Like
#execStartActivity(Context, IBinder, IBinder, Activity, Intent, int) ,
but accepts an array of activities to be started. |
void |
execStartActivitiesAsUser(Context who,
IBinder contextThread,
IBinder token,
Activity target,
Intent[] intents,
Bundle options,
int userId)
Like
#execStartActivity(Context, IBinder, IBinder, Activity, Intent, int) ,
but accepts an array of activities to be started. |
Instrumentation.ActivityResult |
execStartActivity(Context who,
IBinder contextThread,
IBinder token,
Activity target,
Intent intent,
int requestCode,
Bundle options)
Execute a startActivity call made by the application.
|
Instrumentation.ActivityResult |
execStartActivity(Context who,
IBinder contextThread,
IBinder token,
Activity target,
Intent intent,
int requestCode,
Bundle options,
UserHandle user)
Like
#execStartActivity(Context, IBinder, IBinder, Activity, Intent, int) ,
but for starting as a particular user. |
Instrumentation.ActivityResult |
execStartActivity(Context who,
IBinder contextThread,
IBinder token,
Fragment target,
Intent intent,
int requestCode,
Bundle options)
Like
#execStartActivity(Context, IBinder, IBinder, Activity, Intent, int) ,
but for calls from a {#link Fragment}. |
void |
finish(int resultCode,
Bundle results)
Terminate instrumentation of the application.
|
Bundle |
getAllocCounts()
Returns a bundle with the current results from the allocation counting.
|
Bundle |
getBinderCounts()
Returns a bundle with the counts for various binder counts for this process.
|
ComponentName |
getComponentName()
Returns complete component name of this instrumentation.
|
Context |
getContext()
Return the Context of this instrumentation's package.
|
Context |
getTargetContext()
Return a Context for the target application being instrumented.
|
boolean |
invokeContextMenuAction(Activity targetActivity,
int id,
int flag)
Show the context menu for the currently focused view and executes a
particular context menu item.
|
boolean |
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(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. |
Activity |
newActivity(ClassLoader cl,
String className,
Intent intent)
Perform instantiation of the process's
Activity object. |
static Application |
newApplication(Class<?> clazz,
Context context)
Perform instantiation of the process's
Application object. |
Application |
newApplication(ClassLoader cl,
String className,
Context context)
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(Instrumentation.ActivityMonitor monitor)
Remove an
Instrumentation.ActivityMonitor that was previously added with
addMonitor(android.app.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 |
sendStatus(int resultCode,
Bundle results)
Provide a status report about the application.
|
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 |
setAutomaticPerformanceSnapshots() |
void |
setInTouchMode(boolean inTouch)
Force the global system in or out of touch mode.
|
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 |
startPerformanceSnapshot() |
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(Instrumentation.ActivityMonitor monitor)
Wait for an existing
Instrumentation.ActivityMonitor to be hit. |
Activity |
waitForMonitorWithTimeout(Instrumentation.ActivityMonitor monitor,
long timeOut)
Wait for an existing
Instrumentation.ActivityMonitor to be hit till the timeout
expires. |
public static final String REPORT_KEY_IDENTIFIER
public static final String REPORT_KEY_STREAMRESULT
public void onCreate(Bundle arguments)
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 Context.startActivity(android.content.Intent)
to
begin the appropriate first activity of the application.
arguments
- Any additional arguments that were supplied when the
instrumentation was started.public void start()
onStart()
where you can implement the
instrumentation.public void onStart()
sendKeySync(android.view.KeyEvent)
or startActivitySync(android.content.Intent)
.
You will typically want to call finish() when this function is done, to end your instrumentation.
public boolean onException(Object obj, Throwable e)
obj
- The client object that generated the exception. May be an
Application, Activity, BroadcastReceiver, Service, or null.e
- The exception that was thrown.public void sendStatus(int resultCode, Bundle results)
resultCode
- Current success/failure of instrumentation.results
- Any results to send back to the code that started the instrumentation.public void finish(int resultCode, Bundle results)
resultCode
- Overall success/failure of instrumentation.results
- Any results to send back to the code that started the
instrumentation.public void setAutomaticPerformanceSnapshots()
public void startPerformanceSnapshot()
public void endPerformanceSnapshot()
public void onDestroy()
public Context getContext()
getTargetContext()
to retrieve a Context for the target
application.getTargetContext()
public ComponentName getComponentName()
public Context getTargetContext()
getContext()
to retrieve a Context for the instrumentation code.getContext()
public boolean isProfiling()
public void startProfiling()
public void stopProfiling()
public void setInTouchMode(boolean inTouch)
inTouch
- Set to true to be in touch mode, false to be in
focus mode.public void waitForIdle(Runnable recipient)
recipient
- Called the next time the thread's message queue is
idle.public void waitForIdleSync()
start()
to execute
instrumentation in its own thread.public void runOnMainSync(Runnable runner)
runner
- The code to run on the main thread.public Activity startActivitySync(Intent intent)
Context.startActivity(android.content.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 Activity.onCreate(android.os.Bundle)
. Generally this means it has gone
through the full initialization including Activity.onResume()
and
drawn and displayed its initial window.
intent
- Description of the activity to start.Context.startActivity(android.content.Intent)
public void addMonitor(Instrumentation.ActivityMonitor monitor)
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.addMonitor(IntentFilter, ActivityResult, boolean)
,
checkMonitorHit(android.app.Instrumentation.ActivityMonitor, int)
public Instrumentation.ActivityMonitor addMonitor(IntentFilter filter, Instrumentation.ActivityResult result, boolean block)
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.addMonitor(ActivityMonitor)
,
checkMonitorHit(android.app.Instrumentation.ActivityMonitor, int)
public Instrumentation.ActivityMonitor addMonitor(String cls, Instrumentation.ActivityResult result, boolean block)
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.addMonitor(ActivityMonitor)
,
checkMonitorHit(android.app.Instrumentation.ActivityMonitor, int)
public boolean checkMonitorHit(Instrumentation.ActivityMonitor monitor, int minHits)
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.addMonitor(android.app.Instrumentation.ActivityMonitor)
public Activity waitForMonitor(Instrumentation.ActivityMonitor monitor)
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.public Activity waitForMonitorWithTimeout(Instrumentation.ActivityMonitor monitor, long timeOut)
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.public void removeMonitor(Instrumentation.ActivityMonitor monitor)
Instrumentation.ActivityMonitor
that was previously added with
addMonitor(android.app.Instrumentation.ActivityMonitor)
.monitor
- The monitor to remove.addMonitor(android.app.Instrumentation.ActivityMonitor)
public boolean invokeMenuActionSync(Activity targetActivity, int id, int flag)
targetActivity
- The activity in question.id
- The identifier associated with the menu item.flag
- Additional flags, if any.public boolean invokeContextMenuAction(Activity targetActivity, int id, int flag)
targetActivity
- The activity in question.id
- The identifier associated with the context menu item.flag
- Additional flags, if any.public void sendStringSync(String text)
text
- The text to be sent.public void sendKeySync(KeyEvent event)
event
- The event to send to the current focus.public void sendKeyDownUpSync(int key)
key
- The integer keycode for the event.public void sendCharacterSync(int keyCode)
sendKeySync(android.view.KeyEvent)
. The event appears
as if it came from keyboard 0, the built in one.keyCode
- The key code of the character to send.public void sendPointerSync(MotionEvent event)
event
- A motion event describing the pointer action. (As noted in
MotionEvent.obtain(long, long, int, float, float, int)
, be sure to use
SystemClock.uptimeMillis()
as the timebase.public void sendTrackballEventSync(MotionEvent event)
event
- A motion event describing the trackball action. (As noted in
MotionEvent.obtain(long, long, int, float, float, int)
, be sure to use
SystemClock.uptimeMillis()
as the timebase.public Application newApplication(ClassLoader cl, String className, Context context) throws InstantiationException, IllegalAccessException, ClassNotFoundException
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 withInstantiationException
IllegalAccessException
ClassNotFoundException
public static Application newApplication(Class<?> clazz, Context context) throws InstantiationException, IllegalAccessException, ClassNotFoundException
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 withInstantiationException
IllegalAccessException
ClassNotFoundException
public void callApplicationOnCreate(Application app)
Application.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.public Activity newActivity(Class<?> clazz, Context context, IBinder token, Application application, Intent intent, ActivityInfo info, CharSequence title, Activity parent, String id, Object lastNonConfigurationInstance) throws InstantiationException, IllegalAccessException
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 Activitycontext
- The base context for the activity to usetoken
- The token for this activity to communicate withapplication
- The application object (if any)intent
- The intent that started this Activityinfo
- ActivityInfo from the manifesttitle
- The title, typically retrieved from the ActivityInfo recordparent
- The parent Activity (if any)id
- The embedded Id (if any)lastNonConfigurationInstance
- Arbitrary object that will be
available via Activity.getLastNonConfigurationInstance()
.InstantiationException
IllegalAccessException
public Activity newActivity(ClassLoader cl, String className, Intent intent) throws InstantiationException, IllegalAccessException, ClassNotFoundException
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.InstantiationException
IllegalAccessException
ClassNotFoundException
public void callActivityOnCreate(Activity activity, Bundle icicle)
Activity.onCreate(android.os.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().public void callActivityOnDestroy(Activity activity)
public void callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState)
Activity.onRestoreInstanceState(android.os.Bundle)
method. The default implementation simply calls through to that method.activity
- The activity being restored.savedInstanceState
- The previously saved state being restored.public void callActivityOnPostCreate(Activity activity, Bundle icicle)
Activity.onPostCreate(android.os.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().public void callActivityOnNewIntent(Activity activity, Intent intent)
Activity.onNewIntent(android.content.Intent)
method. The default implementation simply calls through to that method.activity
- The activity receiving a new Intent.intent
- The new intent being received.public void callActivityOnStart(Activity activity)
Activity.onStart()
method. The default implementation simply calls through to that method.activity
- The activity being started.public void callActivityOnRestart(Activity activity)
Activity.onRestart()
method. The default implementation simply calls through to that method.activity
- The activity being restarted.public void callActivityOnResume(Activity activity)
Activity.onResume()
method. The
default implementation simply calls through to that method.activity
- The activity being resumed.public void callActivityOnStop(Activity activity)
Activity.onStop()
method. The default implementation simply calls through to that method.activity
- The activity being stopped.public void callActivityOnSaveInstanceState(Activity activity, Bundle outState)
Activity.onPause()
method. The
default implementation simply calls through to that method.activity
- The activity being saved.outState
- The bundle to pass to the call.public void callActivityOnPause(Activity activity)
Activity.onPause()
method. The
default implementation simply calls through to that method.activity
- The activity being paused.public void callActivityOnUserLeaving(Activity activity)
Activity.onUserLeaveHint()
method.
The default implementation simply calls through to that method.activity
- The activity being notified that the user has navigated awaypublic void startAllocCounting()
public void stopAllocCounting()
public Bundle getAllocCounts()
public Bundle getBinderCounts()
public Instrumentation.ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Activity target, Intent intent, int requestCode, Bundle options)
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.
who
- The Context from which the activity is being started.contextThread
- 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 performing 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.options
- Addition options.ActivityNotFoundException
Activity.startActivity(Intent)
,
Activity.startActivityForResult(Intent, int)
,
{@hide}
public void execStartActivities(Context who, IBinder contextThread, IBinder token, Activity target, Intent[] intents, Bundle options)
#execStartActivity(Context, IBinder, IBinder, Activity, Intent, int)
,
but accepts an array of activities to be started. Note that active
Instrumentation.ActivityMonitor
objects only match against the first activity in
the array.
public void execStartActivitiesAsUser(Context who, IBinder contextThread, IBinder token, Activity target, Intent[] intents, Bundle options, int userId)
#execStartActivity(Context, IBinder, IBinder, Activity, Intent, int)
,
but accepts an array of activities to be started. Note that active
Instrumentation.ActivityMonitor
objects only match against the first activity in
the array.
public Instrumentation.ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Fragment target, Intent intent, int requestCode, Bundle options)
#execStartActivity(Context, IBinder, IBinder, Activity, Intent, int)
,
but for calls from a {#link Fragment}.who
- The Context from which the activity is being started.contextThread
- 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 fragment is performing the start (and thus receiving
any result).intent
- The actual Intent to start.requestCode
- Identifier for this request's result; less than zero
if the caller is not expecting a result.ActivityNotFoundException
Activity.startActivity(Intent)
,
Activity.startActivityForResult(Intent, int)
,
{@hide}
public Instrumentation.ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Activity target, Intent intent, int requestCode, Bundle options, UserHandle user)
#execStartActivity(Context, IBinder, IBinder, Activity, Intent, int)
,
but for starting as a particular user.who
- The Context from which the activity is being started.contextThread
- 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 fragment is performing the start (and thus receiving
any result).intent
- The actual Intent to start.requestCode
- Identifier for this request's result; less than zero
if the caller is not expecting a result.ActivityNotFoundException
Activity.startActivity(Intent)
,
Activity.startActivityForResult(Intent, int)
,
{@hide}