MonitoringInstrumentation

class MonitoringInstrumentation : Instrumentation

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

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

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

An instrumentation that enables several advanced features and makes some hard guarantees about the state of the application under instrumentation.

A short list of these capabilities:

  • Forces Application.onCreate() to happen before Instrumentation.onStart() runs (ensuring your code always runs in a sane state).
  • Logs application death due to exceptions.
  • Allows tracking of activity lifecycle states.
  • Registers instrumentation arguments in an easy to access place.
  • Ensures your activities are creating themselves in reasonable amounts of time.
  • Provides facilities to dump current app threads to test outputs.
  • Ensures all activities finish before instrumentation exits.
This Instrumentation is *NOT* a test instrumentation (some of its subclasses are). It makes no assumptions about what the subclass wants to do.

Summary

Nested types

Loops through all the activities that have not yet finished and explicitly calls finish on them.

Public constructors

Public functions
Unit
callActivityOnCreate(activity: Activity!, bundle: Bundle!)
Unit
Unit
Unit
Unit
Unit
Unit
Unit
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.
Unit
interceptActivityUsing(
    interceptingActivityFactory: InterceptingActivityFactory!
)

Use the given InterceptingActivityFactory to create Activity instance in newActivity.
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!
)
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.
Unit
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
runOnMainSync(runnable: Runnable!)

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

Use default mechanism of creating activity instance in newActivity

Protected functions
Unit
dumpThreadStateToOutputs(outputFileName: String!)
String!
Unit
Unit
installOldMultiDex(multidexClass: Class<Any!>!)

Perform application MultiDex installation only when instrumentation installation is not available.
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()
Unit
Unit
Boolean
Unit
Throwable!

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

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

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
callActivityOnNewIntent(activity: Activity!, intent: Intent!)
Unit
Unit
callActivityOnPostCreate(activity: Activity!, savedInstanceState: Bundle!)
Unit
callActivityOnRestoreInstanceState(
    activity: Activity!,
    savedInstanceState: Bundle!
)
Unit
Unit
Boolean
Unit
Bundle!
Bundle!
ComponentName!
Context!
String!
Context!
UiAutomation!
Boolean
invokeContextMenuAction(targetActivity: Activity!, id: Int, flag: Int)
Boolean
invokeMenuActionSync(targetActivity: Activity!, id: Int, flag: Int)
Boolean
java-static Application!
newApplication(clazz: Class<Any!>!, context: Context!)
Unit
Unit
Unit
Unit
Unit
Unit
Unit
sendStatus(resultCode: Int, results: Bundle!)
Unit
Unit
Unit
Unit
Unit
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
)

Public constructors

MonitoringInstrumentation

MonitoringInstrumentation()

Public functions

callActivityOnCreate

fun callActivityOnCreate(activity: Activity!, bundle: Bundle!): Unit

callActivityOnDestroy

fun callActivityOnDestroy(activity: Activity!): Unit

callActivityOnPause

fun callActivityOnPause(activity: Activity!): Unit

callActivityOnRestart

fun callActivityOnRestart(activity: Activity!): Unit

callActivityOnResume

fun callActivityOnResume(activity: Activity!): Unit

callActivityOnStart

fun callActivityOnStart(activity: Activity!): Unit

callActivityOnStop

fun callActivityOnStop(activity: Activity!): Unit

callApplicationOnCreate

fun callApplicationOnCreate(app: Application!): Unit

execStartActivities

fun execStartActivities(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Activity!,
    intents: Array<Intent!>!,
    options: Bundle!
): Unit

execStartActivity

fun execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Activity!,
    intent: Intent!,
    requestCode: Int
): Instrumentation.ActivityResult!

execStartActivity

fun execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Activity!,
    intent: Intent!,
    requestCode: Int,
    options: Bundle!
): Instrumentation.ActivityResult!

execStartActivity

fun execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Fragment!,
    intent: Intent!,
    requestCode: Int,
    options: Bundle!
): Instrumentation.ActivityResult!

execStartActivity

fun execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: String!,
    intent: Intent!,
    requestCode: Int,
    options: Bundle!
): Instrumentation.ActivityResult!

This API was added in Android API 23 (M)

execStartActivity

fun execStartActivity(
    who: Context!,
    contextThread: IBinder!,
    token: IBinder!,
    target: Activity!,
    intent: Intent!,
    requestCode: Int,
    options: Bundle!,
    user: UserHandle!
): Instrumentation.ActivityResult!

