Set Up Snapshots

Set up Snapshots for your Android app with the Sentry Android Gradle Plugin. Generate snapshots locally or in your own CI using your preferred snapshot library, then upload the generated images to Sentry for image diffing, visual review, and GitHub status checks.

Step 1: Enable Snapshots

Ensure the Sentry Android Gradle Plugin version 6.8.1 or higher is applied and configured.

Then enable snapshots in your build.gradle:

sentry {
  snapshots {
    enabled = true
  }
}

sentry {
  snapshots {
    enabled = true
  }
}

Step 2: Generate Images

On Android you can either generate images from compose previews (recommended) or from an existing snapshot tool like Roborazzi or Paparazzi.

These methods are not mutually exclusive — you can generate and upload snapshots from your previews and any existing snapshot tests.

Generate Snapshots From Compose Previews (Recommended)

Paparazzi and ComposePreviewScanner automatically turns every @Preview composable in your project into a snapshot image, so you don't have to maintain explicit snapshot tests.

First, choose a Paparazzi version compatible with your project:

Then apply the plugin:

plugins {
  // existing plugins
  id("app.cash.paparazzi") version "<paparazzi_version>"
}

plugins {
  // existing plugins
  id("app.cash.paparazzi") version "<paparazzi_version>"
}

Continue to Step 3.

Generate Snapshots From an Existing Snapshot Tool

Use this path if you already generate snapshots with another tool. The configuration depends on which tool you use.

Paparazzi

If you already have Paparazzi configured, set generateTests = false inside the previews block so Sentry uses your existing tests instead of auto-generating preview-based ones:

sentry {
  snapshots {
    enabled = true
    previews {
      generateTests = false
    }
  }
}

sentry {
  snapshots {
    enabled = true
    previews {
      generateTests = false
    }
  }
}

Continue to Step 3.

Roborazzi

If you already have Roborazzi configured, wire the Sentry upload task to the output of your Roborazzi record task:

afterEvaluate {
  tasks.named<SentryUploadSnapshotsTask>("sentryUploadSnapshotsDebug") {
    dependsOn(tasks.named("recordRoborazziDebug"))
    snapshotsPath.set(
      project.extensions.getByType<RoborazziExtension>().outputDir
    )
  }
}

afterEvaluate {
  tasks.named<SentryUploadSnapshotsTask>("sentryUploadSnapshotsDebug") {
    dependsOn(tasks.named("recordRoborazziDebug"))
    snapshotsPath.set(
      project.extensions.getByType<RoborazziExtension>().outputDir
    )
  }
}

Continue to Step 3.

Other Tools

The same pattern works with any snapshot tool. Set snapshotsPath to the directory your tool writes images to, and add a dependsOn for the task that generates them:

afterEvaluate {
  tasks.named<SentryUploadSnapshotsTask>("sentryUploadSnapshotsDebug") {
    dependsOn(tasks.named("yourSnapshotTask"))
    snapshotsPath.set(layout.projectDirectory.dir("path/to/snapshots"))
  }
}

afterEvaluate {
  tasks.named<SentryUploadSnapshotsTask>("sentryUploadSnapshotsDebug") {
    dependsOn(tasks.named("yourSnapshotTask"))
    snapshotsPath.set(layout.projectDirectory.dir("path/to/snapshots"))
  }
}

Alternatively, you can skip the Gradle plugin entirely and upload with sentry-cli snapshots upload:

sentry-cli snapshots upload ./build/paparazzi/snapshots \
  --app-id android-app

sentry-cli snapshots upload ./build/paparazzi/snapshots \
  --app-id android-app

Use this path if your build pipeline doesn't use Gradle, or if you want to run the upload outside of a Gradle task. See Uploading Snapshots for the expected directory layout.

Step 3: Test Locally

Verify your setup by running:

./gradlew sentryUploadSnapshotsDebug

./gradlew sentryUploadSnapshotsDebug

Step 4: Integrate Into CI

Once the local upload succeeds, wire the same command into your CI. See Integrating Into CI for an example GitHub Actions workflow.

Customize Preview Generation

The options below apply when using the Compose Previews path with generateTests = true (the default).

Preview Options

The previews block inside snapshots exposes options that shape the generated Paparazzi tests.

