# BenchmarkRule

Artifact: [androidx.benchmark:benchmark-junit4](https://developer.android.com/jetpack/androidx/releases/benchmark) [View Source](https://cs.android.com/search?q=file:androidx/benchmark/junit4/BenchmarkRule.kt+class:androidx.benchmark.junit4.BenchmarkRule) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.0.0)

*** ** * ** ***


```
public final class BenchmarkRule implements TestRule
```

<br />

*** ** * ** ***

JUnit rule for benchmarking code on an Android device.

In Kotlin, benchmark with `https://developer.android.com/reference/androidx/benchmark/junit4/package-summary#(androidx.benchmark.junit4.BenchmarkRule).measureRepeated(kotlin.Function1)`. In Java, use `https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule#getState()`.

Benchmark results will be output:

- Summary in Android Studio 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](https://developer.android.com/studio/profile/benchmark) for more information on writing Benchmarks.

```kotlin
import androidx.benchmark.junit4.BenchmarkRule
import androidx.benchmark.junit4.measureRepeated
import androidx.test.ext.junit.runners.AndroidJUnit4

@RunWith(AndroidJUnit4::class)
class MyBenchmark {
    @get:Rule val benchmarkRule = BenchmarkRule()

    @Test
    fun measureWork() {
        benchmarkRule.measureRepeated { doSomeWork() }
    }
}
```

## Summary

| ### Nested types |
|---|
| `public final inner class https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule.Scope extends https://developer.android.com/reference/androidx/benchmark/MicrobenchmarkScope` Handle used for controlling measurement during `https://developer.android.com/reference/androidx/benchmark/junit4/package-summary#(androidx.benchmark.junit4.BenchmarkRule).measureRepeated(kotlin.Function1)`. |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule#BenchmarkRule()()` |
| `@https://developer.android.com/reference/androidx/benchmark/ExperimentalBenchmarkConfigApi https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule#BenchmarkRule(androidx.benchmark.MicrobenchmarkConfig)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/MicrobenchmarkConfig config)` |

| ### 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/junit4/BenchmarkRule#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 @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/MicrobenchmarkConfig` | `https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule#getConfig()()` |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/BenchmarkState` | `https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule#getState()()` Object used for benchmarking in Java. |

| ### Extension functions |
|---|---|
| `final void` | `https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRuleKt.https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule#(androidx.benchmark.junit4.BenchmarkRule).measureRepeated(kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule receiver, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule.Scope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block )` Benchmark a block of code. |
| `final void` | `https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRuleKt.https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule#(androidx.benchmark.junit4.BenchmarkRule).measureRepeatedOnMainThread(kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule receiver, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule.Scope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block )` 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](https://developer.android.com/jetpack/androidx/releases/benchmark#1.0.0)

```
public BenchmarkRule()
```

### BenchmarkRule

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

```
@ExperimentalBenchmarkConfigApi
public BenchmarkRule(@NonNull MicrobenchmarkConfig config)
```

## Public methods

### apply

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

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

### getConfig

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

```
public final @NonNull MicrobenchmarkConfig getConfig()
```

### getState

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/benchmark#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 |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the BenchmarkRule isn't correctly applied to a test. |

## Extension functions

### BenchmarkRuleKt.measureRepeated

Artifact: [androidx.benchmark:benchmark-junit4](https://developer.android.com/jetpack/androidx/releases/benchmark) [View Source](https://cs.android.com/search?q=file:androidx/benchmark/junit4/BenchmarkRule.kt+function:measureRepeated)

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

Benchmark a block of code.

```kotlin
import androidx.benchmark.junit4.BenchmarkRule
import androidx.benchmark.junit4.measureRepeated
import androidx.test.ext.junit.runners.AndroidJUnit4

@RunWith(AndroidJUnit4::class)
class MyBenchmark {
    @get:Rule val benchmarkRule = BenchmarkRule()

    @Test
    fun measureWork() {
        benchmarkRule.measureRepeated { doSomeWork() }
    }
}
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule.Scope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block` | The block of code to benchmark. |

### BenchmarkRuleKt.measureRepeatedOnMainThread

Artifact: [androidx.benchmark:benchmark-junit4](https://developer.android.com/jetpack/androidx/releases/benchmark) [View Source](https://cs.android.com/search?q=file:androidx/benchmark/junit4/BenchmarkRule.kt+function:measureRepeatedOnMainThread)

```
public final void BenchmarkRuleKt.measureRepeatedOnMainThread(
    @NonNull BenchmarkRule receiver,
    @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.

```kotlin
import androidx.benchmark.junit4.BenchmarkRule
import androidx.benchmark.junit4.measureRepeated
import androidx.benchmark.junit4.measureRepeatedOnMainThread
import androidx.test.ext.junit.runners.AndroidJUnit4

@RunWith(AndroidJUnit4::class)
class MainThreadBenchmark {
    @get:Rule val benchmarkRule = BenchmarkRule()

    @Test
    fun measureWork() {
        benchmarkRule.measureRepeatedOnMainThread {
            // this block is run on the main thread
            doSomeWorkOnMainThread()
        }
    }
}
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/junit4/BenchmarkRule.Scope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block` | The block of code to benchmark. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/Throwable.html` | when an exception is thrown on the main thread. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if a hard deadline is exceeded while the block is running on the main thread. |