Roborazzi

https://github.com/takahirom/roborazzi
Admin
Roborazzi is a screenshot testing library for JVM Android tests that integrates with Robolectric,...
Tokens:132,839
Snippets:859
Trust Score:9.6
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Accessibility check log output example

Source: https://github.com/takahirom/roborazzi/blob/main/roborazzi-accessibility-check/README.md

Example log output when accessibility checks fail, showing Error and Warning entries with details about the failing checks.

```text
Error: [AccessibilityViewCheckResult check=AccessibilityHierarchyCheckResult ERROR SpeakableTextPresentCheck 4 [ViewHierarchyElement class=android.view.View bounds=Rect(474, 1074 - 606, 1206)] null num_answers:0 view=null]
Warning: [AccessibilityViewCheckResult check=AccessibilityHierarchyCheckResult WARNING TextContrastCheck 11 [ViewHierarchyElement class=android.widget.TextView text=Something hard to read bounds=Rect(403, 1002 - 678, 1092)] {KEY_BACKGROUND_COLOR=-12303292, KEY_CONTRAST_RATIO=1.02, KEY_FOREGROUND_COLOR=-12369085, KEY_REQUIRED_CONTRAST_RATIO=3.0} num_answers:0 view=null]
```

--------------------------------

### UI tree dump JSON format example

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/ui_tree_dump.md

Example of the JSON output format. The root capture object carries image dimensions and scale; bounds are in raw unscaled window pixel coordinates. Empty/default fields are omitted, and output is deterministic.

```json
{ "schemaVersion": 1, "capture": { "imageWidth": 220, "imageHeight": 100, "scale": 1.0 }, "root":
 { "type": "view", "className": "androidx.compose.ui.platform.ComposeView", "bounds": [0, 0, 220, 100], "children": [
  { "n": 1, "type": "compose", "testTag": "login_button", "bounds": [16, 24, 204, 72], "properties": { "Role": "Button", "Text": "Login" }, "actions": ["OnClick"], "flags": ["MergeDescendants"] },
  { "n": 2, "type": "compose", "bounds": [16, 80, 204, 96], "properties": { "Text": "Forgot password?" } } ] }
}
```

--------------------------------

### Capture Espresso onView() with captureRoboImage()

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/how_to_use.md

Capture a screenshot of an Espresso view matcher. The first example captures the root view; the second captures a view identified by ID.

```kotlin
onView(ViewMatchers.isRoot())
  .captureRoboImage()
```

```kotlin
onView(withId(R.id.button_first))
  .captureRoboImage()
```

--------------------------------

### roborazzi.record.namingStrategy in gradle.properties

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gradle_properties_options.md

Defines the naming strategy for recorded images. Default is testPackageAndClassAndMethod. This example uses testClassAndMethod, which produces filenames like MyTest.testMethod.png.

```properties
roborazzi.record.namingStrategy=testClassAndMethod
```

--------------------------------

### Install Roborazzi agent skill with npx

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/top.md

Installs the Roborazzi documentation as an agent skill for AI coding agents such as Claude Code, Cursor, Codex, Android Studio Agent Mode, Antigravity, and Gemini CLI. Run this command to enable the agent to look up Roborazzi setup and usage while working on your project.

```bash
npx skills add takahirom/roborazzi
```

--------------------------------

### roborazzi.dumpUiTree in gradle.properties

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gradle_properties_options.md

Enables UI tree dump. When true, each captured screenshot gets a .uitree.json sidecar (MyTest.uitree.json on record, MyTest_actual.uitree.json on compare/verify). Default is false. The sidecar is informational only and never affects diffing or verification.

```properties
roborazzi.dumpUiTree=true
```

--------------------------------

### Verify and record screenshots with verifyAndRecordRoborazziDebug

Source: https://github.com/takahirom/roborazzi/blob/main/README.md

First verify the images and, if differences are detected, record a new baseline.

```bash
./gradlew verifyAndRecordRoborazziDebug
```

```bash
./gradlew testDebugUnitTest after adding  `roborazzi.test.verify=true` and `roborazzi.test.record=true` to your gradle.properties file.

or

./gradlew testDebugUnitTest -Proborazzi.test.verify=true -Proborazzi.test.record=true
```

--------------------------------

### Run screenshot tests with Gradle

Source: https://github.com/takahirom/roborazzi/blob/main/CONTRIBUTING.md

Run screenshot tests against sample modules. First record baseline screenshots, then verify or compare them. Success indicator: BUILD SUCCESSFUL.

```bash
./gradlew recordRoborazziDebug

# Then, verify screenshots match the baseline
./gradlew verifyRoborazziDebug

# Or, compare and generate diff images
./gradlew compareRoborazziDebug
```

--------------------------------

### Customize desktop preview tester with Capturer

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Customizes the desktop preview tester by providing a Capturer that wraps the preview in a theme and advances the main clock to support manualClockOptions. Reference the tester in Gradle with testerQualifiedClassName = "com.example.MyDesktopPreviewTester" (requires a parameterless constructor).

```kotlin
@OptIn(ExperimentalRoborazziApi::class, ExperimentalTestApi::class)
class MyDesktopPreviewTester : DesktopComposePreviewTester by DefaultDesktopComposePreviewTester(
  capturer = DefaultDesktopComposePreviewTester.Capturer { parameter ->
    setContent { MyTheme { parameter.preview() } }
    // Keep @RoboComposePreviewOptions manualClockOptions working: without this,
    // time-suffixed captures would all show the initial state.
    advanceMainClockFor(parameter)
    onRoot().captureRoboImage(parameter.filePath, parameter.roborazziOptions)
  }
)
```