sentry {
  snapshots {
    enabled = true
    previews {
      theme = "@style/Theme.MyApp"          // optional
      includePrivatePreviews = false        // optional, defaults to true
      packageTrees = listOf("com.example")  // optional, defaults to Android namespace
    }
  }
}

sentry {
  snapshots {
    enabled = true
    previews {
      theme = "@style/Theme.MyApp"          // optional
      includePrivatePreviews = false        // optional, defaults to true
      packageTrees = listOf("com.example")  // optional, defaults to Android namespace
    }
  }
}

If you don't set a theme, Paparazzi uses its own default (android:Theme.Material.NoActionBar.Fullscreen). If the background of your previews isn't important — for example, when you just want to compare component geometry — you can use a translucent platform theme such as android:Theme.Translucent.NoTitleBar:

sentry {
  snapshots {
    enabled = true
    previews {
      theme = "android:Theme.Translucent.NoTitleBar"
    }
  }
}

sentry {
  snapshots {
    enabled = true
    previews {
      theme = "android:Theme.Translucent.NoTitleBar"
    }
  }
}

Set a Global Diff Threshold

To ignore small pixel changes across all snapshots, set diffThreshold in the plugin configuration:

sentry {
  snapshots {
    enabled = true
    diffThreshold = 0.01 // ignore changes of 1% or less
  }
}

sentry {
  snapshots {
    enabled = true
    diffThreshold = 0.01 // ignore changes of 1% or less
  }
}

The diffThreshold is a value between 0.0 and 1.0. Sentry reports a snapshot as changed only when the share of changed pixels exceeds this value. The default is 0.0 (report any difference).

Set Diff Thresholds Per Preview

To override the global threshold for specific previews, annotate them with @SentrySnapshot and set a diff threshold. First, add the runtime dependency:

dependencies {
  testImplementation("io.sentry:sentry-snapshots-runtime:6.18.0")
}

dependencies {
  testImplementation("io.sentry:sentry-snapshots-runtime:6.18.0")
}

Then annotate any @Preview composable:

import io.sentry.snapshots.runtime.SentrySnapshot

@SentrySnapshot(diffThreshold = 0.01f) // ignore changes of 1% or less
@Preview
@Composable
fun BillingPagePreview() {
  BillingPage()
}

import io.sentry.snapshots.runtime.SentrySnapshot

@SentrySnapshot(diffThreshold = 0.01f) // ignore changes of 1% or less
@Preview
@Composable
fun BillingPagePreview() {
  BillingPage()
}

Per-preview values take precedence over the global diffThreshold. See Diff Thresholds for other ways to configure thresholds.

Preview Annotation Reference

When you use the Compose previews path, the plugin renders one image per @Preview and writes a JSON metadata file next to it. The annotations on the composable control everything about the snapshot: how it's rendered, how it's named and grouped in Sentry, and how it's compared against its baseline.

The table below lists all supported attributes across Google's @Preview annotation and Sentry's @SentrySnapshot annotation. The Metadata column shows how each attribute is recorded in the snapshot's JSON metadata. Tags are only written when the attribute differs from its default, and tag values are always serialized as strings, even for numeric and boolean attributes.

For example, this preview:

@Preview(name = "Dark", group = "Checkout")
@Composable
fun BillingPagePreview() {
  BillingPage()
}

@Preview(name = "Dark", group = "Checkout")
@Composable
fun BillingPagePreview() {
  BillingPage()
}

produces the following metadata:

{
  "display_name": "BillingPagePreview.Dark_Checkout",
  "group": "Checkout",
  "tags": {
    "preview_name": "Dark"
  },
  "context": {
    "image_file_name": "com.example.billing.BillingScreenKt.BillingPagePreview.Dark_Checkout",
    "class_name": "com.example.billing.BillingScreenKt",
    "method_name": "BillingPagePreview"
  }
}

{
  "display_name": "BillingPagePreview.Dark_Checkout",
  "group": "Checkout",
  "tags": {
    "preview_name": "Dark"
  },
  "context": {
    "image_file_name": "com.example.billing.BillingScreenKt.BillingPagePreview.Dark_Checkout",
    "class_name": "com.example.billing.BillingScreenKt",
    "method_name": "BillingPagePreview"
  }
}