feat(snapshots): Add diff_threshold field to snapshot manifest

CHANGELOG.md

@@ -12,6 +12,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.