Skip to content
Back to search

roborazzi

Make JVM Android integration test visible πŸ€–πŸ“Έ

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/takahirom/roborazzi with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/takahirom/roborazzi'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/takahirom--roborazzi/badge.svg)](/listings/takahirom--roborazzi)

HTML

<a href="/listings/takahirom--roborazzi"><img src="/api/listings/takahirom--roborazzi/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Roborazzi is available on maven central.

This plugin simply creates Gradle tasks record, verify, compare and passes the configuration to the test.

**build.gradle.kts** <table> <tr><td>plugins</td><td>buildscript</td></tr> <tr><td>

Define plugin in root build.gradle.kts

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

Apply plugin in module build.gradle.kts

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

</td><td>

root build.gradle.kts

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

module build.gradle.kts

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

</td></tr>

</table>

<details> <summary>build.gradle version</summary> <table> <tr><td>plugins</td><td>buildscript</td></tr> <tr><td>

Define plugin in root build.gradle

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

Apply plugin in module build.gradle

plugins {
  ...
  id 'io.github.takahirom.roborazzi'
}

</td><td>

root build.gradle

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

module build.gradle

apply plugin: "io.github.takahirom.roborazzi"

</td></tr>

</table> </details>

Add dependencies

| Description | Dependencies | |-----------------|--------------------------------------------------------------------------------------| | Core functions | `testImplementation("io.github.takahirom.roborazzi:roborazzi:[version]")` | | Jetpack Compose | `testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:[version]")` | | JUnit rules | `testImplementation("io.github.takahirom.roborazzi:roborazzi-junit-rule:[version]")` |

Run tasks

<table> <tr> <td> Use Roborazzi task </td> <td> Use default unit test task </td> <td> Description </td> </tr> <tr> <td>

`./gradlew recordRoborazziDebug`

</td><td>

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

or

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

</td><td>

Record a screenshot Default output directory is `build/outputs/roborazzi` You can check a report under `build/reports/roborazzi/index.html`

</td> </tr> <tr> <td>

`./gradlew compareRoborazziDebug`

</td><td>

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

or

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

</td><td>

Review changes made to an image. This action will compare the current image with the saved one, generating a comparison image labeled as `[original]_compare.png`. It also produces a JSON file containing the diff information, which can be found under `build/test-results/roborazzi`.

</td> </tr> <tr> <td>

`./gradlew verifyRoborazziDebug`

</td><td>

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

or

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

</td><td>

Validate changes made to an image. If there is any difference between the current image and the saved one, the test will fail.

</td> </tr> <tr> <td>

`./gradlew verifyAndRecordRoborazziDebug`

</td><td>

`./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`

</td><td>

This task will first verify the images and, if differences are detected, it will record a new baseline.

</td> </tr>

<tr> <td>

`./gradlew clearRoborazziDebug`

</td><td>

This is not a test task.

</td><td>

