Roborazzi Documentation

Roborazzi is a screenshot testing library that makes JVM Android Integration Tests visible. It integrates with Robolectric (specifically supporting Robolectric Native Graphics (RNG)) to enable efficient screenshot testing on the JVM.

Key Benefits

• Visual Validation: Detects visual regressions and validates app appearance more efficiently than manual assertion statements.
• JVM-based Testing: Unlike Instrumentation tests (which run on real devices/emulators in androidTest/ and are prone to environment-related false negatives), Roborazzi runs JVM tests (local tests in test/) on a developer's PC or CI environment.
• Robolectric Integration: Unlike Paparazzi, which is incompatible with Robolectric, Roborazzi works alongside Robolectric. This allows you to use tools like Hilt and interact with complex Android components within your JVM tests.

Comparison: Paparazzi vs. Roborazzi

While captureRoboImage() can be used standalone, RoborazziRule is an optional JUnit rule that provides advanced control over the screenshot lifecycle and output.

Key features of RoborazziRule:

1. Context Injection: Provides RoborazziOptions and outputDirectoryPath to captureRoboImage() calls.
2. Automatic Capture Types: Can automatically capture screenshots for every test based on the captureType setting.

RoborazziRule.Options properties:

• captureType: Determines what is captured per test:
  • None (default): Rule only provides context.
  • LastImage: Captures the last image of the test.
  • AllImage: Captures an image for every layout change (e.g., TestClass_method_0.png).
  • Gif: Captures an animated GIF.
  • Note: Image-generating types can be set to onlyFail = true to capture only on test failure.
• outputDirectoryPath: Custom directory for output files.
• outputFileProvider: A lambda to customize how files are named.
• roborazziOptions: Custom RoborazziOptions to be used by the capture functions.

@get:Rule
val roborazziRule = RoborazziRule(
    options = Options(
      outputDirectoryPath = "$DEFAULT_ROBORAZZI_OUTPUT_DIR_PATH/custom_dir",
      outputFileProvider = { description, outputDirectory, fileExtension ->
        File(outputDirectory, "custom-${description.testClass.name}.${description.methodName}.$fileExtension")
      }
    ),
  )

Roborazzi can generate 'Set-of-Mark' annotated images to help vision-language models (AI agents) identify UI elements. These images overlay numbered marks on image regions, allowing an agent to refer to an element by its number (e.g., "element #3").

Key Details:

• Naming Convention: The annotated image is a sidecar to your screenshot. For a record named MyTest.png, the annotated version is MyTest.annotated.png. For a comparison named MyTest_actual.png, it is MyTest_actual.annotated.png.
• Mapping: Each box's number matches the n value in the generated UI tree JSON, allowing agents to look up exact bounds, properties, and actions.
• Lifecycle: Annotated images are display artifacts of the current run only. They are never used for comparison, never cause test failures, and are never treated as golden images.
• Opt-out: You can disable this feature using UiTreeDumpOptions(annotateImage = false).

While captureRoboImage() can be used standalone, RoborazziRule (a JUnit rule) provides advanced control over the screenshot lifecycle and output.

Key features of RoborazziRule:

1. Context Injection: Provides RoborazziOptions and outputDirectoryPath to captureRoboImage() calls.
2. Automatic Capture: Can automatically capture screenshots for every test based on the captureType option.

RoborazziRule.Options properties:

• captureType: Determines what is captured per test:
  • None (default): Rule only provides context.
  • LastImage: Captures the last image change.
  • AllImage: Captures an image for every layout change (e.g., TestClass_method_0.png).
  • Gif: Captures an animated GIF.
  • Note: Image-generating types support onlyFail = true to capture only on test failure.
• outputDirectoryPath: The directory where output files are saved.
• outputFileProvider: A lambda to customize file naming logic.
• roborazziOptions: Custom RoborazziOptions to be used during capture.

@get:Rule
val roborazziRule = RoborazziRule(
  options = Options(
    outputDirectoryPath = "$DEFAULT_ROBORAZZI_OUTPUT_DIR_PATH/custom_output_dir",
    outputFileProvider = { description, outputDirectory, fileExtension ->
      File(outputDirectory, "custom_prefix-${description.testClass.name}.${description.methodName}.$fileExtension")
    }
  ),
)