Summary: Inherited Constants | Ctors | Methods | Inherited Methods

AndroidJUnitRunner

Kotlin |Java

Note: This library does not have Kotlin reference docs, but you can call the Java API from Kotlin source code. To learn more, see Kotlin's interop documentation.

public class AndroidJUnitRunner
extends MonitoringInstrumentation implements TestEventClientConnectListener

java.lang.Object
↳	android.app.Instrumentation
	↳	androidx.test.internal.runner.hidden.ExposedInstrumentationApi
		↳	androidx.test.runner.MonitoringInstrumentation
			↳	androidx.test.runner.AndroidJUnitRunner

---

An Instrumentation that runs JUnit3 and JUnit4 tests against an Android package (application).

Based on and replacement for InstrumentationTestRunner. Supports a superset of InstrumentationTestRunner features, while maintaining command/output format compatibility with that class.

Typical Usage

Write JUnit3 style TestCases and/or JUnit4 style Tests that perform tests against the classes in your package. Make use of the InstrumentationRegistry if needed.

In an appropriate AndroidManifest.xml, define an instrumentation with android:name set to AndroidJUnitRunner and the appropriate android:targetPackage set.

Execution options:

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

Running all tests in a class: adb shell am instrument -w -e class com.android.foo.FooTest com.android.foo/androidx.test.runner.AndroidJUnitRunner

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

Running all tests in multiple classes: adb shell am instrument -w -e class com.android.foo.FooTest,com.android.foo.TooTest com.android.foo/androidx.test.runner.AndroidJUnitRunner

Running all tests except those in a particular class: adb shell am instrument -w -e notClass com.android.foo.FooTest com.android.foo/androidx.test.runner.AndroidJUnitRunner

Running all but a single test: adb shell am instrument -w -e notClass com.android.foo.FooTest#testFoo com.android.foo/androidx.test.runner.AndroidJUnitRunner

