MacrobenchmarkScope

class MacrobenchmarkScope

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

Summary

Public constructors
MacrobenchmarkScope(packageName: String, launchWithClearTask: Boolean)

Public functions
Unit

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

Deletes the shader cache for an application.
Unit

Force-stop the process being measured.
Unit
killProcess(useKillAll: Boolean)

This function is deprecated. Use the parameter-less killProcess() API instead
Unit
pressHome(delayDurationMs: Long)

Perform a home button click.
Unit

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

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

Public properties
UiDevice

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

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

ApplicationId / Package name of the app being tested.

Public constructors

MacrobenchmarkScope

Added in 1.1.0
MacrobenchmarkScope(packageName: String, launchWithClearTask: Boolean)

Public functions

dropKernelPageCache

Added in 1.1.0
fun dropKernelPageCache(): Unit

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
fun dropShaderCache(): Unit

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.

killProcess

Added in 1.1.0
fun killProcess(): Unit

Force-stop the process being measured.

killProcess

Added in 1.2.0
Deprecated in 1.3.0
fun killProcess(useKillAll: Boolean = false): Unit

Force-stop the process being measured.

Parameters
useKillAll: Boolean = false

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

pressHome

Added in 1.1.0
fun pressHome(delayDurationMs: Long = 0): Unit

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
fun startActivityAndWait(block: (Intent) -> Unit = {}): Unit

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
block: (Intent) -> Unit = {}

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
fun startActivityAndWait(intent: Intent): Unit

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
intent: Intent

Specifies which app/Activity should be launched.

Public properties

device

Added in 1.1.0
val device: UiDevice

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

iteration

Added in 1.1.0
val iteration: Int?

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.

packageName

Added in 1.1.0
val packageName: String

ApplicationId / Package name of the app being tested.