Add preview param support for @Paparazzi

gradle/libs.versions.toml

@@ -28,6 +28,7 @@ bytebuddy-agent = { module = "net.bytebuddy:byte-buddy-agent", version.ref = "by
 bytebuddy-core = { module = "net.bytebuddy:byte-buddy", version.ref = "bytebuddy" }
 
 compose-runtime = { module = "androidx.compose.runtime:runtime", version.ref = "compose" }
+composeUi-foundation = { module = "androidx.compose.foundation:foundation", version.ref = "compose" }
 composeUi-material = { module = "androidx.compose.material:material", version.ref = "compose" }
 composeUi-material3-android = { module = "androidx.compose.material3:material3-android", version = "1.3.1" }
 composeUi-material-icons = { module = "androidx.compose.material:material-icons-core", version.ref = "compose" }

paparazzi-annotations/README.md

@@ -0,0 +1,112 @@
+# `@Paparazzi`
+An annotation used to generate Paparazzi snapshots for composable preview functions.
+
+## Installation
+Add the following to your `build.gradle` file
+
+```groovy
+apply plugin: 'app.cash.paparazzi.preview'
+```
+
+## Basic Usage
+Apply the annotation alongside an existing preview method. The annotation processor will generate a manifest of information about this method and the previews applied.
+
+```kotlin
+import app.cash.paparazzi.preview.Paparazzi
+
+@Paparazzi
+@Preview
+@Composable
+fun MyViewPreview() {
+  MyView(title = "Hello, Paparazzi Annotation")
+}
+```
+
+Run `:recordPaparazziDebug` in your module to generate preview snapshots (and optionally verify them using `:verifyPaparazziDebug`) as you normally would.
+
+A test class to generate snapshots for annotated previews will automatically be generated.
+If you prefer to define a custom snapshot test, you mey disable test generation by adding the following to your `gradle.properties` file.
+
+```properties
+app.cash.paparazzi.annotation.generateTestClass=false
+```
+
+You may implement your own test class, as shown below, to create snapshots for all previews included in the generated manifest (`paparazziAnnotations`).
+
+```kotlin
+import app.cash.paparazzi.Paparazzi
+import app.cash.paparazzi.preview.PaparazziPreviewData
+import app.cash.paparazzi.preview.PaparazziValuesProvider
+import app.cash.paparazzi.preview.deviceConfig
+import app.cash.paparazzi.preview.snapshot
+import com.android.ide.common.rendering.api.SessionParams.RenderingMode.SHRINK
+import com.google.testing.junit.testparameterinjector.TestParameter
+import com.google.testing.junit.testparameterinjector.TestParameterInjector
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(TestParameterInjector::class)
+class PreviewTests(
+  @TestParameter(valuesProvider = PreviewConfigValuesProvider::class)
+  private val preview: PaparazziPreviewData,
+) {
+  private class PreviewConfigValuesProvider : PaparazziValuesProvider(paparazziPreviews)
+
+  @get:Rule
+  val paparazzi = Paparazzi(
+    deviceConfig = preview.deviceConfig(),
+    renderingMode = SHRINK,
+  )
+
+  @Test
+  fun preview() {
+    paparazzi.snapshot(preview)
+  }
+}
+```
+
+## Preview Parameter
+If your preview function accepts a parameter using `@PreviewParameter`, then snapshots will be created for each combination of preview / param.
+
+```kotlin
+@Paparazzi
+@Preview
+@Composable
+fun MyViewPreview(@PreviewParameter(MyTitleProvider::class) title: String) {
+  MyView(title = title)
+}
+
+class MyTitleProvider : PreviewParameterProvider<String> {
+  override val values = sequenceOf("Hello", "Paparazzi", "Annotation")
+}
+```
+
+## Composable Wrapping
+If you need to apply additional UI treatment around your previews, you may provide a composable wrapper within the test.
+
+```kotlin
+paparazzi.snapshot(preview) { content ->
+  Box(modifier = Modifier.background(Color.Gray)) {
+    content()
+  }
+}
+```
+
+## Preview Composition
+If you have multiple preview annotations applied to a function, or have them nested behind a custom annotation, they will all be included in the snapshot manifest.
+
+```kotlin
+@Paparazzi
+@ScaledThemedPreviews
+@Composable
+fun MyViewPreview() {
+  MyView(title = "Hello, Paparazzi Annotation")
+}
+
+@Preview(name = "small light", fontScale = 1f, uiMode = Configuration.UI_MODE_NIGHT_NO, device = PIXEL_3_XL)
+@Preview(name = "small dark", fontScale = 1f, uiMode = Configuration.UI_MODE_NIGHT_YES, device = PIXEL_3_XL)
+@Preview(name = "large light", fontScale = 2f, uiMode = Configuration.UI_MODE_NIGHT_NO, device = PIXEL_3_XL)
+@Preview(name = "large dark", fontScale = 2f, uiMode = Configuration.UI_MODE_NIGHT_YES, device = PIXEL_3_XL)
+annotation class ScaledThemedPreviews
+```

paparazzi-annotations/build.gradle

@@ -3,5 +3,5 @@ apply plugin: 'org.jetbrains.kotlin.plugin.compose'
 apply plugin: 'com.vanniktech.maven.publish'
 
 dependencies {
-  implementation libs.compose.runtime
+  compileOnly libs.compose.runtime
 }

paparazzi-gradle-plugin/api/paparazzi-gradle-plugin.api

@@ -1,3 +1,12 @@
+public abstract class app/cash/paparazzi/gradle/GeneratePreviewTestFileTask : org/gradle/api/DefaultTask {
+	public fun <init> ()V
+	public final fun createFile ()V
+	public abstract fun getNamespace ()Lorg/gradle/api/provider/Property;
+	public abstract fun getPaparazziPreviewsFile ()Lorg/gradle/api/file/RegularFileProperty;
+	public abstract fun getPreviewTestOutputDir ()Lorg/gradle/api/file/DirectoryProperty;
+	public abstract fun getPreviewTestOutputFile ()Lorg/gradle/api/file/RegularFileProperty;
+}
+
 public final class app/cash/paparazzi/gradle/PaparazziPlugin : org/gradle/api/Plugin {
 	public fun <init> (Lorg/gradle/api/provider/ProviderFactory;Lorg/gradle/internal/operations/BuildOperationRunner;Lorg/gradle/internal/operations/BuildOperationExecutor;)V
 	public synthetic fun apply (Ljava/lang/Object;)V

paparazzi-gradle-plugin/build.gradle

@@ -35,6 +35,7 @@ dependencies {
   compileOnly libs.plugin.android
 
   implementation platform(libs.kotlin.bom)
+  implementation libs.plugin.ksp
   implementation(libs.tools.sdkCommon) {
     because "SymbolUtils.getPackageNameFromManifest removed in AGP 7.0.  Replace?"
   }
@@ -63,6 +64,10 @@ buildConfig {
 
 tasks.withType(Test).configureEach {
   dependsOn(':paparazzi:publishMavenPublicationToProjectLocalMavenRepository')
+  dependsOn(':paparazzi-annotations:publishMavenPublicationToProjectLocalMavenRepository')
+  dependsOn(':paparazzi-preview-processor:publishMavenPublicationToProjectLocalMavenRepository')
+  dependsOn(':paparazzi-preview-runtime:publishMavenPublicationToProjectLocalMavenRepository')
+  dependsOn(':paparazzi-preview-test-junit:publishMavenPublicationToProjectLocalMavenRepository')
 }
 
 // When cleaning this project, we also want to clean the test projects.

paparazzi-gradle-plugin/src/main/java/app/cash/paparazzi/gradle/GeneratePreviewTestFileTask.kt

@@ -0,0 +1,47 @@
+package app.cash.paparazzi.gradle
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.CacheableTask
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.Optional
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.OutputFile
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.SkipWhenEmpty
+import org.gradle.api.tasks.TaskAction
+
+@CacheableTask
+public abstract class GeneratePreviewTestFileTask : DefaultTask() {
+  @get:Input
+  public abstract val namespace: Property<String>
+
+  @get:Optional
+  @get:SkipWhenEmpty
+  @get:InputFile
+  @get:PathSensitive(PathSensitivity.NONE)
+  public abstract val paparazziPreviewsFile: RegularFileProperty
+
+  @get:OutputDirectory
+  public abstract val previewTestOutputDir: DirectoryProperty
+
+  @get:OutputFile
+  public abstract val previewTestOutputFile: RegularFileProperty
+
+  @TaskAction
+  public fun createFile() {
+    val previewDataFile = paparazziPreviewsFile.asFile.get()
+    val previewTestFile = previewTestOutputFile.asFile.get()
+
+    if (!previewDataFile.exists()) {
+      logger.warn("Preview data file not found: $previewDataFile")
+      return
+    }
+
+    previewTestFile.writeText(previewTestSource(namespace.get()))
+  }
+}

paparazzi-gradle-plugin/src/main/java/app/cash/paparazzi/gradle/PaparazziPlugin.kt

@@ -18,6 +18,7 @@ package app.cash.paparazzi.gradle
 import app.cash.paparazzi.gradle.instrumentation.ResourcesCompatVisitorFactory
 import app.cash.paparazzi.gradle.reporting.PaparazziTestReporter
 import app.cash.paparazzi.gradle.utils.artifactViewFor
+import app.cash.paparazzi.gradle.utils.registerGeneratePreviewTask
 import app.cash.paparazzi.gradle.utils.relativize
 import com.android.build.api.instrumentation.FramesComputationMode
 import com.android.build.api.instrumentation.InstrumentationScope
@@ -27,6 +28,8 @@ import com.android.build.api.variant.DynamicFeatureAndroidComponentsExtension
 import com.android.build.api.variant.HasUnitTest
 import com.android.build.api.variant.LibraryAndroidComponentsExtension
 import com.android.build.gradle.BaseExtension
+import com.google.devtools.ksp.gradle.KspExtension
+import com.google.devtools.ksp.gradle.KspGradleSubplugin
 import org.gradle.api.DefaultTask
 import org.gradle.api.Plugin
 import org.gradle.api.Project
@@ -86,6 +89,7 @@ public class PaparazziPlugin @Inject constructor(
           else -> error("${androidComponents.javaClass.name} from $plugin is not supported in Paparazzi")
         }
         setupPaparazzi(project, androidComponents)
+        setupPreviewProcessor(project, androidComponents)
       }
     }
   }
@@ -238,7 +242,7 @@ public class PaparazziPlugin @Inject constructor(
         test.inputs.dir(
           isVerifyRun.flatMap {
             project.objects.directoryProperty().apply {
-              set(if (it) snapshotOutputDir else null)
+              set(if (it && snapshotOutputDir.asFile.exists()) snapshotOutputDir else null)
             }
           }
         ).withPropertyName("paparazzi.snapshot.input.dir")
@@ -278,6 +282,23 @@ public class PaparazziPlugin @Inject constructor(
     }
   }
 
+  private fun setupPreviewProcessor(project: Project, extension: AndroidComponentsExtension<*, *, *>) {
+    project.pluginManager.apply(KspGradleSubplugin::class.java)
+
+    project.addAnnotationsDependency()
+    project.addPreviewRuntimeDependency()
+    project.addProcessorDependency()
+    project.addPreviewTestDependency()
+    project.registerGeneratePreviewTask(extension)
+
+    project.afterEvaluate {
+      // pass the namespace to the processor
+      val kspExtension = project.extensions.getByType(KspExtension::class.java)
+      val android = project.extensions.getByType(BaseExtension::class.java)
+      kspExtension.arg(KSP_ARG_NAMESPACE, android.packageName())
+    }
+  }
+
   public abstract class PaparazziTask : DefaultTask() {
     @Option(option = "tests", description = "Sets test class or method name to be included, '*' is supported.")
     public open fun setTestNameIncludePatterns(testNamePattern: List<String>): PaparazziTask {
@@ -345,6 +366,46 @@ public class PaparazziPlugin @Inject constructor(
     configurations.getByName("testImplementation").dependencies.add(dependency)
   }
 
+  private fun Project.addAnnotationsDependency() {
+    val dependency = if (isInternal()) {
+      dependencies.project(mapOf("path" to ":paparazzi-annotations"))
+    } else {
+      dependencies.create("app.cash.paparazzi:paparazzi-annotations:$VERSION")
+    }
+    configurations.getByName("implementation").dependencies.add(dependency)
+  }
+
+  private fun Project.addPreviewRuntimeDependency() {
+    val dependency = if (isInternal()) {
+      dependencies.project(mapOf("path" to ":paparazzi-preview-runtime"))
+    } else {
+      dependencies.create("app.cash.paparazzi:paparazzi-preview-runtime:$VERSION")
+    }
+    configurations.getByName("implementation").dependencies.add(dependency)
+  }
+
+  private fun Project.addProcessorDependency() {
+    val dependency = if (isInternal()) {
+      dependencies.project(mapOf("path" to ":paparazzi-preview-processor"))
+    } else {
+      dependencies.create("app.cash.paparazzi:paparazzi-preview-processor:$VERSION")
+    }
+    if (project.plugins.hasPlugin("org.jetbrains.kotlin.multiplatform")) {
+      configurations.getByName("kspCommonMainMetadata").dependencies.add(dependency)
+    } else {
+      configurations.getByName("ksp").dependencies.add(dependency)
+    }
+  }
+
+  private fun Project.addPreviewTestDependency() {
+    val dependency = if (isInternal()) {
+      dependencies.project(mapOf("path" to ":paparazzi-preview-test-junit"))
+    } else {
+      dependencies.create("app.cash.paparazzi:paparazzi-preview-test-junit:$VERSION")
+    }
+    configurations.getByName("testImplementation").dependencies.add(dependency)
+  }
+
   private fun Project.isInternal(): Boolean = providers.gradleProperty("app.cash.paparazzi.internal").orNull == "true"
 
   private fun BaseExtension.packageName(): String = namespace ?: ""
@@ -359,3 +420,4 @@ public class PaparazziPlugin @Inject constructor(
 }
 
 private const val DEFAULT_COMPILE_SDK_VERSION = 34
+private const val KSP_ARG_NAMESPACE = "app.cash.paparazzi.preview.namespace"

paparazzi-gradle-plugin/src/main/java/app/cash/paparazzi/gradle/PreviewTests.kt

@@ -0,0 +1,44 @@
+package app.cash.paparazzi.gradle
+
+internal fun previewTestSource(packageName: String) =
+  """
+package $packageName
+
+import app.cash.paparazzi.Paparazzi
+import app.cash.paparazzi.preview.DefaultLocaleRule
+import app.cash.paparazzi.preview.PaparazziValuesProvider
+import app.cash.paparazzi.preview.deviceConfig
+import app.cash.paparazzi.preview.locale
+import app.cash.paparazzi.preview.snapshot
+import app.cash.paparazzi.preview.runtime.PaparazziPreviewData
+import com.android.ide.common.rendering.api.SessionParams.RenderingMode.SHRINK
+import com.google.testing.junit.testparameterinjector.TestParameter
+import com.google.testing.junit.testparameterinjector.TestParameterInjector
+import org.junit.Assume.assumeTrue
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(TestParameterInjector::class)
+class PreviewTests(
+  @TestParameter(valuesProvider = PreviewConfigValuesProvider::class)
+  private val preview: PaparazziPreviewData,
+) {
+  private class PreviewConfigValuesProvider : PaparazziValuesProvider(paparazziPreviews)
+
+  @get:Rule
+  val paparazzi = Paparazzi(
+    deviceConfig = preview.deviceConfig(),
+    renderingMode = SHRINK,
+    maxPercentDifference = 0.11,
+  )
+
+  @get:Rule
+  val localeRule = DefaultLocaleRule(preview.locale())
+
+  @Test
+  fun preview() {
+    paparazzi.snapshot(preview)
+  }
+}
+"""