MacrobenchmarkRule

class MacrobenchmarkRule : TestRule


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

    @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("mypackage.myapp")
intent.setAction("mypackage.myapp.myaction")
startActivityAndWait(intent)
}

See the Macrobenchmark Guide for more information on macrobenchmarks.

Summary

Public constructors

Public functions

open Statement
apply(base: Statement, description: Description)
Unit
measureRepeated(
    packageName: String,
    metrics: List<Metric>,
    compilationMode: CompilationMode,
    startupMode: StartupMode?,
    iterations: @IntRange(from = 1) Int,
    setupBlock: MacrobenchmarkScope.() -> Unit,
    measureBlock: MacrobenchmarkScope.() -> Unit
)

Measure behavior of the specified packageName given a set of metrics.

Public constructors

MacrobenchmarkRule

Added in 1.1.0
MacrobenchmarkRule()

Public functions

apply

Added in 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 packageName given a set of metrics.

This performs a macrobenchmark with the below control flow:

    resetAppCompilation()
compile(compilationMode)
repeat(iterations) {
setupBlock()
captureTraceAndMetrics {
measureBlock()
}
}
Parameters
packageName: String

ApplicationId / Application manifest package name of the app for which profiles are generated.

metrics: List<Metric>

List of metrics to measure.

compilationMode: CompilationMode = CompilationMode.DEFAULT

Mode of compilation used before capturing measurement, such as CompilationMode.Partial, defaults to CompilationMode.DEFAULT.

startupMode: StartupMode? = null

Optional mode to force app launches performed with MacrobenchmarkScope.startActivityAndWait (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: @IntRange(from = 1) Int

Number of times the measureBlock will be run during measurement. Note that total iteration count may not match, due to warmup iterations needed for the compilationMode.

setupBlock: MacrobenchmarkScope.() -> Unit = {}

The block performing app actions each iteration, prior to the measureBlock. For example, navigating to a UI where scrolling will be measured.

measureBlock: MacrobenchmarkScope.() -> Unit

The block performing app actions to benchmark each iteration.