MacrobenchmarkScope

class MacrobenchmarkScope : UiAutomatorTestScope

kotlin.Any
   ↳ androidx.test.uiautomator.UiAutomatorTestScope
     ↳ androidx.benchmark.macro.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.

Protected functions
open Unit

When launching activities through UiAutomator APIs, perform a full startActivityAndWait, which includes Macrobenchmark's custom wait-for-frames logic which would be hard to reproduce/implement in UiAutomator.

Public properties
Int?

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

ApplicationId / Package name of the app being tested.

Inherited functions
From androidx.test.uiautomator.UiAutomatorTestScope
AccessibilityNodeInfo

Returns the active window root node.
Unit

Clears the instrumentation test target app data.
UiObject2
onElement(timeoutMs: Long, pollIntervalMs: Long, block: AccessibilityNodeInfo.() -> Boolean)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block.
UiObject2?
onElementOrNull(timeoutMs: Long, pollIntervalMs: Long, block: AccessibilityNodeInfo.() -> Boolean)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block.
List<UiObject2>
onElements(timeoutMs: Long, pollIntervalMs: Long, block: AccessibilityNodeInfo.() -> Boolean)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block.
Boolean

Press the back key.
Unit
pressDelete(count: Int)

Similar to type but presses the delete key for the given count times.
Boolean

Press the enter key.
Boolean

Press the home key.
Unit
startActivity(clazz: Class<*>, intentFlags: List<Int>)

Starts an activity with the given class.
Unit
startActivity(
    packageName: String,
    activityName: String,
    intentFlags: List<Int>
)

Starts an activity with the given packageName and activityName.
Unit

Starts the given intent for an activity.
Unit
startApp(packageName: String, intentFlags: List<Int>)

Starts the app with the given packageName.
Unit
type(text: String)

Types the given text string simulating key press through Instrumentation.sendKeySync.
Unit

Unregisters all the watchers previously registered with watchFor.
Boolean
waitForAppToBeVisible(appPackageName: String, timeoutMs: Long)

Waits for an application to become visible.
StableResult
waitForStableInActiveWindow(
    stableTimeoutMs: Long,
    stableIntervalMs: Long,
    stablePollIntervalMs: Long,
    requireStableScreenshot: Boolean
)

Waits for the root node of the active window to become stable.
WatcherRegistration
<T : Any?> watchFor(watcher: ScopedUiWatcher<T>, block: T.() -> Unit)

Registers a watcher for this androidx.test.uiautomator.UiAutomatorTestScope to handle unexpected UI elements.
List<AccessibilityNodeInfo>

Returns all the window roots on all the displays.
List<AccessibilityWindowInfo>

Returns all the windows on all the displays.

Inherited properties
From androidx.test.uiautomator.UiAutomatorTestScope
UiDevice
Instrumentation
UiAutomation

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.

Protected functions

startIntentAndWait

protected open fun startIntentAndWait(intent: Intent): Unit

When launching activities through UiAutomator APIs, perform a full startActivityAndWait, which includes Macrobenchmark's custom wait-for-frames logic which would be hard to reproduce/implement in UiAutomator.

Public properties

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.