MacrobenchmarkScope

public final class MacrobenchmarkScope extends UiAutomatorTestScope

java.lang.Object
   ↳ 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(
    @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 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.

Protected methods
void

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.

Inherited methods
From androidx.test.uiautomator.UiAutomatorTestScope
final @NonNull AccessibilityNodeInfo

Returns the active window root node.
final void

Clears the instrumentation test target app data.
final @NonNull UiDevice
final @NonNull Instrumentation
final @NonNull UiAutomation
final @NonNull UiObject2
onElement(
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

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.
final UiObject2
onElementOrNull(
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

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.
final @NonNull List<@NonNull UiObject2>
onElements(
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

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

Press the back key.
final void
pressDelete(int count)

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

Press the enter key.
final boolean

Press the home key.
final void
startActivity(
    @NonNull Class<@NonNull ?> clazz,
    @NonNull List<@NonNull Integer> intentFlags
)

Starts an activity with the given class.
final void
startActivity(
    @NonNull String packageName,
    @NonNull String activityName,
    @NonNull List<@NonNull Integer> intentFlags
)

Starts an activity with the given packageName and activityName.
final void

Starts the given intent for an activity.
final void
startApp(
    @NonNull String packageName,
    @NonNull List<@NonNull Integer> intentFlags
)

Starts the app with the given packageName.
final void

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

Unregisters all the watchers previously registered with watchFor.
final boolean
waitForAppToBeVisible(@NonNull String appPackageName, long timeoutMs)

Waits for an application to become visible.
final @NonNull StableResult
waitForStableInActiveWindow(
    long stableTimeoutMs,
    long stableIntervalMs,
    long stablePollIntervalMs,
    boolean requireStableScreenshot
)

Waits for the root node of the active window to become stable.
final @NonNull WatcherRegistration
<T extends Object> watchFor(
    @NonNull ScopedUiWatcher<@NonNull T> watcher,
    @NonNull Function1<@NonNull T, Unit> block
)

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

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

Returns all the windows on all the displays.

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.

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 Intent, Unit> 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 Intent, Unit> 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.

Protected methods

startIntentAndWait

protected void startIntentAndWait(@NonNull Intent intent)

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.