AndroidJUnitRunner
public
class
AndroidJUnitRunner
extends
MonitoringInstrumentation
implements
OrchestratedInstrumentationListener.OnConnectListener
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/android.support.test.runner.AndroidJUnitRunner
Running all tests in a class:
adb shell am instrument -w -e class
com.android.foo.FooTest com.android.foo/android.support.test.runner.AndroidJUnitRunner
Running a single test:
adb shell am instrument -w -e class
com.android.foo.FooTest#testFoo com.android.foo/android.support.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/android.support.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/android.support.test.runner.AndroidJUnitRunner
Running all but a single test:
adb shell am instrument -w -e notClass
com.android.foo.FooTest#testFoo com.android.foo/android.support.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/android.support.test.runner.AndroidJUnitRunner
Running all tests except a particular package:
adb shell am instrument -w -e notPackage
com.android.foo.bar com.android.foo/android.support.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/android.support.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/android.support.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
without
given annotation:
adb shell am instrument -w -e
notAnnotation com.android.foo.MyAnnotation
com.android.foo/android.support.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/android.support.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/android.support.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 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/android.support.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/android.support.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
RunListener
s to observe the test run:
-e listener
com.foo.Listener,com.foo.Listener2
To use the new order of
RunListener
s during a test run:
-e newRunListenerMode true
New order of listeners guarantee that user defined
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.
Note:
The new order will become the default in the future.
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 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
ScreenCaptureProcessor
to use when processing a
ScreenCapture
produced by
capture()
: -e screenCaptureProcessors
com.foo.Processor,com.foo.Processor2
If no
ScreenCaptureProcessor
is provided then
the
BasicScreenCaptureProcessor
is used. If one or
more are provided the
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="android.support.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
Inherited constants
|
From
class
android.app.Instrumentation
|
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
android.support.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)
.
|
boolean
|
isPrimaryInstrProcess
(
String
argsProcessName)
Checks whether this instance of instrumentation should be considered as a primary
instrumentation process.
|
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.
|
final
void
|
setJsBridgeClassName
(
String
className)
|
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
android.support.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
|
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
android.support.test.orchestrator.instrumentationlistener.OrchestratedInstrumentationListener.OnConnectListener
abstract
void
|
onOrchestratorConnect()
|
|
Public constructors
AndroidJUnitRunner
AndroidJUnitRunner ()
Public methods
finish
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
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
boolean onException (
Object
obj,
Throwable
e)
Parameters
|
obj
|
Object
|
e
|
Throwable
|
onStart
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.