AndroidJUnitRunner

class AndroidJUnitRunner : MonitoringInstrumentation

kotlin.Any
   ↳ android.app.Instrumentation
     ↳ androidx.test.runner.MonitoringInstrumentation
       ↳ androidx.test.runner.AndroidJUnitRunner
Known direct subclasses
AndroidBenchmarkRunner

Instrumentation runner for benchmarks, used to increase stability of measurements and minimize interference.

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

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

Typical Usage

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

In an appropriate AndroidManifest.xml, define an instrumentation with android:name set to androidx.test.runner.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) If -e useTestStorageService is also provided, the testfile will be converted to a relative path and retrieved from TestStorage

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) If -e useTestStorageService is also provided, the testfile will be converted to a relative path and retrieved from TestStorage

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 org.junit.runner.notification.RunListeners to observe the test run: -e listener com.foo.Listener,com.foo.Listener2

To use the new order of org.junit.runner.notification.RunListeners during a test run: -e newRunListenerMode true

New order of listeners guarantee that user defined s 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.

org.junit.runner.notification.RunListener can also be specified via metadata.

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

Deprecated: Set timeout (in milliseconds) that will be applied to each test: -e timeout_msec 5000 -e timeout essentially reuses the deprecated @Test(timeout) functionality. Use junit's Timeout Rule instead.

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 runner. It overrides timeouts specified via . Please note that in JUnit4 timeout annotation will take precedence over both, this flag and org.junit.rules.Timeout rule.

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

If no androidx.test.runner.screenshot.ScreenCaptureProcessor is provided then the androidx.test.runner.screenshot.BasicScreenCaptureProcessor is used. If one or more are provided the 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: 

<instrumentation
   android:name="androidx.test.runner.AndroidJUnitRunner"
   android:targetPackage="com.foo.Bar">
   <meta-data
       android:name="listener"
       android:value="com.foo.Listener,com.foo.Listener2" />
</instrumentation>
 Arguments specified via shell will override manifest specified arguments.

Summary

Public constructors

Public functions
Application!
newApplication(cl: ClassLoader!, className: String!, context: Context!)

Does initialization before creating the application.
Unit
onCreate(arguments: Bundle!)

Sets up lifecycle monitoring, and argument registry.
Boolean
onException(obj: Any!, e: Throwable!)
Unit

This implementation of onStart() will guarantee that the Application's onCreate method has completed when it returns.
Unit
sendStatus(resultCode: Int, results: Bundle!)

Inherited Constants
From android.app.Instrumentation
const String!
const String!

Inherited functions
From android.app.Instrumentation
TestLooperManager!
Unit
Instrumentation.ActivityMonitor!
addMonitor(
    filter: IntentFilter!,
    result: Instrumentation.ActivityResult!,
    block: Boolean
)
Unit
addResults(results: Bundle!)
Unit
callActivityOnCreate(activity: Activity!, icicle: Bundle!)
Unit
Unit
callActivityOnNewIntent(activity: Activity!, intent: Intent!)
Unit
Unit
Unit
callActivityOnPostCreate(activity: Activity!, savedInstanceState: Bundle!)
Unit
Unit
callActivityOnRestoreInstanceState(
    activity: Activity!,
    savedInstanceState: Bundle!
)
Unit
Unit
Unit
Unit
Unit
Unit
Boolean
Unit
Unit
finish(resultCode: Int, results: Bundle!)
Bundle!
Bundle!
ComponentName!
Context!
String!
Context!
UiAutomation!
Boolean
invokeContextMenuAction(targetActivity: Activity!, id: Int, flag: Int)
Boolean
invokeMenuActionSync(targetActivity: Activity!, id: Int, flag: Int)
Boolean
Activity!
newActivity(
    clazz: Class<Any!>!,
    context: Context!,
    token: IBinder!,
    application: Application!,
    intent: Intent!,
    info: ActivityInfo!,
    title: CharSequence!,
    parent: Activity!,
    id: String!,
    lastNonConfigurationInstance: Any!
)
Application!
newApplication(cl: ClassLoader!, className: String!, context: Context!)
Unit
onCreate(arguments: Bundle!)
Unit
Boolean
onException(obj: Any!, e: Throwable!)
Unit
Unit
Unit
Unit
Unit
Unit
Unit
Unit
Unit
Unit
Unit
Unit
Unit
Activity!
Unit

