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

*** ** * ** ***


```
class BenchmarkRule : TestRule
```

<br />

*** ** * ** ***

JUnit rule for benchmarking code on an Android device.

In Kotlin, benchmark with `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/package-summary#(androidx.benchmark.junit4.BenchmarkRule).measureRepeated(kotlin.Function1)`. In Java, use `https://developer.android.com/reference/kotlin/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 |
|---|
| `inner class https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule.Scope : https://developer.android.com/reference/kotlin/androidx/benchmark/MicrobenchmarkScope` Handle used for controlling measurement during `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/package-summary#(androidx.benchmark.junit4.BenchmarkRule).measureRepeated(kotlin.Function1)`. |

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

| ### Public functions |
|---|---|
| `open https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(base: https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` |
| `https://developer.android.com/reference/kotlin/androidx/benchmark/BenchmarkState` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule#getState()()` Object used for benchmarking in Java. |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/benchmark/MicrobenchmarkConfig` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule#config()` |

| ### Extension functions |
|---|---|
| `inline https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule.https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule#(androidx.benchmark.junit4.BenchmarkRule).measureRepeated(kotlin.Function1)(crossinline block: https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule.Scope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Benchmark a block of code. |
| `inline https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule.https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule#(androidx.benchmark.junit4.BenchmarkRule).measureRepeatedOnMainThread(kotlin.Function1)(crossinline block: https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule.Scope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` 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)

```
BenchmarkRule()
```

### BenchmarkRule

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

```
@ExperimentalBenchmarkConfigApi
BenchmarkRule(config: MicrobenchmarkConfig)
```

## Public functions

### apply

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

```
open fun apply(base: Statement, description: Description): Statement
```

### getState

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

```
fun getState(): BenchmarkState
```

Object used for benchmarking in Java.

```kotlin
@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. |

## Public properties

### config

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

```
val config: MicrobenchmarkConfig
```

## Extension functions

### BenchmarkRule.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)

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

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 |
|---|---|
| `crossinline block: https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule.Scope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The block of code to benchmark. |

### BenchmarkRule.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)

```
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.

```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 |
|---|---|
| `crossinline block: https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/BenchmarkRule.Scope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | 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. |