MacrobenchmarkScope


public final class MacrobenchmarkScope


Provides access to common operations in app automation, such as killing the app, or navigating home.

Summary

Public constructors

MacrobenchmarkScope(
    @NonNull String packageName,
    boolean launchWithClearTask
)

Public methods

final void

Drop Kernel's in-memory cache of disk pages.

final void

Deletes the shader cache for an application.

final @NonNull UiDevice

Get the UiDevice instance, to use in reading target app UI state, or interacting with the UI via touches, scrolls, or other inputs.

final Integer

Current Macrobenchmark measurement iteration, or null if measurement is not yet enabled.

final @NonNull String

ApplicationId / Package name of the app being tested.

final void

Force-stop the process being measured.

final void
killProcess(boolean useKillAll)

This method is deprecated. Use the parameter-less killProcess() API instead

final void
pressHome(long delayDurationMs)

Perform a home button click.

final void

Start an activity, by default the launcher activity of the package, and wait until its launch completes.

final void

Start an activity with the provided intent, and wait until its launch completes.

Public constructors

MacrobenchmarkScope

Added in 1.1.0
public MacrobenchmarkScope(
    @NonNull String packageName,
    boolean launchWithClearTask
)

Public methods

dropKernelPageCache

Added in 1.1.0
public final void dropKernelPageCache()

Drop Kernel's in-memory cache of disk pages.

Enables measuring disk-based startup cost, without simply accessing cache of disk data held in memory, such as during cold startup.

Throws
kotlin.IllegalStateException

if dropping the cache fails on a API 31+ or rooted device, where it is expected to work.

dropShaderCache

Added in 1.2.0
public final void dropShaderCache()

Deletes the shader cache for an application.

Used by measureRepeated(startupMode = StartupMode.COLD) to remove compiled shaders for each measurement, to ensure their cost is captured each time.

Requires profileinstaller 1.3.0-alpha02 to be used by the target, or a rooted device.

Throws
kotlin.IllegalStateException

if the device is not rooted, and the target app cannot be signalled to drop its shader cache.

getDevice

Added in 1.1.0
public final @NonNull UiDevice getDevice()

Get the UiDevice instance, to use in reading target app UI state, or interacting with the UI via touches, scrolls, or other inputs.

Convenience for UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())

getIteration

Added in 1.1.0
public final Integer getIteration()

Current Macrobenchmark measurement iteration, or null if measurement is not yet enabled.

Non-measurement iterations can occur due to warmup a CompilationMode, or prior to the first iteration for StartupMode.WARM or StartupMode.HOT, to create the Process or Activity ahead of time.

getPackageName

Added in 1.1.0
public final @NonNull String getPackageName()

ApplicationId / Package name of the app being tested.

killProcess

Added in 1.1.0
public final void killProcess()

Force-stop the process being measured.

killProcess

Added in 1.2.0
Deprecated in 1.3.0
public final void killProcess(boolean useKillAll)

Force-stop the process being measured.

Parameters
boolean useKillAll

should be set to true for System apps or pre-installed apps.

pressHome

Added in 1.1.0
public final void pressHome(long delayDurationMs)

Perform a home button click.

Useful for resetting the test to a base condition in cases where the app isn't killed in each iteration.

startActivityAndWait

Added in 1.1.0
public final void startActivityAndWait(@NonNull Function1<@NonNull IntentUnit> block)

Start an activity, by default the launcher activity of the package, and wait until its launch completes.

This call supports primitive extras on the intent, but will ignore any android.os.Parcelable extras, as the start is performed by converting the Intent to a URI, and starting via the am start shell command. Note that from api 33 the launch intent needs to have category android.intent.category.LAUNCHER.

Parameters
@NonNull Function1<@NonNull IntentUnit> block

Allows customization of the intent used to launch the activity.

Throws
kotlin.IllegalStateException

if unable to acquire intent for package.

startActivityAndWait

Added in 1.1.0
public final void startActivityAndWait(@NonNull Intent intent)

Start an activity with the provided intent, and wait until its launch completes.

This call supports primitive extras on the intent, but will ignore any android.os.Parcelable extras, as the start is performed by converting the Intent to a URI, and starting via the am start shell command. Note that from api 33 the launch intent needs to have category android.intent.category.LAUNCHER.

Parameters
@NonNull Intent intent

Specifies which app/Activity should be launched.