--------------------------------

### Configure Gradle for Compose Desktop

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/compose_multiplatform.md

Configure Gradle for Compose Desktop support with Roborazzi. Add the Compose plugin and the roborazzi-compose-desktop dependency (version 1.6.0-alpha-2 or higher) to the desktop test source set.

```kotlin
plugins {
  kotlin("multiplatform")
  id("org.jetbrains.compose")
  id("io.github.takahirom.roborazzi")
}

kotlin {
  // You can use your source set name
  jvm("desktop")
  sourceSets {
    ...
    val desktopTest by getting {
      dependencies {
        implementation("io.github.takahirom.roborazzi:roborazzi-compose-desktop:[version]") // Use 1.6.0-alpha-2 or higher
        implementation(kotlin("test"))
      }
    }
    ...
```

--------------------------------

### Use @PreviewWrapper with PreviewWrapperProvider

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Shows how to define a PreviewWrapperProvider and apply it with @PreviewWrapper so that the wrapper's content (e.g., theme) appears in screenshots automatically when using ComposablePreviewScanner 0.9.0 or later.

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

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

--------------------------------

### Extend CaptureParameter with Default Values

Source: https://github.com/takahirom/roborazzi/blob/main/proposals/01-make-AndroidComposePreviewTester-customizable.md

Illustrates the extensibility of the CaptureParameter data class. New fields can be added with default values to maintain backward compatibility, as shown by the commented newField example.

```kotlin
data class CaptureParameter(
  val preview: ComposablePreview<AndroidPreviewInfo>,
  val filePath: String,
  val roborazziComposeOptions: RoborazziComposeOptions,
  val roborazziOptions: RoborazziOptions = provideRoborazziContext().options,
  // Future fields can be added with default values
  val newField: String = "default"
)
```

--------------------------------

### Test Compose Desktop with Roborazzi

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/compose_multiplatform.md

Test a Compose Desktop composable with Roborazzi. Uses runDesktopComposeUiTest, captures the root image, clicks a button, and captures again with custom options.

```kotlin
class MainKmpTest {
  @OptIn(ExperimentalTestApi::class)
  @Test
  fun test() = runDesktopComposeUiTest {
    setContent {
      App()
    }
    val roborazziOptions = RoborazziOptions(
      recordOptions = RoborazziOptions.RecordOptions(
        resizeScale = 0.5
      ),
      compareOptions = RoborazziOptions.CompareOptions(
        changeThreshold = 0F
      )
    )
    onRoot().captureRoboImage(roborazziOptions = roborazziOptions)

    onNodeWithTag("button").performClick()

    onRoot().captureRoboImage(roborazziOptions = roborazziOptions)
  }
}
```

--------------------------------

### Capture Roborazzi images in an iOS Compose test

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/compose_multiplatform.md

Example iOS test using runComposeUiTest and captureRoboImage. Note that filePath is required for every capture on iOS, and RoborazziOptions works the same as on other targets.

```kotlin
class IosTest {
  @OptIn(ExperimentalTestApi::class)
  @Test
  fun test() {
    runComposeUiTest {
      setContent {
        MaterialTheme {
          Column {
            Button(onClick = { }) {
              Text("Hello World")
            }
            Box(
              modifier = Modifier
                .background(Color.Red.copy(alpha = 0.5f), MaterialTheme.shapes.small)
                .size(100.dp),
            )
          }
        }
      }
      // iOS uses the same RoborazziOptions as the other targets. For example,
      // allow up to 1% of pixels to differ before a comparison fails.
      val roborazziOptions = RoborazziOptions(
        compareOptions = RoborazziOptions.CompareOptions(changeThreshold = 0.01F),
      )
      // Unlike the JVM, iOS has no automatic file-name generation, so filePath
      // is required for every capture.
      onRoot().captureRoboImage(this, filePath = "ios.png", roborazziOptions = roborazziOptions)
      onNodeWithText("Hello World").captureRoboImage(
        this,
        filePath = "ios_button.png",
        roborazziOptions = roborazziOptions,
      )
    }
  }
}
```

--------------------------------

### Enable generateComposePreviewDesktopTests in build.gradle.kts

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Enable desktop preview test generation in the Roborazzi Gradle plugin. Requires the ExperimentalRoborazziApi opt-in. Set packages to the package(s) containing previews. Uncomment targetName only when the project has multiple Kotlin JVM targets.

```kotlin
roborazzi {
  @OptIn(ExperimentalRoborazziApi::class)
  generateComposePreviewDesktopTests {
    enable = true
    packages = listOf("com.example")
    // Required only when the project has multiple Kotlin JVM targets:
    // targetName = "desktop"
  }
}
```

--------------------------------

### SampleComposableFunction composable for GIF test

Source: https://github.com/takahirom/roborazzi/blob/main/README.md

A composable function that displays a clickable box with testTag "AddBoxButton" and a dynamic number of boxes based on the click count. Used as the test target for the GIF capture example.

```kotlin
@Composable
fun SampleComposableFunction() {
  var count by remember { mutableStateOf(0) }
  Column(
    Modifier
      .size(300.dp)
  ) {
    Box(
      Modifier
        .testTag("AddBoxButton")
        .size(50.dp)
        .clickable {
          count++
        }
    )
    (0..count).forEach {
      Box(
        Modifier
          .size(30.dp)
      )
    }
  }
}
```