This function is deprecated.
Unit
Unit
Unit

This function is deprecated.
Unit
Unit
waitForIdle(recipient: Runnable!)
Unit
Activity!
Activity!
waitForMonitorWithTimeout(
    monitor: Instrumentation.ActivityMonitor!,
    timeOut: Long
)
From androidx.test.runner.MonitoringInstrumentation
Unit
callActivityOnCreate(activity: Activity!, bundle: Bundle!)
Unit
Unit
Unit
Unit
Unit
Unit
Unit
Unit
dumpThreadStateToOutputs(outputFileName: String!)
Unit
execStartActivities(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Activity!,
    intents: Array<Intent!>!,
    options: Bundle!
)
Instrumentation.ActivityResult!
execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Activity!,
    intent: Intent!,
    requestCode: Int
)
Instrumentation.ActivityResult!
execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Activity!,
    intent: Intent!,
    requestCode: Int,
    options: Bundle!
)
Instrumentation.ActivityResult!
execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Fragment!,
    intent: Intent!,
    requestCode: Int,
    options: Bundle!
)
Instrumentation.ActivityResult!
execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: String!,
    intent: Intent!,
    requestCode: Int,
    options: Bundle!
)

This API was added in Android API 23 (M)
Instrumentation.ActivityResult!
execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Activity!,
    intent: Intent!,
    requestCode: Int,
    options: Bundle!,
    user: UserHandle!
)

This API was added in Android API 17 (JELLY_BEAN_MR1)
Unit
finish(resultCode: Int, results: Bundle!)

Ensures all activities launched in this instrumentation are finished before the instrumentation exits.
String!
Unit
Unit
installOldMultiDex(multidexClass: Class<Any!>!)

Perform application MultiDex installation only when instrumentation installation is not available.
Unit
interceptActivityUsing(
    interceptingActivityFactory: InterceptingActivityFactory!
)

Use the given InterceptingActivityFactory to create Activity instance in newActivity.
Boolean

Checks whether this instance of instrumentation should be considered as a primary instrumentation process.
Boolean
isPrimaryInstrProcess(argsProcessName: String?)

This function is deprecated.

use isPrimaryInstrProcess()
Activity!
newActivity(cl: ClassLoader!, className: String!, intent: Intent!)
Activity!
newActivity(
    clazz: Class<Any!>!,
    context: Context!,
    token: IBinder!,
    application: Application!,
    intent: Intent!,
    info: ActivityInfo!,
    title: CharSequence!,
    parent: Activity!,
    id: String!,
    lastNonConfigurationInstance: Any!
)
Unit
Unit
Unit
runOnMainSync(runnable: Runnable!)

Posts a runnable to the main thread and blocks the caller's thread until the runnable is executed.
Unit
Boolean
Unit
Activity!
Throwable!

Unwraps an exception from certain wrapper types, e.g. RuntimeException.
Unit

Use default mechanism of creating activity instance in newActivity
Unit

Ensures we've onStopped() all activities which were onStarted().

Public constructors

AndroidJUnitRunner

AndroidJUnitRunner()

Public functions

newApplication

fun newApplication(cl: ClassLoader!, className: String!, context: Context!): Application!

Does initialization before creating the application.

Note, newApplication is called before onCreate on API >15. For API <= 15, onCreate is called first.

Throws
java.lang.InstantiationException
java.lang.IllegalAccessException
java.lang.ClassNotFoundException

onCreate

fun onCreate(arguments: Bundle!): Unit

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.

onException

fun onException(obj: Any!, e: Throwable!): Boolean

onStart

fun onStart(): Unit

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.

sendStatus

fun sendStatus(resultCode: Int, results: Bundle!): Unit