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

*** ** * ** ***


```
class MacrobenchmarkScope : UiAutomatorTestScope
```

<br />

|---|---|---|
| [kotlin.Any](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html) |||
| ↳ | [androidx.test.uiautomator.UiAutomatorTestScope](https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope) ||
|   | ↳ | [androidx.benchmark.macro.MacrobenchmarkScope](https://developer.android.com/reference/kotlin/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/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#MacrobenchmarkScope(kotlin.String,kotlin.Boolean)(packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, launchWithClearTask: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#dropKernelPageCache()()` Drop Kernel's in-memory cache of disk pages. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#dropShaderCache()()` Deletes the shader cache for an application. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#killProcess()()` Force-stop the process being measured. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `[killProcess](https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#killProcess(kotlin.Boolean))(useKillAll: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` **This function is deprecated.** Use the parameter-less killProcess() API instead |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#pressHome(kotlin.Long)(delayDurationMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)` Perform a home button click. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#startActivityAndWait(kotlin.Function1)(block: (https://developer.android.com/reference/android/content/Intent.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Start an activity, by default the launcher activity of the package, and wait until its launch completes. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#startActivityAndWait(android.content.Intent)(intent: https://developer.android.com/reference/android/content/Intent.html)` Start an activity with the provided intent, and wait until its launch completes. |

| ### Protected functions |
|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#startIntentAndWait(android.content.Intent)(intent: https://developer.android.com/reference/android/content/Intent.html)` 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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html?` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#iteration()` Current Macrobenchmark measurement iteration, or null if measurement is not yet enabled. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#packageName()` ApplicationId / Package name of the app being tested. |

### Inherited functions

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

Returns the active window root node.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#clearAppData()()`

Clears the instrumentation test target app data.
`https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)(timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)`

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/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`.
`https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2?` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)(timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)`

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/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2>` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)(timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)`

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/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressBack()()`

Press the back key.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)(count: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)`

Similar to `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)` times.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressEnter()()`

Press the enter key.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressHome()()`

Press the home key.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(java.lang.Class,kotlin.collections.List)(clazz: https://developer.android.com/reference/java/lang/Class.html<*>, intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>)`

Starts an activity with the given class.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)(
packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html,
activityName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html,
intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>
)`

Starts an activity with the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)` and `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)`.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)(intent: https://developer.android.com/reference/android/content/Intent.html)`

Starts the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)` for an activity.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)(packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>)`

Starts the app with the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)`.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)(text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)`

Types the given `https://developer.android.com/reference/kotlin/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)`.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#unregisterWatchers()()`

Unregisters all the watchers previously registered with `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)`.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#waitForAppToBeVisible(kotlin.String,kotlin.Long)(appPackageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)`

Waits for an application to become visible.
`https://developer.android.com/reference/kotlin/androidx/test/uiautomator/StableResult` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#waitForStableInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)(
stableTimeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html,
stableIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html,
stablePollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html,
requireStableScreenshot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html
)`

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

Registers a watcher for this `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope` to handle unexpected UI elements.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html>` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#windowRoots()()`

Returns all the window roots on all the displays.
`https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/android/view/accessibility/AccessibilityWindowInfo.html>` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#windows()()`

Returns all the windows on all the displays.

### Inherited properties

From [androidx.test.uiautomator.UiAutomatorTestScope](https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope) `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiDevice` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#device()` `https://developer.android.com/reference/android/app/Instrumentation.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#instrumentation()` `https://developer.android.com/reference/android/app/UiAutomation.html` `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#uiAutomation()`

## Public constructors

### MacrobenchmarkScope

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

```
MacrobenchmarkScope(packageName: String, launchWithClearTask: Boolean)
```

## Public functions

### dropKernelPageCache

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

```
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 |
|---|---|
| `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. |

### killProcess

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

```
fun killProcess(): Unit
```

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)

```
fun [killProcess](https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#killProcess(kotlin.Boolean))(useKillAll: Boolean = false): Unit
```

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

Force-stop the process being measured.

| Parameters |
|---|---|
| `useKillAll: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | 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)

```
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](https://developer.android.com/jetpack/androidx/releases/benchmark#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 `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 |
|---|---|
| `block: (https://developer.android.com/reference/android/content/Intent.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | 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)

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

### packageName

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

```
val packageName: String
```

ApplicationId / Package name of the app being tested.