--------------------------------

### Set predefined device configuration with @Config and RobolectricDeviceQualifiers.Pixel5

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/how_to_use.md

Use @Config with RobolectricDeviceQualifiers.Pixel5 to set a predefined device configuration for a test class or method. The class-level example also includes @RunWith(AndroidJUnit4::class) and @GraphicsMode(GraphicsMode.Mode.NATIVE).

```kotlin
@RunWith(AndroidJUnit4::class)
@GraphicsMode(GraphicsMode.Mode.NATIVE)
@Config(qualifiers = RobolectricDeviceQualifiers.Pixel5)
class RoborazziTest {
```

```kotlin
@Test
@Config(qualifiers = RobolectricDeviceQualifiers.Pixel5)
fun test() {
```

--------------------------------

### Manual AiAssertionModel implementation with custom assertions

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/ai_powered_image_assertion.md

Shows how to implement AiAssertionModel manually without extra dependencies. The implementation returns AiAssertionResults with 100% fulfillment for each assertion, using a placeholder explanation. It demonstrates both assert methods, with the second using targetImages.images to access image file paths.

```kotlin
compareOptions = RoborazziOptions.CompareOptions(
  aiAssertionOptions = AiAssertionOptions(
    aiAssertionModel = object : AiAssertionOptions.AiAssertionModel {
      override fun assert(
        referenceImageFilePath: String,
        comparisonImageFilePath: String,
        actualImageFilePath: String,
        aiAssertionOptions: AiAssertionOptions
      ): AiAssertionResults {
        // You can use any LLMs here to create AiAssertionResults
        return AiAssertionResults(
          aiAssertionResults = aiAssertionOptions.aiAssertions.map { assertion ->
            AiAssertionResult(
              assertionPrompt = assertion.assertionPrompt,
              fulfillmentPercent = 100,
              requiredFulfillmentPercent = assertion.requiredFulfillmentPercent,
              failIfNotFulfilled = assertion.failIfNotFulfilled,
              explanation = "This is a manual test.",
            )
          }
        )
      }

      override fun assert(
        targetImages: TargetImages,
        aiAssertionOptions: AiAssertionOptions
      ): AiAssertionResults {
        // targetImages.images holds the images to assert (e.g. targetImages.images.first().filePath)
        return AiAssertionResults(
          aiAssertionResults = aiAssertionOptions.aiAssertions.map { assertion ->
            AiAssertionResult(
              assertionPrompt = assertion.assertionPrompt,
              fulfillmentPercent = 100,
              requiredFulfillmentPercent = assertion.requiredFulfillmentPercent,
              failIfNotFulfilled = assertion.failIfNotFulfilled,
              explanation = "This is a manual test.",
            )
          }
        )
      }
    },
    aiAssertions = listOf(
      AiAssertionOptions.AiAssertion(
        assertionPrompt = "it should have PREVIOUS button",
        requiredFulfillmentPercent = 90,
      ),
    ),
  )
)
          ...
```

--------------------------------

### Annotate a preview with @RoboComposePreviewOptions(renderScale = 0.5)

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Use this annotation to override the global renderScale for a single preview. The example shows a tablet preview with a custom device spec and a renderScale of 0.5. Previews without this annotation use the scale configured in the Gradle extension.

```kotlin
@RoboComposePreviewOptions(renderScale = 0.5)
@Preview(device = "spec:width=1280dp,height=800dp,dpi=240")
@Composable
fun TabletPreview() {
}
```

--------------------------------

### Configure generateComposePreviewRobolectricTests in build.gradle.kts

Source: https://github.com/takahirom/roborazzi/blob/main/README.md

Configure the Compose Preview screenshot test generation in build.gradle.kts. Set enable to true, specify packages to scan, Robolectric config, whether to include private previews, the custom tester class, and the number of generated test classes. The renderScale and annotationFilter options are commented out by default.

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

    // Experimental: render at a lower density to make the tests faster and the images smaller.
    // See "Making the tests faster with renderScale" below.
    // renderScale = 1.0 / 3

    // Filter previews by annotation. See "Filtering previews by annotation" below.
    annotationFilter = AnnotationFilter.Filter.RoboPreviewInclude
  }
}
```

--------------------------------

### RoborazziRule with Gif captureType and onlyFail to save GIF only on failure

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gif_and_video.md

Use RoborazziRule with captureType = RoborazziRule.CaptureType.Gif(onlyFail = true) to automatically name the GIF file and only save it if the test fails. The output file is placed in build/outputs/roborazzi/ with the test class and method name. This example shows a test that fails because the button does not exist, causing the GIF to be saved.

```kotlin
@RunWith(AndroidJUnit4::class)
@GraphicsMode(GraphicsMode.Mode.NATIVE)
class RuleTestWithOnlyFail {
  @get:Rule
  val roborazziRule = RoborazziRule(
    captureRoot = onView(isRoot()),
    options = Options(
      captureType = RoborazziRule.CaptureType.Gif(
        onlyFail = true
      ),
    )
  )

