feat(snapshots): Add global diffThreshold setting (#1186)

* feat(snapshots): Add global diffThreshold setting

The @SentrySnapshot annotation already supports per-snapshot
diffThreshold overrides, but there was no way to set a default
threshold for all snapshots globally. This adds a diffThreshold
property to SnapshotsExtension so users can configure it in the
DSL without annotating every composable.

The per-snapshot @SentrySnapshot annotation still takes precedence
when present.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(snapshots): Pass diffThreshold as CLI arg, not sidecar metadata

Move the global diffThreshold from sidecar metadata to a --diff-threshold
CLI argument on the upload task. Per-snapshot @SentrySnapshot annotation
thresholds in sidecar metadata remain unchanged.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: Add diffThreshold to changelog

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(snapshots): Remove redundant assertion in diffThreshold test

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: runningcode

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Add global `diffThreshold` option for snapshots ([#1186](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1186))
+
 ### Fixes
 
 - Change auto-install trigger for log4j2 from -api to -core dependency ([#1155](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1155))

plugin-build/src/main/kotlin/io/sentry/android/gradle/AndroidComponentsConfig.kt

@@ -509,7 +509,7 @@ private fun ApplicationVariant.configureSnapshotsTasks(
       val generateTask =
         GenerateSnapshotTestsTask.register(
           project,
-          extension.snapshots.previews,
+          extension.snapshots,
           android,
           this@configureSnapshotsTasks,
           paparazziMajorVersion,

plugin-build/src/main/kotlin/io/sentry/android/gradle/extensions/SnapshotsExtension.kt

@@ -11,6 +11,8 @@ open class SnapshotsExtension @Inject constructor(objects: ObjectFactory) {
 
   val enabled: Property<Boolean> = objects.property(Boolean::class.java).convention(false)
 
+  val diffThreshold: Property<Double> = objects.property(Double::class.java).convention(0.0)
+
   val previews: SnapshotPreviewsExtension =
     objects.newInstance(SnapshotPreviewsExtension::class.java)
 

plugin-build/src/main/kotlin/io/sentry/android/gradle/snapshot/GenerateSnapshotTestsTask.kt

@@ -3,7 +3,7 @@ package io.sentry.android.gradle.snapshot
 import com.android.build.api.variant.ApplicationVariant
 import com.android.build.gradle.BaseExtension
 import io.sentry.android.gradle.SentryTasksProvider.capitalized
-import io.sentry.android.gradle.extensions.SnapshotPreviewsExtension
+import io.sentry.android.gradle.extensions.SnapshotsExtension
 import java.io.File
 import org.gradle.api.DefaultTask
 import org.gradle.api.Project
@@ -32,6 +32,8 @@ abstract class GenerateSnapshotTestsTask : DefaultTask() {
 
   @get:Input @get:Optional abstract val theme: Property<String>
 
+  @get:Input abstract val diffThreshold: Property<Double>
+
   @get:Input abstract val paparazziMajorVersion: Property<Int>
 
   @get:OutputDirectory abstract val outputDir: DirectoryProperty
@@ -51,6 +53,7 @@ abstract class GenerateSnapshotTestsTask : DefaultTask() {
         includePrivatePreviews = includePrivatePreviews.get(),
         packageTrees = packageTrees.get(),
         theme = theme.orNull,
+        diffThreshold = diffThreshold.get(),
         paparazziMajorVersion = paparazziMajorVersion.get(),
       )
     File(packageDir, "$CLASS_NAME.kt").writeText(content)
@@ -63,7 +66,7 @@ abstract class GenerateSnapshotTestsTask : DefaultTask() {
 
     fun register(
       project: Project,
-      extension: SnapshotPreviewsExtension,
+      extension: SnapshotsExtension,
       android: BaseExtension,
       variant: ApplicationVariant,
       paparazziMajorVersion: Provider<Int>,
@@ -72,12 +75,13 @@ abstract class GenerateSnapshotTestsTask : DefaultTask() {
         "sentryGenerateSnapshotsTests${variant.name.capitalized}",
         GenerateSnapshotTestsTask::class.java,
       ) { task ->
-        task.includePrivatePreviews.set(extension.includePrivatePreviews)
-        task.theme.set(extension.theme)
+        task.includePrivatePreviews.set(extension.previews.includePrivatePreviews)
+        task.theme.set(extension.previews.theme)
+        task.diffThreshold.set(extension.diffThreshold)
         task.paparazziMajorVersion.value(paparazziMajorVersion)
         // Fall back to the Android namespace when the user doesn't configure packageTrees
         task.packageTrees.set(
-          extension.packageTrees.map { packages ->
+          extension.previews.packageTrees.map { packages ->
             packages.ifEmpty { listOf(android.namespace!!) }
           }
         )
@@ -92,6 +96,7 @@ abstract class GenerateSnapshotTestsTask : DefaultTask() {
       includePrivatePreviews: Boolean,
       packageTrees: List<String>,
       theme: String? = null,
+      diffThreshold: Double = 0.0,
       paparazziMajorVersion: Int = 2,
     ): String {
       val includePrivateExpr =
@@ -232,7 +237,7 @@ private object PaparazziPreviewRule {
             true -> env
             false -> env.copy(compileSdkVersion = previewInfo.apiLevel)
         }
-        val tolerance = 0.0
+        val tolerance = $diffThreshold
         return Paparazzi(
             environment = environment,
             deviceConfig = DeviceConfigBuilder.build(preview.previewInfo),

plugin-build/src/main/kotlin/io/sentry/android/gradle/tasks/SentryUploadSnapshotsTask.kt

@@ -37,6 +37,8 @@ abstract class SentryUploadSnapshotsTask : SentryCliExecTask() {
     snapshotsPath.set(project.file(path))
   }
 
+  @get:Input @get:Optional abstract val diffThreshold: Property<Double>
+
   @get:Input @get:Optional abstract val vcsHeadSha: Property<String>
   @get:Input @get:Optional abstract val vcsBaseSha: Property<String>
   @get:Input @get:Optional abstract val vcsProvider: Property<String>
@@ -52,6 +54,10 @@ abstract class SentryUploadSnapshotsTask : SentryCliExecTask() {
     args.add("--app-id")
     args.add(appId.get())
 
+    diffThreshold.orNull?.let {
+      if (it != 0.0) args.addAll(listOf("--diff-threshold", it.toString()))
+    }
+
     vcsHeadSha.orNull?.let { args.addAll(listOf("--head-sha", it)) }
     vcsBaseSha.orNull?.let { args.addAll(listOf("--base-sha", it)) }
     vcsProvider.orNull?.let { args.addAll(listOf("--vcs-provider", it)) }
@@ -93,6 +99,7 @@ abstract class SentryUploadSnapshotsTask : SentryCliExecTask() {
         task.sentryAuthToken.set(extension.authToken)
         task.sentryUrl.set(extension.url)
         task.appId.set(applicationId)
+        task.diffThreshold.set(extension.snapshots.diffThreshold)
         task.vcsHeadSha.set(extension.vcsInfo.headSha)
         task.vcsBaseSha.set(extension.vcsInfo.baseSha)
         task.vcsProvider.set(extension.vcsInfo.vcsProvider)

plugin-build/src/test/kotlin/io/sentry/android/gradle/extensions/SnapshotsExtensionTest.kt

@@ -1,5 +1,6 @@
 package io.sentry.android.gradle.extensions
 
+import kotlin.test.assertEquals
 import kotlin.test.assertFalse
 import kotlin.test.assertNull
 import kotlin.test.assertTrue
@@ -16,6 +17,24 @@ class SnapshotsExtensionTest {
     assertFalse(extension.enabled.get())
   }
 
+  @Test
+  fun `diffThreshold is zero by default`() {
+    val project = ProjectBuilder.builder().build()
+    val extension = project.objects.newInstance(SnapshotsExtension::class.java)
+
+    assertEquals(0.0, extension.diffThreshold.get())
+  }
+
+  @Test
+  fun `diffThreshold can be configured`() {
+    val project = ProjectBuilder.builder().build()
+    val extension = project.objects.newInstance(SnapshotsExtension::class.java)
+
+    extension.diffThreshold.set(0.05)
+
+    assertEquals(0.05, extension.diffThreshold.get())
+  }
+
   @Test
   fun `previews generateTests is true by default`() {
     val project = ProjectBuilder.builder().build()

plugin-build/src/test/kotlin/io/sentry/android/gradle/snapshot/GenerateSnapshotTestsTaskTest.kt

@@ -225,12 +225,28 @@ class GenerateSnapshotTestsTaskTest {
     assertFalse(content.contains("HtmlReportWriter()"))
   }
 
+  @Test
+  fun `generated file uses default tolerance of zero`() {
+    val content = generateAndRead(packageTrees = listOf("com.example"))
+
+    assertTrue(content.contains("val tolerance = 0.0"))
+  }
+
+  @Test
+  fun `generated file uses configured diffThreshold as tolerance`() {
+    val content = generateAndRead(packageTrees = listOf("com.example"), diffThreshold = 0.05)
+
+    assertTrue(content.contains("val tolerance = 0.05"))
+  }
+
   private fun generateAndRead(
     packageTrees: List<String>,
     includePrivatePreviews: Boolean = false,
+    diffThreshold: Double = 0.0,
     paparazziMajorVersion: Int = 2,
   ): String {
-    val task = createTask(packageTrees, includePrivatePreviews, paparazziMajorVersion)
+    val task =
+      createTask(packageTrees, includePrivatePreviews, diffThreshold, paparazziMajorVersion)
     task.generate()
     val file =
       File(task.outputDir.get().asFile, "io/sentry/snapshot/ComposablePreviewSnapshotTest.kt")
@@ -240,13 +256,15 @@ class GenerateSnapshotTestsTaskTest {
   private fun createTask(
     packageTrees: List<String>,
     includePrivatePreviews: Boolean = false,
+    diffThreshold: Double = 0.0,
     paparazziMajorVersion: Int = 2,
   ): GenerateSnapshotTestsTask {
     val project = ProjectBuilder.builder().build()
     return project.tasks
       .register("testGenerateSnapshotTests", GenerateSnapshotTestsTask::class.java) { task ->
         task.includePrivatePreviews.set(includePrivatePreviews)
         task.packageTrees.set(packageTrees)
+        task.diffThreshold.set(diffThreshold)
         task.paparazziMajorVersion.set(paparazziMajorVersion)
         task.outputDir.set(tmpDir.newFolder("output"))
       }

plugin-build/src/test/kotlin/io/sentry/android/gradle/tasks/SentryUploadSnapshotsTaskTest.kt

@@ -156,6 +156,47 @@ class SentryUploadSnapshotsTaskTest {
     assertThat(args).containsAtLeast("--pr-number", "123").inOrder()
   }
 
+  @Test
+  fun `diffThreshold is passed to CLI when non-zero`() {
+    val task = createTestTask {
+      it.cliExecutable.set("sentry-cli")
+      it.appId.set("com.example")
+      it.snapshotsPath.set(File("/path/to/snapshots"))
+      it.diffThreshold.set(0.05)
+    }
+
+    val args = task.computeCommandLineArgs()
+
+    assertThat(args).containsAtLeast("--diff-threshold", "0.05").inOrder()
+  }
+
+  @Test
+  fun `diffThreshold is omitted when zero`() {
+    val task = createTestTask {
+      it.cliExecutable.set("sentry-cli")
+      it.appId.set("com.example")
+      it.snapshotsPath.set(File("/path/to/snapshots"))
+      it.diffThreshold.set(0.0)
+    }
+
+    val args = task.computeCommandLineArgs()
+
+    assertThat(args).doesNotContain("--diff-threshold")
+  }
+
+  @Test
+  fun `diffThreshold is omitted when not set`() {
+    val task = createTestTask {
+      it.cliExecutable.set("sentry-cli")
+      it.appId.set("com.example")
+      it.snapshotsPath.set(File("/path/to/snapshots"))
+    }
+
+    val args = task.computeCommandLineArgs()
+
+    assertThat(args).doesNotContain("--diff-threshold")
+  }
+
   @Test
   fun `vcs parameters are omitted when not set`() {
     val task = createTestTask {