Note: This is an experimental task.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 2,236 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- Generated by ./gradlew generateReadme. Do not edit this file. -->
  2. <!-- topic_top -->
  3. <!-- Generated by docs/topics/top.md. Do not edit this file. -->
  4. # Roborazzi
  5. **Make JVM Android Integration Test Visible**
  6. ## Roborazzi now supports [Robolectric Native Graphics (RNG)](https://github.com/robolectric/robolectric/releases/tag/robolectric-4.10) and enables screenshot testing.πŸ“£
  7. ## Why Choose Roborazzi?
  8. ### Why is screenshot testing important?
  9. Screenshot testing is key to validate your app's appearance and functionality. It efficiently
  10. detects visual issues and tests the app as users would use it, making it easier to spot problems.
  11. It's quicker than writing many assert statements, ensuring your app looks right and behaves
  12. correctly.
  13. ### What are JVM tests and why test with JVM instead of on Android?
  14. JVM tests, also known as local tests, are placed in the test/ directory and are run on a developer's
  15. PC or CI environment. On the other hand, device tests, also known as Instrumentation tests, are
  16. written in the androidTest/ directory and are run on real devices or emulators. Device testing can
  17. result in frequent failures due to the device environment, leading to false negatives. These
  18. failures are often hard to reproduce, making them tough to resolve.
  19. ### Paparazzi and Roborazzi: A Comparison
  20. Paparazzi is a great tool for visualizing displays within the JVM. However, it's incompatible with
  21. Robolectric, which also mocks the Android framework.
  22. Roborazzi fills this gap. It integrates with Robolectric, allowing tests to run with Hilt and
  23. interact with components. Essentially, Roborazzi enhances Paparazzi's capabilities, providing a more
  24. efficient and reliable testing process by capturing screenshots with Robolectric.
  25. **Leveraging Roborazzi in Test Architecture: An Example**
  26. <img src="https://github.com/takahirom/roborazzi/assets/1386930/937a96a4-f637-4029-87e1-c1bb94abc8ae" width="320" />
  27. **Integrating Roborazzi into the Architecture: An Example from DroidKaigi 2023 App**
  28. In the DroidKaigi 2023 app, Roborazzi was introduced from the early stages of development as part of the architectural design. This integration allowed the team to verify changes throughout the development process. The specific architectural decisions and how they were implemented can be found [README](https://github.com/DroidKaigi/conference-app-2023#screenshot-testing-with-robolectric-native-graphics-rng-and-roborazzi).
  29. ## Using Roborazzi documentation with AI coding agents
  30. Roborazzi ships its documentation as an installable [agent skill](https://skills.sh/). Running the
  31. following command installs the docs into your AI coding agent (Claude Code, Cursor, Codex,
  32. [Android Studio Agent Mode](https://developer.android.com/studio/gemini/skills), Antigravity,
  33. Gemini CLI, etc.),
  34. so the agent can look up Roborazzi setup and usage while working on your project:
  35. ```bash
  36. npx skills add takahirom/roborazzi
  37. ```
  38. <!-- end -->
  39. <!-- topic_try_it_out -->
  40. <!-- Generated by docs/topics/try_it_out.md. Do not edit this file. -->
  41. # Try it out
  42. Available on Maven Central.
  43. ## Add Robolectric
  44. This is an example of adding Robolectric to your project:
  45. https://github.com/takahirom/roborazzi-usage-examples/compare/b697...5c12
  46. This library is dependent on Robolectric. Please see below to add Robolectric.
  47. https://robolectric.org/getting-started/
  48. ## Add Roborazzi
  49. This is an example of adding Roborazzi to your project:
  50. https://github.com/takahirom/roborazzi-usage-examples/commit/3a02
  51. To take screenshots, please use Robolectric 4.10 alpha 1 or later and please
  52. add `@GraphicsMode(GraphicsMode.Mode.NATIVE)` to your test class.
  53. ```kotlin
  54. @GraphicsMode(GraphicsMode.Mode.NATIVE)
  55. ```
  56. <!-- end -->
  57. <!-- topic_build_setup -->
  58. <!-- Generated by docs/topics/build_setup.md. Do not edit this file. -->
  59. # Build setup
  60. Roborazzi is available on maven central.
  61. This plugin simply creates Gradle tasks record, verify, compare and passes the configuration to the
  62. test.
  63. **build.gradle.kts**
  64. <table>
  65. <tr><td>plugins</td><td>buildscript</td></tr>
  66. <tr><td>
  67. Define plugin in root build.gradle.kts
  68. ```kotlin
  69. plugins {
  70. ...
  71. id("io.github.takahirom.roborazzi") version "[version]" apply false
  72. }
  73. ```
  74. Apply plugin in module build.gradle.kts
  75. ```kotlin
  76. plugins {
  77. ...
  78. id("io.github.takahirom.roborazzi")
  79. }
  80. ```
  81. </td><td>
  82. root build.gradle.kts
  83. ```kotlin
  84. buildscript {
  85. dependencies {
  86. ...
  87. classpath("io.github.takahirom.roborazzi:roborazzi-gradle-plugin:[version]")
  88. }
  89. }
  90. ```
  91. module build.gradle.kts
  92. ```kotlin
  93. plugins {
  94. ...
  95. id("io.github.takahirom.roborazzi")
  96. }
  97. ```
  98. </td></tr>
  99. </table>
  100. <details>
  101. <summary>build.gradle version</summary>
  102. <table>
  103. <tr><td>plugins</td><td>buildscript</td></tr>
  104. <tr><td>
  105. Define plugin in root build.gradle
  106. ```groovy
  107. plugins {
  108. ...
  109. id "io.github.takahirom.roborazzi" version "[version]" apply false
  110. }
  111. ```
  112. Apply plugin in module build.gradle
  113. ```groovy
  114. plugins {
  115. ...
  116. id 'io.github.takahirom.roborazzi'
  117. }
  118. ```
  119. </td><td>
  120. root build.gradle
  121. ```groovy
  122. buildscript {
  123. dependencies {
  124. ...
  125. classpath "io.github.takahirom.roborazzi:roborazzi-gradle-plugin:[version]"
  126. }
  127. }
  128. ```
  129. module build.gradle
  130. ```groovy
  131. apply plugin: "io.github.takahirom.roborazzi"
  132. ```
  133. </td></tr>
  134. </table>
  135. </details>
  136. ## Add dependencies
  137. | Description | Dependencies |
  138. |-----------------|--------------------------------------------------------------------------------------|
  139. | Core functions | `testImplementation("io.github.takahirom.roborazzi:roborazzi:[version]")` |
  140. | Jetpack Compose | `testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:[version]")` |
  141. | JUnit rules | `testImplementation("io.github.takahirom.roborazzi:roborazzi-junit-rule:[version]")` |
  142. ## Run tasks
  143. <table>
  144. <tr>
  145. <td> Use Roborazzi task </td> <td> Use default unit test task </td> <td> Description </td>
  146. </tr>
  147. <tr>
  148. <td>
  149. `./gradlew recordRoborazziDebug`
  150. </td><td>
  151. `./gradlew testDebugUnitTest` after adding `roborazzi.test.record=true` to your gradle.properties file.
  152. or
  153. `./gradlew testDebugUnitTest -Proborazzi.test.record=true`
  154. </td><td>
  155. Record a screenshot
  156. Default output directory is `build/outputs/roborazzi`
  157. You can check a report under `build/reports/roborazzi/index.html`
  158. </td>
  159. </tr>
  160. <tr>
  161. <td>
  162. `./gradlew compareRoborazziDebug`
  163. </td><td>
  164. `./gradlew testDebugUnitTest` after adding `roborazzi.test.compare=true` to your gradle.properties file.
  165. or
  166. `./gradlew testDebugUnitTest -Proborazzi.test.compare=true`
  167. </td><td>
  168. Review changes made to an image. This action will
  169. compare the current image with the saved one, generating a comparison image labeled
  170. as `[original]_compare.png`. It also produces a JSON file containing the diff information, which can
  171. be found under `build/test-results/roborazzi`.
  172. </td>
  173. </tr>
  174. <tr>
  175. <td>
  176. `./gradlew verifyRoborazziDebug`
  177. </td><td>
  178. `./gradlew testDebugUnitTest` after adding `roborazzi.test.verify=true` to your gradle.properties file.
  179. or
  180. `./gradlew testDebugUnitTest -Proborazzi.test.verify=true`
  181. </td><td>
  182. Validate changes made to an image. If there is any difference between the current image and the
  183. saved one, the test will fail.
  184. </td>
  185. </tr>
  186. <tr>
  187. <td>
  188. `./gradlew verifyAndRecordRoborazziDebug`
  189. </td><td>
  190. `./gradlew testDebugUnitTest` after adding `roborazzi.test.verify=true` and `roborazzi.test.record=true` to your gradle.properties file.
  191. or
  192. `./gradlew testDebugUnitTest -Proborazzi.test.verify=true -Proborazzi.test.record=true`
  193. </td><td>
  194. This task will first verify the images and, if differences are detected, it will record a new
  195. baseline.
  196. </td>
  197. </tr>
  198. <tr>
  199. <td>
  200. `./gradlew clearRoborazziDebug`
  201. </td><td>
  202. This is not a test task.
  203. </td><td>
  204. Note: This is an experimental task.
  205. This task will clear the saved images. This task also deletes the cached images.
  206. Please be careful when using this task.
  207. </td>
  208. </tr>
  209. </table>
  210. The comparison image, saved as `[original]_compare.png`, is shown below:
  211. ![Comparison image highlighting the differences between the recorded and actual screenshots](https://github.com/takahirom/roborazzi/assets/1386930/722090ff-77c4-4a04-a0e3-8ce562ffa6be)
  212. You can check the test report in `build/reports/roborazzi/index.html`
  213. <img width="400" alt="image" src="https://github.com/takahirom/roborazzi/assets/1386930/7834a436-1927-438d-8656-61f583ae3f48" />
  214. This
  215. uses [JetNew from Compose Samples](https://github.com/android/compose-samples/tree/main/JetNews).
  216. You can check the pull request introducing Roborazzi to the
  217. compose-samples [here](https://github.com/takahirom/compose-samples/pull/1/files).
  218. ## Gradle DSL Options (Optional)
  219. Roborazzi uses `module/build/outputs/roborazzi` as the default directory for reference images and comparison images. You can customize these paths in your `build.gradle` file:
  220. ```kotlin
  221. roborazzi {
  222. // Directory for reference images
  223. outputDir.set(file("src/screenshots"))
  224. // Directory for comparison images (Experimental option)
  225. compare {
  226. outputDir.set(file("build/outputs/screenshots_comparison"))
  227. }
  228. }
  229. ```
  230. > [!NOTE]
  231. > By default, when you use `captureRoboImage("image.png")`, the image will be saved as `module/image.png`.
  232. > You can customize the file path strategy for the recorded image. The default strategy is `relativePathFromCurrentDirectory`. If you select `relativePathFromRoborazziContextOutputDirectory`, the file will be saved in the output directory specified by `roborazzi.outputDir`.
  233. > This can be configured in your `gradle.properties` file:
  234. >
  235. > ```properties
  236. > roborazzi.record.filePathStrategy=relativePathFromRoborazziContextOutputDirectory
  237. > ```
  238. ### Separate output directories per variant/target (Experimental)
  239. By default, every Roborazzi task shares a single output directory (`build/outputs/roborazzi`) and a single intermediate directory (`build/intermediates/roborazzi`). When multiple Roborazzi test tasks run in a single Gradle invocation (for example `check`, or Kotlin Multiplatform's `allTests`), their directory reads and writes can race with each other. On Gradle 9 this can hard-fail with `Cannot access input property 'roborazziImageInput'` (see [#830](https://github.com/takahirom/roborazzi/issues/830)).
  240. Enabling `separateOutputDirs` gives each task slug its own subdirectory, so the tasks never share a directory:
  241. ```kotlin
  242. roborazzi {
  243. // Experimental
  244. separateOutputDirs.set(true)
  245. }
  246. ```
  247. The unit of separation is the `recordRoborazzi<Slug>` slug:
  248. - Android: the variant name, e.g. `build/outputs/roborazzi/debug/`, `build/outputs/roborazzi/release/`.
  249. - Kotlin Multiplatform: the target (Γ— test run) name, e.g. `build/outputs/roborazzi/desktop/`.
  250. The intermediate directory is separated the same way (e.g. `build/intermediates/roborazzi/debug/`). If you set a custom `outputDir`, the per-slug subdirectory is created under it.
  251. > [!IMPORTANT]
  252. > Enabling this option changes where golden images are stored. Existing users must re-record (or manually move) their goldens into the new per-slug subdirectory, otherwise verification will not find them. This is opt-in and defaults to `false`, so existing behavior is unchanged unless you enable it.
  253. >
  254. > This also partially addresses requests for per-flavor/variant subdirectories ([#804](https://github.com/takahirom/roborazzi/issues/804), [#731](https://github.com/takahirom/roborazzi/issues/731)).
  255. <!-- end -->
  256. <!-- topic_how_to_use -->
  257. <!-- Generated by docs/topics/how_to_use.md. Do not edit this file. -->
  258. # How to use
  259. ## Take a screenshot manually
  260. You can take a screenshot by calling captureRoboImage().
  261. app/src/test/java/../ManualTest.kt
  262. ```kotlin
  263. import androidx.compose.ui.test.junit4.createAndroidComposeRule
  264. import androidx.test.core.app.ActivityScenario
  265. import androidx.test.espresso.Espresso.onView
  266. import androidx.test.ext.junit.runners.AndroidJUnit4
  267. import org.junit.Test
  268. import org.junit.runner.RunWith
  269. import org.robolectric.annotation.GraphicsMode
  270. // All you need to do is use the captureRoboImage function in the test!
  271. import com.github.takahirom.roborazzi.captureRoboImage
  272. // Tips: You can use Robolectric while using AndroidJUnit4
  273. @RunWith(AndroidJUnit4::class)
  274. // Enable Robolectric Native Graphics (RNG)
  275. @GraphicsMode(GraphicsMode.Mode.NATIVE)
  276. class ManualTest {
  277. @get:Rule
  278. val composeTestRule = createAndroidComposeRule<MainActivity>()
  279. @Test
  280. fun captureRoboImageSample() {
  281. // Tips: You can use Robolectric with Espresso API
  282. // launch
  283. ActivityScenario.launch(MainActivity::class.java)
  284. // Capture screen
  285. onView(ViewMatchers.isRoot())
  286. // If you don't specify a screenshot file name, Roborazzi will automatically use the method name as the file name for you.
  287. // The format of the file name will be as follows:
  288. // build/outputs/roborazzi/com_..._ManualTest_captureRoboImageSample.png
  289. .captureRoboImage()
  290. // Capture Jetpack Compose Node
  291. composeTestRule.onNodeWithTag("AddBoxButton")
  292. .onParent()
  293. .captureRoboImage("build/compose.png")
  294. }
  295. }
  296. ```
  297. Roborazzi supports the following APIs.
  298. <table>
  299. <tr><td>Capture</td><td>Code</td></tr>
  300. <tr><td>
  301. βœ… Jetpack Compose's onNode()
  302. </td><td>
  303. ```kotlin
  304. composeTestRule.onNodeWithTag("AddBoxButton")
  305. .captureRoboImage()
  306. ```
  307. </td></tr>
  308. <tr><td>
  309. βœ… Espresso's onView()
  310. </td><td>
  311. ```kotlin
  312. onView(ViewMatchers.isRoot())
  313. .captureRoboImage()
  314. ```
  315. ```kotlin
  316. onView(withId(R.id.button_first))
  317. .captureRoboImage()
  318. ```
  319. </td></tr>
  320. <tr><td>
  321. βœ… View
  322. </td><td>
  323. ```kotlin
  324. val view: View = composeTestRule.activity.findViewById<View>(R.id.button_second)
  325. view.captureRoboImage()
  326. ```
  327. </td></tr>
  328. <tr><td>
  329. βœ… Jetpack Compose lambda
  330. </td><td>
  331. ```kotlin
  332. captureRoboImage() {
  333. Text("Hello Compose!")
  334. }
  335. ```
  336. </td></tr>
  337. <tr><td>
  338. ExperimentalπŸ§ͺ<br/>
  339. βœ… Captures the entire screen, including dialogs
  340. </td><td>
  341. ```kotlin
  342. captureScreenRoboImage()
  343. ```
  344. </td></tr>
  345. <tr><td>
  346. βœ… Bitmap
  347. </td><td>
  348. ```kotlin
  349. val bitmap: Bitmap = createBitmap(100, 100, Bitmap.Config.ARGB_8888)
  350. .apply {
  351. applyCanvas {
  352. drawColor(android.graphics.Color.YELLOW)
  353. }
  354. }
  355. bitmap.captureRoboImage()
  356. ```
  357. </td></tr>
  358. </table>
  359. ## Device configuration
  360. You can configure the device by using the `@Config` annotation and `RobolectricDeviceQualifiers`.
  361. <table>
  362. <tr><td>Configuration</td><td>Code</td></tr>
  363. <tr><td>
  364. βœ… Predefined device configuration
  365. </td><td>
  366. You can change the device configuration by adding `@Config` to the class or method.
  367. ```kotlin
  368. @RunWith(AndroidJUnit4::class)
  369. @GraphicsMode(GraphicsMode.Mode.NATIVE)
  370. @Config(qualifiers = RobolectricDeviceQualifiers.Pixel5)
  371. class RoborazziTest {
  372. ```
  373. ```kotlin
  374. @Test
  375. @Config(qualifiers = RobolectricDeviceQualifiers.Pixel5)
  376. fun test() {
  377. ```
  378. </td></tr>
  379. <tr><td>
  380. βœ… Night mode
  381. </td><td>
  382. ```kotlin
  383. @Config(qualifiers = "+night")
  384. ```
  385. </td></tr>
  386. <tr><td>
  387. βœ… Locale
  388. </td><td>
  389. ```kotlin
  390. @Config(qualifiers = "+ja")
  391. ```
  392. </td></tr>
  393. <tr><td>
  394. βœ… Screen size
  395. </td><td>
  396. ```kotlin
  397. @Config(qualifiers = RobolectricDeviceQualifiers.MediumTablet)
  398. ```
  399. </td></tr>
  400. </table>
  401. ## Integrate to your GitHub Actions
  402. See [Integrate to your GitHub Actions](https://takahirom.github.io/roborazzi/github-actions.html)
  403. for CI workflows that store, verify, and compare screenshots.
  404. ## RoborazziRule (Optional)
  405. RoborazziRule is a JUnit rule for Roborazzi.
  406. RoborazziRule is **optional**. You can use `captureRoboImage()` without this rule.
  407. RoborazziRule has two features.
  408. 1. Provide context such as `RoborazziOptions` and `outputDirectoryPath` etc for `captureRoboImage()`.
  409. 2. Capture screenshots for each test when specifying RoborazziRule.options.captureType.
  410. For example, The following code generates an output file
  411. named `**custom_outputDirectoryPath**/**custom_outputFileProvider**-com.github.takahirom.roborazzi.sample.RuleTestWithPath.captureRoboImage.png` :
  412. ```kotlin
  413. @RunWith(AndroidJUnit4::class)
  414. @GraphicsMode(GraphicsMode.Mode.NATIVE)
  415. class RuleTestWithPath {
  416. @get:Rule
  417. val roborazziRule = RoborazziRule(
  418. options = Options(
  419. outputDirectoryPath = "$DEFAULT_ROBORAZZI_OUTPUT_DIR_PATH/custom_outputDirectoryPath",
  420. outputFileProvider = { description, outputDirectory, fileExtension ->
  421. File(
  422. outputDirectory,
  423. "custom_outputFileProvider-${description.testClass.name}.${description.methodName}.$fileExtension"
  424. )
  425. }
  426. ),
  427. )
  428. @Test
  429. fun captureRoboImage() {
  430. launch(MainActivity::class.java)
  431. // The file will be saved using the rule's outputDirectoryPath and outputFileProvider
  432. onView(isRoot()).captureRoboImage()
  433. }
  434. }
  435. ```
  436. To record test interactions as animated images (`captureRoboGif()`, `recordRoboVideo()`),
  437. see [Capture GIFs and videos](https://takahirom.github.io/roborazzi/gif-and-video.html).
  438. ### RoborazziRule options
  439. `RoborazziRule.Options` has:
  440. - `captureType` β€” what the rule captures per test: `None` (default; the rule only provides
  441. context), `LastImage`, `AllImage` (an image per layout change, like `TestClass_method_0.png`),
  442. or `Gif`. The image-generating types take `onlyFail = true` to capture only when the test
  443. fails. Annotate a test with `@RoborazziRule.Ignore` to exclude it from these capture types.
  444. - `outputDirectoryPath` / `outputFileProvider` β€” where output files go and how they are named.
  445. - `roborazziOptions` β€” the `RoborazziOptions` provided to `captureRoboImage()` in the test.
  446. See [RoborazziRule](https://github.com/takahirom/roborazzi/blob/main/roborazzi-junit-rule/src/main/java/com/github/takahirom/roborazzi/RoborazziRule.kt)
  447. for the full definition.
  448. #### Image comparator custom settings
  449. When comparing images, you may encounter differences due to minor changes related to antialiasing. You can use the options below to avoid this.
  450. ```kotlin
  451. @get:Rule
  452. val roborazziRule = RoborazziRule(
  453. options = RoborazziRule.Options(
  454. roborazziOptions = RoborazziOptions(
  455. compareOptions = RoborazziOptions.CompareOptions(
  456. changeThreshold = 0.01, // For 1% accepted difference
  457. imageComparator = SimpleImageComparator(
  458. maxDistance = 0.007F, // 0.001F is default value from Differ
  459. vShift = 2, // Increasing the shift can help resolve antialiasing issues
  460. hShift = 2 // Increasing the shift can help resolve antialiasing issues
  461. )
  462. )
  463. )
  464. )
  465. )
  466. ```
  467. ## Experimental WebP support and other image formats
  468. You can set `roborazzi.record.image.extension` to `webp` in your `gradle.properties` file to generate WebP images.
  469. ```kotlin
  470. roborazzi.record.image.extension=webp
  471. ```
  472. 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.
  473. To enable WebP support, add `testImplementation("io.github.darkxanter:webp-imageio:0.3.3")` to your `build.gradle.kts` file.
  474. ```kotlin
  475. onView(ViewMatchers.withId(R.id.textview_first))
  476. .captureRoboImage(
  477. roborazziOptions = RoborazziOptions(
  478. recordOptions = RoborazziOptions.RecordOptions(
  479. imageIoFormat = LosslessWebPImageIoFormat(),
  480. ),
  481. )
  482. )
  483. ```
  484. You can also use other image formats by implementing your own `AwtImageWriter` and `AwtImageLoader`.
  485. ```kotlin
  486. data class JvmImageIoFormat(
  487. val awtImageWriter: AwtImageWriter,
  488. val awtImageLoader: AwtImageLoader
  489. ) : ImageIoFormat
  490. ```
  491. ## Dump mode
  492. If you are having trouble debugging your test, try Dump mode as follows.
  493. ![image](https://user-images.githubusercontent.com/1386930/226364158-a07a0fb0-d8e7-46b7-a495-8dd217faaadb.png)
  494. For a machine-readable version of the UI tree for tools and AI agents, see
  495. [UI tree dump (JSON)](https://takahirom.github.io/roborazzi/ui-tree-dump.html).
  496. ## Accessibility Check
  497. Roborazzi Accessibility Checks is a library that integrates accessibility checks into Roborazzi.
  498. Please refer to [Accessibility Check](https://github.com/takahirom/roborazzi/blob/main/roborazzi-accessibility-check/README.md)
  499. ## Accessibility legend
  500. The `AccessibilityLegend` capture type (experimental) renders the screenshot next to a legend of the elements a screen
  501. reader focuses, numbered in traversal order. It is recorded and verified like any other screenshot, so a changed label,
  502. role, state or order shows up as a golden diff.
  503. ```kotlin
  504. composeTestRule.onRoot().captureRoboImage(
  505. roborazziOptions = RoborazziOptions(
  506. captureType = RoborazziOptions.CaptureType.AccessibilityLegend(),
  507. ),
  508. )
  509. ```
  510. <img src="https://github.com/user-attachments/assets/0a05ee3d-befb-46ca-8554-187df0dacd53" alt="Accessibility legend example" width="600" />
  511. For each element the legend shows:
  512. - the label: content description or text; for a clickable container, the texts of its descendants;
  513. - the role (Button, Checkbox, Switch, Tab, Slider, Heading, EditText, …), the state (checked, selected, disabled or a
  514. state description) and the value of sliders and progress bars;
  515. - for text fields, the value, hint, error and whether it is a password;
  516. - live regions and pane titles;
  517. - `⚠ NO LABEL` for a clickable element without a label.
  518. The numbers sit in a column next to the screenshot, so they don't cover the UI. Colors come from a hash of the element's
  519. text, so inserting an element rarely recolors the others.
  520. Compose content is read from the merged semantics tree in the order Compose reports to screen readers. Views are read
  521. from `AccessibilityNodeInfo`, so `AccessibilityDelegate`s are taken into account. Compose computes the order only while
  522. a screen reader is on, so the capture turns one on in Robolectric while it reads the tree and restores the previous
  523. state afterwards. The screenshot itself is taken before that.
  524. The legend approximates what TalkBack reads; it doesn't run TalkBack. It works on Android with Robolectric only.
  525. Views that expose virtual children through their own `AccessibilityNodeProvider` (for example charts or custom widgets)
  526. are not expanded: their virtual children don't appear in the legend.
  527. ## Roborazzi options
  528. Please check out [RoborazziOptions](https://github.com/takahirom/roborazzi/blob/main/include-build/roborazzi-core/src/commonJvmMain/kotlin/com/github/takahirom/roborazzi/RoborazziOptions.kt) for available Roborazzi options.
  529. <!-- end -->
  530. <!-- topic_ui_tree_dump -->
  531. <!-- Generated by docs/topics/ui_tree_dump.md. Do not edit this file. -->
  532. # UI tree dump (JSON)
  533. While [Dump mode](https://takahirom.github.io/roborazzi/how-to-use.html#dump-mode)
  534. renders the UI tree *into an image* for humans, **UI tree dump** writes a
  535. machine-readable JSON **sidecar** next to the screenshot it describes, for tools
  536. and AI agents to read. When enabled, capturing `MyTest.png` also writes
  537. `MyTest.uitree.json` (the Compose semantics + View hierarchy of the current run)
  538. and, by default, an annotated `MyTest.annotated.png` (see
  539. [Annotated image](#annotated-image-set-of-mark) below).
  540. The sidecar is written on record and compare/verify, next to the image the task
  541. writes: `MyTest.uitree.json` on record, and `MyTest_actual.uitree.json` in the
  542. compare output directory on compare/verify (an unchanged verify still writes it).
  543. The sidecar is **informational only**: it never participates in image diffing and
  544. never fails verification. Bitmap-based `captureRoboImage(Bitmap...)` captures
  545. (which have no component tree) do not produce one.
  546. Supported on Android/Robolectric, Compose Desktop, and Compose iOS, with identical
  547. output.
  548. ## Enabling it
  549. Via the Gradle property (no code change):
  550. ```shell
  551. ./gradlew recordRoborazziDebug -Proborazzi.dumpUiTree=true
  552. ```
  553. Or per capture via `RoborazziOptions`:
  554. ```kotlin
  555. onView(ViewMatchers.isRoot())
  556. .captureRoboImage(
  557. roborazziOptions = RoborazziOptions(
  558. uiTreeDumpOptions = UiTreeDumpOptions()
  559. )
  560. )
  561. ```
  562. ## Format
  563. ```json
  564. { "schemaVersion": 1, "capture": { "imageWidth": 220, "imageHeight": 100, "scale": 1.0 }, "root":
  565. { "type": "view", "className": "androidx.compose.ui.platform.ComposeView", "bounds": [0, 0, 220, 100], "children": [
  566. { "n": 1, "type": "compose", "testTag": "login_button", "bounds": [16, 24, 204, 72], "properties": { "Role": "Button", "Text": "Login" }, "actions": ["OnClick"], "flags": ["MergeDescendants"] },
  567. { "n": 2, "type": "compose", "bounds": [16, 80, 204, 96], "properties": { "Text": "Forgot password?" } } ] }
  568. }
  569. ```
  570. The format is deliberately grep-first: one node per line with all of its scalar
  571. attributes, so a single `grep` finds a node and its coordinates.
  572. * `bounds` is `[left, top, right, bottom]` in **RAW (unscaled) window pixel**
  573. coordinates; the root `capture` object carries the output `imageWidth`/
  574. `imageHeight` and `scale`. Map to image pixels with
  575. `image = (raw βˆ’ root.bounds origin) Γ— capture.scale` β€” the root origin is
  576. `0, 0` for full-screen captures.
  577. * Empty/default fields are omitted (no empty maps/lists, no `visibility` when the
  578. node is visible).
  579. * `n` is a sequential (1-based, pre-order) number on *annotatable* nodes only β€”
  580. visible nodes with a test tag, a `Text`/`ContentDescription`, or an action; a
  581. numbered `MergeDescendants` node's descendants are skipped.
  582. * Output is **deterministic**: the same UI produces byte-identical JSON (no
  583. timestamps, no hashes).
  584. ## Annotated image (Set-of-Mark)
  585. "Set-of-Mark" refers to a prompting technique for vision-language models:
  586. overlaying numbered marks on image regions lets a model refer to a region
  587. unambiguously by its number ([Yang et al., 2023](https://arxiv.org/abs/2310.11441)).
  588. <img width="440" alt="Annotated Set-of-Mark image" src="https://github.com/user-attachments/assets/208593c3-cd2b-4c0a-ae5b-e7cf6cd0260e" />
  589. Written by default next to the screenshot β€” a copy of the output with every
  590. numbered node drawn as a labelled box β€” under the same naming as the sidecar:
  591. `MyTest.annotated.png` on record, `MyTest_actual.annotated.png` on compare/verify
  592. (an unchanged verify annotates the identical golden).
  593. Each box's number is the same `n` as in the JSON, so an agent can point at
  594. "element #3" and look up `"n": 3` for its exact bounds, properties, and actions.
  595. The annotated image is a **display artifact of the current run only** β€” never
  596. compared, never failing a capture, never treated as a golden. Opt out with
  597. `UiTreeDumpOptions(annotateImage = false)`.
  598. The annotated image is only written for the default screenshot capture type. Other
  599. capture types, such as `CaptureType.Dump()`, place the screenshot among other
  600. content, so the boxes would be drawn in the wrong place; for them only the sidecar
  601. is written.
  602. ## Primary use case: letting an AI agent prove its UI fixes
  603. AI agents are bad at judging small layout changes from screenshots β€” ask one to
  604. "add margin above the button" and it will often claim "fixed" when nothing moved.
  605. The deterministic UI tree gives it exact coordinates to check instead, so the
  606. agent can read the button's bounds before and after and prove the change actually
  607. landed.
  608. 1. Record and read the node line:
  609. ```shell
  610. ./gradlew recordRoborazziDebug -Proborazzi.dumpUiTree=true
  611. grep login_button build/outputs/roborazzi/MyTest.uitree.json
  612. # { "n": 1, "testTag": "login_button", "bounds": [16, 24, 204, 72], ... }
  613. ```
  614. `bounds` is `[left, top, right, bottom]`, so the top edge is at `24`.
  615. 2. Make the change, keeping that `before` value in context.
  616. 3. Re-record (it overwrites the sidecar in place) and grep the same line:
  617. ```text
  618. # { "n": 1, "testTag": "login_button", "bounds": [16, 32, 204, 80], ... }
  619. ```
  620. Top moved `24 β†’ 32` β€” the button provably sits 8px lower. (To prove a *gap*,
  621. also compare the sibling above: its `bottom` vs this `top`.) Because the output
  622. is deterministic, any change in the numbers is a real layout change, not noise.
  623. <!-- end -->
  624. <!-- topic_github_actions -->
  625. <!-- Generated by docs/topics/github_actions.md. Do not edit this file. -->
  626. # Integrate to your GitHub Actions
  627. It is easy to integrate Roborazzi to your GitHub Actions.
  628. ## Add a job to store screenshots
  629. ```yaml
  630. name: store screenshots
  631. on:
  632. push
  633. env:
  634. GRADLE_OPTS: "-Dorg.gradle.jvmargs=-Xmx6g -Dorg.gradle.daemon=false -Dkotlin.incremental=false"
  635. jobs:
  636. test:
  637. runs-on: macos-latest
  638. steps:
  639. - uses: actions/checkout@v4
  640. - uses: actions/setup-java@v4
  641. with:
  642. distribution: 'zulu'
  643. java-version: 19
  644. - name: Setup Gradle
  645. uses: gradle/actions/setup-gradle@v4
  646. - name: test
  647. run: |
  648. # Create screenshots
  649. ./gradlew app:recordRoborazziDebug --stacktrace
  650. # Upload screenshots to GitHub Actions Artifacts
  651. - uses: actions/upload-artifact@v4
  652. with:
  653. name: screenshots
  654. path: app/build/outputs/roborazzi
  655. retention-days: 30
  656. ```
  657. ## Add a job to verify screenshots
  658. ```yaml
  659. name: verify test
  660. on:
  661. push
  662. env:
  663. GRADLE_OPTS: "-Dorg.gradle.jvmargs=-Xmx6g -Dorg.gradle.daemon=false -Dkotlin.incremental=false"
  664. jobs:
  665. test:
  666. runs-on: macos-latest
  667. steps:
  668. - uses: actions/checkout@v4
  669. - uses: actions/setup-java@v4
  670. with:
  671. distribution: 'zulu'
  672. java-version: 19
  673. - name: Setup Gradle
  674. uses: gradle/actions/setup-gradle@v4
  675. # Download screenshots from main branch
  676. - uses: dawidd6/action-download-artifact@v6
  677. with:
  678. name: screenshots
  679. path: app/build/outputs/roborazzi
  680. workflow: test.yaml
  681. branch: main
  682. - name: verify test
  683. id: verify-test
  684. run: |
  685. # If there is a difference between the screenshots, the test will fail.
  686. ./gradlew app:verifyRoborazziDebug --stacktrace
  687. - uses: actions/upload-artifact@v4
  688. if: ${{ always() }}
  689. with:
  690. name: screenshot-diff
  691. path: app/build/outputs/roborazzi
  692. retention-days: 30
  693. - uses: actions/upload-artifact@v4
  694. if: ${{ always() }}
  695. with:
  696. name: screenshot-diff-reports
  697. path: app/build/reports
  698. retention-days: 30
  699. - uses: actions/upload-artifact@v4
  700. if: ${{ always() }}
  701. with:
  702. name: screenshot-diff-test-results
  703. path: app/build/test-results
  704. retention-days: 30
  705. ```
  706. ## Advanced workflow Sample: Compare Snapshot Results on Pull Requests
  707. For those who are looking for a more advanced example, we have prepared a sample repository that
  708. demonstrates how to use Roborazzi to compare snapshot results on GitHub pull requests. This sample
  709. showcases the integration of Roborazzi with GitHub Actions workflows, making it easy to visualize
  710. and review the differences between snapshots directly in the pull request comments.
  711. Check out
  712. the [roborazzi-compare-on-github-comment-sample](https://github.com/takahirom/roborazzi-compare-on-github-comment-sample)
  713. repository to see this powerful feature in action and learn how to implement it in your own
  714. projects.
  715. Example of the comment
  716. <img alt="Example of a Roborazzi screenshot comparison comment on a GitHub pull request" src="https://user-images.githubusercontent.com/1386930/236480693-80483cde-53fe-4c04-ba1f-2352e14b5f15.png" width="600" />
  717. <!-- end -->
  718. <!-- topic_gif_and_video -->
  719. <!-- Generated by docs/topics/gif_and_video.md. Do not edit this file. -->
  720. # Capture GIFs and videos
  721. Roborazzi can record test interactions as animated images: `captureRoboGif()`
  722. captures visually distinct states as a GIF, and `recordRoboVideo()` records
  723. animations frame by frame over virtual time.
  724. ## Generate gif image
  725. ```kotlin
  726. @Test
  727. fun captureRoboGifSample() {
  728. onView(ViewMatchers.isRoot())
  729. .captureRoboGif("build/test.gif") {
  730. // launch
  731. ActivityScenario.launch(MainActivity::class.java)
  732. // move to next page
  733. onView(withId(R.id.button_first))
  734. .perform(click())
  735. // back
  736. pressBack()
  737. // move to next page
  738. onView(withId(R.id.button_first))
  739. .perform(click())
  740. }
  741. }
  742. ```
  743. <img alt="GIF of the test interactions captured by captureRoboGif" width="350" src="https://user-images.githubusercontent.com/1386930/226362212-35d34c9e-6df1-4671-8949-10fad7ad98c9.gif" />
  744. ## Generate gif with test rule
  745. > **Note**
  746. > You **don't need to use RoborazziRule** if you're using captureRoboGif().
  747. With the JUnit test rule, you do not need to name the gif image,
  748. and if you prefer, you can output the gif image **only if the test fails**.
  749. This test will output this file.
  750. `build/outputs/roborazzi/com.github.takahirom.roborazzi.sample.RuleTestWithOnlyFail_captureRoboGifSampleFail.gif`
  751. ```kotlin
  752. @RunWith(AndroidJUnit4::class)
  753. @GraphicsMode(GraphicsMode.Mode.NATIVE)
  754. class RuleTestWithOnlyFail {
  755. @get:Rule
  756. val roborazziRule = RoborazziRule(
  757. captureRoot = onView(isRoot()),
  758. options = Options(
  759. captureType = RoborazziRule.CaptureType.Gif(
  760. onlyFail = true
  761. ),
  762. )
  763. )
  764. @Test
  765. fun captureRoboGifSampleFail() {
  766. // launch
  767. ActivityScenario.launch(MainActivity::class.java)
  768. // move to next page
  769. onView(withId(R.id.button_first))
  770. .perform(click())
  771. // should fail because the button does not exist
  772. // Due to failure, the gif image will be saved in the outputs folder.
  773. onView(withId(R.id.button_first))
  774. .perform(click())
  775. }
  776. }
  777. ```
  778. ## Generate Jetpack Compose gif with test rule
  779. Test target
  780. ```kotlin
  781. @Composable
  782. fun SampleComposableFunction() {
  783. var count by remember { mutableStateOf(0) }
  784. Column(
  785. Modifier
  786. .size(300.dp)
  787. ) {
  788. Box(
  789. Modifier
  790. .testTag("AddBoxButton")
  791. .size(50.dp)
  792. .clickable {
  793. count++
  794. }
  795. )
  796. (0..count).forEach {
  797. Box(
  798. Modifier
  799. .size(30.dp)
  800. )
  801. }
  802. }
  803. }
  804. ```
  805. Test (Just add RoborazziRule)
  806. ```kotlin
  807. @RunWith(AndroidJUnit4::class)
  808. @GraphicsMode(GraphicsMode.Mode.NATIVE)
  809. class ComposeTest {
  810. @get:Rule
  811. val composeTestRule = createAndroidComposeRule<ComponentActivity>()
  812. @get:Rule
  813. val roborazziRule = RoborazziRule(
  814. composeRule = composeTestRule,
  815. captureRoot = composeTestRule.onRoot(),
  816. options = RoborazziRule.Options(
  817. RoborazziRule.CaptureType.Gif()
  818. )
  819. )
  820. @Test
  821. fun composable() {
  822. composeTestRule.setContent {
  823. SampleComposableFunction()
  824. }
  825. (0 until 3).forEach { _ ->
  826. composeTestRule
  827. .onNodeWithTag("AddBoxButton")
  828. .performClick()
  829. }
  830. }
  831. }
  832. ```
  833. ![com github takahirom roborazzi sample ComposeTest_composable](https://user-images.githubusercontent.com/1386930/226366224-b9950b60-26a2-489e-bc03-08bfb86c533a.gif)
  834. ## Record a video of the UI (experimental)
  835. `recordRoboVideo()` records how the UI evolves over virtual time -- animations, transitions,
  836. gestures and any other time-driven change -- as an animated image that plays back in real time.
  837. Unlike `captureRoboGif()`, which only records visually distinct states with a fixed 1-second
  838. delay, it pauses the Compose main clock and drives it frame by frame, so intermediate animation
  839. frames are captured with faithful timing. Interactions in the block run with the clock paused;
  840. call `delay()` in the scope to advance virtual time while frames are recorded. After the block
  841. returns, recording continues until the UI settles, so a block that only performs a click still
  842. records the whole animation the click starts.
  843. ```kotlin
  844. @OptIn(ExperimentalRoborazziApi::class)
  845. @Test
  846. fun recordVideo() {
  847. composeTestRule.setContent {
  848. AnimatedBoxContent()
  849. }
  850. composeTestRule.onNodeWithTag("root")
  851. .recordRoboVideo(
  852. composeRule = composeTestRule,
  853. filePath = "build/outputs/roborazzi/video.gif",
  854. videoOptions = RoboVideoOptions(fps = 10),
  855. ) {
  856. composeTestRule.onNodeWithTag("toggle").performClick()
  857. delay(300)
  858. composeTestRule.onNodeWithTag("toggle").performClick()
  859. delay(300)
  860. }
  861. }
  862. ```
  863. - `RoboVideoOptions`: `fps` (default `10`), `settleTimeoutMillis` (additional virtual time to
  864. keep recording while the UI is still changing after the block ends; default `3000`), and
  865. `backgroundColor` (ARGB fill for the fixed recording viewport when frames have different
  866. sizes; default white).
  867. - **Output format is chosen by the file extension:** `.gif` produces a GIF (256 colors; the
  868. default), `.png` a lossless, full-color APNG (Animated PNG) -- prefer `.png` when color
  869. fidelity matters. Only these animated-image formats are supported for now; the "video" name
  870. was chosen deliberately so real video formats (e.g. mp4) can be added later without renaming
  871. the API.
  872. - GIF stores frame delays in centiseconds (10ms resolution), so prefer an `fps` whose frame step
  873. (`1000 / fps`) is a multiple of 10ms (e.g. 10, 20, 25, 50) for exact GIF timing. APNG encodes
  874. the step exactly.
  875. - The API is experimental (`@ExperimentalRoborazziApi`) and currently only supports recording:
  876. when the Roborazzi task runs in compare/verify mode it is a complete no-op -- the block is not
  877. executed and no image is recorded or verified.
  878. `recordScreenRoboVideo()` records all window roots instead of a single node, mirroring how
  879. `captureScreenRoboImage()` relates to `captureRoboImage()`. Prefer it when you want a stable,
  880. device-sized viewport for every frame, or to capture window overlays such as dialogs added
  881. mid-recording or touch/tap indicators, which live on separate window roots and are invisible to a
  882. node-scoped recording. Usage is the same, just without node scoping:
  883. ```kotlin
  884. recordScreenRoboVideo(
  885. composeRule = composeTestRule,
  886. filePath = "build/outputs/roborazzi/video_screen.gif",
  887. videoOptions = RoboVideoOptions(fps = 10),
  888. ) {
  889. composeTestRule.onNodeWithTag("toggle").performClick()
  890. delay(300)
  891. }
  892. ```
  893. Because the recorder idles the Robolectric main Looper in lockstep with the Compose main clock,
  894. suspend-based gesture drivers make progress while frames are recorded. For example, you can drive
  895. a swipe with [saket/touch-robot](https://github.com/saket/touch-robot) from a `LaunchedEffect`,
  896. use `recordScreenRoboVideo()` so the touch indicator overlay is captured, and just pump virtual
  897. time in the block:
  898. ```kotlin
  899. composeTestRule.setContent {
  900. // A composable whose LaunchedEffect drives a touch-robot swipe on the root.
  901. DraggableBoxContent()
  902. }
  903. recordScreenRoboVideo(
  904. composeRule = composeTestRule,
  905. filePath = "build/outputs/roborazzi/swipe.gif",
  906. ) {
  907. // Pump virtual time so the LaunchedEffect gesture progresses while frames are captured.
  908. delay(1000)
  909. }
  910. ```
  911. <!-- end -->
  912. <!-- topic_preview_support -->
  913. <!-- Generated by docs/topics/preview_support.md. Do not edit this file. -->
  914. # Experimental Compose Preview Support
  915. Roborazzi provides support for generating screenshot tests and easy setup for Jetpack Compose Preview.
  916. This support uses [ComposablePreviewScanner](https://github.com/sergio-sastre/ComposablePreviewScanner) to scan the Composable Previews in your project.
  917. ## Generate Compose Preview screenshot tests
  918. You first need to add the Roborazzi plugin to your project. Please refer to the [setup guide](https://takahirom.github.io/roborazzi/build-setup.html) for more information.
  919. Then you can enable the Compose Preview screenshot test generation feature by adding the following configuration to your `build.gradle.kts` file:
  920. ```kotlin
  921. roborazzi {
  922. generateComposePreviewRobolectricTests {
  923. enable = true
  924. }
  925. }
  926. ```
  927. 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](https://github.com/takahirom/roborazzi/tree/main/sample-generate-preview-tests) for a complete example.
  928. After that, you can run the `recordRoborazziDebug` task to generate screenshots using the generated tests, as described in the [setup guide](https://takahirom.github.io/roborazzi/build-setup.html).
  929. ### Customizing the Preview screenshot test
  930. You can customize the generated test by adding the following configuration to your `build.gradle.kts` file:
  931. ```kotlin
  932. roborazzi {
  933. @OptIn(ExperimentalRoborazziApi::class)
  934. generateComposePreviewRobolectricTests {
  935. enable = true
  936. // The package names to scan for Composable Previews.
  937. packages = listOf("com.example")
  938. // robolectricConfig will be passed to Robolectric's @Config annotation in the generated test class.
  939. // See https://robolectric.org/configuring/ for more information.
  940. robolectricConfig = mapOf(
  941. "sdk" to "[32]",
  942. "qualifiers" to "RobolectricDeviceQualifiers.Pixel5",
  943. )
  944. // If true, the private previews will be included in the test.
  945. includePrivatePreviews = true
  946. // The fully qualified class name of the custom test class that implements [com.github.takahirom.roborazzi.ComposePreviewTester].
  947. testerQualifiedClassName = "com.example.MyCustomComposePreviewTester"
  948. // The number of test classes to generate. Set this to match maxParallelForks for parallel test execution.
  949. generatedTestClassCount = 4
  950. // Experimental: render at a lower density to make the tests faster and the images smaller.
  951. // See "Making the tests faster with renderScale" below.
  952. // renderScale = 1.0 / 3
  953. // Filter previews by annotation. See "Filtering previews by annotation" below.
  954. annotationFilter = AnnotationFilter.Filter.RoboPreviewInclude
  955. }
  956. }
  957. ```
  958. #### Advanced: Custom ComposePreviewTester Implementation
  959. You can create a custom `ComposePreviewTester` to control the screenshot capture behavior, such as setting a custom image comparison threshold.
  960. 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:
  961. ```kotlin
  962. import com.dropbox.differ.SimpleImageComparator
  963. import com.github.takahirom.roborazzi.*
  964. import com.github.takahirom.roborazzi.ComposePreviewTester.TestParameter.JUnit4TestParameter.AndroidPreviewJUnit4TestParameter
  965. @OptIn(ExperimentalRoborazziApi::class)
  966. class MyCustomComposePreviewTester :
  967. ComposePreviewTester<AndroidPreviewJUnit4TestParameter> by AndroidComposePreviewTester(
  968. capturer = { parameter ->
  969. val customOptions = parameter.roborazziOptions.copy(
  970. compareOptions = parameter.roborazziOptions.compareOptions.copy(
  971. // Set custom comparison threshold (0.0 = exact match, 1.0 = ignore differences)
  972. imageComparator = SimpleImageComparator(maxDistance = 0.01f)
  973. )
  974. )
  975. AndroidComposePreviewTester.DefaultCapturer().capture(
  976. parameter.copy(roborazziOptions = customOptions)
  977. )
  978. }
  979. )
  980. ```
  981. 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.
  982. `Options` is how the Gradle extension reaches your tester: the generated test assigns the configured values to `ComposePreviewTester.defaultOptionsFromPlugin`, and the default `options()` returns them. So when you override `options()`, derive the result with `super.options().copy(...)` instead of constructing a new `Options`, otherwise every setting the plugin configured is silently replaced by defaults. The same applies if you implement `test()` or the capture yourself: read the values from `options()` rather than assuming defaults.
  983. Two settings need extra care with a custom tester:
  984. - `includePrivatePreviews` and `annotationFilter` are consumed by `testParameters()`. Because a custom tester usually overrides it, the plugin rejects the combination unless you set `useScanOptionParametersInTester = true` and read `options().scanOptions` yourself.
  985. - `renderScale` (see [Making the tests faster with `renderScale`](#making-the-tests-faster-with-renderscale)) is consumed at capture time, so the class-delegation pattern above keeps working. If you override `test()` yourself, see the `renderScale` property documentation for what to pass to `preview.toRoborazziComposeOptions(renderScale)`. A tester that drops the value fails the generated test with an explanation, so a silently unscaled screenshot is not possible.
  986. Then reference your custom tester in the Gradle configuration:
  987. ```kotlin
  988. roborazzi {
  989. @OptIn(ExperimentalRoborazziApi::class)
  990. generateComposePreviewRobolectricTests {
  991. enable = true
  992. testerQualifiedClassName = "com.example.MyCustomComposePreviewTester"
  993. }
  994. }
  995. ```
  996. > [!NOTE]
  997. > If you are using Groovy DSL instead of Kotlin DSL, you need to use the set method for each assignment:
  998. > ```kotlin
  999. > generateComposePreviewRobolectricTests.enable.set(true)
  1000. > generateComposePreviewRobolectricTests.packages.set(["com.example"])
  1001. > ```
  1002. ### Making the tests faster with `renderScale`
  1003. If the generated tests are slow or the recorded images are large, `renderScale` is the knob for it.
  1004. A value below 1.0 renders every preview at a lower device density, so fewer pixels are rendered:
  1005. the tests spend less time rendering and the images take less space. What you pay for it is
  1006. fidelity, so it pays off on previews that stay readable at the smaller size.
  1007. What the scale does and does not change β€” density-qualified resources, raw-pixel drawing, the dpi
  1008. rounding, when it is applied β€” is documented on the `renderScale` property itself, which your IDE
  1009. shows as you type it.
  1010. `renderScale` is not the same as `resizeScale`:
  1011. | Property | When it applies | What it changes |
  1012. | --- | --- | --- |
  1013. | `renderScale` | Before Compose renders | Device density. Logical dp dimensions are preserved, so a smaller surface is rendered. Density-qualified resources (`drawable-hdpi` and so on) may resolve differently. |
  1014. | `resizeScale` (`RoborazziOptions.RecordOptions`, `roborazzi.record.resizeScale`) | After the screenshot is captured | Downsamples the captured bitmap. Rendering cost is unchanged. |
  1015. Both change the recorded image dimensions at the same output paths, so existing golden images have to be recorded again after you set either of them.
  1016. In the Groovy DSL, write the value as a `double` literal: `renderScale = 0.5d`. A bare `0.5` is a `BigDecimal` and fails to convert.
  1017. To scale a single preview differently, annotate it with `@RoboComposePreviewOptions(renderScale = ...)`. This is useful when only a few previews are large enough to be worth the loss of fidelity:
  1018. ```kotlin
  1019. @RoboComposePreviewOptions(renderScale = 0.5)
  1020. @Preview(device = "spec:width=1280dp,height=800dp,dpi=240")
  1021. @Composable
  1022. fun TabletPreview() {
  1023. }
  1024. ```
  1025. Previews without the annotation keep the scale configured in the Gradle extension.
  1026. ### Filtering previews by annotation
  1027. `annotationFilter` controls which previews are captured (requires the `roborazzi-annotations` dependency).
  1028. By default it is `AnnotationFilter.Filter.RoboPreviewExclude`, so previews annotated with
  1029. `@RoboPreviewExclude` are skipped. Set it to `RoboPreviewInclude` to capture **only** previews
  1030. annotated with `@RoboPreviewInclude`:
  1031. ```kotlin
  1032. roborazzi {
  1033. @OptIn(ExperimentalRoborazziApi::class)
  1034. generateComposePreviewRobolectricTests {
  1035. enable = true
  1036. packages = listOf("com.example")
  1037. annotationFilter = AnnotationFilter.Filter.RoboPreviewInclude
  1038. }
  1039. }
  1040. ```
  1041. To filter by your own annotations, pass their fully qualified class names
  1042. (use the JVM binary name with `$` for nested classes, e.g. `com.example.Outer$Inner`):
  1043. ```kotlin
  1044. // Set either one, not both
  1045. annotationFilter = AnnotationFilter.Exclude("com.example.MyExcludeAnnotation")
  1046. annotationFilter = AnnotationFilter.Include("com.example.MyIncludeAnnotation")
  1047. ```
  1048. ### Compose Multiplatform previews
  1049. The Compose Preview support also works with Compose Multiplatform common previews (`@Preview` in `commonMain`). You can scan them with the `CommonComposablePreviewScanner` from the ComposablePreviewScanner `common` artifact in a custom tester; the generated tests run as Android unit tests with Robolectric. See the [multiplatform sample project](https://github.com/takahirom/roborazzi/tree/main/sample-generate-preview-tests-multiplatform) for a complete setup.
  1050. ## Experimental Compose Desktop Preview Support
  1051. Roborazzi can also generate preview screenshot tests for the Compose Desktop (JVM)
  1052. target, without Robolectric. Previews are scanned with ComposablePreviewScanner's
  1053. `android` artifact, which is a pure-JVM jar: it finds the multiplatform
  1054. `androidx.compose.ui.tooling.preview.Preview` annotation on the classpath, so previews
  1055. declared in `commonMain` are captured too.
  1056. ### Robolectric or Desktop β€” trade-offs
  1057. - **Fidelity**: Robolectric renders with the Android framework; desktop renders with the
  1058. host's Skia, so the same preview produces different images β€” goldens are per-platform.
  1059. - **Speed**: desktop tests run roughly 4–6x faster than the Robolectric ones ([benchmark](https://github.com/takahirom/roborazzi/pull/903)).
  1060. - **Adoption cost**: requires a Kotlin JVM target β€” a Kotlin Multiplatform `jvm()`
  1061. target or a plain `org.jetbrains.kotlin.jvm` project. For an Android-only project
  1062. that means a KMP migration first β€” stick with the Robolectric preview tests there.
  1063. Desktop tests shine for already-multiplatform code and Desktop-only apps.
  1064. Enable it in your `build.gradle.kts`:
  1065. ```kotlin
  1066. roborazzi {
  1067. @OptIn(ExperimentalRoborazziApi::class)
  1068. generateComposePreviewDesktopTests {
  1069. enable = true
  1070. packages = listOf("com.example")
  1071. // Required only when the project has multiple Kotlin JVM targets:
  1072. // targetName = "desktop"
  1073. }
  1074. }
  1075. ```
  1076. Add the dependencies to the JVM target's test source set. If your previews use the
  1077. Roborazzi marker annotations (`@RoboPreviewExclude`, `@RoboComposePreviewOptions`, ...),
  1078. also add `roborazzi-annotations` to the source set that declares the previews
  1079. (usually `commonMain` β€” test dependencies do not flow into main source sets):
  1080. ```kotlin
  1081. kotlin {
  1082. sourceSets {
  1083. val commonMain by getting {
  1084. dependencies {
  1085. // Only needed when previews use the Roborazzi marker annotations
  1086. implementation("io.github.takahirom.roborazzi:roborazzi-annotations:[version]")
  1087. }
  1088. }
  1089. val desktopTest by getting {
  1090. dependencies {
  1091. implementation("io.github.takahirom.roborazzi:roborazzi-compose-desktop-preview-scanner-support:[version]")
  1092. implementation("io.github.sergio-sastre.ComposablePreviewScanner:android:[version]")
  1093. implementation("junit:junit:4.13.2")
  1094. }
  1095. }
  1096. }
  1097. }
  1098. ```
  1099. Plain JVM projects (`org.jetbrains.kotlin.jvm`) are also supported: add the same
  1100. dependencies with `testImplementation(...)` and use the `Jvm` task names
  1101. (`recordRoborazziJvm`, `compareRoborazziJvm`, `verifyRoborazziJvm`).
  1102. Then run the desktop Roborazzi tasks:
  1103. ```shell
  1104. ./gradlew recordRoborazziDesktop
  1105. ./gradlew compareRoborazziDesktop
  1106. ./gradlew verifyRoborazziDesktop
  1107. ```
  1108. Note: ComposablePreviewScanner is published with JVM 17 metadata, so the desktop
  1109. target needs to target JVM 17 (or relax the test classpath's `TargetJvmVersion`
  1110. attribute). See the [desktop multiplatform sample](https://github.com/takahirom/roborazzi/tree/main/sample-compose-desktop-multiplatform)
  1111. for a complete setup, including manual usage of the tester API without the generator.
  1112. ### Screenshot naming and mixed modules
  1113. Desktop preview screenshots use the same file names as the Robolectric preview tests
  1114. (fully qualified class name + method name + preview parameter suffix), so the same
  1115. preview produces the same file name on both platforms. If one module enables **both**
  1116. `generateComposePreviewRobolectricTests` and `generateComposePreviewDesktopTests`, the
  1117. two sets of screenshots would overwrite each other in the shared output directory, so
  1118. Roborazzi fails with a configuration error unless
  1119. [`separateOutputDirs`](https://takahirom.github.io/roborazzi/build-setup.html#separate-output-directories-per-varianttarget-experimental)
  1120. is enabled, which gives each task its own subdirectory.
  1121. ### Customizing the desktop tester
  1122. `DefaultDesktopComposePreviewTester` accepts a `Capturer` whose receiver is the raw
  1123. `ComposeUiTest` scope, so anything possible inside `runDesktopComposeUiTest` β€” clock
  1124. control, interactions, wrapping the content in a theme β€” stays possible:
  1125. ```kotlin
  1126. @OptIn(ExperimentalRoborazziApi::class, ExperimentalTestApi::class)
  1127. class MyDesktopPreviewTester : DesktopComposePreviewTester by DefaultDesktopComposePreviewTester(
  1128. capturer = DefaultDesktopComposePreviewTester.Capturer { parameter ->
  1129. setContent { MyTheme { parameter.preview() } }
  1130. // Keep @RoboComposePreviewOptions manualClockOptions working: without this,
  1131. // time-suffixed captures would all show the initial state.
  1132. advanceMainClockFor(parameter)
  1133. onRoot().captureRoboImage(parameter.filePath, parameter.roborazziOptions)
  1134. }
  1135. )
  1136. ```
  1137. Reference your tester in the Gradle configuration with
  1138. `testerQualifiedClassName = "com.example.MyDesktopPreviewTester"` (the class needs a
  1139. parameterless constructor). If you need to change scanning or file naming as well,
  1140. implement `DesktopComposePreviewTester` by delegating to the default tester and
  1141. override the corresponding method (`testParameters()` / `test()`).
  1142. To wrap each generated test in a JUnit `TestRule` (a `TestWatcher`, retry rule, etc.),
  1143. override `options()` and provide a `testRuleFactory`:
  1144. ```kotlin
  1145. @OptIn(ExperimentalRoborazziApi::class, InternalRoborazziApi::class)
  1146. class MyDesktopPreviewTester : DesktopComposePreviewTester by DefaultDesktopComposePreviewTester() {
  1147. override fun options(): DesktopComposePreviewTester.Options =
  1148. DesktopComposePreviewTester.defaultOptionsFromPlugin.copy(
  1149. testLifecycleOptions = DesktopComposePreviewTester.Options.JUnit4TestLifecycleOptions(
  1150. testRuleFactory = { MyWatcherRule() }
  1151. )
  1152. )
  1153. }
  1154. ```
  1155. Unlike the Robolectric tester there is no compose rule factory: Compose Desktop's test
  1156. harness is function-scoped (`runDesktopComposeUiTest`), not rule-based.
  1157. ### Feature parity with the Android preview support
  1158. | Feature | Android (Robolectric) | Compose Desktop |
  1159. |---|---|---|
  1160. | Generated preview tests | βœ… | βœ… |
  1161. | `packages`, `includePrivatePreviews`, `testerQualifiedClassName`, `generatedTestClassCount` | βœ… | βœ… |
  1162. | `annotationFilter` (`@RoboPreviewInclude` / `@RoboPreviewExclude`) | βœ… | βœ… |
  1163. | `@PreviewParameter` (`PreviewParameterProvider`, one capture per value) | βœ… | βœ… |
  1164. | `@RoboComposePreviewOptions` (`manualClockOptions`, one test per variation) | βœ… | βœ… |
  1165. | Custom JUnit `TestRule` around generated tests (`testRuleFactory`) | βœ… | βœ… |
  1166. | Compose rule factory (`composeRuleFactory`) | βœ… | Not applicable (function-scoped harness) |
  1167. | `@Preview` annotation options (`widthDp`/`heightDp`, `fontScale`, `showBackground`/`backgroundColor`, `locale`, `uiMode` dark bit) | βœ… (see below) | βœ… |
  1168. | `@Preview(device = ...)` | βœ… | Not applicable (no device configuration on desktop) |
  1169. | `robolectricConfig` (device qualifiers, SDK) | βœ… | Not applicable |
  1170. On Compose Desktop the `@Preview` annotation options are applied as follows:
  1171. - `widthDp`/`heightDp`: the preview is wrapped in a fixed-size box (density is `1`, so 1dp equals 1px). When neither is specified the preview still renders wrap-content.
  1172. - `fontScale`: applied through `LocalDensity` (density stays `1`), because `DeviceConfigurationOverride.FontScale` is unsupported on desktop.
  1173. - `showBackground`/`backgroundColor`: draws a background behind the preview, defaulting to white when `showBackground = true` but no color is given.
  1174. - `locale`: sets `java.util.Locale.getDefault()` for the capture and restores it afterwards. Accepts `"ja"`, `"ja-rJP"`, and `"ja-JP"` forms.
  1175. - `uiMode`: only the night bit is honored (dark mode via `LocalSystemTheme`); other configuration bits are ignored.
  1176. - `device`: not applicable, as desktop has no device configuration.
  1177. ## Annotation-based Capture Control
  1178. To enable fine-grained control over screenshot timing in Compose Previews, add the annotations dependency:
  1179. ```gradle
  1180. testImplementation("io.github.takahirom.roborazzi:roborazzi-annotations:[version]")
  1181. ```
  1182. Use `@RoboComposePreviewOptions` to configure time-based captures:
  1183. ```kotlin
  1184. @RoboComposePreviewOptions(
  1185. manualClockOptions = [ManualClockOptions(advanceTimeMillis = 516L)]
  1186. )
  1187. @Preview
  1188. @Composable
  1189. fun DelayedPreview() {
  1190. var visible by remember { mutableStateOf(false) }
  1191. LaunchedEffect(Unit) {
  1192. delay(500)
  1193. visible = true
  1194. }
  1195. if (visible) {
  1196. Text("Content appears after 500ms")
  1197. }
  1198. }
  1199. ```
  1200. This annotation enables capturing screenshots at specific time intervals, particularly useful for testing animated components or delayed state changes.
  1201. ## PreviewWrapper support
  1202. Previews annotated with [`@PreviewWrapper`](https://developer.android.com/reference/kotlin/androidx/compose/ui/tooling/preview/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:
  1203. ```kotlin
  1204. class MyWrapperProvider : PreviewWrapperProvider {
  1205. @Composable
  1206. override fun Wrap(content: @Composable () -> Unit) {
  1207. MyTheme { content() }
  1208. }
  1209. }
  1210. @PreviewWrapper(MyWrapperProvider::class)
  1211. @Preview
  1212. @Composable
  1213. fun WrappedPreview() { ... }
  1214. ```
  1215. ## Manually adding Compose Preview screenshot tests
  1216. Roborazzi provides a helper function for ComposablePreviewScanner.
  1217. You can add the following dependency to your project to use the helper function:
  1218. `testImplementation("io.github.takahirom.roborazzi:roborazzi-compose-preview-scanner-support:[version]")`
  1219. Then you can use the `ComposablePreview<AndroidPreviewInfo>.captureRoboImage()` function to capture the Composable Preview using the settings in Preview annotations.
  1220. To obtain the `ComposablePreview` object, please refer to [ComposablePreviewScanner](https://github.com/sergio-sastre/ComposablePreviewScanner).
  1221. ```kotlin
  1222. fun ComposablePreview<AndroidPreviewInfo>.captureRoboImage(
  1223. filePath: String,
  1224. roborazziOptions: RoborazziOptions
  1225. )
  1226. ```
  1227. ### The supported `@Preview` annotation options
  1228. Currently, we don't support all the annotation options provided by the Compose Preview.
  1229. You can check the supported annotations in the [source code](https://github.com/takahirom/roborazzi/blob/0810ceb7133e6ec38472046cb741242a5ef6ab9e/roborazzi-compose-preview-scanner-support/src/main/java/com/github/takahirom/roborazzi/RoborazziPreviewScannerSupport.kt#L27).
  1230. We are looking forward to your contributions to support more annotation options.
  1231. <!-- end -->
  1232. <!-- topic_ai_powered_image_assertion -->
  1233. <!-- Generated by docs/topics/ai_powered_image_assertion.md. Do not edit this file. -->
  1234. # Experimental AI-Powered Image Assertion
  1235. Roborazzi supports AI-powered image assertion.
  1236. AI-powered image assertion is an experimental feature. Screenshot tests are a great way to verify your app's UI, but verifying the content of the images can be a tedious and time-consuming task. This manual effort reduces scalability. Roborazzi can help automate this process through AI-powered image assertion, making it more efficient and scalable.
  1237. There are two library modules: `io.github.takahirom.roborazzi:roborazzi-ai-gemini` and `io.github.takahirom.roborazzi:roborazzi-ai-openai` for AI-powered image assertion.
  1238. `roborazzi-ai-gemini` leverages [Gemini](https://gemini.google.com/) and [generative-ai-kmp](https://github.com/PatilShreyas/generative-ai-kmp), while `roborazzi-ai-openai` utilizes the [OpenAI API](https://platform.openai.com/) through raw HTTP API calls implemented with Ktor and KotlinX Serialization
  1239. ```kotlin
  1240. ...
  1241. @get:Rule
  1242. val composeTestRule = createAndroidComposeRule<MainActivity>()
  1243. @get:Rule
  1244. val roborazziRule = RoborazziRule(
  1245. options = RoborazziRule.Options(
  1246. roborazziOptions = RoborazziOptions(
  1247. compareOptions = RoborazziOptions.CompareOptions(
  1248. aiAssertionOptions = AiAssertionOptions(
  1249. aiAssertionModel = GeminiAiAssertionModel(
  1250. // DO NOT HARDCODE your API key in your code.
  1251. // This is an example passing API Key through unitTests.all{ environment(key, value) }
  1252. apiKey = System.getenv("gemini_api_key") ?: ""
  1253. ),
  1254. )
  1255. )
  1256. )
  1257. )
  1258. )
  1259. @Test
  1260. fun captureWithAi() {
  1261. ROBORAZZI_DEBUG = true
  1262. onView(ViewMatchers.isRoot())
  1263. .captureRoboImage(
  1264. roborazziOptions = provideRoborazziContext().options.addedAiAssertions(
  1265. AiAssertionOptions.AiAssertion(
  1266. assertionPrompt = "it should have PREVIOUS button",
  1267. requiredFulfillmentPercent = 90,
  1268. ),
  1269. AiAssertionOptions.AiAssertion(
  1270. assertionPrompt = "it should show First Fragment",
  1271. requiredFulfillmentPercent = 90,
  1272. )
  1273. )
  1274. )
  1275. }
  1276. ```
  1277. ## Behavior of AI-Powered Image Assertion
  1278. AI-Powered Image Assertion runs only when the images are different. If the images are the same, AI-Powered Image Assertion is skipped.
  1279. This is because AI-Powered Image Assertion can be slow and expensive.
  1280. ## Manual Image Assertion
  1281. You can use manual image assertion with Roborazzi. This allows you to utilize local LLMs or other LLMs. Manual Image Assertion doesn't require adding any dependencies other than Roborazzi itself.
  1282. You must provide the `AiAssertionModel` to `RoborazziOptions` to use manual image assertion.
  1283. ```kotlin
  1284. interface AiAssertionModel {
  1285. fun assert(
  1286. referenceImageFilePath: String,
  1287. comparisonImageFilePath: String,
  1288. actualImageFilePath: String,
  1289. aiAssertionOptions: AiAssertionOptions
  1290. ): AiAssertionResults
  1291. fun assert(
  1292. targetImages: TargetImages,
  1293. aiAssertionOptions: AiAssertionOptions
  1294. ): AiAssertionResults
  1295. }
  1296. ```
  1297. ```kotlin
  1298. compareOptions = RoborazziOptions.CompareOptions(
  1299. aiAssertionOptions = AiAssertionOptions(
  1300. aiAssertionModel = object : AiAssertionOptions.AiAssertionModel {
  1301. override fun assert(
  1302. referenceImageFilePath: String,
  1303. comparisonImageFilePath: String,
  1304. actualImageFilePath: String,
  1305. aiAssertionOptions: AiAssertionOptions
  1306. ): AiAssertionResults {
  1307. // You can use any LLMs here to create AiAssertionResults
  1308. return AiAssertionResults(
  1309. aiAssertionResults = aiAssertionOptions.aiAssertions.map { assertion ->
  1310. AiAssertionResult(
  1311. assertionPrompt = assertion.assertionPrompt,
  1312. fulfillmentPercent = 100,
  1313. requiredFulfillmentPercent = assertion.requiredFulfillmentPercent,
  1314. failIfNotFulfilled = assertion.failIfNotFulfilled,
  1315. explanation = "This is a manual test.",
  1316. )
  1317. }
  1318. )
  1319. }
  1320. override fun assert(
  1321. targetImages: TargetImages,
  1322. aiAssertionOptions: AiAssertionOptions
  1323. ): AiAssertionResults {
  1324. // targetImages.images holds the images to assert (e.g. targetImages.images.first().filePath)
  1325. return AiAssertionResults(
  1326. aiAssertionResults = aiAssertionOptions.aiAssertions.map { assertion ->
  1327. AiAssertionResult(
  1328. assertionPrompt = assertion.assertionPrompt,
  1329. fulfillmentPercent = 100,
  1330. requiredFulfillmentPercent = assertion.requiredFulfillmentPercent,
  1331. failIfNotFulfilled = assertion.failIfNotFulfilled,
  1332. explanation = "This is a manual test.",
  1333. )
  1334. }
  1335. )
  1336. }
  1337. },
  1338. aiAssertions = listOf(
  1339. AiAssertionOptions.AiAssertion(
  1340. assertionPrompt = "it should have PREVIOUS button",
  1341. requiredFulfillmentPercent = 90,
  1342. ),
  1343. ),
  1344. )
  1345. )
  1346. ...
  1347. ```
  1348. <!-- end -->
  1349. <!-- topic_idea_plugin -->
  1350. <!-- Generated by docs/topics/idea_plugin.md. Do not edit this file. -->
  1351. # Roborazzi IntelliJ IDEA and Android Studio Plugin
  1352. [https://plugins.jetbrains.com/plugin/24561-roborazzi](https://plugins.jetbrains.com/plugin/24561-roborazzi)
  1353. Demo of Roborazzi IntelliJ IDEA and Android Studio Plugin.
  1354. [https://github.com/takahirom/roborazzi/assets/1386930/bd3e8106-1971-4ec4-b764-3f1831999228](https://github.com/takahirom/roborazzi/assets/1386930/bd3e8106-1971-4ec4-b764-3f1831999228)
  1355. The Roborazzi plugin enhances your development workflow by automatically displaying screenshots related to Roborazzi's screenshot tests within IntelliJ IDEA. Easily view and verify visual outputs directly in your IDE, streamlining your testing and development process.
  1356. <!-- end -->
  1357. <!-- topic_compose_multiplatform -->
  1358. <!-- Generated by docs/topics/compose_multiplatform.md. Do not edit this file. -->
  1359. # Multiplatform support
  1360. ## Experimental feature: iOS support
  1361. Roborazzi supports Compose Multiplatform iOS. You can use Roborazzi with Compose iOS as follows:
  1362. Gradle settings
  1363. ```kotlin
  1364. plugins {
  1365. kotlin("multiplatform")
  1366. id("org.jetbrains.compose")
  1367. id("io.github.takahirom.roborazzi")
  1368. }
  1369. kotlin {
  1370. sourceSets {
  1371. ...
  1372. val appleTest by getting {
  1373. dependencies {
  1374. implementation("io.github.takahirom.roborazzi:roborazzi-compose-ios:[version]") // Use 1.13.0 or higher
  1375. implementation(kotlin("test"))
  1376. }
  1377. }
  1378. ...
  1379. ```
  1380. Test with Roborazzi
  1381. ```kotlin
  1382. class IosTest {
  1383. @OptIn(ExperimentalTestApi::class)
  1384. @Test
  1385. fun test() {
  1386. runComposeUiTest {
  1387. setContent {
  1388. MaterialTheme {
  1389. Column {
  1390. Button(onClick = { }) {
  1391. Text("Hello World")
  1392. }
  1393. Box(
  1394. modifier = Modifier
  1395. .background(Color.Red.copy(alpha = 0.5f), MaterialTheme.shapes.small)
  1396. .size(100.dp),
  1397. )
  1398. }
  1399. }
  1400. }
  1401. // iOS uses the same RoborazziOptions as the other targets. For example,
  1402. // allow up to 1% of pixels to differ before a comparison fails.
  1403. val roborazziOptions = RoborazziOptions(
  1404. compareOptions = RoborazziOptions.CompareOptions(changeThreshold = 0.01F),
  1405. )
  1406. // Unlike the JVM, iOS has no automatic file-name generation, so filePath
  1407. // is required for every capture.
  1408. onRoot().captureRoboImage(this, filePath = "ios.png", roborazziOptions = roborazziOptions)
  1409. onNodeWithText("Hello World").captureRoboImage(
  1410. this,
  1411. filePath = "ios_button.png",
  1412. roborazziOptions = roborazziOptions,
  1413. )
  1414. }
  1415. }
  1416. }
  1417. ```
  1418. Then, you can run the Gradle tasks for iOS Support, just like you do for Android Support.
  1419. ```
  1420. ./gradlew recordRoborazzi[SourceSet]
  1421. ```
  1422. ```
  1423. ./gradlew recordRoborazziIosSimulatorArm64
  1424. ./gradlew compareRoborazziIosSimulatorArm64
  1425. ./gradlew verifyRoborazziIosSimulatorArm64
  1426. ...
  1427. ```
  1428. The currently implemented features for iOS support are as follows:
  1429. | Feature | status |
  1430. |---|---|
  1431. | Record | supported |
  1432. | Compare | supported |
  1433. | Verify | supported |
  1434. | Report | supported |
  1435. | Dropbox/Differ comparison | supported |
  1436. | threshold / resultValidator | supported |
  1437. | diffPercentage | supported |
  1438. | resizing image (resizeScale) | supported |
  1439. | context data | supported (user-supplied only; the automatically-added default context data such as the test class name is JVM-only) |
  1440. | custom reporter | supported |
  1441. | ComparisonStyle | supported (Simple and Grid; Grid falls back to Simple when the density is unavailable) |
  1442. | RoborazziRecordFilePathStrategy | πŸ†– (filePath is required; a relative path always resolves against the output directory) |
  1443. | automatic file naming | πŸ†– (filePath is required) |
  1444. | image format | PNG only (WebP encoding is not supported on iOS) |
  1445. | pixelBitConfig | πŸ†– (Rgb565 falls back to Argb8888 with a warning; CoreGraphics has no 5-6-5 format) |
  1446. | dump | n/a (Robolectric-only concept) |
  1447. | applyDeviceCrop | n/a (Robolectric-only concept) |
  1448. | UI tree dump JSON sidecar (`uiTreeDumpOptions`) | supported (record writes `MyTest.uitree.json` next to the golden; compare/verify writes `MyTest_actual.uitree.json` in the compare output directory β€” the same `_actual` basename contract as the other platforms) |
  1449. | UI tree annotated image (`annotateImage`) | supported (drawn with UIKit/CoreGraphics; `MyTest.annotated.png` / `MyTest_actual.annotated.png`, matching the Android/Desktop look) |
  1450. > **Note on translucent pixels:** the iOS canvas stores pixels premultiplied (a CoreGraphics constraint), so translucent colors lose precision proportional to `255 / alpha` (opaque pixels are lossless). The loss is deterministic, so comparing identically-produced images is unaffected; only cross-source comparisons of low-alpha content may need a small threshold.
  1451. iOS runs on the same shared pipeline as the JVM and Compose Desktop targets
  1452. (`RoborazziOptions` β†’ `processOutputImageAndReport` β†’ `RoboCanvas`), so the image
  1453. comparator, threshold / `resultValidator`, `resizeScale`, context data, custom
  1454. reporters, and the `reference | diff | new` comparison output (including
  1455. `ComparisonStyle.Grid`) all behave the same way. A few platform-specific
  1456. features remain unsupported (see the table above); contributions are welcome.
  1457. ## Experimental feature: Compose Desktop support
  1458. Roborazzi supports Compose Desktop. You can use Roborazzi with Compose Desktop as follows:
  1459. Gradle settings
  1460. ```kotlin
  1461. plugins {
  1462. kotlin("multiplatform")
  1463. id("org.jetbrains.compose")
  1464. id("io.github.takahirom.roborazzi")
  1465. }
  1466. kotlin {
  1467. // You can use your source set name
  1468. jvm("desktop")
  1469. sourceSets {
  1470. ...
  1471. val desktopTest by getting {
  1472. dependencies {
  1473. implementation("io.github.takahirom.roborazzi:roborazzi-compose-desktop:[version]") // Use 1.6.0-alpha-2 or higher
  1474. implementation(kotlin("test"))
  1475. }
  1476. }
  1477. ...
  1478. ```
  1479. Test target Composable function
  1480. ```kotlin
  1481. @Composable
  1482. fun App() {
  1483. var text by remember { mutableStateOf("Hello, World!") }
  1484. MaterialTheme {
  1485. Button(
  1486. modifier = Modifier.testTag("button"),
  1487. onClick = {
  1488. text = "Hello, Desktop!"
  1489. }) {
  1490. Text(
  1491. style = MaterialTheme.typography.h2,
  1492. text = text
  1493. )
  1494. }
  1495. }
  1496. }
  1497. ```
  1498. Test with Roborazzi
  1499. ```kotlin
  1500. class MainKmpTest {
  1501. @OptIn(ExperimentalTestApi::class)
  1502. @Test
  1503. fun test() = runDesktopComposeUiTest {
  1504. setContent {
  1505. App()
  1506. }
  1507. val roborazziOptions = RoborazziOptions(
  1508. recordOptions = RoborazziOptions.RecordOptions(
  1509. resizeScale = 0.5
  1510. ),
  1511. compareOptions = RoborazziOptions.CompareOptions(
  1512. changeThreshold = 0F
  1513. )
  1514. )
  1515. onRoot().captureRoboImage(roborazziOptions = roborazziOptions)
  1516. onNodeWithTag("button").performClick()
  1517. onRoot().captureRoboImage(roborazziOptions = roborazziOptions)
  1518. }
  1519. }
  1520. ```
  1521. Then, you can run the Gradle tasks for Desktop Support, just like you do for Android Support.
  1522. ```
  1523. ./gradlew recordRoborazzi[SourceSet]
  1524. ```
  1525. ```
  1526. ./gradlew recordRoborazziDesktop
  1527. ./gradlew compareRoborazziDesktop
  1528. ./gradlew verifyRoborazziDesktop
  1529. ...
  1530. ```
  1531. If you use the Kotlin JVM plugin, the task will be `recordRoborazzi**Jvm**`.
  1532. Compose Desktop has **full [UI tree dump](https://takahirom.github.io/roborazzi/ui-tree-dump.html)
  1533. support**: enabling `uiTreeDumpOptions` (or `-Proborazzi.dumpUiTree=true`) on a
  1534. `SemanticsNodeInteraction.captureRoboImage` writes both the `MyTest.uitree.json`
  1535. sidecar and (by default) the annotated `MyTest.annotated.png`, with the same
  1536. naming and `_actual` basename semantics as Android.
  1537. The sample image
  1538. ![MainJvmTest test](https://github.com/takahirom/roborazzi/assets/1386930/41287c29-26ae-4539-b387-de570ae3f2b3)
  1539. ![MainJvmTest test_2](https://github.com/takahirom/roborazzi/assets/1386930/2edc828c-6fd8-4a9a-8f3d-b0e7baa85f0d)
  1540. <!-- end -->
  1541. <!-- topic_gradle_properties_options -->
  1542. <!-- Generated by docs/topics/gradle_properties_options.md. Do not edit this file. -->
  1543. # Roborazzi gradle.properties Options and Recommendations
  1544. You can configure the following options in your `gradle.properties` file.
  1545. You can also use `-P` to set the options in the command line. For example, `./gradlew test -Proborazzi.test.record=true`.
  1546. ## roborazzi.test
  1547. This option enables you to configure the behavior of Roborazzi. By default, all settings are set to false.

Lines 2,001–2,236 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.