  @Test
  fun captureRoboGifSampleFail() {
    // launch
    ActivityScenario.launch(MainActivity::class.java)
    // move to next page
    onView(withId(R.id.button_first))
      .perform(click())
    // should fail because the button does not exist
    // Due to failure, the gif image will be saved in the outputs folder.
    onView(withId(R.id.button_first))
      .perform(click())
  }
}
```

--------------------------------

### Verify and record screenshots with unit test task and properties

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Use the default unit test task with both `roborazzi.test.verify=true` and `roborazzi.test.record=true` properties in `gradle.properties` or via the `-P` flags to verify and record screenshots.

```bash
./gradlew testDebugUnitTest after adding  `roborazzi.test.verify=true` and `roborazzi.test.record=true` to your gradle.properties file.
```

```bash
./gradlew testDebugUnitTest -Proborazzi.test.verify=true -Proborazzi.test.record=true
```

--------------------------------

### Capture entire screen (experimental) with captureScreenRoboImage()

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/how_to_use.md

Experimental API that captures the entire screen, including dialogs.

```kotlin
captureScreenRoboImage()
```

--------------------------------

### Enable UI tree dump via Gradle property

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/ui_tree_dump.md

Run the Gradle task with the -Proborazzi.dumpUiTree=true property to enable UI tree dump for the entire build without code changes.

```shell
./gradlew recordRoborazziDebug -Proborazzi.dumpUiTree=true
```

--------------------------------

### captureRoboGif() to record test interactions as a GIF

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gif_and_video.md

Use captureRoboGif() on a root view to record the test interactions as a GIF. The first argument is the output file path. The lambda contains the test steps to be recorded.

```kotlin
@Test
fun captureRoboGifSample() {
  onView(ViewMatchers.isRoot())
    .captureRoboGif("build/test.gif") {
      // launch
      ActivityScenario.launch(MainActivity::class.java)
      // move to next page
      onView(withId(R.id.button_first))
        .perform(click())
      // back
      pressBack()
      // move to next page
      onView(withId(R.id.button_first))
        .perform(click())
    }
}
```

--------------------------------

### Enable night mode with @Config(qualifiers = "+night")

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/how_to_use.md

Use @Config with qualifiers "+night" to enable night mode for the test.

```kotlin
@Config(qualifiers = "+night")
```

--------------------------------

### Record a node-scoped UI video with recordRoboVideo()

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gif_and_video.md

Records a node-scoped UI video with recordRoboVideo(). The block runs with the Compose main clock paused; call delay() to advance virtual time while frames are captured. After the block returns, recording continues until the UI settles. Requires @OptIn(ExperimentalRoborazziApi::class).

```kotlin
@OptIn(ExperimentalRoborazziApi::class)
@Test
fun recordVideo() {
  composeTestRule.setContent {
    AnimatedBoxContent()
  }
  composeTestRule.onNodeWithTag("root")
    .recordRoboVideo(
      composeRule = composeTestRule,
      filePath = "build/outputs/roborazzi/video.gif",
      videoOptions = RoboVideoOptions(fps = 10),
    ) {
      composeTestRule.onNodeWithTag("toggle").performClick()
      delay(300)
      composeTestRule.onNodeWithTag("toggle").performClick()
      delay(300)
    }
}
```

--------------------------------

### Run recordRoborazzi Gradle task

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/compose_multiplatform.md

Generic Gradle task to record Roborazzi images for a given source set, similar to Android support.

```bash
./gradlew recordRoborazzi[SourceSet]
```

--------------------------------

### Set screen size with @Config(qualifiers = RobolectricDeviceQualifiers.MediumTablet)

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/how_to_use.md

Use @Config with RobolectricDeviceQualifiers.MediumTablet to set the screen size to a medium tablet for the test.

```kotlin
@Config(qualifiers = RobolectricDeviceQualifiers.MediumTablet)
```

--------------------------------

### Configure time-based capture with @RoboComposePreviewOptions

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Uses @RoboComposePreviewOptions with manualClockOptions to capture a screenshot after advancing the clock by 516ms, useful for testing delayed state changes or animations.

```kotlin
@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")
  }
}
```

--------------------------------

### Verify and record screenshots with Roborazzi task

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Use the `verifyAndRecordRoborazziDebug` task to first verify the images and, if differences are detected, record a new baseline.

```bash
./gradlew verifyAndRecordRoborazziDebug
```

--------------------------------

### Record a touch-robot swipe with recordScreenRoboVideo()

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gif_and_video.md

Drives a swipe with saket/touch-robot from a LaunchedEffect while recording with recordScreenRoboVideo(). Because the recorder idles the Robolectric main Looper in lockstep with the Compose main clock, suspend-based gesture drivers make progress while frames are recorded. Pump virtual time with delay() in the block.

```kotlin
composeTestRule.setContent {
  // A composable whose LaunchedEffect drives a touch-robot swipe on the root.
  DraggableBoxContent()
}
recordScreenRoboVideo(
  composeRule = composeTestRule,
  filePath = "build/outputs/roborazzi/swipe.gif",
) {
  // Pump virtual time so the LaunchedEffect gesture progresses while frames are captured.
  delay(1000)
}
```

--------------------------------

### Run Roborazzi tasks

Source: https://github.com/takahirom/roborazzi/blob/main/skills/roborazzi/references/build_setup.md

Use these Gradle commands to record, compare, verify, and clear screenshots. The default unit test task can be used with the appropriate system property or gradle.properties setting. The clear task is experimental and deletes saved and cached images.

```bash
./gradlew recordRoborazziDebug
```

```bash
./gradlew testDebugUnitTest -Proborazzi.test.record=true
```

```bash
./gradlew compareRoborazziDebug
```

```bash
./gradlew testDebugUnitTest -Proborazzi.test.compare=true
```

```bash
./gradlew verifyRoborazziDebug
```

```bash
./gradlew testDebugUnitTest -Proborazzi.test.verify=true
```

```bash
./gradlew verifyAndRecordRoborazziDebug
```

```bash
./gradlew testDebugUnitTest -Proborazzi.test.verify=true -Proborazzi.test.record=true
```

```bash
./gradlew clearRoborazziDebug
```

--------------------------------

### Record a screen-wide UI video with recordScreenRoboVideo()

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gif_and_video.md

Records all window roots instead of a single node, mirroring how captureScreenRoboImage() relates to captureRoboImage(). Prefer it for a stable, device-sized viewport or to capture window overlays such as dialogs or touch indicators. Usage is the same as recordRoboVideo() but without node scoping.

```kotlin
recordScreenRoboVideo(
  composeRule = composeTestRule,
  filePath = "build/outputs/roborazzi/video_screen.gif",
  videoOptions = RoboVideoOptions(fps = 10),
) {
  composeTestRule.onNodeWithTag("toggle").performClick()
  delay(300)
}
```

--------------------------------

### Gradle tasks for iOS support

Source: https://github.com/takahirom/roborazzi/blob/main/skills/roborazzi/references/compose_multiplatform.md

Commands to record, compare, and verify Roborazzi screenshots for iOS simulator arm64.

```shell
./gradlew recordRoborazzi[SourceSet]

