MonitoringInstrumentation

Artifact: androidx.test:monitor

View Source

---

Kotlin |Java

public class MonitoringInstrumentation extends Instrumentation

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

Known direct subclasses

AndroidJUnitRunner

AndroidJUnitRunner

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

Known indirect subclasses

AndroidBenchmarkRunner

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
public inner class MonitoringInstrumentation.ActivityFinisher implements Runnable Loops through all the activities that have not yet finished and explicitly calls finish on them.

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,     Activity target,     Intent intent,     int requestCode )
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,     Fragment target,     Intent intent,     int requestCode,     Bundle options )
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)
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)
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.
Activity	newActivity(ClassLoader cl, String className, Intent intent)
Activity	newActivity(     Class<Object> clazz,     Context context,     IBinder token,     Application application,     Intent intent,     ActivityInfo info,     CharSequence title,     Activity parent,     String id,     Object lastNonConfigurationInstance )
Application	newApplication(ClassLoader cl, String className, Context context) Does initialization before creating the application.
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

Protected methods
void	dumpThreadStateToOutputs(String outputFileName)
String	getThreadState()
void	installMultidex()
void	installOldMultiDex(Class<Object> 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(@Nullable String argsProcessName) This method is deprecated. use isPrimaryInstrProcess()
void	restoreUncaughtExceptionHandler()
final void	setJsBridgeClassName(String className)
boolean	shouldWaitForActivitiesToComplete()
void	specifyDexMakerCacheProperty()
Throwable	unwrapException(Throwable t) Unwraps an exception from certain wrapper types, e.g. RuntimeException.
void	waitForActivitiesToComplete() Ensures we've onStopped() all activities which were onStarted().

Inherited Constants
From android.app.Instrumentation static final String REPORT_KEY_IDENTIFIER = "id" static final String REPORT_KEY_STREAMRESULT = "stream"

Inherited methods

From android.app.Instrumentation TestLooperManager acquireLooperManager(Looper looper) void addMonitor(Instrumentation.ActivityMonitor monitor) Instrumentation.ActivityMonitor addMonitor(     IntentFilter filter,     Instrumentation.ActivityResult result,     boolean block ) void addResults(Bundle results) void callActivityOnNewIntent(Activity activity, Intent intent) void callActivityOnPictureInPictureRequested(Activity activity) void callActivityOnPostCreate(Activity activity, Bundle savedInstanceState) void callActivityOnRestoreInstanceState(     Activity activity,     Bundle savedInstanceState ) void callActivityOnSaveInstanceState(Activity activity, Bundle outState) void callActivityOnUserLeaving(Activity activity) boolean checkMonitorHit(Instrumentation.ActivityMonitor monitor, int minHits) void endPerformanceSnapshot() Bundle getAllocCounts() Bundle getBinderCounts() ComponentName getComponentName() Context getContext() String getProcessName() Context getTargetContext() UiAutomation getUiAutomation() boolean invokeContextMenuAction(Activity targetActivity, int id, int flag) boolean invokeMenuActionSync(Activity targetActivity, int id, int flag) boolean isProfiling() void removeMonitor(Instrumentation.ActivityMonitor monitor) void resetInTouchMode() void sendCharacterSync(int keyCode) void sendKeyDownUpSync(int keyCode) void sendKeySync(KeyEvent event) void sendPointerSync(MotionEvent event) void sendStatus(int resultCode, Bundle results) void sendStringSync(String text) void sendTrackballEventSync(MotionEvent event) void setAutomaticPerformanceSnapshots() void setInTouchMode(boolean inTouch) void start() void startAllocCounting() This method is deprecated. void startPerformanceSnapshot() void startProfiling() void stopAllocCounting() This method is deprecated. void stopProfiling() void waitForIdle(Runnable recipient) void waitForIdleSync() Activity waitForMonitor(Instrumentation.ActivityMonitor monitor) Activity waitForMonitorWithTimeout(     Instrumentation.ActivityMonitor monitor,     long timeOut )

Public constructors

MonitoringInstrumentation

public MonitoringInstrumentation()

Public methods

callActivityOnCreate

public void callActivityOnCreate(Activity activity, Bundle bundle)

callActivityOnDestroy

public void callActivityOnDestroy(Activity activity)

callActivityOnPause

public void callActivityOnPause(Activity activity)

callActivityOnRestart

public void callActivityOnRestart(Activity activity)

callActivityOnResume

public void callActivityOnResume(Activity activity)

callActivityOnStart

public void callActivityOnStart(Activity activity)

callActivityOnStop

public void callActivityOnStop(Activity activity)

callApplicationOnCreate

public void callApplicationOnCreate(Application app)

execStartActivities

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

execStartActivity

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

execStartActivity

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

execStartActivity

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

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)

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)

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.

interceptActivityUsing

public void interceptActivityUsing(
    InterceptingActivityFactory interceptingActivityFactory
)

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

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

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

newActivity

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

Throws
java.lang.InstantiationException
java.lang.IllegalAccessException

newApplication

public Application newApplication(ClassLoader cl, String className, Context context)

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

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.

onDestroy

public void onDestroy()

onException

public boolean onException(Object obj, Throwable e)

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)

useDefaultInterceptingActivityFactory

public void useDefaultInterceptingActivityFactory()

Use default mechanism of creating activity instance in newActivity

Protected methods

dumpThreadStateToOutputs

protected void dumpThreadStateToOutputs(String outputFileName)

getThreadState

protected String getThreadState()

installMultidex

protected void installMultidex()

installOldMultiDex

protected void installOldMultiDex(Class<Object> multidexClass)

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 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(@Nullable 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
@Nullable String argsProcessName	unused.

Returns
boolean	true if the given process is the primary instrumentation process

restoreUncaughtExceptionHandler

protected void restoreUncaughtExceptionHandler()

setJsBridgeClassName

protected final void setJsBridgeClassName(String className)

shouldWaitForActivitiesToComplete

protected boolean shouldWaitForActivitiesToComplete()

specifyDexMakerCacheProperty

protected void specifyDexMakerCacheProperty()

unwrapException

protected Throwable unwrapException(Throwable t)

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