# MacrobenchmarkScope

Artifact: [androidx.benchmark:benchmark-macro](https://developer.android.com/jetpack/androidx/releases/benchmark) [View Source](https://cs.android.com/search?q=file:androidx/benchmark/macro/MacrobenchmarkScope.kt+class:androidx.benchmark.macro.MacrobenchmarkScope) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.1.0)

*** ** * ** ***


```
public final class MacrobenchmarkScope extends UiAutomatorTestScope
```

<br />

|---|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object.html) |||
| ↳ | [androidx.test.uiautomator.UiAutomatorTestScope](https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope) ||
|   | ↳ | [androidx.benchmark.macro.MacrobenchmarkScope](https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope) |

*** ** * ** ***

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

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#MacrobenchmarkScope(kotlin.String,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName, boolean launchWithClearTask )` |

| ### Public methods |
|---|---|
| `final void` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#dropKernelPageCache()()` Drop Kernel's in-memory cache of disk pages. |
| `final void` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#dropShaderCache()()` Deletes the shader cache for an application. |
| `final https://developer.android.com/reference/java/lang/Integer.html` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#getIteration()()` Current Macrobenchmark measurement iteration, or null if measurement is not yet enabled. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#getPackageName()()` ApplicationId / Package name of the app being tested. |
| `final void` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#killProcess()()` Force-stop the process being measured. |
| `final void` | `[killProcess](https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#killProcess(kotlin.Boolean))(boolean useKillAll)` **This method is deprecated.** Use the parameter-less killProcess() API instead |
| `final void` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#pressHome(kotlin.Long)(long delayDurationMs)` Perform a home button click. |
| `final void` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#startActivityAndWait(kotlin.Function1)(@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block)` Start an activity, by default the launcher activity of the package, and wait until its launch completes. |
| `final void` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#startActivityAndWait(android.content.Intent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html intent)` Start an activity with the provided intent, and wait until its launch completes. |

| ### Protected methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#startIntentAndWait(android.content.Intent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html 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. |

### Inherited methods

From [androidx.test.uiautomator.UiAutomatorTestScope](https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope) `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#activeWindowRoot()()`

Returns the active window root node.
`final void` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#clearAppData()()`

Clears the instrumentation test target app data.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#getDevice()()` `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/app/Instrumentation.html` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#getInstrumentation()()` `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/app/UiAutomation.html` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#getUiAutomation()()` `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)(
long timeoutMs,
long pollIntervalMs,
@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> 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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`.
`final https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)(
long timeoutMs,
long pollIntervalMs,
@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> 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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2>` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)(
long timeoutMs,
long pollIntervalMs,
@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> 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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`.
`final boolean` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressBack()()`

Press the back key.
`final void` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)(int count)`

Similar to `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)` times.
`final boolean` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressEnter()()`

Press the enter key.
`final boolean` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressHome()()`

Press the home key.
`final void` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(java.lang.Class,kotlin.collections.List)(
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Class.html<@https://developer.android.com/reference/androidx/annotation/NonNull ?> clazz,
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags
)`

Starts an activity with the given class.
`final void` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)(
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName,
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html activityName,
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags
)`

Starts an activity with the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)` and `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)`.
`final void` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html intent)`

Starts the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)` for an activity.
`final void` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)(
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName,
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags
)`

Starts the app with the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)`.
`final void` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html text)`

Types the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` string simulating key press through `https://developer.android.com/reference/android/app/Instrumentation.html#sendKeySync(android.view.KeyEvent)`.
`final void` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#unregisterWatchers()()`

Unregisters all the watchers previously registered with `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)`.
`final boolean` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#waitForAppToBeVisible(kotlin.String,kotlin.Long)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html appPackageName, long timeoutMs)`

Waits for an application to become visible.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/StableResult` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#waitForStableInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)(
long stableTimeoutMs,
long stableIntervalMs,
long stablePollIntervalMs,
boolean requireStableScreenshot
)`

Waits for the root node of the active window to become stable.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/watcher/WatcherRegistration` `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)(
@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/watcher/ScopedUiWatcher<@https://developer.android.com/reference/androidx/annotation/NonNull T> watcher,
@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull T, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block
)`

Registers a watcher for this `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope` to handle unexpected UI elements.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html>` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#windowRoots()()`

Returns all the window roots on all the displays.
`final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityWindowInfo.html>` `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#windows()()`

Returns all the windows on all the displays.

## Public constructors

### MacrobenchmarkScope

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.1.0)

```
public MacrobenchmarkScope(
    @NonNull String packageName,
    boolean launchWithClearTask
)
```

## Public methods

### dropKernelPageCache

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/benchmark#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 androidx.benchmark.macro.StartupMode.COLD.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if dropping the cache fails on a API 31+ or rooted device, where it is expected to work. |

### dropShaderCache

Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/benchmark#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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the device is not rooted, and the target app cannot be signalled to drop its shader cache. |

### getIteration

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/benchmark#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 `https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode`, or prior to the first iteration for `https://developer.android.com/reference/androidx/benchmark/macro/StartupMode#WARM` or `https://developer.android.com/reference/androidx/benchmark/macro/StartupMode#HOT`, to create the Process or Activity ahead of time.

### getPackageName

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.1.0)

```
public final @NonNull String getPackageName()
```

ApplicationId / Package name of the app being tested.

### killProcess

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.1.0)

```
public final void killProcess()
```

Force-stop the process being measured.

### killProcess

Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.2.0) Deprecated in [1.3.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.3.0)

```
public final void [killProcess](https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope#killProcess(kotlin.Boolean))(boolean useKillAll)
```

> [!CAUTION]
> **This method is deprecated.**   
> Use the parameter-less killProcess() API instead, use this instead:
>
> ```
> killProcess()
> ```

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](https://developer.android.com/jetpack/androidx/releases/benchmark#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](https://developer.android.com/jetpack/androidx/releases/benchmark#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 `https://developer.android.com/reference/android/os/Parcelable.html` 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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block` | Allows customization of the intent used to launch the activity. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if unable to acquire intent for package. |

### startActivityAndWait

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/benchmark#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 `https://developer.android.com/reference/android/os/Parcelable.html` 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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html 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.