```

```shell
./gradlew recordRoborazziIosSimulatorArm64
./gradlew compareRoborazziIosSimulatorArm64
./gradlew verifyRoborazziIosSimulatorArm64
...

```

--------------------------------

### Enable Compose Preview screenshot test generation in build.gradle.kts

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Add this configuration to your build.gradle.kts file to enable the Compose Preview screenshot test generation feature. The plugin will not automatically change settings or add dependencies, but will provide instructions on next steps.

```kotlin
roborazzi {
  generateComposePreviewRobolectricTests {
    enable = true
  }
}
```

--------------------------------

### recordScreenRoboVideo()

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gif_and_video.md

Records all window roots instead of a single node, mirroring how captureScreenRoboImage() relates to captureRoboImage(). Prefer it for a stable, device-sized viewport for every frame, or to capture window overlays such as dialogs or touch indicators.

```APIDOC
## recordScreenRoboVideo()

### Description
Records all window roots instead of a single node, mirroring how captureScreenRoboImage() relates to captureRoboImage(). Prefer it for a stable, device-sized viewport for every frame, or to capture window overlays such as dialogs added mid-recording or touch/tap indicators, which live on separate window roots and are invisible to a node-scoped recording.

### Method
Top-level function call (e.g., recordScreenRoboVideo(...))

### Signature
```kotlin
@OptIn(ExperimentalRoborazziApi::class)
fun recordScreenRoboVideo(
  composeRule: ComposeTestRule,
  filePath: String,
  videoOptions: RoboVideoOptions = RoboVideoOptions(),
  block: suspend () -> Unit
)
```

### Parameters
- **composeRule** (ComposeTestRule) - Required - The Compose test rule used to control the UI.
- **filePath** (String) - Required - The output file path. The extension determines the format: .gif for GIF, .png for APNG.
- **videoOptions** (RoboVideoOptions) - Optional - Options for the video recording. Defaults to RoboVideoOptions().
- **block** (suspend () -> Unit) - Required - A suspend block that performs interactions and calls delay() to advance virtual time.

### RoboVideoOptions
- **fps** (Int) - Optional - Frames per second. Default is 10.
- **settleTimeoutMillis** (Long) - Optional - Additional virtual time to keep recording while the UI is still changing after the block ends. Default is 3000.
- **backgroundColor** (Long) - Optional - ARGB fill for the fixed recording viewport when frames have different sizes. Default is white.

### Output Formats
- **.gif** - GIF format with 256 colors. Frame delays are stored in centiseconds (10ms resolution), so prefer an fps whose frame step (1000 / fps) is a multiple of 10ms (e.g., 10, 20, 25, 50) for exact timing.
- **.png** - APNG (Animated PNG) format, lossless and full-color. Encodes frame step exactly. Prefer when color fidelity matters.

### Example
```kotlin
recordScreenRoboVideo(
  composeRule = composeTestRule,
  filePath = "build/outputs/roborazzi/video_screen.gif",
  videoOptions = RoboVideoOptions(fps = 10),
) {
  composeTestRule.onNodeWithTag("toggle").performClick()
  delay(300)
}
```

