Implement generateRobolectricPreviewTests prototype

README.md

@@ -944,6 +944,77 @@ If you are having trouble debugging your test, try Dump mode as follows.
 
 ![image](https://user-images.githubusercontent.com/1386930/226364158-a07a0fb0-d8e7-46b7-a495-8dd217faaadb.png)
 
+</div>
+<div name="topic_preview_support">
+
+<!-- Generated by docs/topics/preview_support.md. Do not edit this file. -->
+# Compose Preview Support
+
+Roborazzi provides support for generating screenshot tests and easy setup for Jetpack Compose Preview.
+This support uses [ComposePreviewScanner](https://github.com/sergio-sastre/ComposablePreviewScanner) to scan the Composable Previews in your project.
+
+## Generate Compose Preview screenshot tests
+
+You first need to add the Roborazzi plugin to your project. Please refer to the [setup guide](https://takahirom.github.io/roborazzi/build-setup.html) for more information.
+Then you can enable the Compose Preview screenshot test generation feature by adding the following configuration to your `build.gradle.kts` file:
+
+```kotlin
+roborazzi {
+  generateComposePreviewRobolectricTests {
+    enable = true
+  }
+}
+```
+
+The plugin will not automatically change your settings or add dependencies to prevent conflicts with your existing setup. However, it will provide instructions on what to do next, such as adding dependencies and required code.
+
+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).
+
+### Customizing the Preview screenshot test
+
+You can customize the generated test by adding the following configuration to your `build.gradle` file:
+
+```kotlin
+roborazzi {
+  generateComposePreviewRobolectricTests {
+    enable = true
+    // The package names to scan for Composable Previews.
+    packages = listOf("com.example")
+    // The fully qualified class name of the custom test class that implements [com.github.takahirom.roborazzi.RobolectricPreviewTest].
+    customTestQualifiedClassName = "com.example.MyCustomRobolectricPreviewTest"
+    // 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",
+    )
+  }
+}
+```
+
+## Manually adding Compose Preview screenshot tests
+
+Roborazzi provides a helper function for ComposePreviewScanner.
+You can add the following dependency to your project to use the helper function:
+
+`testImplementation("io.github.takahirom.roborazzi:roborazzi-compose-preview-scanner-support:[version]")`
+
+Then you can use the `ComposablePreview<AndroidPreviewInfo>.captureRoboImage()` function to capture the Composable Preview using the settings in Preview annotations.
+To obtain the `ComposablePreview` object, please refer to [ComposePreviewScanner](https://github.com/sergio-sastre/ComposablePreviewScanner).
+
+```kotlin
+fun ComposablePreview<AndroidPreviewInfo>.captureRoboImage(
+  filePath: String,
+  roborazziOptions: RoborazziOptions
+)
+```
+
+### The supported `@Preview` annotation options
+
+Currently, we don't support all the annotation options provided by the Compose Preview.
+You can check the supported annotations in the [source code](https://github.com/takahirom/roborazzi/blob/main/roborazzi-compose-preview-scanner-support/src/main/java/com/github/takahirom/roborazzi/RobolectricPreviewInfosApplier.kt).
+We are looking forward to your contributions to support more annotation options.
+
 </div>
 <div name="topic_idea_plugin">
 

README.template.md

@@ -7,6 +7,8 @@
 </div>
 <div name="topic_how_to_use">
 </div>
+<div name="topic_preview_support">
+</div>
 <div name="topic_idea_plugin">
 </div>
 <div name="topic_compose_multiplatform">

build.gradle

@@ -21,7 +21,7 @@ allprojects {
   def javaTargetVersion = JavaVersion.toVersion(javaVersion)
   def jvmTargetVersion = org.jetbrains.kotlin.gradle.dsl.JvmTarget.@Companion.fromTarget(javaVersion)
 
-  plugins.withId("java") {
+    plugins.withId("java") {
     java {
       toolchain {
         languageVersion.set(JavaLanguageVersion.of(toolchainVersion))
@@ -83,6 +83,14 @@ allprojects {
       }
     }
   }
+
+  configurations.all {
+    resolutionStrategy {
+      dependencySubstitution {
+        substitute(module("io.github.takahirom.roborazzi:roborazzi-compose-preview-scanner-support")).using(project(":roborazzi-compose-preview-scanner-support"))
+      }
+    }
+  }
 }
 
 class Topic {

docs/roborazzi-docs.tree

@@ -10,6 +10,7 @@
     <toc-element topic="try_it_out.md"/>
     <toc-element topic="build_setup.md"/>
     <toc-element topic="how_to_use.md"/>
+    <toc-element topic="preview_support.md"/>
     <toc-element topic="idea_plugin.md"/>
     <toc-element topic="compose_multiplatform.md"/>
     <toc-element topic="gradle_properties_options.md"/>

docs/topics/preview_support.md

@@ -0,0 +1,66 @@
+# Compose Preview Support
+
+Roborazzi provides support for generating screenshot tests and easy setup for Jetpack Compose Preview.
+This support uses [ComposePreviewScanner](https://github.com/sergio-sastre/ComposablePreviewScanner) to scan the Composable Previews in your project.
+
+## Generate Compose Preview screenshot tests
+
+You first need to add the Roborazzi plugin to your project. Please refer to the [setup guide](https://takahirom.github.io/roborazzi/build-setup.html) for more information.
+Then you can enable the Compose Preview screenshot test generation feature by adding the following configuration to your `build.gradle.kts` file:
+
+```kotlin
+roborazzi {
+  generateComposePreviewRobolectricTests {
+    enable = true
+  }
+}
+```
+
+The plugin will not automatically change your settings or add dependencies to prevent conflicts with your existing setup. However, it will provide instructions on what to do next, such as adding dependencies and required code.
+
+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).
+
+### Customizing the Preview screenshot test
+
+You can customize the generated test by adding the following configuration to your `build.gradle` file:
+
+```kotlin
+roborazzi {
+  generateComposePreviewRobolectricTests {
+    enable = true
+    // The package names to scan for Composable Previews.
+    packages = listOf("com.example")
+    // The fully qualified class name of the custom test class that implements [com.github.takahirom.roborazzi.RobolectricPreviewTest].
+    customTestQualifiedClassName = "com.example.MyCustomRobolectricPreviewTest"
+    // 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",
+    )
+  }
+}
+```
+
+## Manually adding Compose Preview screenshot tests
+
+Roborazzi provides a helper function for ComposePreviewScanner.
+You can add the following dependency to your project to use the helper function:
+
+`testImplementation("io.github.takahirom.roborazzi:roborazzi-compose-preview-scanner-support:[version]")`
+
+Then you can use the `ComposablePreview<AndroidPreviewInfo>.captureRoboImage()` function to capture the Composable Preview using the settings in Preview annotations.
+To obtain the `ComposablePreview` object, please refer to [ComposePreviewScanner](https://github.com/sergio-sastre/ComposablePreviewScanner).
+
+```kotlin
+fun ComposablePreview<AndroidPreviewInfo>.captureRoboImage(
+  filePath: String,
+  roborazziOptions: RoborazziOptions
+)
+```
+
+### The supported `@Preview` annotation options
+
+Currently, we don't support all the annotation options provided by the Compose Preview.
+You can check the supported annotations in the [source code](https://github.com/takahirom/roborazzi/blob/main/roborazzi-compose-preview-scanner-support/src/main/java/com/github/takahirom/roborazzi/RobolectricPreviewInfosApplier.kt).
+We are looking forward to your contributions to support more annotation options.

gradle/libs.versions.toml

@@ -43,6 +43,8 @@ webjar-material-design-icons = "4.0.0"
 webjar-materialize = "1.0.0"
 webjars-locator-lite = "0.0.4"
 
+composable-preview-scanner = "0.1.2"
+
 [libraries]
 roborazzi = { module = "io.github.takahirom.roborazzi:roborazzi", version.ref = "roborazzi-for-replacing-by-include-build" }
 roborazzi-junit-rule = { module = "io.github.takahirom.roborazzi:roborazzi-junit-rule", version.ref = "roborazzi-for-replacing-by-include-build" }
@@ -53,6 +55,9 @@ kotlin-stdlib-jdk8 = { module = "org.jetbrains.kotlin:kotlin-stdlib-jdk8" }
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test" }
 kotlin-test-junit = { module = "org.jetbrains.kotlin:kotlin-test-junit" }
 
+# for sample
+composable-preview-scanner = { module = "com.github.sergio-sastre.ComposablePreviewScanner:android", version.ref = "composable-preview-scanner" }
+
 androidx-activity = { module = "androidx.activity:activity", version.ref = "androidx-activity" }
 androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "androidx-activity" }
 androidx-appcompat = { module = "androidx.appcompat:appcompat", version.ref = "androidx-appcompat" }

include-build/roborazzi-core/src/commonJvmMain/kotlin/com/github/takahirom/roborazzi/DefaultFileNameGenerator.kt

@@ -11,6 +11,19 @@ object DefaultFileNameGenerator {
     EscapedTestPackageAndClassAndMethod("escapedTestPackageAndClassAndMethod"),
     TestClassAndMethod("testClassAndMethod");
 
+    @ExperimentalRoborazziApi
+    fun generateOutputName(className: String, methodName: String?): String {
+      return when (this) {
+        TestPackageAndClassAndMethod -> "$className.$methodName"
+        EscapedTestPackageAndClassAndMethod -> className.replace(
+          ".",
+          "_"
+        ) + "." + methodName
+
+        TestClassAndMethod -> className.substringAfterLast(".") + "." + methodName
+      }
+    }
+
     companion object {
       fun fromOptionName(optionName: String): DefaultNamingStrategy {
         return values().firstOrNull { it.optionName == optionName } ?: TestPackageAndClassAndMethod
@@ -89,7 +102,7 @@ object DefaultFileNameGenerator {
       }
       ?: throw IllegalArgumentException("Roborazzi can't find method of test. Please specify file name or use Rule")
     val testName =
-      generateOutputName(stackTraceElement.className, stackTraceElement.methodName)
+      defaultNamingStrategy.generateOutputName(stackTraceElement.className, stackTraceElement.methodName)
     return testName
   }
 
@@ -112,19 +125,8 @@ object DefaultFileNameGenerator {
   internal fun generateOutputNameWithDescription(description: Description): String {
     val className = description.className
     val methodName = description.methodName
-    val testName = generateOutputName(className, methodName)
+    val testName = defaultNamingStrategy.generateOutputName(className, methodName)
     return testName
   }
 
-  private fun generateOutputName(className: String, methodName: String?): String {
-    return when (defaultNamingStrategy) {
-      DefaultNamingStrategy.TestPackageAndClassAndMethod -> "$className.$methodName"
-      DefaultNamingStrategy.EscapedTestPackageAndClassAndMethod -> className.replace(
-        ".",
-        "_"
-      ) + "." + methodName
-
-      DefaultNamingStrategy.TestClassAndMethod -> className.substringAfterLast(".") + "." + methodName
-    }
-  }
 }