# BaselineProfileRule

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

*** ** * ** ***


```
@RequiresApi(value = 28)
public final class BaselineProfileRule implements TestRule
```

<br />

*** ** * ** ***

A `https://junit.org/junit4/javadoc/latest/org/junit/rules/TestRule.html` that collects Baseline Profiles to be embedded in your APK.

These rules are used at install time to partially pre-compile your application code.

`BaselineProfileRule` is only supported on Android 13 (API 33) and above, or if using a rooted device, Android P (API 28) and above.

Note that you can specify a `filterPredicate` to filter captured rules, for example, if you're generating rules for a library, and don't want to record profiles from outside that library.

See the [Baseline Profile Guide](https://d.android.com/baseline-profiles) for more information on creating Baseline Profiles.

```kotlin
import androidx.benchmark.macro.junit4.BaselineProfileRule
import androidx.test.ext.junit.runners.AndroidJUnit4

@RunWith(AndroidJUnit4::class)
class AppBaselineProfileGenerator {
    @get:Rule val baselineProfileRule = BaselineProfileRule()

    @Test
    fun startup() =
        baselineProfileRule.collect(packageName = "com.example.my.application.id") {
            pressHome()
            // This block defines the scenario for which profiles are captured.
            // Here we are interested in optimizing for app startup, but you
            // could also navigate and scroll through your most important UI.
            startActivityAndWait()
        }
}
```

```kotlin
import androidx.benchmark.macro.junit4.BaselineProfileRule
import androidx.test.ext.junit.runners.AndroidJUnit4

@RunWith(AndroidJUnit4::class)
class LibraryBaselineProfileGenerator {
    @get:Rule val baselineProfileRule = BaselineProfileRule()

    @Test
    fun libraryStartupRules() =
        baselineProfileRule.collect(
            packageName = "com.example.my.application.id",
            filterPredicate = {
                // Only capture rules in the library's package, excluding test app code
                // Rules are prefixed by tag characters, followed by JVM method signature,
                // e.g. `HSPLcom/mylibrary/LibraryClass;-><init>()V`, where `L`
                // signifies the start of the package/class, and '/' is divider instead of '.'
                val libPackagePrefix = "com.mylibrary"
                it.contains("^.*L${libPackagePrefix.replace(".", "/")}".toRegex())
            },
        ) {
            startActivityAndWait()
        }
}
```

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/benchmark/macro/junit4/BaselineProfileRule#BaselineProfileRule()()` |

| ### 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/macro/junit4/BaselineProfileRule#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 void` | `https://developer.android.com/reference/androidx/benchmark/macro/junit4/BaselineProfileRule#collect(kotlin.String,kotlin.Int,kotlin.Int,kotlin.String,kotlin.Boolean,kotlin.Boolean,kotlin.Function1,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName, int maxIterations, int stableIterations, https://developer.android.com/reference/java/lang/String.html outputFilePrefix, boolean includeInStartupProfile, boolean strictStability, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> filterPredicate, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> profileBlock )` Collects baseline profiles for a critical user journey, while ensuring that the generated profiles are stable for a minimum of `https://developer.android.com/reference/androidx/benchmark/macro/junit4/BaselineProfileRule#collect(kotlin.String,kotlin.Int,kotlin.Int,kotlin.String,kotlin.Boolean,kotlin.Boolean,kotlin.Function1,kotlin.Function1)`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileResult` | `https://developer.android.com/reference/androidx/benchmark/macro/junit4/BaselineProfileRule#collectWithResults(androidx.benchmark.macro.BaselineProfileConfig)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileConfig config)` Collects baseline profiles for a critical user journey, while ensuring that the generated profiles are stable. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileResult` | `https://developer.android.com/reference/androidx/benchmark/macro/junit4/BaselineProfileRule#collectWithResults(kotlin.String,kotlin.Int,kotlin.Int,kotlin.String,kotlin.Boolean,kotlin.Boolean,kotlin.Function1,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName, int maxIterations, int stableIterations, https://developer.android.com/reference/java/lang/String.html outputFilePrefix, boolean includeInStartupProfile, boolean strictStability, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> filterPredicate, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> profileBlock )` Collects baseline profiles for a critical user journey, while ensuring that the generated profiles are stable for a minimum of `https://developer.android.com/reference/androidx/benchmark/macro/junit4/BaselineProfileRule#collectWithResults(kotlin.String,kotlin.Int,kotlin.Int,kotlin.String,kotlin.Boolean,kotlin.Boolean,kotlin.Function1,kotlin.Function1)`. |

## Public constructors

### BaselineProfileRule

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

```
public BaselineProfileRule()
```

## Public methods

### apply

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

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

### collect

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

```
public final void collect(
    @NonNull String packageName,
    int maxIterations,
    int stableIterations,
    String outputFilePrefix,
    boolean includeInStartupProfile,
    boolean strictStability,
    @NonNull Function1<@NonNull String, @NonNull Boolean> filterPredicate,
    @NonNull Function1<@NonNull MacrobenchmarkScope, Unit> profileBlock
)
```

Collects baseline profiles for a critical user journey, while ensuring that the generated profiles are stable for a minimum of `https://developer.android.com/reference/androidx/benchmark/macro/junit4/BaselineProfileRule#collect(kotlin.String,kotlin.Int,kotlin.Int,kotlin.String,kotlin.Boolean,kotlin.Boolean,kotlin.Function1,kotlin.Function1)`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName` | Package name of the app for which profiles are to be generated. |
| `int maxIterations` | Maximum number of iterations to run when collecting profiles. |
| `int stableIterations` | Minimum number of iterations to observe as stable before assuming stability, and completing profile generation. |
| `https://developer.android.com/reference/java/lang/String.html outputFilePrefix` | An optional file name prefix used when creating the output file with the contents of the human readable baseline profile. For example: `outputFilePrefix-baseline-prof.txt` |
| `boolean includeInStartupProfile` | determines whether the generated profile should be also used as a startup profile. A startup profile is utilized during the build process in order to determine which classes are needed in the primary dex to optimize the startup time. This flag should be used only for startup flows, such as main application startup pre and post login or other entry points of the app. Note that methods collected in a startup profiles are also utilized for baseline profiles. |
| `boolean strictStability` | Enforce if the generated profile was stable |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> filterPredicate` | Function used to filter individual rules / lines of the baseline profile. By default, no filters are applied. Note that this works only when the target application's code is not obfuscated. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> profileBlock` | defines the critical user journey. |

### collectWithResults

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

```
public final @NonNull BaselineProfileResult collectWithResults(@NonNull BaselineProfileConfig config)
```

Collects baseline profiles for a critical user journey, while ensuring that the generated profiles are stable.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileConfig config` | which is used to manage the collection of Baseline Profiles. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileResult` | `https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileResult` which can be used to determine the absolute paths of the collected baseline profiles. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileConfig.Builder` | to construct an instance of `https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileConfig`. |

### collectWithResults

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

```
public final @NonNull BaselineProfileResult collectWithResults(
    @NonNull String packageName,
    int maxIterations,
    int stableIterations,
    String outputFilePrefix,
    boolean includeInStartupProfile,
    boolean strictStability,
    @NonNull Function1<@NonNull String, @NonNull Boolean> filterPredicate,
    @NonNull Function1<@NonNull MacrobenchmarkScope, Unit> profileBlock
)
```

Collects baseline profiles for a critical user journey, while ensuring that the generated profiles are stable for a minimum of `https://developer.android.com/reference/androidx/benchmark/macro/junit4/BaselineProfileRule#collectWithResults(kotlin.String,kotlin.Int,kotlin.Int,kotlin.String,kotlin.Boolean,kotlin.Boolean,kotlin.Function1,kotlin.Function1)`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName` | Package name of the app for which profiles are to be generated. |
| `int maxIterations` | Maximum number of iterations to run when collecting profiles. |
| `int stableIterations` | Minimum number of iterations to observe as stable before assuming stability, and completing profile generation. |
| `https://developer.android.com/reference/java/lang/String.html outputFilePrefix` | An optional file name prefix used when creating the output file with the contents of the human readable baseline profile. For example: `outputFilePrefix-baseline-prof.txt` |
| `boolean includeInStartupProfile` | determines whether the generated profile should be also used as a startup profile. A startup profile is utilized during the build process in order to determine which classes are needed in the primary dex to optimize the startup time. This flag should be used only for startup flows, such as main application startup pre and post login or other entry points of the app. Note that methods collected in a startup profiles are also utilized for baseline profiles. |
| `boolean strictStability` | Enforce if the generated profile was stable |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> filterPredicate` | Function used to filter individual rules / lines of the baseline profile. By default, no filters are applied. Note that this works only when the target application's code is not obfuscated. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> profileBlock` | defines the critical user journey. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileResult` | `https://developer.android.com/reference/androidx/benchmark/macro/BaselineProfileResult` which can be used to determine the absolute paths of the collected baseline profiles. |