MonitoringInstrumentation

public class MonitoringInstrumentation
extends ExposedInstrumentationApi

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

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 classes

class MonitoringInstrumentation.ActivityFinisher

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

Inherited constants

Public constructors

MonitoringInstrumentation()

Public methods

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 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.

void interceptActivityUsing(InterceptingActivityFactory interceptingActivityFactory)

Use the given InterceptingActivityFactory to create Activity instance in newActivity(ClassLoader, String, Intent).

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 runOnMainSync(Runnable runnable)

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

Activity startActivitySync(Intent intent)
void useDefaultInterceptingActivityFactory()

Use default mechanism of creating activity instance in newActivity(ClassLoader, String, Intent)

Protected methods

void dumpThreadStateToOutputs(String outputFileName)
String getThreadState()
void installMultidex()
void installOldMultiDex(Class<?> multidexClass)

Perform application MultiDex installation only when instrumentation installation is not available.

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()

void restoreUncaughtExceptionHandler()
final void setJsBridgeClassName(String className)
boolean shouldWaitForActivitiesToComplete()
void specifyDexMakerCacheProperty()
void waitForActivitiesToComplete()

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

Inherited methods

Public constructors

MonitoringInstrumentation

public MonitoringInstrumentation ()

Public methods

callActivityOnCreate

public void callActivityOnCreate (Activity activity, 
                Bundle bundle)

Parameters
activity Activity

bundle Bundle

callActivityOnDestroy

public void callActivityOnDestroy (Activity activity)

Parameters
activity Activity

callActivityOnPause

public void callActivityOnPause (Activity activity)

Parameters
activity Activity

callActivityOnRestart

public void callActivityOnRestart (Activity activity)

Parameters
activity Activity

callActivityOnResume

public void callActivityOnResume (Activity activity)

Parameters
activity Activity

callActivityOnStart

public void callActivityOnStart (Activity activity)

Parameters
activity Activity

callActivityOnStop

public void callActivityOnStop (Activity activity)

Parameters
activity Activity

callApplicationOnCreate

public void callApplicationOnCreate (Application app)

Parameters
app Application

execStartActivities

public void execStartActivities (Context who, 
                IBinder contextThread, 
                IBinder token, 
                Activity target, 
                Intent[] intents, 
                Bundle options)

Parameters
who Context

contextThread IBinder

token IBinder

target Activity

intents Intent

options Bundle

execStartActivity

public Instrumentation.ActivityResult execStartActivity (Context who, 
                IBinder contextThread, 
                IBinder token, 
                Fragment target, 
                Intent intent, 
                int requestCode, 
                Bundle options)

Parameters
who Context

contextThread IBinder

token IBinder

target Fragment

intent Intent

requestCode int

options Bundle

Returns
Instrumentation.ActivityResult

execStartActivity

public Instrumentation.ActivityResult execStartActivity (Context who, 
                IBinder contextThread, 
                IBinder token, 
                Activity target, 
                Intent intent, 
                int requestCode, 
                Bundle options)

Parameters
who Context

contextThread IBinder

token IBinder

target Activity

intent Intent

requestCode int

options Bundle

Returns
Instrumentation.ActivityResult

execStartActivity

public 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)

Parameters
who Context

contextThread IBinder

token IBinder

target Activity

intent Intent

requestCode int

options Bundle

user UserHandle

Returns
Instrumentation.ActivityResult

execStartActivity

public Instrumentation.ActivityResult execStartActivity (Context who, 
                IBinder contextThread, 
                IBinder token, 
                Activity target, 
                Intent intent, 
                int requestCode)

Parameters
who Context

contextThread IBinder

token IBinder

target Activity

intent Intent

requestCode int

Returns
Instrumentation.ActivityResult

execStartActivity

public 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)

Parameters
who Context

contextThread IBinder

token IBinder

target String

intent Intent

requestCode int

options Bundle

Returns
Instrumentation.ActivityResult

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

interceptActivityUsing

public void interceptActivityUsing (InterceptingActivityFactory interceptingActivityFactory)

Use the given InterceptingActivityFactory to create Activity instance in newActivity(ClassLoader, String, Intent). 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(ClassLoader, String, Intent)

newActivity

public Activity newActivity (Class<?> clazz, 
                Context context, 
                IBinder token, 
                Application application, 
                Intent intent, 
                ActivityInfo info, 
                CharSequence title, 
                Activity parent, 
                String id, 
                Object lastNonConfigurationInstance)

Parameters
clazz Class

context Context

token IBinder

application Application

intent Intent

info ActivityInfo

title CharSequence

parent Activity

id String

lastNonConfigurationInstance Object

Returns
Activity

Throws
InstantiationException
IllegalAccessException

newActivity

public Activity newActivity (ClassLoader cl, 
                String className, 
                Intent intent)

Parameters
cl ClassLoader

className String

intent Intent

Returns
Activity

Throws
InstantiationException
IllegalAccessException
ClassNotFoundException

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

onDestroy

public void onDestroy ()

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.

runOnMainSync

public void runOnMainSync (Runnable runnable)

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

public Activity startActivitySync (Intent intent)

Parameters
intent Intent

Returns
Activity

useDefaultInterceptingActivityFactory

public void useDefaultInterceptingActivityFactory ()

Use default mechanism of creating activity instance in newActivity(ClassLoader, String, Intent)

Protected methods

dumpThreadStateToOutputs

protected void dumpThreadStateToOutputs (String outputFileName)

Parameters
outputFileName String

getThreadState

protected String getThreadState ()

Returns
String

installMultidex

protected void installMultidex ()

installOldMultiDex

protected void installOldMultiDex (Class<?> multidexClass)

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

Parameters
multidexClass Class

Throws
NoSuchMethodException
InvocationTargetException
IllegalAccessException

isPrimaryInstrProcess

protected final boolean isPrimaryInstrProcess ()

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 boolean isPrimaryInstrProcess (String argsProcessName)

This method is deprecated.
use isPrimaryInstrProcess()

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 void restoreUncaughtExceptionHandler ()

setJsBridgeClassName

protected final void setJsBridgeClassName (String className)

Parameters
className String

shouldWaitForActivitiesToComplete

protected boolean shouldWaitForActivitiesToComplete ()

Returns
boolean

specifyDexMakerCacheProperty

protected void specifyDexMakerCacheProperty ()

waitForActivitiesToComplete

protected void waitForActivitiesToComplete ()

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.