feat(snapshots): Add diff_threshold field to snapshot manifest (#3259)

Add an optional `--diff-threshold` CLI flag to the `build snapshots`
command. The value is included in the snapshot manifest JSON sent to the
backend.

When set, Sentry will only report images as changed if their pixel
difference percentage exceeds the given threshold (e.g. `0.01` = only
report changes >= 1%). The backend does not yet consume this field — a
follow-up PR in `getsentry/sentry` will read and apply it during
comparison.

Changes:
- `SnapshotsManifest`: new `diff_threshold: Option<f64>` field, skipped
when `None`
- `make_command`: new `--diff-threshold <THRESHOLD>` CLI argument
- `execute`: wires the CLI value into the manifest

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: NicoHinderling

CHANGELOG.md

@@ -20,6 +20,7 @@
 
 ### New Features ✨
 
+- (snapshots) Add `--diff-threshold` option to `build snapshots` to set a minimum pixel difference percentage for reporting image changes ([#3259](https://github.com/getsentry/sentry-cli/pull/3259))
 - Add `sentry-cli build download` command to download installable builds (IPA/APK) by build ID ([#3221](https://github.com/getsentry/sentry-cli/pull/3221)).
 - Add `sentry-cli code-mappings upload` command to bulk upload code mappings from a JSON file ([#3207](https://github.com/getsentry/sentry-cli/pull/3207), [#3208](https://github.com/getsentry/sentry-cli/pull/3208), [#3209](https://github.com/getsentry/sentry-cli/pull/3209), [#3210](https://github.com/getsentry/sentry-cli/pull/3210)).
   - Code mappings link stack trace paths (e.g. `com/example/module`) to source paths in your repository (e.g. `src/main/java/com/example/module`), enabling Sentry to display source context and link directly to your code from error stack traces.

src/api/data_types/snapshots.rs

@@ -25,6 +25,10 @@ pub struct CreateSnapshotResponse {
 pub struct SnapshotsManifest<'a> {
     pub app_id: String,
     pub images: HashMap<String, ImageMetadata>,
+    /// If set, Sentry will only report images as changed if their difference %
+    /// is greater than this value (e.g. 0.01 = only report changes >= 1%).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub diff_threshold: Option<f64>,
     #[serde(flatten)]
     pub vcs_info: VcsInfo<'a>,
 }

src/commands/build/snapshots.rs

@@ -51,6 +51,23 @@ pub fn make_command(command: Command) -> Command {
                 .help("The application identifier.")
                 .required(true),
         )
+        .arg(
+            Arg::new("diff_threshold")
+                .long("diff-threshold")
+                .value_name("THRESHOLD")
+                .value_parser(|s: &str| {
+                    let v: f64 = s.parse().map_err(|e| format!("invalid float: {e}"))?;
+                    if !(0.0..=1.0).contains(&v) {
+                        return Err("value must be between 0.0 and 1.0".to_owned());
+                    }
+                    Ok(v)
+                })
+                .help(
+                    "If set, Sentry will only report images as changed if their \
+                     difference % is greater than this value. \
+                     Example: 0.01 = only report image changes >= 1%.",
+                ),
+        )
         .git_metadata_args()
 }
 
@@ -123,9 +140,12 @@ pub fn execute(matches: &ArgMatches) -> Result<()> {
     let manifest_entries = upload_images(images, &org, &project)?;
 
     // Build manifest from discovered images
+    let diff_threshold = matches.get_one::<f64>("diff_threshold").copied();
+
     let manifest = SnapshotsManifest {
         app_id: app_id.clone(),
         images: manifest_entries,
+        diff_threshold,
         vcs_info,
     };
 

tests/integration/_cases/build/build-snapshots-help.trycmd

@@ -29,23 +29,27 @@ Options:
       --auth-token <AUTH_TOKEN>
           Use the given Sentry auth token.
 
-      --head-sha <head_sha>
-          The VCS commit sha to use for the upload. If not provided, the current commit sha will be
-          used.
+      --diff-threshold <THRESHOLD>
+          If set, Sentry will only report images as changed if their difference % is greater than
+          this value. Example: 0.01 = only report image changes >= 1%.
 
       --log-level <LOG_LEVEL>
           Set the log output verbosity. [possible values: trace, debug, info, warn, error]
 
-      --base-sha <base_sha>
-          The VCS commit's base sha to use for the upload. If not provided, the merge-base of the
-          current and remote branch will be used.
+      --head-sha <head_sha>
+          The VCS commit sha to use for the upload. If not provided, the current commit sha will be
+          used.
 
       --quiet
           Do not print any output while preserving correct exit code. This flag is currently
           implemented only for selected subcommands.
 
           [aliases: --silent]
 
+      --base-sha <base_sha>
+          The VCS commit's base sha to use for the upload. If not provided, the merge-base of the
+          current and remote branch will be used.
+
       --vcs-provider <vcs_provider>
           The VCS provider to use for the upload. If not provided, the current provider will be
           used.