# MacrobenchmarkRule

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

*** ** * ** ***


```
class MacrobenchmarkRule : TestRule
```

<br />

*** ** * ** ***

JUnit rule for benchmarking large app operations like startup, scrolling, or animations.

See the [Macrobenchmark Guide](https://developer.android.com/studio/profile/macrobenchmark) for more information on macrobenchmarks.

```kotlin
import androidx.benchmark.macro.StartupMode
import androidx.benchmark.macro.StartupTimingMetric
import androidx.benchmark.macro.junit4.MacrobenchmarkRule
import androidx.test.ext.junit.runners.AndroidJUnit4

@RunWith(AndroidJUnit4::class)
class StartupMacrobenchmark {
    @get:Rule val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() =
        benchmarkRule.measureRepeated(
            packageName = "com.example.my.application.id",
            metrics = listOf(StartupTimingMetric()),
            iterations = 5,
            startupMode = StartupMode.COLD,
            setupBlock = { pressHome() },
        ) { // this = MacrobenchmarkScope
            val intent = Intent()
            intent.setPackage(packageName)
            intent.setAction("com.example.my.application.id.myaction")
            startActivityAndWait(intent)
        }
}
```

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#MacrobenchmarkRule()()` |

| ### Public functions |
|---|---|
| `open https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(base: https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1)( packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, metrics: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/benchmark/macro/Metric>, compilationMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode, startupMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/StartupMode?, iterations: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, setupBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, measureBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Measure behavior of the specified `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1)` given a set of `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/benchmark/ExperimentalBenchmarkConfigApi https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.ExperimentalConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1)( packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, metrics: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/benchmark/macro/Metric>, iterations: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, experimentalConfig: https://developer.android.com/reference/kotlin/androidx/benchmark/ExperimentalConfig, compilationMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode, startupMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/StartupMode?, setupBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, measureBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Measure behavior of the specified `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.ExperimentalConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1)` given a set of `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.ExperimentalConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1)`, with a custom `https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/PerfettoConfig`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/benchmark/ExperimentalBenchmarkConfigApi [measureRepeated](https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.perfetto.PerfettoConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1))( packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, metrics: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/benchmark/macro/Metric>, iterations: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, perfettoConfig: https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/PerfettoConfig, compilationMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode, startupMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/StartupMode?, setupBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, measureBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` **This function is deprecated.** Deprecated in favour of a variant that accepts experimental config |

## Public constructors

### MacrobenchmarkRule

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

```
MacrobenchmarkRule()
```

## Public functions

### apply

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

```
open fun apply(base: Statement, description: Description): Statement
```

### measureRepeated

```
fun measureRepeated(
    packageName: String,
    metrics: List<Metric>,
    compilationMode: CompilationMode = CompilationMode.DEFAULT,
    startupMode: StartupMode? = null,
    iterations: @IntRange(from = 1) Int,
    setupBlock: MacrobenchmarkScope.() -> Unit = {},
    measureBlock: MacrobenchmarkScope.() -> Unit
): Unit
```

Measure behavior of the specified `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1)` given a set of `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1)`.

This performs a macrobenchmark with the below control flow:

```kotlin
    resetAppCompilation()
    compile(compilationMode)
    repeat(iterations) {
        setupBlock()
        captureTraceAndMetrics {
            measureBlock()
        }
    }
```

| Parameters |
|---|---|
| `packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | ApplicationId / Application manifest package name of the app for which profiles are generated. |
| `metrics: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/benchmark/macro/Metric>` | List of metrics to measure. |
| `compilationMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode = CompilationMode.DEFAULT` | Mode of compilation used before capturing measurement, such as `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode.Partial`, defaults to `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode#DEFAULT()`. |
| `startupMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/StartupMode? = null` | Optional mode to force app launches performed with `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#startActivityAndWait(kotlin.Function1)` (and similar variants) to be of the assigned type. For example, `COLD` launches kill the process before the measureBlock, to ensure startups will go through full process creation. Generally, leave as null for non-startup benchmarks. |
| `iterations: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Number of times the `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1)` will be run during measurement. Note that total iteration count may not match, due to warmup iterations needed for the `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1)`. |
| `setupBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | The block performing app actions each iteration, prior to the `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1)`. For example, navigating to a UI where scrolling will be measured. |
| `measureBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The block performing app actions to benchmark each iteration. |

### measureRepeated

```
@ExperimentalBenchmarkConfigApi
fun measureRepeated(
    packageName: String,
    metrics: List<Metric>,
    iterations: @IntRange(from = 1) Int,
    experimentalConfig: ExperimentalConfig,
    compilationMode: CompilationMode = CompilationMode.DEFAULT,
    startupMode: StartupMode? = null,
    setupBlock: MacrobenchmarkScope.() -> Unit = {},
    measureBlock: MacrobenchmarkScope.() -> Unit
): Unit
```

Measure behavior of the specified `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.ExperimentalConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1)` given a set of `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.ExperimentalConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1)`, with a custom `https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/PerfettoConfig`.

This performs a macrobenchmark with the below control flow:

```kotlin
    resetAppCompilation()
    compile(compilationMode)
    repeat(iterations) {
        setupBlock()
        captureTraceAndMetrics {
            measureBlock()
        }
    }
