From 246b96080e66d8e0bf5ac2796987ad306fc2bccc Mon Sep 17 00:00:00 2001 From: "max.topolsky" Date: Tue, 9 Jun 2026 22:59:24 +0000 Subject: [PATCH 1/2] docs(snapshots): document --all-image-file-names and --all-image-file-names-file flags Co-Authored-By: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> --- docs/cli/snapshots.mdx | 26 +++++++++++++- .../snapshots/uploading-snapshots/index.mdx | 35 ++++++++++++++++++- 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/docs/cli/snapshots.mdx b/docs/cli/snapshots.mdx index 4e100b8f2285b..a2c35caa0c111 100644 --- a/docs/cli/snapshots.mdx +++ b/docs/cli/snapshots.mdx @@ -58,7 +58,29 @@ If you only upload a subset of your snapshots per CI run — for example, becaus sentry-cli snapshots upload ./snapshots --app-id web-frontend --selective ``` -When an upload is marked as selective, Sentry only diffs the snapshots you uploaded. Any snapshot that exists in the base build but was not included in the upload is treated as unchanged rather than removed. Removals and renames cannot be detected when using `--selective`, because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset. +When an upload is marked as selective, Sentry only diffs the snapshots you uploaded. Any snapshot that exists in the base build but was not included in the upload is treated as unchanged rather than removed. Removals and renames cannot be detected when using `--selective` alone, because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset. + +### Detecting Removals and Renames + +To enable removal and rename detection with selective uploads, pass the full list of image names in your test suite using `--all-image-file-names` or `--all-image-file-names-file`. Both flags implicitly enable `--selective`, so you don't need to pass it separately. + +Pass a comma-separated list inline: + +```bash +sentry-cli snapshots upload ./snapshots \ + --app-id web-frontend \ + --all-image-file-names "homepage.png,settings/profile.png,settings/billing.png" +``` + +Or provide a file with one image name per line: + +```bash +sentry-cli snapshots upload ./snapshots \ + --app-id web-frontend \ + --all-image-file-names-file all-snapshot-names.txt +``` + +With either flag, Sentry knows the complete set of images in your suite and can distinguish a skipped test from a deleted snapshot. The CLI also validates that every uploaded image is present in the provided list and exits with an error if any is missing. ## Diff Threshold @@ -84,6 +106,8 @@ sentry-cli snapshots upload [OPTIONS] --app-id | `-o`, `--org ` | Sentry organization slug. Can also be set via `SENTRY_ORG`. | | `-p`, `--project ` | Sentry project slug. Can also be set via `SENTRY_PROJECT`. | | `--selective` | Mark the upload as a subset. Use when uploading only a portion of your snapshots (for example, affected tests only). | +| `--all-image-file-names ` | Comma-separated list of all image names (including subdirectory paths) in the full test suite. Used with selective uploads to detect removals and renames. Implicitly enables `--selective`. Mutually exclusive with `--all-image-file-names-file`. | +| `--all-image-file-names-file ` | Path to a file listing all image names (including subdirectory paths), one per line. Used with selective uploads to detect removals and renames. Implicitly enables `--selective`. Mutually exclusive with `--all-image-file-names`. | | `--diff-threshold ` | Float between `0.0` and `1.0`. Sentry only reports images as changed if the percentage of changed pixels exceeds this value. | | `--head-sha ` | Commit SHA for the upload. Auto-detected in CI. | | `--base-sha ` | Base commit SHA for comparison (PR only). Auto-detected from merge-base. | diff --git a/docs/product/snapshots/uploading-snapshots/index.mdx b/docs/product/snapshots/uploading-snapshots/index.mdx index 354db37eafdac..b21b95aa12c00 100644 --- a/docs/product/snapshots/uploading-snapshots/index.mdx +++ b/docs/product/snapshots/uploading-snapshots/index.mdx @@ -93,7 +93,40 @@ When an upload is marked as selective, Sentry only diffs the snapshots you uploa Because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset, removals and renames cannot be detected when - using `--selective`. + using `--selective` alone. Use `--all-image-file-names` or + `--all-image-file-names-file` to enable removal and rename detection. +### Detecting Removals and Renames + +To enable removal and rename detection with selective uploads, provide the complete list of image names in your test suite. Both flags below implicitly enable `--selective`, so you don't need to pass it separately. + +Pass a comma-separated list inline: + +```bash +sentry-cli snapshots upload ./snapshots \ + --app-id web-frontend \ + --all-image-file-names "homepage.png,settings/profile.png,settings/billing.png" +``` + +Or provide a file with one image name per line (useful when the list is large or generated by your test runner): + +```bash +sentry-cli snapshots upload ./snapshots \ + --app-id web-frontend \ + --all-image-file-names-file all-snapshot-names.txt +``` + +Where `all-snapshot-names.txt` contains: + +``` +homepage.png +settings/profile.png +settings/billing.png +``` + +With either flag, Sentry knows the complete set of images in your suite and can tell the difference between a skipped test and a deleted snapshot — enabling accurate removal and rename detection. + +The CLI validates that every image you upload is present in the provided list, and exits with an error if any uploaded image is missing from it. + For the full `sentry-cli snapshots upload` flag reference, see [Snapshots (CLI)](/cli/snapshots/). From f3d0e96d584f8fafeb128e9f24f4b91c1cf56af0 Mon Sep 17 00:00:00 2001 From: "max.topolsky" Date: Tue, 9 Jun 2026 23:03:15 +0000 Subject: [PATCH 2/2] docs(snapshots): trim selective testing additive content Co-Authored-By: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> --- docs/cli/snapshots.mdx | 12 +++------- .../snapshots/uploading-snapshots/index.mdx | 22 ++++--------------- 2 files changed, 7 insertions(+), 27 deletions(-) diff --git a/docs/cli/snapshots.mdx b/docs/cli/snapshots.mdx index a2c35caa0c111..78dccc34ac75a 100644 --- a/docs/cli/snapshots.mdx +++ b/docs/cli/snapshots.mdx @@ -62,26 +62,20 @@ When an upload is marked as selective, Sentry only diffs the snapshots you uploa ### Detecting Removals and Renames -To enable removal and rename detection with selective uploads, pass the full list of image names in your test suite using `--all-image-file-names` or `--all-image-file-names-file`. Both flags implicitly enable `--selective`, so you don't need to pass it separately. - -Pass a comma-separated list inline: +Pass the full list of image names in your suite to enable removal and rename detection. Both flags implicitly enable `--selective`. ```bash +# comma-separated inline sentry-cli snapshots upload ./snapshots \ --app-id web-frontend \ --all-image-file-names "homepage.png,settings/profile.png,settings/billing.png" -``` - -Or provide a file with one image name per line: -```bash +# or a file with one name per line sentry-cli snapshots upload ./snapshots \ --app-id web-frontend \ --all-image-file-names-file all-snapshot-names.txt ``` -With either flag, Sentry knows the complete set of images in your suite and can distinguish a skipped test from a deleted snapshot. The CLI also validates that every uploaded image is present in the provided list and exits with an error if any is missing. - ## Diff Threshold Use `--diff-threshold` to ignore sub-pixel or anti-aliasing noise. The value is a float between `0.0` and `1.0` representing the fraction of pixels that must change before Sentry reports an image as changed: diff --git a/docs/product/snapshots/uploading-snapshots/index.mdx b/docs/product/snapshots/uploading-snapshots/index.mdx index b21b95aa12c00..58b68da0c5cd1 100644 --- a/docs/product/snapshots/uploading-snapshots/index.mdx +++ b/docs/product/snapshots/uploading-snapshots/index.mdx @@ -99,34 +99,20 @@ When an upload is marked as selective, Sentry only diffs the snapshots you uploa ### Detecting Removals and Renames -To enable removal and rename detection with selective uploads, provide the complete list of image names in your test suite. Both flags below implicitly enable `--selective`, so you don't need to pass it separately. - -Pass a comma-separated list inline: +Pass the full list of image names in your suite to enable removal and rename detection. Both flags implicitly enable `--selective`. ```bash +# comma-separated inline sentry-cli snapshots upload ./snapshots \ --app-id web-frontend \ --all-image-file-names "homepage.png,settings/profile.png,settings/billing.png" -``` - -Or provide a file with one image name per line (useful when the list is large or generated by your test runner): -```bash +# or a file with one name per line sentry-cli snapshots upload ./snapshots \ --app-id web-frontend \ --all-image-file-names-file all-snapshot-names.txt ``` -Where `all-snapshot-names.txt` contains: - -``` -homepage.png -settings/profile.png -settings/billing.png -``` - -With either flag, Sentry knows the complete set of images in your suite and can tell the difference between a skipped test and a deleted snapshot — enabling accurate removal and rename detection. - -The CLI validates that every image you upload is present in the provided list, and exits with an error if any uploaded image is missing from it. +The CLI validates that every uploaded image appears in the provided list. For the full `sentry-cli snapshots upload` flag reference, see [Snapshots (CLI)](/cli/snapshots/).