### Notes
- The API is experimental (@ExperimentalRoborazziApi).
- Currently only supports recording: when the Roborazzi task runs in compare/verify mode it is a complete no-op – the block is not executed and no image is recorded or verified.
- Because the recorder idles the Robolectric main Looper in lockstep with the Compose main clock, suspend-based gesture drivers make progress while frames are recorded. For example, you can drive a swipe with touch-robot from a LaunchedEffect, use recordScreenRoboVideo() so the touch indicator overlay is captured, and just pump virtual time in the block.
```

--------------------------------

### Compare screenshots with unit test task and property

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Use the default unit test task with the `roborazzi.test.compare=true` property in `gradle.properties` or via the `-P` flag to compare screenshots.

```bash
./gradlew testDebugUnitTest after adding `roborazzi.test.compare=true` to your gradle.properties file.
```

```bash
./gradlew testDebugUnitTest -Proborazzi.test.compare=true
```

--------------------------------

### Record screenshot with unit test task and property

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Use the default unit test task with the `roborazzi.test.record=true` property in `gradle.properties` or via the `-P` flag to record a screenshot.

```bash
./gradlew testDebugUnitTest after adding `roborazzi.test.record=true` to your gradle.properties file.
```

```bash
./gradlew testDebugUnitTest -Proborazzi.test.record=true
```

--------------------------------

### Run Compose Desktop Roborazzi tasks

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/compose_multiplatform.md

Gradle tasks for Compose Desktop support: record, compare, and verify Roborazzi images. If using the Kotlin JVM plugin, the task becomes recordRoborazziJvm.

```bash
./gradlew recordRoborazziDesktop
./gradlew compareRoborazziDesktop
./gradlew verifyRoborazziDesktop
...
```

--------------------------------

### Run desktop Roborazzi Gradle tasks

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Run the desktop Roborazzi tasks to record, compare, and verify preview screenshots. These tasks are available after enabling generateComposePreviewDesktopTests and adding the dependencies.

```shell
./gradlew recordRoborazziDesktop
./gradlew compareRoborazziDesktop
./gradlew verifyRoborazziDesktop
```

--------------------------------

### Implement custom ImageIoFormat

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/how_to_use.md

Implement your own ImageIoFormat by providing AwtImageWriter and AwtImageLoader to support other image formats.

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

--------------------------------

### RoboVideoOptions

Source: https://github.com/takahirom/roborazzi/blob/main/skills/roborazzi/references/gif_and_video.md

Configuration options for video recording: frames per second, settle timeout, and background color.

```APIDOC
## RoboVideoOptions

### Description
Configuration options for video recording: frames per second, settle timeout, and background color.

### Method
N/A (Data class)

### Endpoint
N/A

### Parameters
#### Constructor Parameters
- **fps** (Int) - Optional - Frames per second; default 10.
- **settleTimeoutMillis** (Long) - Optional - Additional virtual time to keep recording while the UI is still changing after the block ends; default 3000.
- **backgroundColor** (Long) - Optional - ARGB fill for the fixed recording viewport when frames have different sizes; default white.

### Request Example
```kotlin
RoboVideoOptions(fps = 10)
```

### Response
#### Success Response
- **RoboVideoOptions** - An instance of the configuration.

#### Response Example
N/A

### Error Handling
- **None** - This is a plain data class with no error conditions.
```

--------------------------------

### DefaultDesktopComposePreviewTester with Capturer

Source: https://github.com/takahirom/roborazzi/blob/main/proposals/02-compose-desktop-preview-tests.md

Default implementation that uses a Capturer composition to render previews and capture screenshots. The capturer receives the raw ComposeUiTest scope, allowing full control over mainClock, interactions, and content wrapping. The default capturer sets content (not preview) to honor @Preview options and advances the main clock for manual clock variations.

```kotlin
@ExperimentalRoborazziApi
class DefaultDesktopComposePreviewTester(
  private val capturer: Capturer = DefaultCapturer()
) : DesktopComposePreviewTester {

  fun interface Capturer {
    fun ComposeUiTest.capture(parameter: CaptureParameter)
  }

  data class CaptureParameter(
    val preview: ComposablePreview<AndroidPreviewInfo>,
    val filePath: String,            // precomputed default output path (incl. _TIME_Xms suffix)
    val roborazziOptions: RoborazziOptions,
    val manualClockOptions: ManualClockOptions?,  // set for @RoboComposePreviewOptions variations
    val content: @Composable () -> Unit = { preview() },  // preview wrapped with its @Preview options
  )

  class DefaultCapturer : Capturer {
    override fun ComposeUiTest.capture(parameter: CaptureParameter) {
      // content (not preview) so the @Preview annotation options are honored.
      setContent(parameter.content)
      // Keeps @RoboComposePreviewOptions manual clock variations working; the tester
      // has already disabled mainClock.autoAdvance for them.
      advanceMainClockFor(parameter)
      onRoot().captureRoboImage(parameter.filePath, parameter.roborazziOptions)
    }
  }
}
```

--------------------------------

### Verify screenshots with unit test task and property

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Use the default unit test task with the `roborazzi.test.verify=true` property in `gradle.properties` or via the `-P` flag to verify screenshots.

```bash
./gradlew testDebugUnitTest after adding `roborazzi.test.verify=true` to your gradle.properties file.
```

```bash
./gradlew testDebugUnitTest -Proborazzi.test.verify=true
```

--------------------------------

### Custom AndroidComposePreviewTester with capturer

Source: https://github.com/takahirom/roborazzi/blob/main/proposals/01-make-AndroidComposePreviewTester-customizable.md

Demonstrates how to customize AndroidComposePreviewTester by providing a capturer lambda that receives a parameter for custom logic.

```kotlin
class MyTester : AndroidComposePreviewTester(
  capturer = { parameter -> /* custom logic */ }
)
```

--------------------------------

### Configure generateComposePreviewDesktopTests in roborazzi block

Source: https://github.com/takahirom/roborazzi/blob/main/proposals/02-compose-desktop-preview-tests.md

Configure the new Gradle extension to generate Compose preview tests for desktop. Requires opt-in to ExperimentalRoborazziApi. The testerQualifiedClassName is optional; annotationFilter and includePrivatePreviews follow the same semantics as the Robolectric generator. Generated tests are placed only in the JVM target's test compilation, never main.

```kotlin
roborazzi {
  @OptIn(ExperimentalRoborazziApi::class)
  generateComposePreviewDesktopTests {
    enable = true
    packages = listOf("com.example")
    testerQualifiedClassName = "com.example.MyDesktopPreviewTester" // optional
    annotationFilter = ...            // same semantics as the Robolectric generator
    includePrivatePreviews = ...      // same semantics as the Robolectric generator
  }
}
```

--------------------------------

### DesktopComposePreviewTester interface and DesktopPreviewTestParameter

Source: https://github.com/takahirom/roborazzi/blob/main/proposals/02-compose-desktop-preview-tests.md

Defines the desktop-specific tester interface with options, test parameters, and a test method. The parameter class is deliberately not a data class for binary compatibility. Manual clock variations expand to one test parameter each.

```kotlin
@ExperimentalRoborazziApi
interface DesktopComposePreviewTester {
  data class Options(
    val testLifecycleOptions: TestLifecycleOptions = JUnit4TestLifecycleOptions(),
    val scanOptions: ScanOptions = ScanOptions(packages = emptyList()),
  ) {
    interface TestLifecycleOptions
    data class JUnit4TestLifecycleOptions(
      val testRuleFactory: () -> TestRule = { TestRule { base, _ -> base } },
    ) : TestLifecycleOptions
  }
  fun options(): Options
  fun testParameters(): List<DesktopPreviewTestParameter>
  fun test(testParameter: DesktopPreviewTestParameter)
}

