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

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

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.