InstrumentationTestRunner

Class Overview

An Instrumentation that runs various types of TestCases against an Android package (application).

Typical Usage

1. Write TestCases that perform unit, functional, or performance tests against the classes in your package. Typically these are subclassed from:
   • ActivityInstrumentationTestCase2
   • ActivityUnitTestCase
   • AndroidTestCase
   • ApplicationTestCase
   • InstrumentationTestCase
   • ProviderTestCase
   • ServiceTestCase
   • SingleLaunchActivityTestCase
2. Set the android:targetPackage attribute of the <instrumentation> element in the test package's manifest. You should set the attribute value to the package name of the target application under test.
3. Run the instrumentation using "adb shell am instrument -w", with no optional arguments, to run all tests (except performance tests).
4. Run the instrumentation using "adb shell am instrument -w", with the argument '-e func true' to run all functional tests. These are tests that derive from InstrumentationTestCase.
5. Run the instrumentation using "adb shell am instrument -w", with the argument '-e unit true' to run all unit tests. These are tests that do notderive from InstrumentationTestCase (and are not performance tests).
6. Run the instrumentation using "adb shell am instrument -w", with the argument '-e class' set to run an individual TestCase.

Running all tests: adb shell am instrument -w com.android.foo/android.test.InstrumentationTestRunner

Running all small tests: adb shell am instrument -w -e size small com.android.foo/android.test.InstrumentationTestRunner

Running all medium tests: adb shell am instrument -w -e size medium com.android.foo/android.test.InstrumentationTestRunner

Running all large tests: adb shell am instrument -w -e size large com.android.foo/android.test.InstrumentationTestRunner

Filter test run to tests with given annotation: adb shell am instrument -w -e annotation com.android.foo.MyAnnotation com.android.foo/android.test.InstrumentationTestRunner

If used with other options, the resulting test run will contain the union of the two options. e.g. "-e size large -e annotation com.android.foo.MyAnnotation" will run only tests with both the LargeTest and "com.android.foo.MyAnnotation" annotations.

Filter test run to tests without given annotation: adb shell am instrument -w -e notAnnotation com.android.foo.MyAnnotation com.android.foo/android.test.InstrumentationTestRunner

Running a single testcase: adb shell am instrument -w -e class com.android.foo.FooTest com.android.foo/android.test.InstrumentationTestRunner

Running a single test: adb shell am instrument -w -e class com.android.foo.FooTest#testFoo com.android.foo/android.test.InstrumentationTestRunner

Running multiple tests: adb shell am instrument -w -e class com.android.foo.FooTest,com.android.foo.TooTest com.android.foo/android.test.InstrumentationTestRunner

Running all tests in a java package: adb shell am instrument -w -e package com.android.foo.subpkg com.android.foo/android.test.InstrumentationTestRunner

Including performance tests: adb shell am instrument -w -e perf true com.android.foo/android.test.InstrumentationTestRunner

To debug your tests, set a break point in your code and pass: -e debug true

To run in 'log only' mode -e log true This option will load and iterate through all test classes and methods, but will bypass actual test execution. Useful for quickly obtaining info on the tests to be executed by an instrumentation command.

To generate EMMA code coverage: -e coverage true Note: this requires an emma instrumented build. By default, the code coverage results file will be saved in a /data//coverage.ec file, unless overridden by coverageFile flag (see below)

To specify EMMA code coverage results file path: -e coverageFile /sdcard/myFile.ec
in addition to the other arguments.

Summary

[Expand] Inherited Constants
From class android.app.Instrumentation 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.

[Expand] Inherited Methods
From class android.app.Instrumentation 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. void addMonitor(Instrumentation.ActivityMonitor monitor) Add a new Instrumentation.ActivityMonitor that will be checked whenever an activity is started. 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 onCreate(Bundle) method. void callActivityOnCreate(Activity activity, Bundle icicle, PersistableBundle persistentState) Perform calling of an activity's onCreate(Bundle) method. void callActivityOnDestroy(Activity activity) 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, PersistableBundle persistentState) Perform calling of an activity's onPostCreate(Bundle) 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 callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState) Perform calling of an activity's onRestoreInstanceState(Bundle) method. void callActivityOnRestoreInstanceState(Activity activity, Bundle savedInstanceState, PersistableBundle persistentState) Perform calling of an activity's onRestoreInstanceState(Bundle) method. void callActivityOnResume(Activity activity) Perform calling of an activity's onResume() method. void callActivityOnSaveInstanceState(Activity activity, Bundle outState) Perform calling of an activity's onSaveInstanceState(Bundle) method. void callActivityOnSaveInstanceState(Activity activity, Bundle outState, PersistableBundle outPersistentState) Perform calling of an activity's onSaveInstanceState(Bundle) method. void callActivityOnStart(Activity activity) Perform calling of an activity's onStart() method. void callActivityOnStop(Activity activity) Perform calling of an activity's onStop() method. void callActivityOnUserLeaving(Activity activity) Perform calling of an activity's onUserLeaveHint() method. void callApplicationOnCreate(Application app) Perform calling of the application's onCreate() method. boolean checkMonitorHit(Instrumentation.ActivityMonitor monitor, int minHits) Test whether an existing Instrumentation.ActivityMonitor has been hit. void endPerformanceSnapshot() 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. UiAutomation getUiAutomation() Gets the UiAutomation instance. 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(ClassLoader cl, String className, Intent intent) Perform instantiation of the process's Activity object. 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. Application newApplication(ClassLoader cl, String className, Context context) Perform instantiation of the process's Application object. static Application newApplication(Class<?> clazz, 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(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.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
From interface android.test.TestSuiteProvider abstract TestSuite getTestSuite()