class DesktopPreviewTestParameter(
  val preview: ComposablePreview<AndroidPreviewInfo>,
  val manualClockOptions: ManualClockOptions? = null,
)
```

--------------------------------

### Define plugin in root build.gradle.kts (buildscript)

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Adds the Roborazzi Gradle plugin to the buildscript classpath in the root build.gradle.kts file.

```kotlin
buildscript {
  dependencies {
    ...
    classpath("io.github.takahirom.roborazzi:roborazzi-gradle-plugin:[version]")
  }
}
```

--------------------------------

### recordRoboVideo()

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/gif_and_video.md

Records the UI evolution of a single composable node as an animated image. The block runs with the Compose main clock paused; call delay() to advance virtual time while frames are recorded. After the block returns, recording continues until the UI settles.

```APIDOC
## recordRoboVideo()

### Description
Records the UI evolution of a single composable node as an animated image. The block runs with the Compose main clock paused; call delay() to advance virtual time while frames are recorded. After the block returns, recording continues until the UI settles.

### Method
Function call on a SemanticsNodeInteraction (e.g., composeTestRule.onNodeWithTag("root").recordRoboVideo(...))

### Signature
```kotlin
@OptIn(ExperimentalRoborazziApi::class)
fun SemanticsNodeInteraction.recordRoboVideo(
  composeRule: ComposeTestRule,
  filePath: String,
  videoOptions: RoboVideoOptions = RoboVideoOptions(),
  block: suspend () -> Unit
)
```

### Parameters
- **composeRule** (ComposeTestRule) - Required - The Compose test rule used to control the UI.
- **filePath** (String) - Required - The output file path. The extension determines the format: .gif for GIF, .png for APNG.
- **videoOptions** (RoboVideoOptions) - Optional - Options for the video recording. Defaults to RoboVideoOptions().
- **block** (suspend () -> Unit) - Required - A suspend block that performs interactions and calls delay() to advance virtual time.

### RoboVideoOptions
- **fps** (Int) - Optional - Frames per second. Default is 10.
- **settleTimeoutMillis** (Long) - Optional - Additional virtual time to keep recording while the UI is still changing after the block ends. Default is 3000.
- **backgroundColor** (Long) - Optional - ARGB fill for the fixed recording viewport when frames have different sizes. Default is white.

### Output Formats
- **.gif** - GIF format with 256 colors. Frame delays are stored in centiseconds (10ms resolution), so prefer an fps whose frame step (1000 / fps) is a multiple of 10ms (e.g., 10, 20, 25, 50) for exact timing.
- **.png** - APNG (Animated PNG) format, lossless and full-color. Encodes frame step exactly. Prefer when color fidelity matters.

### Example
```kotlin
@OptIn(ExperimentalRoborazziApi::class)
@Test
fun recordVideo() {
  composeTestRule.setContent {
    AnimatedBoxContent()
  }
  composeTestRule.onNodeWithTag("root")
    .recordRoboVideo(
      composeRule = composeTestRule,
      filePath = "build/outputs/roborazzi/video.gif",
      videoOptions = RoboVideoOptions(fps = 10),
    ) {
      composeTestRule.onNodeWithTag("toggle").performClick()
      delay(300)
      composeTestRule.onNodeWithTag("toggle").performClick()
      delay(300)
    }
}
```

