Experimental Compose Preview Support

Roborazzi provides support for generating screenshot tests and easy setup for Jetpack Compose Preview. This support uses ComposablePreviewScanner to scan the Composable Previews in your project.

Generate Compose Preview screenshot tests

You first need to add the Roborazzi plugin to your project. Please refer to the setup guide for more information. Then you can enable the Compose Preview screenshot test generation feature by adding the following configuration to your build.gradle.kts file:

roborazzi {
  generateComposePreviewRobolectricTests {
    enable = true
  }
}

The plugin will not automatically change your settings or add dependencies to prevent conflicts with your existing setup. However, it will provide instructions on what to do next, such as adding dependencies and required code. You can also check the sample project for a complete example.

After that, you can run the recordRoborazziDebug task to generate screenshots using the generated tests, as described in the setup guide.

Customizing the Preview screenshot test

You can customize the generated test by adding the following configuration to your build.gradle.kts file:

roborazzi {
  @OptIn(ExperimentalRoborazziApi::class)
  generateComposePreviewRobolectricTests {
    enable = true
    // The package names to scan for Composable Previews.
    packages = listOf("com.example")
    // robolectricConfig will be passed to Robolectric's @Config annotation in the generated test class.
    // See https://robolectric.org/configuring/ for more information.
    robolectricConfig = mapOf(
      "sdk" to "[32]",
      "qualifiers" to "RobolectricDeviceQualifiers.Pixel5",
    )
    // If true, the private previews will be included in the test.
    includePrivatePreviews = true
    // The fully qualified class name of the custom test class that implements [com.github.takahirom.roborazzi.ComposePreviewTester].
    testerQualifiedClassName = "com.example.MyCustomComposePreviewTester"
    // The number of test classes to generate. Set this to match maxParallelForks for parallel test execution.
    generatedTestClassCount = 4
    // Filter previews by annotation. Defaults to AnnotationFilter.Filter.RoboPreviewExclude
    // (previews annotated with @RoboPreviewExclude are skipped). Override to switch to opt-in mode
    // where only previews annotated with @RoboPreviewInclude are captured.
    annotationFilter = AnnotationFilter.Filter.RoboPreviewInclude
  }
}

Advanced: Custom ComposePreviewTester Implementation

You can create a custom ComposePreviewTester to control the screenshot capture behavior, such as setting a custom image comparison threshold.

Note that AndroidComposePreviewTester is a final class, so you can't subclass it. Instead, use Kotlin class delegation and pass a custom Capturer to its constructor. Also, your tester class must have a parameterless constructor because the plugin instantiates it via reflection:

import com.dropbox.differ.SimpleImageComparator
import com.github.takahirom.roborazzi.*
import com.github.takahirom.roborazzi.ComposePreviewTester.TestParameter.JUnit4TestParameter.AndroidPreviewJUnit4TestParameter

@OptIn(ExperimentalRoborazziApi::class)
class MyCustomComposePreviewTester :
  ComposePreviewTester<AndroidPreviewJUnit4TestParameter> by AndroidComposePreviewTester(
    capturer = { parameter ->
      val customOptions = parameter.roborazziOptions.copy(
        compareOptions = parameter.roborazziOptions.compareOptions.copy(
          // Set custom comparison threshold (0.0 = exact match, 1.0 = ignore differences)
          imageComparator = SimpleImageComparator(maxDistance = 0.01f)
        )
      )
      AndroidComposePreviewTester.DefaultCapturer().capture(
        parameter.copy(roborazziOptions = customOptions)
      )
    }
  )

If you need to customize more than the capture behavior, such as the scan options or the test lifecycle, you can override options() or test() in the delegating class.

Then reference your custom tester in the Gradle configuration:

roborazzi {
  @OptIn(ExperimentalRoborazziApi::class)
  generateComposePreviewRobolectricTests {
    enable = true
    testerQualifiedClassName = "com.example.MyCustomComposePreviewTester"
  }
}

Filtering previews by annotation

annotationFilter controls which previews are captured (requires the roborazzi-annotations dependency). By default it is AnnotationFilter.Filter.RoboPreviewExclude, so previews annotated with @RoboPreviewExclude are skipped. Set it to RoboPreviewInclude to capture only previews annotated with @RoboPreviewInclude:

roborazzi {
  @OptIn(ExperimentalRoborazziApi::class)
  generateComposePreviewRobolectricTests {
    enable = true
    packages = listOf("com.example")
    annotationFilter = AnnotationFilter.Filter.RoboPreviewInclude
  }
}

To filter by your own annotations, pass their fully qualified class names (use the JVM binary name with $ for nested classes, e.g. com.example.Outer$Inner):

// Set either one, not both
annotationFilter = AnnotationFilter.Exclude("com.example.MyExcludeAnnotation")
annotationFilter = AnnotationFilter.Include("com.example.MyIncludeAnnotation")

Annotation-based Capture Control

To enable fine-grained control over screenshot timing in Compose Previews, add the new annotations dependency:

testImplementation("io.github.takahirom.roborazzi:roborazzi-annotations:[version]")

Use @RoboComposePreviewOptions to configure time-based captures:

@RoboComposePreviewOptions(
  manualClockOptions = [ManualClockOptions(advanceTimeMillis = 516L)]
)
@Preview
@Composable
fun DelayedPreview() {
  var visible by remember { mutableStateOf(false) }
  LaunchedEffect(Unit) {
    delay(500)
    visible = true
  }
  if (visible) {
    Text("Content appears after 500ms")
  }
}

This annotation enables capturing screenshots at specific time intervals, particularly useful for testing animated components or delayed state changes.

PreviewWrapper support

Previews annotated with @PreviewWrapper (Compose UI 1.11+) are automatically wrapped by ComposablePreviewScanner 0.9.0 or later, so the wrapper's content, such as a theme or background, appears in the screenshots without any extra setup:

class MyWrapperProvider : PreviewWrapperProvider {
  @Composable
  override fun Wrap(content: @Composable () -> Unit) {
    MyTheme { content() }
  }
}

@PreviewWrapper(MyWrapperProvider::class)
@Preview
@Composable
fun WrappedPreview() { ... }

Manually adding Compose Preview screenshot tests

Roborazzi provides a helper function for ComposablePreviewScanner. You can add the following dependency to your project to use the helper function:

testImplementation("io.github.takahirom.roborazzi:roborazzi-compose-preview-scanner-support:[version]")

Then you can use the ComposablePreview<AndroidPreviewInfo>.captureRoboImage() function to capture the Composable Preview using the settings in Preview annotations. To obtain the ComposablePreview object, please refer to ComposablePreviewScanner.

fun ComposablePreview<AndroidPreviewInfo>.captureRoboImage(
  filePath: String,
  roborazziOptions: RoborazziOptions
)

The supported `@Preview` annotation options

Currently, we don't support all the annotation options provided by the Compose Preview. You can check the supported annotations in the source code. We are looking forward to your contributions to support more annotation options.

Last modified: 12 July 2026