```

Note that a custom `https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/PerfettoConfig`s may result in built-in `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/Metric`s not working.

You can see the PerfettoConfig used by a trace (as a text proto) by opening the trace in [ui.perfetto.dev](http://ui.perfetto.dev), and selecting `Info and Stats` view on the left panel. You can also generate a custom text proto config by selecting `Record new trace` on the same panel, selecting recording options, and then clicking `Recording command` to access the generated text proto.

| Parameters |
|---|---|
| `packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | ApplicationId / Application manifest package name of the app for which profiles are generated. |
| `metrics: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/benchmark/macro/Metric>` | List of metrics to measure. |
| `iterations: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Number of times the `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.ExperimentalConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1)` will be run during measurement. Note that total iteration count may not match, due to warmup iterations needed for the `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.ExperimentalConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1)`. |
| `experimentalConfig: https://developer.android.com/reference/kotlin/androidx/benchmark/ExperimentalConfig` | Configuration for experimental features. |
| `compilationMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode = CompilationMode.DEFAULT` | Mode of compilation used before capturing measurement, such as `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode.Partial`, defaults to `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/CompilationMode#DEFAULT()`. |
| `startupMode: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/StartupMode? = null` | Optional mode to force app launches performed with `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope#startActivityAndWait(kotlin.Function1)` (and similar variants) to be of the assigned type. For example, `COLD` launches kill the process before the measureBlock, to ensure startups will go through full process creation. Generally, leave as null for non-startup benchmarks. |
| `setupBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | The block performing app actions each iteration, prior to the `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.ExperimentalConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1)`. For example, navigating to a UI where scrolling will be measured. |
| `measureBlock: https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The block performing app actions to benchmark each iteration. |

### measureRepeated

```
@ExperimentalBenchmarkConfigApi
fun [measureRepeated](https://developer.android.com/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,kotlin.Int,androidx.benchmark.perfetto.PerfettoConfig,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Function1,kotlin.Function1))(
    packageName: String,
    metrics: List<Metric>,
    iterations: @IntRange(from = 1) Int,
    perfettoConfig: PerfettoConfig,
    compilationMode: CompilationMode = CompilationMode.DEFAULT,
    startupMode: StartupMode? = null,
    setupBlock: MacrobenchmarkScope.() -> Unit = {},
    measureBlock: MacrobenchmarkScope.() -> Unit
): Unit
```

> [!CAUTION]
> **This function is deprecated.**   
> Deprecated in favour of a variant that accepts experimental config, use this instead:
>
> ```kotlin
> measureRepeated(packageName, metrics, iterations,experimentalConfig, compilationMode, startupMode, setupBlock, measureBlock)
> ```

| Parameters |
|---|---|
| `perfettoConfig: https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/PerfettoConfig` | Configuration for Perfetto trace capture during each iteration. Note that insufficient or invalid configs may result in built-in `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/Metric`s not working. |