Running all tests listed in a file: adb shell am instrument -w -e testFile /sdcard/tmp/testFile.txt com.android.foo/com.android.test.runner.AndroidJUnitRunner The file should contain a list of line separated package names or test classes and optionally methods. Valid package names consist of one or more java identifiers delimited by the '.' character, in which the first character of the last identifier is not a capitalized letter. Valid class names consist of one or more java identifiers delimited by the '.' character, in which the first character of the last identifier is a capitalized letter. Valid method names are valid class names with a '#' character and an additional java identifier appended to the end. (expected class format: com.android.foo.FooClassName#testMethodName) (expected package format: com.android.foo)

Running all tests not listed in a file: adb shell am instrument -w -e notTestFile /sdcard/tmp/notTestFile.txt com.android.foo/com.android.test.runner.AndroidJUnitRunner The file should contain a list of line separated package names or test classes and optionally methods. Valid package names consist of one or more java identifiers delimited by the '.' character, in which the first character of the last identifier is not a capitalized letter. Valid class names consist of one or more java identifiers delimited by the '.' character, in which the first character of the last identifier is a capitalized letter. Valid method names are valid class names with a '#' character and an additional java identifier appended to the end. (expected class format: com.android.foo.FooClassName#testMethodName) (expected package format: com.android.foo)

Running all tests in a java package: adb shell am instrument -w -e package com.android.foo.bar com.android.foo/androidx.test.runner.AndroidJUnitRunner

Running all tests except a particular package: adb shell am instrument -w -e notPackage com.android.foo.bar com.android.foo/androidx.test.runner.AndroidJUnitRunner

Running all tests matching a given regular expression: adb shell am instrument -w -e tests_regex BarTest.* com.android.foo/androidx.test.runner.AndroidJUnitRunner

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

Running a specific test size i.e. annotated with SmallTest or MediumTest or LargeTest: adb shell am instrument -w -e size [small|medium|large] com.android.foo/androidx.test.runner.AndroidJUnitRunner

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

If used with other options, the resulting test run will contain the intersection 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 with all annotations in a list: adb shell am instrument -w -e annotation com.android.foo.MyAnnotation,com.android.foo.AnotherAnnotation com.android.foo/androidx.test.runner.AndroidJUnitRunner

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

As above, if used with other options, the resulting test run will contain the intersection of the two options. e.g. "-e size large -e notAnnotation com.android.foo.MyAnnotation" will run tests with the LargeTest annotation that do NOT have the "com.android.foo.MyAnnotation" annotations.

Filter test run to tests without any of a list of annotations: adb shell am instrument -w -e notAnnotation com.android.foo.MyAnnotation,com.android.foo.AnotherAnnotation com.android.foo/androidx.test.runner.AndroidJUnitRunner

Filter test run to tests that pass all of a list of custom filter(s): adb shell am instrument -w -e filter com.android.foo.MyCustomFilter,com.android.foo.AnotherCustomFilter com.android.foo/androidx.test.runner.AndroidJUnitRunner

A Filter class provided to the filter option must be public and must provide a public constructor of one of the following patterns. They are searched in order and the first one found is the one that is used.

1. <init>() - a no arguments constructor. This is for filters whose behavior is hard coded.
2. <init>(Bundle bundle - accepts a Bundle that contains the options passed to this instance. This is for filters whose behavior needs to be configured through additional options to am instrument.

Filter test run to a shard of all tests, where numShards is an integer greater than 0 and shardIndex is an integer between 0 (inclusive) and numShards (exclusive): adb shell am instrument -w -e numShards 4 -e shardIndex 1 com.android.foo/androidx.test.runner.AndroidJUnitRunner

Use custom builders to run test classes: adb shell am instrument -w -e runnerBuilder com.android.foo.MyCustomBuilder,com.android.foo.AnotherCustomBuilder com.android.foo/androidx.test.runner.AndroidJUnitRunner

A RunnerBuilder class provided to the runnerBuilder option must be public and must provide a public no-argument constructor.

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 code coverage files (*.ec) that can be used by EMMA or JaCoCo: -e coverage true Note: For this to work, your classes have to be instrumented offline (i.e. at build time) by EMMA/JaCoCo. By default, the code coverage results file will be saved in a /data/data//files/coverage.ec file, unless overridden by coverageFile flag (see below)

To specify EMMA or JaCoCo code coverage results file path: -e coverage true -e coverageFile /sdcard/myFile.ec

To specify one or more RunListeners to observe the test run: -e listener com.foo.Listener,com.foo.Listener2

To use the new order of RunListeners during a test run: -e newRunListenerMode true

New order of listeners guarantee that user defined RunListeners will be running before any of the default listeners defined in this runner. Legacy order had those user defined listeners running after the default ones.

Note:The new order will become the default in the future.

can also be specified via java.util.ServiceLoader metadata.

To specify a custom ClassLoader to load the test class: -e classLoader com.foo.CustomClassLoader

Set timeout (in milliseconds) that will be applied to each test: -e timeout_msec 5000

Supported for both JUnit3 and JUnit4 style tests. For JUnit3 tests, this flag is the only way to specify timeouts. For JUnit4 tests, this flag is only supported when using the the {@link androidx.test.ext.junit.runners.AndroidJUnit4) runner. It overrides timeouts specified via org.junit.rules.Timeout . Please note that in JUnit4 org.junit.Test#timeout() annotation will take precedence over both, this flag and org.junit.rules.Timeout rule.

To disable Google Analytics: -e disableAnalytics true

In order to make sure we are on the right track with each new release, the test runner collects analytics. More specifically, it uploads a hash of the package name of the application under test for each invocation. This allows us to measure both the count of unique packages using this library as well as the volume of usage.

(Beta)To specify a custom {@link androidx.test.runner.screenshot.ScreenCaptureProcessor} to use when processing a {@link androidx.test.runner.screenshot.ScreenCapture} produced by {@link androidx.test.runner.screenshot.Screenshot#capture}: -e screenCaptureProcessors com.foo.Processor,com.foo.Processor2

If no {@link androidx.test.runner.screenshot.ScreenCaptureProcessor} is provided then the {@link androidx.test.runner.screenshot.BasicScreenCaptureProcessor} is used. If one or more are provided the {@link androidx.test.runner.screenshot.BasicScreenCaptureProcessor} is not used unless it is one of the ones provided.

(Beta) To specify a remote static method for the runner to attempt to call reflectively: adb shell am instrument -w -e remoteMethod com.foo.bar#init

Note: The method must be static. Usually used to initiate a remote testing client that depends on the runner (e.g. Espresso).

All arguments can also be specified in the in the AndroidManifest via a meta-data tag:

eg. using listeners:

{@code
 
    
 
 }

Arguments specified via shell will override manifest specified arguments.

Summary

Inherited constants
From class android.app.Instrumentation String REPORT_KEY_IDENTIFIER String REPORT_KEY_STREAMRESULT

Public constructors
AndroidJUnitRunner()

Public methods
void	finish(int resultCode, Bundle results) Ensures all activities launched in this instrumentation are finished before the instrumentation exits.
void	onCreate(Bundle arguments) Sets up lifecycle monitoring, and argument registry.
boolean	onException(Object obj, Throwable e)
void	onStart() This implementation of onStart() will guarantee that the Application's onCreate method has completed when it returns.

Inherited methods
From class androidx.test.runner.MonitoringInstrumentation void callActivityOnCreate(Activity activity, Bundle bundle) void callActivityOnDestroy(Activity activity) void callActivityOnPause(Activity activity) void callActivityOnRestart(Activity activity) void callActivityOnResume(Activity activity) void callActivityOnStart(Activity activity) void callActivityOnStop(Activity activity) void callApplicationOnCreate(Application app) void dumpThreadStateToOutputs(String outputFileName) void execStartActivities(Context who, IBinder contextThread, IBinder token, Activity target, Intent[] intents, Bundle options) Instrumentation.ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Fragment target, Intent intent, int requestCode, Bundle options) Instrumentation.ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Activity target, Intent intent, int requestCode, Bundle options) Instrumentation.ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Activity target, Intent intent, int requestCode, Bundle options, UserHandle user) This API was added in Android API 17 (JELLY_BEAN_MR1) Instrumentation.ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, Activity target, Intent intent, int requestCode) Instrumentation.ActivityResult execStartActivity(Context who, IBinder contextThread, IBinder token, String target, Intent intent, int requestCode, Bundle options) This API was added in Android API 23 (M) void finish(int resultCode, Bundle results) Ensures all activities launched in this instrumentation are finished before the instrumentation exits. String getThreadState() void installMultidex() void installOldMultiDex(Class<?> multidexClass) Perform application MultiDex installation only when instrumentation installation is not available. void interceptActivityUsing(InterceptingActivityFactory interceptingActivityFactory) Use the given InterceptingActivityFactory to create Activity instance in newActivity(ClassLoader, String, Intent). final boolean isPrimaryInstrProcess() Checks whether this instance of instrumentation should be considered as a primary instrumentation process. boolean isPrimaryInstrProcess(String argsProcessName) This method is deprecated. use isPrimaryInstrProcess() Activity newActivity(Class<?> clazz, Context context, IBinder token, Application application, Intent intent, ActivityInfo info, CharSequence title, Activity parent, String id, Object lastNonConfigurationInstance) Activity newActivity(ClassLoader cl, String className, Intent intent) void onCreate(Bundle arguments) Sets up lifecycle monitoring, and argument registry. void onDestroy() boolean onException(Object obj, Throwable e) void onStart() This implementation of onStart() will guarantee that the Application's onCreate method has completed when it returns. void restoreUncaughtExceptionHandler() void runOnMainSync(Runnable runnable) Posts a runnable to the main thread and blocks the caller's thread until the runnable is executed. final void setJsBridgeClassName(String className) boolean shouldWaitForActivitiesToComplete() void specifyDexMakerCacheProperty() Activity startActivitySync(Intent intent) void useDefaultInterceptingActivityFactory() Use default mechanism of creating activity instance in newActivity(ClassLoader, String, Intent) void waitForActivitiesToComplete() Ensures we've onStopped() all activities which were onStarted().
From class androidx.test.internal.runner.hidden.ExposedInstrumentationApi void execStartActivities(Context arg0, IBinder arg1, IBinder arg2, Activity arg3, Intent[] arg4, Bundle arg5) Instrumentation.ActivityResult execStartActivity(Context arg0, IBinder arg1, IBinder arg2, Activity arg3, Intent arg4, int arg5) Instrumentation.ActivityResult execStartActivity(Context arg0, IBinder arg1, IBinder arg2, Fragment arg3, Intent arg4, int arg5, Bundle arg6) Instrumentation.ActivityResult execStartActivity(Context arg0, IBinder arg1, IBinder arg2, String arg3, Intent arg4, int arg5, Bundle arg6) Instrumentation.ActivityResult execStartActivity(Context arg0, IBinder arg1, IBinder arg2, Activity arg3, Intent arg4, int arg5, Bundle arg6) Instrumentation.ActivityResult execStartActivity(Context arg0, IBinder arg1, IBinder arg2, Activity arg3, Intent arg4, int arg5, Bundle arg6, UserHandle arg7)
From class android.app.Instrumentation TestLooperManager acquireLooperManager(Looper arg0) Instrumentation.ActivityMonitor addMonitor(String arg0, Instrumentation.ActivityResult arg1, boolean arg2) Instrumentation.ActivityMonitor addMonitor(IntentFilter arg0, Instrumentation.ActivityResult arg1, boolean arg2) void addMonitor(Instrumentation.ActivityMonitor arg0) void addResults(Bundle arg0) void callActivityOnCreate(Activity arg0, Bundle arg1) void callActivityOnCreate(Activity arg0, Bundle arg1, PersistableBundle arg2) void callActivityOnDestroy(Activity arg0) void callActivityOnNewIntent(Activity arg0, Intent arg1) void callActivityOnPause(Activity arg0) void callActivityOnPictureInPictureRequested(Activity arg0) void callActivityOnPostCreate(Activity arg0, Bundle arg1, PersistableBundle arg2) void callActivityOnPostCreate(Activity arg0, Bundle arg1) void callActivityOnRestart(Activity arg0) void callActivityOnRestoreInstanceState(Activity arg0, Bundle arg1) void callActivityOnRestoreInstanceState(Activity arg0, Bundle arg1, PersistableBundle arg2) void callActivityOnResume(Activity arg0) void callActivityOnSaveInstanceState(Activity arg0, Bundle arg1, PersistableBundle arg2) void callActivityOnSaveInstanceState(Activity arg0, Bundle arg1) void callActivityOnStart(Activity arg0) void callActivityOnStop(Activity arg0) void callActivityOnUserLeaving(Activity arg0) void callApplicationOnCreate(Application arg0) boolean checkMonitorHit(Instrumentation.ActivityMonitor arg0, int arg1) void endPerformanceSnapshot() void finish(int arg0, Bundle arg1) Bundle getAllocCounts() Bundle getBinderCounts() ComponentName getComponentName() Context getContext() String getProcessName() Context getTargetContext() UiAutomation getUiAutomation(int arg0) UiAutomation getUiAutomation() boolean invokeContextMenuAction(Activity arg0, int arg1, int arg2) boolean invokeMenuActionSync(Activity arg0, int arg1, int arg2) boolean isProfiling() Activity newActivity(Class<?> arg0, Context arg1, IBinder arg2, Application arg3, Intent arg4, ActivityInfo arg5, CharSequence arg6, Activity arg7, String arg8, Object arg9) Activity newActivity(ClassLoader arg0, String arg1, Intent arg2) Application newApplication(ClassLoader arg0, String arg1, Context arg2) static Application newApplication(Class<?> arg0, Context arg1) void onCreate(Bundle arg0) void onDestroy() boolean onException(Object arg0, Throwable arg1) void onStart() void removeMonitor(Instrumentation.ActivityMonitor arg0) void runOnMainSync(Runnable arg0) void sendCharacterSync(int arg0) void sendKeyDownUpSync(int arg0) void sendKeySync(KeyEvent arg0) void sendPointerSync(MotionEvent arg0) void sendStatus(int arg0, Bundle arg1) void sendStringSync(String arg0) void sendTrackballEventSync(MotionEvent arg0) void setAutomaticPerformanceSnapshots() void setInTouchMode(boolean arg0) void start() Activity startActivitySync(Intent arg0, Bundle arg1) Activity startActivitySync(Intent arg0) void startAllocCounting() void startPerformanceSnapshot() void startProfiling() void stopAllocCounting() void stopProfiling() void waitForIdle(Runnable arg0) void waitForIdleSync() Activity waitForMonitor(Instrumentation.ActivityMonitor arg0) Activity waitForMonitorWithTimeout(Instrumentation.ActivityMonitor arg0, long arg1)
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait(long arg0, int arg1) final void wait(long arg0) final void wait()
From interface androidx.test.internal.events.client.TestEventClientConnectListener abstract void onTestEventClientConnect() Called from the connection's ServiceConnection.onServiceConnected(ComponentName, IBinder) implementation to indicate that the async ERROR(/#connect(Context)) operation has finished.

Public constructors

AndroidJUnitRunner

public AndroidJUnitRunner ()

Public methods

finish

public void finish (int resultCode, 
                Bundle results)

Ensures all activities launched in this instrumentation are finished before the instrumentation exits.

Subclasses who override this method should do their finish processing and then call super.finish to invoke this logic. Not waiting for all activities to finish() before exiting can cause device wide instability.

Parameters
resultCode	int
results	Bundle

onCreate

public void onCreate (Bundle arguments)

Sets up lifecycle monitoring, and argument registry.

Subclasses must call up to onCreate(). This onCreate method does not call start() it is the subclasses responsibility to call start if it desires.

Parameters
arguments	Bundle

onException

public boolean onException (Object obj, 
                Throwable e)

Parameters
obj	Object
e	Throwable

Returns
boolean

onStart

public void onStart ()

This implementation of onStart() will guarantee that the Application's onCreate method has completed when it returns.

Subclasses should call super.onStart() before executing any code that touches the application and it's state.