BenchmarkRule

public final class BenchmarkRule implements 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
public final inner class BenchmarkRule.Scope

Handle used for controlling timing during measureRepeated.

Public constructors

Public methods
@NonNull Statement
apply(@NonNull Statement base, @NonNull Description description)
final @NonNull BenchmarkState

Object used for benchmarking in Java.

Extension functions
final void

Benchmark a block of code.
final void

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

BenchmarkRule

Added in 1.2.0
@ExperimentalBenchmarkConfigApi
public BenchmarkRule(@NonNull MicrobenchmarkConfig config)

Public methods

apply

Added in 1.0.0
public @NonNull Statement apply(@NonNull Statement base, @NonNull Description description)

getState

Added in 1.0.0
public final @NonNull BenchmarkState getState()

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

BenchmarkRuleKt.measureRepeated

public final void BenchmarkRuleKt.measureRepeated(
    @NonNull BenchmarkRule receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull BenchmarkRule.Scope, Unit> block
)

Benchmark a block of code.

@get:Rule
val benchmarkRule = BenchmarkRule();

@Test
fun myBenchmark() {
    ...
    benchmarkRule.measureRepeated {
        doSomeWork()
    }
    ...
}
Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull BenchmarkRule.Scope, Unit> block

The block of code to benchmark.

BenchmarkRuleKt.measureRepeatedOnMainThread

public final void BenchmarkRuleKt.measureRepeatedOnMainThread(
    @NonNull BenchmarkRule receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull BenchmarkRule.Scope, Unit> block
)

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
@ExtensionFunctionType @NonNull Function1<@NonNull BenchmarkRule.Scope, Unit> block

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.