### Notes
- The API is experimental (@ExperimentalRoborazziApi).
- Currently only supports recording: when the Roborazzi task runs in compare/verify mode it is a complete no-op – the block is not executed and no image is recorded or verified.
```

--------------------------------

### Apply plugin in module build.gradle.kts (plugins DSL)

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Applies the Roborazzi plugin to a module using the plugins DSL in Kotlin.

```kotlin
plugins {
  ...
  id("io.github.takahirom.roborazzi")
}
```

--------------------------------

### Wrap desktop preview tests in JUnit TestRule

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Overrides options() to wrap each generated test in a JUnit TestRule via testRuleFactory. Unlike the Robolectric tester, there is no compose rule factory because Compose Desktop's test harness is function-scoped.

```kotlin
@OptIn(ExperimentalRoborazziApi::class, InternalRoborazziApi::class)
class MyDesktopPreviewTester : DesktopComposePreviewTester by DefaultDesktopComposePreviewTester() {
  override fun options(): DesktopComposePreviewTester.Options =
    DesktopComposePreviewTester.defaultOptionsFromPlugin.copy(
      testLifecycleOptions = DesktopComposePreviewTester.Options.JUnit4TestLifecycleOptions(
        testRuleFactory = { MyWatcherRule() }
      )
    )
}
```

--------------------------------

### Record screenshot with Roborazzi task

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Use the `recordRoborazziDebug` task to record a screenshot. The default output directory is `build/outputs/roborazzi`, and a report is available at `build/reports/roborazzi/index.html`.

```bash
./gradlew recordRoborazziDebug
```

--------------------------------

### Define plugin in root build.gradle (plugins DSL)

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Adds the Roborazzi plugin to the root project's plugin management with the specified version, using the plugins DSL in Groovy.

```groovy
plugins {
  ...
  id "io.github.takahirom.roborazzi" version "[version]" apply false
}
```

--------------------------------

### Set roborazzi.record.image.extension to webp

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/how_to_use.md

Set this property in gradle.properties to generate WebP images instead of the default format.

```kotlin
roborazzi.record.image.extension=webp
```

--------------------------------

### Define plugin in root build.gradle.kts (plugins DSL)

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Adds the Roborazzi plugin to the root project's plugin management with the specified version, using the plugins DSL in Kotlin.

```kotlin
plugins {
  ...
  id("io.github.takahirom.roborazzi") version "[version]" apply false
}
```

--------------------------------

### Apply plugin in module build.gradle.kts (buildscript)

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Applies the Roborazzi plugin to a module using the buildscript approach in Kotlin.

```kotlin
plugins {
    ...
    id("io.github.takahirom.roborazzi")
}
```

--------------------------------

### Configure Roborazzi outputDir in build.gradle

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/faq.md

Sets a custom output directory for Roborazzi screenshots to address caching issues. This is experimental and only needed if you are not using the default output directory (module/build/outputs/roborazzi).

```gradle
roborazzi {
    outputDir = "src/your/screenshot/folder"
}
```

--------------------------------

### Add roborazzi-compose-preview-scanner-support dependency

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/preview_support.md

Adds the roborazzi-compose-preview-scanner-support dependency to use the helper function for capturing Compose Previews.

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

--------------------------------

### Run Gradle plugin integration tests

Source: https://github.com/takahirom/roborazzi/blob/main/CONTRIBUTING.md

Run integration tests for the Gradle plugin with real Gradle projects. Use the --tests filter to run specific tests. Success indicator: Integration tests pass.

```bash
cd include-build && ./gradlew roborazzi-gradle-plugin:integrationTest && cd ..

# Or run specific tests
cd include-build && ./gradlew roborazzi-gradle-plugin:integrationTest --tests "*RoborazziGradleProjectTest.record" && cd ..
```

--------------------------------

### Compose Desktop App composable

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/compose_multiplatform.md

A simple Compose Desktop composable with a button that changes text when clicked. Used as the target for Roborazzi tests.

```kotlin
@Composable
fun App() {
  var text by remember { mutableStateOf("Hello, World!") }

  MaterialTheme {
    Button(
      modifier = Modifier.testTag("button"),
      onClick = {
        text = "Hello, Desktop!"
      }) {
      Text(
        style = MaterialTheme.typography.h2,
        text = text
      )
    }
  }
}
```

--------------------------------

### Set locale with @Config(qualifiers = "+ja")

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/how_to_use.md

Use @Config with qualifiers "+ja" to set the locale to Japanese for the test.

```kotlin
@Config(qualifiers = "+ja")
```

--------------------------------

### Store screenshots with recordRoborazziDebug

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/github_actions.md

GitHub Actions workflow that records Roborazzi screenshots on every push and uploads them as artifacts. Requires Java 19 and uses the gradle/actions/setup-gradle action. The artifact is named 'screenshots' and is retained for 30 days.

```yaml
name: store screenshots

on:
  push

env:
  GRADLE_OPTS: "-Dorg.gradle.jvmargs=-Xmx6g -Dorg.gradle.daemon=false -Dkotlin.incremental=false"

jobs:
  test:
    runs-on: macos-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: 19

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v4

      - name: test
        run: |
          # Create screenshots
          ./gradlew app:recordRoborazziDebug --stacktrace

      # Upload screenshots to GitHub Actions Artifacts
      - uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: app/build/outputs/roborazzi
          retention-days: 30

```

--------------------------------

### Enable screenshot recording in gradle.properties

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/faq.md

Set roborazzi.test.record=true in gradle.properties to allow executing screenshot tests using Android Studio's Run or Debug button.

```groovy
roborazzi.test.record=true
```

--------------------------------

### Apply plugin in module build.gradle (buildscript)

Source: https://github.com/takahirom/roborazzi/blob/main/docs/topics/build_setup.md

Applies the Roborazzi plugin to a module using the buildscript approach in Groovy.

```groovy
apply plugin: "io.github.takahirom.roborazzi"
```
Tokens:
Raw