This API was added in Android API 17 (JELLY_BEAN_MR1)

finish

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

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.

interceptActivityUsing

fun interceptActivityUsing(
    interceptingActivityFactory: InterceptingActivityFactory!
): Unit

Use the given InterceptingActivityFactory to create Activity instance in newActivity. This can be used to override default behavior of activity in tests e.g. mocking startService() method in Activity under test, to avoid starting the real service and instead verifying that a particular service was started.

Parameters
interceptingActivityFactory: InterceptingActivityFactory!

InterceptingActivityFactory to be used for creating activity instance in newActivity

newActivity

fun newActivity(cl: ClassLoader!, className: String!, intent: Intent!): Activity!
Throws
java.lang.InstantiationException
java.lang.IllegalAccessException
java.lang.ClassNotFoundException

newActivity

fun newActivity(
    clazz: Class<Any!>!,
    context: Context!,
    token: IBinder!,
    application: Application!,
    intent: Intent!,
    info: ActivityInfo!,
    title: CharSequence!,
    parent: Activity!,
    id: String!,
    lastNonConfigurationInstance: Any!
): Activity!
Throws
java.lang.InstantiationException
java.lang.IllegalAccessException

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.

onDestroy

fun onDestroy(): Unit

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.

runOnMainSync

fun runOnMainSync(runnable: Runnable!): Unit

Posts a runnable to the main thread and blocks the caller's thread until the runnable is executed. When a Throwable is thrown in the runnable, the exception is propagated back to the caller's thread. If it is an unchecked throwable, it will be rethrown as is. If it is a checked exception, it will be rethrown as a RuntimeException.

Parameters
runnable: Runnable!

a runnable to be executed on the main thread

startActivitySync

fun startActivitySync(intent: Intent!): Activity!

useDefaultInterceptingActivityFactory

fun useDefaultInterceptingActivityFactory(): Unit

Use default mechanism of creating activity instance in newActivity

Protected functions

dumpThreadStateToOutputs

protected fun dumpThreadStateToOutputs(outputFileName: String!): Unit

getThreadState

protected fun getThreadState(): String!

installMultidex

protected fun installMultidex(): Unit

installOldMultiDex

protected fun installOldMultiDex(multidexClass: Class<Any!>!): Unit

Perform application MultiDex installation only when instrumentation installation is not available. Called when MultiDex class is available but MultiDex.installInstrumentation is not.

Throws
java.lang.NoSuchMethodException
java.lang.reflect.InvocationTargetException
java.lang.IllegalAccessException

isPrimaryInstrProcess

protected fun isPrimaryInstrProcess(): Boolean

Checks whether this instance of instrumentation should be considered as a primary instrumentation process.

Prior to API 26, instrumentation could only run in a single process and that would be the primary process. Post API 26, the primary process is the first process listed in android:targetProcesses or the default process of the targetPackage.

Returns
Boolean

true if the given process is the primary instrumentation process

isPrimaryInstrProcess

protected fun isPrimaryInstrProcess(argsProcessName: String?): Boolean

Checks whether this instance of instrumentation should be considered as a primary instrumentation process.

Prior to API 26, instrumentation could only run in a single process and that would be the primary process. Post API 26, the primary process is the first process listed in android:targetProcesses or the default process of the targetPackage.

Parameters
argsProcessName: String?

unused.
Returns
Boolean

true if the given process is the primary instrumentation process

restoreUncaughtExceptionHandler

protected fun restoreUncaughtExceptionHandler(): Unit

setJsBridgeClassName

protected fun setJsBridgeClassName(className: String!): Unit

shouldWaitForActivitiesToComplete

protected fun shouldWaitForActivitiesToComplete(): Boolean

specifyDexMakerCacheProperty

protected fun specifyDexMakerCacheProperty(): Unit

unwrapException

protected fun unwrapException(t: Throwable!): Throwable!

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

We consider two exceptions the same if they are caused by the same root cause. For example, when an exception occurs on the main thread, the #onException method is first called to handle it, and the exception is wrapped with RuntimeException and re-thrown, which is then caught by the uncaught exception handler. In this case, the exception should only be handled once.

Returns
Throwable!

the root cause of the given exception

waitForActivitiesToComplete

protected fun waitForActivitiesToComplete(): Unit

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

According to Activity's contract, the process is not killable between onStart and onStop. Breaking this contract (which finish() will if you let it) can cause bad behaviour (including a full restart of system_server).

We give the app 2 seconds to stop all its activities, then we proceed.

This should never be run on the main thread.