How to use

Take a screenshot manually

You can take a screenshot by calling captureRoboImage().

app/src/test/java/../ManualTest.kt

import androidx.compose.ui.test.junit4.createAndroidComposeRule
import androidx.test.core.app.ActivityScenario
import androidx.test.espresso.Espresso.onView
import androidx.test.ext.junit.runners.AndroidJUnit4
import org.junit.Test
import org.junit.runner.RunWith
import org.robolectric.annotation.GraphicsMode

// All you need to do is use the captureRoboImage function in the test!
import com.github.takahirom.roborazzi.captureRoboImage


// Tips: You can use Robolectric while using AndroidJUnit4
@RunWith(AndroidJUnit4::class)
// Enable Robolectric Native Graphics (RNG) 
@GraphicsMode(GraphicsMode.Mode.NATIVE)
class ManualTest {
  @get:Rule
  val composeTestRule = createAndroidComposeRule<MainActivity>()

  @Test
  fun captureRoboImageSample() {
    // Tips: You can use Robolectric with Espresso API
    // launch
    ActivityScenario.launch(MainActivity::class.java)

    // Capture screen
    onView(ViewMatchers.isRoot())
      // If you don't specify a screenshot file name, Roborazzi will automatically use the method name as the file name for you.
      // The format of the file name will be as follows:
      // build/outputs/roborazzi/com_..._ManualTest_captureRoboImageSample.png
      .captureRoboImage()

    // Capture Jetpack Compose Node
    composeTestRule.onNodeWithTag("AddBoxButton")
      .onParent()
      .captureRoboImage("build/compose.png")
  }
}

Roborazzi supports the following APIs.

Capture	Code
✅ Jetpack Compose's onNode()	composeTestRule.onNodeWithTag("AddBoxButton") .captureRoboImage()
✅ Espresso's onView()	onView(ViewMatchers.isRoot()) .captureRoboImage() onView(withId(R.id.button_first)) .captureRoboImage()
✅ View	val view: View = composeTestRule.activity.findViewById<View>(R.id.button_second) view.captureRoboImage()
✅ Jetpack Compose lambda	captureRoboImage() { Text("Hello Compose!") }
Experimental🧪 ✅ Captures the entire screen, including dialogs	captureScreenRoboImage()
✅ Bitmap	val bitmap: Bitmap = createBitmap(100, 100, Bitmap.Config.ARGB_8888) .apply { applyCanvas { drawColor(android.graphics.Color.YELLOW) } } bitmap.captureRoboImage()

Device configuration

You can configure the device by using the @Config annotation and RobolectricDeviceQualifiers.

Configuration	Code
✅ Predefined device configuration	You can change the device configuration by adding `@Config` to the class or method. @RunWith(AndroidJUnit4::class) @GraphicsMode(GraphicsMode.Mode.NATIVE) @Config(qualifiers = RobolectricDeviceQualifiers.Pixel5) class RoborazziTest { @Test @Config(qualifiers = RobolectricDeviceQualifiers.Pixel5) fun test() {
✅ Night mode	@Config(qualifiers = "+night")
✅ Locale	@Config(qualifiers = "+ja")
✅ Screen size	@Config(qualifiers = RobolectricDeviceQualifiers.MediumTablet)

Integrate to your GitHub Actions

See Integrate to your GitHub Actions for CI workflows that store, verify, and compare screenshots.

RoborazziRule (Optional)

RoborazziRule is a JUnit rule for Roborazzi. RoborazziRule is optional. You can use captureRoboImage() without this rule.

RoborazziRule has two features.

Provide context such as RoborazziOptions and outputDirectoryPath etc for captureRoboImage().
Capture screenshots for each test when specifying RoborazziRule.options.captureType.

For example, The following code generates an output file named **custom_outputDirectoryPath**/**custom_outputFileProvider**-com.github.takahirom.roborazzi.sample.RuleTestWithPath.captureRoboImage.png:

@RunWith(AndroidJUnit4::class)
@GraphicsMode(GraphicsMode.Mode.NATIVE)
class RuleTestWithPath {
  @get:Rule
  val roborazziRule = RoborazziRule(
    options = Options(
      outputDirectoryPath = "$DEFAULT_ROBORAZZI_OUTPUT_DIR_PATH/custom_outputDirectoryPath",
      outputFileProvider = { description, outputDirectory, fileExtension ->
        File(
          outputDirectory,
          "custom_outputFileProvider-${description.testClass.name}.${description.methodName}.$fileExtension"
        )
      }
    ),
  )

  @Test
  fun captureRoboImage() {
    launch(MainActivity::class.java)
    // The file will be saved using the rule's outputDirectoryPath and outputFileProvider
    onView(isRoot()).captureRoboImage()
  }
}

To record test interactions as animated images (captureRoboGif(), recordRoboVideo()), see Capture GIFs and videos.

RoborazziRule options

RoborazziRule.Options has:

captureType — what the rule captures per test: None (default; the rule only provides context), LastImage, AllImage (an image per layout change, like TestClass_method_0.png), or Gif. The image-generating types take onlyFail = true to capture only when the test fails. Annotate a test with @RoborazziRule.Ignore to exclude it from these capture types.
outputDirectoryPath/outputFileProvider — where output files go and how they are named.
roborazziOptions — the RoborazziOptions provided to captureRoboImage() in the test.

See RoborazziRule for the full definition.

Image comparator custom settings

When comparing images, you may encounter differences due to minor changes related to antialiasing. You can use the options below to avoid this.

@get:Rule
val roborazziRule = RoborazziRule(
    options = RoborazziRule.Options(
        roborazziOptions = RoborazziOptions(
            compareOptions = RoborazziOptions.CompareOptions(
                changeThreshold = 0.01, // For 1% accepted difference
                imageComparator = SimpleImageComparator(
                    maxDistance = 0.007F, // 0.001F is default value from Differ
                    vShift = 2, // Increasing the shift can help resolve antialiasing issues
                    hShift = 2 // Increasing the shift can help resolve antialiasing issues
                )
            )
        )
    )
)

Experimental WebP support and other image formats

You can set roborazzi.record.image.extension to webp in your gradle.properties file to generate WebP images.

roborazzi.record.image.extension=webp

WebP is a lossy image format by default, which can make managing image differences challenging. To address this, we provide a lossless WebP image comparison feature. To enable WebP support, add testImplementation("io.github.darkxanter:webp-imageio:0.3.3") to your build.gradle.kts file.

onView(ViewMatchers.withId(R.id.textview_first))
  .captureRoboImage(
    roborazziOptions = RoborazziOptions(
      recordOptions = RoborazziOptions.RecordOptions(
        imageIoFormat = LosslessWebPImageIoFormat(),
      ),
    )
  )

You can also use other image formats by implementing your own AwtImageWriter and AwtImageLoader.

data class JvmImageIoFormat(
  val awtImageWriter: AwtImageWriter,
  val awtImageLoader: AwtImageLoader
) : ImageIoFormat

Dump mode

If you are having trouble debugging your test, try Dump mode as follows.

For a machine-readable version of the UI tree for tools and AI agents, see UI tree dump (JSON).

Accessibility Check

Roborazzi Accessibility Checks is a library that integrates accessibility checks into Roborazzi. Please refer to Accessibility Check

Roborazzi options

Please check out RoborazziOptions for available Roborazzi options.

Last modified: 28 July 2026