BenchmarkRule

class BenchmarkRule : TestRule

JUnit rule for benchmarking code on an Android device.

In Kotlin, benchmark with measureRepeated:

@get:Rule
val benchmarkRule = BenchmarkRule();

@Test
fun myBenchmark() {
    benchmarkRule.measureRepeated {
        doSomeWork()
    }
}

In Java, use getState():

@Rule
public BenchmarkRule benchmarkRule = new BenchmarkRule();

@Test
public void myBenchmark() {
    BenchmarkState state = benchmarkRule.getState();
    while (state.keepRunning()) {
        doSomeWork();
    }
}

Benchmark results will be output:

  • Summary in AndroidStudio in the test log

  • In JSON format, on the host

  • In simple form in Logcat with the tag "Benchmark"

Every test in the Class using this @Rule must contain a single benchmark.

See the Benchmark Guide for more information on writing Benchmarks.

Summary

Nested types

Handle used for controlling timing during measureRepeated.

Public constructors

Public functions
open Statement
apply(base: Statement, description: Description)
BenchmarkState

Object used for benchmarking in Java.

Extension functions
inline Unit

Benchmark a block of code.
inline Unit

Benchmark a block of code, which runs on the main thread, and can safely interact with UI.

Public constructors

BenchmarkRule

Added in 1.0.0
BenchmarkRule()

BenchmarkRule

Added in 1.2.0
@ExperimentalBenchmarkConfigApi
BenchmarkRule(config: MicrobenchmarkConfig)

Public functions

apply

Added in 1.0.0
open fun apply(base: Statement, description: Description): Statement

getState

Added in 1.0.0
fun getState(): BenchmarkState

Object used for benchmarking in Java.

@Rule
public BenchmarkRule benchmarkRule = new BenchmarkRule();

@Test
public void myBenchmark() {
    ...
    BenchmarkState state = benchmarkRule.getBenchmarkState();
    while (state.keepRunning()) {
        doSomeWork();
    }
    ...
}
Throws
kotlin.IllegalStateException

if the BenchmarkRule isn't correctly applied to a test.

Extension functions

measureRepeated

inline fun BenchmarkRule.measureRepeated(crossinline block: BenchmarkRule.Scope.() -> Unit): Unit

Benchmark a block of code.

@get:Rule
val benchmarkRule = BenchmarkRule();

@Test
fun myBenchmark() {
    ...
    benchmarkRule.measureRepeated {
        doSomeWork()
    }
    ...
}
Parameters
crossinline block: BenchmarkRule.Scope.() -> Unit

The block of code to benchmark.

measureRepeatedOnMainThread

inline fun BenchmarkRule.measureRepeatedOnMainThread(crossinline block: BenchmarkRule.Scope.() -> Unit): Unit

Benchmark a block of code, which runs on the main thread, and can safely interact with UI.

While @UiThreadRule works for a standard test, it doesn't work for benchmarks of arbitrary duration, as they may run for much more than 5 seconds and suffer ANRs, especially in continuous runs.

@get:Rule
val benchmarkRule = BenchmarkRule();

@Test
fun myBenchmark() {
    ...
    benchmarkRule.measureRepeatedOnMainThread {
        doSomeWorkOnMainThread()
    }
    ...
}
Parameters
crossinline block: BenchmarkRule.Scope.() -> Unit

The block of code to benchmark.
Throws
java.lang.Throwable

when an exception is thrown on the main thread.
kotlin.IllegalStateException

if a hard deadline is exceeded while the block is running on the main thread.