AndroidJUnitRunner
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 TestCase
s and/or JUnit4 style Test
s 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.
<init>()
- a no arguments constructor. This is for filters whose behavior is hard coded.<init>(Bundle bundle
- accepts aBundle
that contains the options passed to this instance. This is for filters whose behavior needs to be configured through additional options toam 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/ To specify EMMA or JaCoCo code coverage results file path: -e coverage true -e
coverageFile /sdcard/myFile.ec
To specify one or more To use the new order of New order of listeners guarantee that user defined Note:The new order will become the default in the future.
To specify a custom 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 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:
Ensures all activities launched in this instrumentation are finished before the instrumentation
exits.
Sets up lifecycle monitoring, and argument registry.
This implementation of onStart() will guarantee that the Application's onCreate method has
completed when it returns.
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.
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.
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.
RunListener
s to observe the test run: -e listener
com.foo.Listener,com.foo.Listener2
RunListener
s during a test run: -e newRunListenerMode true
RunListener
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.
can also be specified via java.util.ServiceLoader metadata.
ClassLoader
to load the test class: -e
classLoader com.foo.CustomClassLoader
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.
{@code
Arguments specified via shell will override manifest specified arguments.
Summary
Inherited constants
Public constructors
AndroidJUnitRunner()
Public methods
void
finish(int resultCode, Bundle results)
void
onCreate(Bundle arguments)
boolean
onException(Object obj, Throwable e)
void
onStart()
Inherited methods
Public constructors
AndroidJUnitRunner
public AndroidJUnitRunner ()
Public methods
finish
public void finish (int resultCode,
Bundle results)
Parameters
resultCode
int
results
Bundle
onCreate
public void onCreate (Bundle arguments)
Parameters
arguments
Bundle
onException
public boolean onException (Object obj,
Throwable e)
Parameters
obj
Object
e
Throwable
Returns
boolean
onStart
public void onStart ()