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

*** ** * ** ***


```
public final class MacrobenchmarkRule implements 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/androidx/benchmark/macro/junit4/MacrobenchmarkRule#MacrobenchmarkRule()()` |

| ### Public methods |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/androidx/benchmark/macro/junit4/MacrobenchmarkRule#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html base, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `final void` | `https://developer.android.com/reference/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://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/androidx/benchmark/macro/Metric> metrics, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode compilationMode, https://developer.android.com/reference/androidx/benchmark/macro/StartupMode startupMode, @https://developer.android.com/reference/androidx/annotation/IntRange(from = 1) int iterations, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> setupBlock, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> measureBlock )` Measure behavior of the specified `https://developer.android.com/reference/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/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)`. |
| `final void` | `@https://developer.android.com/reference/androidx/benchmark/ExperimentalBenchmarkConfigApi https://developer.android.com/reference/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)( @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/androidx/benchmark/macro/Metric> metrics, @https://developer.android.com/reference/androidx/annotation/IntRange(from = 1) int iterations, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/ExperimentalConfig experimentalConfig, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode compilationMode, https://developer.android.com/reference/androidx/benchmark/macro/StartupMode startupMode, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> setupBlock, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> measureBlock )` Measure behavior of the specified `https://developer.android.com/reference/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/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/androidx/benchmark/perfetto/PerfettoConfig`. |
| `final void` | `@https://developer.android.com/reference/androidx/benchmark/ExperimentalBenchmarkConfigApi [measureRepeated](https://developer.android.com/reference/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))( @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/androidx/benchmark/macro/Metric> metrics, @https://developer.android.com/reference/androidx/annotation/IntRange(from = 1) int iterations, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/perfetto/PerfettoConfig perfettoConfig, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode compilationMode, https://developer.android.com/reference/androidx/benchmark/macro/StartupMode startupMode, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> setupBlock, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> measureBlock )` **This method 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)

```
public MacrobenchmarkRule()
```

## Public methods

### apply

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

```
public @NonNull Statement apply(@NonNull Statement base, @NonNull Description description)
```

### measureRepeated

```
public final void measureRepeated(
    @NonNull String packageName,
    @NonNull List<@NonNull Metric> metrics,
    @NonNull CompilationMode compilationMode,
    StartupMode startupMode,
    @IntRange(from = 1) int iterations,
    @NonNull Function1<@NonNull MacrobenchmarkScope, Unit> setupBlock,
    @NonNull Function1<@NonNull MacrobenchmarkScope, Unit> measureBlock
)
```

Measure behavior of the specified `https://developer.android.com/reference/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/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:

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName` | ApplicationId / Application manifest package name of the app for which profiles are generated. |
| `@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/benchmark/macro/Metric> metrics` | List of metrics to measure. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode compilationMode` | Mode of compilation used before capturing measurement, such as `https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode.Partial`, defaults to `https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode#DEFAULT()`. |
| `https://developer.android.com/reference/androidx/benchmark/macro/StartupMode startupMode` | Optional mode to force app launches performed with `https://developer.android.com/reference/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. |
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1) int iterations` | Number of times the `https://developer.android.com/reference/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/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://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> setupBlock` | The block performing app actions each iteration, prior to the `https://developer.android.com/reference/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. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> measureBlock` | The block performing app actions to benchmark each iteration. |

### measureRepeated

```
@ExperimentalBenchmarkConfigApi
public final void measureRepeated(
    @NonNull String packageName,
    @NonNull List<@NonNull Metric> metrics,
    @IntRange(from = 1) int iterations,
    @NonNull ExperimentalConfig experimentalConfig,
    @NonNull CompilationMode compilationMode,
    StartupMode startupMode,
    @NonNull Function1<@NonNull MacrobenchmarkScope, Unit> setupBlock,
    @NonNull Function1<@NonNull MacrobenchmarkScope, Unit> measureBlock
)
```

Measure behavior of the specified `https://developer.android.com/reference/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/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/androidx/benchmark/perfetto/PerfettoConfig`.

This performs a macrobenchmark with the below control flow:

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

Note that a custom `https://developer.android.com/reference/androidx/benchmark/perfetto/PerfettoConfig`s may result in built-in `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName` | ApplicationId / Application manifest package name of the app for which profiles are generated. |
| `@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/benchmark/macro/Metric> metrics` | List of metrics to measure. |
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1) int iterations` | Number of times the `https://developer.android.com/reference/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/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)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/ExperimentalConfig experimentalConfig` | Configuration for experimental features. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode compilationMode` | Mode of compilation used before capturing measurement, such as `https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode.Partial`, defaults to `https://developer.android.com/reference/androidx/benchmark/macro/CompilationMode#DEFAULT()`. |
| `https://developer.android.com/reference/androidx/benchmark/macro/StartupMode startupMode` | Optional mode to force app launches performed with `https://developer.android.com/reference/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. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> setupBlock` | The block performing app actions each iteration, prior to the `https://developer.android.com/reference/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. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> measureBlock` | The block performing app actions to benchmark each iteration. |

### measureRepeated

```
@ExperimentalBenchmarkConfigApi
public final void [measureRepeated](https://developer.android.com/reference/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))(
    @NonNull String packageName,
    @NonNull List<@NonNull Metric> metrics,
    @IntRange(from = 1) int iterations,
    @NonNull PerfettoConfig perfettoConfig,
    @NonNull CompilationMode compilationMode,
    StartupMode startupMode,
    @NonNull Function1<@NonNull MacrobenchmarkScope, Unit> setupBlock,
    @NonNull Function1<@NonNull MacrobenchmarkScope, Unit> measureBlock
)
```

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/perfetto/PerfettoConfig 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/androidx/benchmark/macro/Metric`s not working. |