feat(snapshots): Add selective flag and rename all_image_names to all_image_file_names (#113006)

## Summary

Adds backend support for the new sentry-cli `--selective` flag
([sentry-cli PR
#3268](getsentry/sentry-cli#3268)).

- **`selective` boolean** added to upload API and manifest
- **`all_image_names` renamed to `all_image_file_names`** to match CLI
naming
- **Three categorization modes:**
- `selective` + `all_image_file_names`: can distinguish removed vs
skipped (like Happo/Chromatic)
- `selective` only: all missing base images treated as skipped, no
removals (like Argos `--subset`)
  - Full build: missing = removed (existing behavior)
- **Validation:** `all_image_file_names` requires `selective`,
`selective` requires `base_sha`
- **Baseline guard:** selective builds excluded from
`find_base_snapshot_artifact` via `is_selective` DB field and don't
trigger waiting-heads comparisons

## Test plan

- [x] Unit tests for 3-branch categorization logic (selective+names,
selective-only, full)
- [x] API validation tests (selective requires base_sha, names requires
selective, names rejects empty)
- [x] Selective build without names: all missing = skipped
- [x] Selective build with names: removed vs skipped distinguished
- [x] Fingerprinting excludes skipped images for auto-approval

---------

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

Author: NicoHinderling

src/sentry/preprod/api/endpoints/preprod_artifact_snapshot.py

@@ -80,6 +80,12 @@
             "maxProperties": 50000,
         },
         "diff_threshold": {"type": "number", "minimum": 0.0, "exclusiveMaximum": 1.0},
+        "selective": {"type": "boolean"},
+        "all_image_file_names": {
+            "type": "array",
+            "items": {"type": "string"},
+            "maxItems": 50000,
+        },
         **VCS_SCHEMA_PROPERTIES,
     },
     "required": ["app_id", "images"],
@@ -89,6 +95,8 @@
 SNAPSHOT_POST_REQUEST_ERROR_MESSAGES: dict[str, str] = {
     "app_id": "The app_id field is required and must be a string with maximum length of 255 characters.",
     "images": "The images field is required and must be an object mapping image names to image metadata.",
+    "selective": "The selective field must be a boolean.",
+    "all_image_file_names": "The all_image_file_names field must be an array of strings with at most 50000 entries.",
     **VCS_ERROR_MESSAGES,
 }
 
@@ -434,6 +442,8 @@ def get(self, request: Request, organization: Organization, snapshot_id: str) ->
                 unchanged_count=len(categorized.unchanged),
                 errored=categorized.errored,
                 errored_count=len(categorized.errored),
+                skipped=categorized.skipped,
+                skipped_count=len(categorized.skipped),
                 comparison_run_info=run_info,
                 approval_info=approval_info,
                 diff_threshold=manifest.diff_threshold,
@@ -481,6 +491,35 @@ def post(self, request: Request, project: Project) -> Response:
         base_ref = data.get("base_ref")
         pr_number = data.get("pr_number")
 
+        selective = data.get("selective", False)
+        all_image_file_names = data.get("all_image_file_names")
+
+        if all_image_file_names is not None and not selective:
+            return Response(
+                {"detail": "all_image_file_names requires selective to be true."},
+                status=400,
+            )
+
+        if selective and not base_sha:
+            return Response(
+                {"detail": "selective requires base_sha to be provided."},
+                status=400,
+            )
+
+        if all_image_file_names is not None:
+            if not all_image_file_names:
+                return Response(
+                    {"detail": "all_image_file_names must not be empty."},
+                    status=400,
+                )
+            all_image_file_names_set = set(all_image_file_names)
+            missing = set(images.keys()) - all_image_file_names_set
+            if missing:
+                return Response(
+                    {"detail": "Every image name must appear in all_image_file_names."},
+                    status=400,
+                )
+
         # has_vcs tag differentiates transactions that include a CommitComparison
         # lookup from those that skip it, so we can isolate their latency on dashboards.
         with (
@@ -522,13 +561,19 @@ def post(self, request: Request, project: Project) -> Response:
             snapshot_metrics = PreprodSnapshotMetrics.objects.create(
                 preprod_artifact=artifact,
                 image_count=len(images),
+                is_selective=selective,
                 extras={"manifest_key": manifest_key},
             )
 
             # Write manifest inside the transaction so that a failed objectstore
             # write rolls back the DB records, ensuring both succeed or neither does.
             session = get_preprod_session(project.organization_id, project.id)
-            manifest = SnapshotManifest(images=images, diff_threshold=diff_threshold)
+            manifest = SnapshotManifest(
+                images=images,
+                diff_threshold=diff_threshold,
+                selective=selective,
+                all_image_file_names=all_image_file_names,
+            )
             manifest_json = manifest.json(exclude_none=True)
             session.put(manifest_json.encode(), key=manifest_key)
 
@@ -654,7 +699,7 @@ def post(self, request: Request, project: Project) -> Response:
 
         # Trigger comparisons for any head artifacts that were uploaded before this base.
         # Handles possible out-of-order uploads where heads arrive before their base build.
-        if commit_comparison is not None:
+        if commit_comparison is not None and not selective:
             try:
                 waiting_heads = find_head_snapshot_artifacts_awaiting_base(
                     organization_id=project.organization_id,

src/sentry/preprod/api/models/snapshots/project_preprod_snapshot_models.py

@@ -16,6 +16,7 @@ class SnapshotDiffSection(StrEnum):
     CHANGED = "changed"
     UNCHANGED = "unchanged"
     ERRORED = "errored"
+    SKIPPED = "skipped"
 
 
 # GET response
@@ -93,6 +94,9 @@ class SnapshotDetailsApiResponse(BaseModel):
     errored: list[SnapshotDiffPair] = []
     errored_count: int = 0
 
+    skipped: list[SnapshotImageResponse] = []
+    skipped_count: int = 0
+
     comparison_run_info: SnapshotComparisonRunInfo | None = None
 
     approval_info: SnapshotApprovalInfo | None = None

src/sentry/preprod/snapshots/comparison_categorizer.py

@@ -21,6 +21,7 @@ class CategorizedComparison(BaseModel):
     unchanged: list[SnapshotImageResponse] = []
     renamed: list[SnapshotDiffPair] = []
     errored: list[SnapshotDiffPair] = []
+    skipped: list[SnapshotImageResponse] = []
 
 
 def _base_image_from_comparison(name: str, img: ComparisonImageResult) -> SnapshotImageResponse:
@@ -109,6 +110,8 @@ def categorize_comparison_images(
                     head_image=head,
                 )
             )
+        elif img.status == "skipped":
+            result.skipped.append(base_img or _base_image_from_comparison(name, img))
 
     result.changed.sort(key=lambda p: p.diff or 0, reverse=True)
     return result

src/sentry/preprod/snapshots/manifest.py

@@ -19,10 +19,12 @@ class Config:
 class SnapshotManifest(BaseModel):
     images: dict[str, ImageMetadata]
     diff_threshold: float | None = Field(default=None, ge=0.0, lt=1.0)
+    selective: bool = False
+    all_image_file_names: list[str] | None = None
 
 
 class ComparisonImageResult(BaseModel):
-    status: Literal["added", "removed", "changed", "unchanged", "errored", "renamed"]
+    status: Literal["added", "removed", "changed", "unchanged", "errored", "renamed", "skipped"]
     head_hash: str | None = None
     base_hash: str | None = None
     changed_pixels: int | None = None
@@ -46,6 +48,7 @@ class ComparisonSummary(BaseModel):
     removed: int
     errored: int
     renamed: int
+    skipped: int = 0
 
 
 class ComparisonManifest(BaseModel):

src/sentry/preprod/snapshots/tasks.py

@@ -51,6 +51,7 @@ class _ImageDiffResult(NamedTuple):
     matched: set[str]
     head_by_name: dict[str, str]
     base_by_name: dict[str, str]
+    skipped: set[str]
 
 
 def categorize_image_diff(
@@ -60,9 +61,21 @@ def categorize_image_diff(
     head_by_name = {key: (meta.content_hash or key) for key, meta in head_manifest.images.items()}
     base_by_name = {key: (meta.content_hash or key) for key, meta in base_manifest.images.items()}
 
+    all_image_file_names = head_manifest.all_image_file_names
+
     matched = head_by_name.keys() & base_by_name.keys()
     added = head_by_name.keys() - base_by_name.keys()
-    removed = base_by_name.keys() - head_by_name.keys()
+
+    if all_image_file_names is not None:
+        all_names_set = set(all_image_file_names)
+        removed = base_by_name.keys() - all_names_set
+        skipped = (all_names_set - head_by_name.keys()) & base_by_name.keys()
+    elif head_manifest.selective:
+        removed = set()
+        skipped = base_by_name.keys() - head_by_name.keys()
+    else:
+        removed = base_by_name.keys() - head_by_name.keys()
+        skipped = set()
 
     added_hash_to_names: dict[str, list[str]] = {}
     for name in added:
@@ -84,8 +97,25 @@ def categorize_image_diff(
     for new_name, old_name in renamed_pairs:
         added.discard(new_name)
         removed.discard(old_name)
-
-    return _ImageDiffResult(renamed_pairs, added, removed, matched, head_by_name, base_by_name)
+        added_hash_to_names.pop(head_by_name[new_name], None)
+
+    if skipped:
+        skipped_hash_to_names: dict[str, list[str]] = {}
+        for name in skipped:
+            h = base_by_name[name]
+            skipped_hash_to_names.setdefault(h, []).append(name)
+
+        for h in added_hash_to_names.keys() & skipped_hash_to_names.keys():
+            a_names = added_hash_to_names[h]
+            s_names = skipped_hash_to_names[h]
+            if len(a_names) == 1 and len(s_names) == 1:
+                renamed_pairs.append((a_names[0], s_names[0]))
+                added.discard(a_names[0])
+                skipped.discard(s_names[0])
+
+    return _ImageDiffResult(
+        renamed_pairs, added, removed, matched, head_by_name, base_by_name, skipped
+    )
 
 
 def _image_name_to_path_stem(name: str) -> str:
@@ -124,7 +154,7 @@ class ImageFingerprint(NamedTuple):
 def _build_comparison_fingerprints(manifest: ComparisonManifest) -> set[ImageFingerprint]:
     fingerprints: set[ImageFingerprint] = set()
     for name, image in manifest.images.items():
-        if image.status == "unchanged":
+        if image.status in ("unchanged", "skipped"):
             continue
         if image.status in ("changed", "added"):
             if not image.head_hash:
@@ -629,6 +659,17 @@ def _fetch_hash(h: str) -> None:
                 "before_height": base_meta.height,
             }
 
+        skipped = categories.skipped
+        for name in sorted(skipped):
+            base_hash = base_by_name[name]
+            base_meta = base_meta_by_hash[base_hash]
+            image_results[name] = {
+                "status": "skipped",
+                "base_hash": base_hash,
+                "before_width": base_meta.width,
+                "before_height": base_meta.height,
+            }
+
         for new_name, old_name in sorted(renamed_pairs):
             content_hash = head_by_name[new_name]
             image_results[new_name] = {
@@ -641,13 +682,14 @@ def _fetch_hash(h: str) -> None:
             head_artifact_id=head_artifact_id,
             base_artifact_id=base_artifact_id,
             summary=ComparisonSummary(
-                total=len(matched) + len(added) + len(removed) + len(renamed_pairs),
+                total=len(matched) + len(added) + len(removed) + len(renamed_pairs) + len(skipped),
                 changed=changed_count,
                 unchanged=unchanged_count,
                 added=len(added),
                 removed=len(removed),
                 errored=error_count,
                 renamed=len(renamed_pairs),
+                skipped=len(skipped),
             ),
             images=image_results,
         )
@@ -668,6 +710,7 @@ def _fetch_hash(h: str) -> None:
         comparison.images_added = len(added)
         comparison.images_removed = len(removed)
         comparison.images_renamed = len(renamed_pairs)
+        comparison.images_skipped = len(skipped)
         extras = comparison.extras or {}
         # EME-896: Could become a proper column on PreprodSnapshotComparison
         extras["comparison_key"] = comparison_key
@@ -682,6 +725,7 @@ def _fetch_hash(h: str) -> None:
                 "images_added",
                 "images_removed",
                 "images_renamed",
+                "images_skipped",
                 "extras",
                 "date_updated",
             ]

src/sentry/preprod/snapshots/utils.py

@@ -23,6 +23,7 @@ def find_base_snapshot_artifact(
             commit_comparison__head_repo_name=base_repo_name,
             project_id=project_id,
             preprodsnapshotmetrics__isnull=False,
+            preprodsnapshotmetrics__is_selective=False,
             app_id=app_id,
             artifact_type=artifact_type,
             build_configuration=build_configuration,

tests/sentry/preprod/api/endpoints/test_preprod_artifact_snapshot.py

@@ -250,6 +250,58 @@ def test_snapshot_invalid_sha_format(self) -> None:
 
         assert response.status_code == 400
 
+    def _selective_data(self, **overrides):
+        data = {
+            "app_id": "com.test.app",
+            "images": {"screen.png": {"width": 100, "height": 200}},
+            "selective": True,
+            "all_image_file_names": ["screen.png", "skipped.png"],
+            "head_sha": "a" * 40,
+            "base_sha": "b" * 40,
+            "provider": "github.com",
+            "head_repo_name": "org/repo",
+            "head_ref": "feature",
+        }
+        data.update(overrides)
+        return data
+
+    def _post_selective(self, **overrides):
+        with self.feature("organizations:preprod-snapshots"):
+            return self.client.post(
+                self._get_create_url(), self._selective_data(**overrides), format="json"
+            )
+
+    def test_all_image_file_names_rejects_empty_list(self):
+        response = self._post_selective(images={}, all_image_file_names=[])
+        assert response.status_code == 400
+        assert "empty" in response.data["detail"]
+
+    def test_selective_requires_base_sha(self):
+        response = self._post_selective(base_sha=None)
+        assert response.status_code == 400
+        assert "base_sha" in response.data["detail"]
+
+    def test_all_image_file_names_must_contain_all_images(self):
+        response = self._post_selective(all_image_file_names=["other.png"])
+        assert response.status_code == 400
+        assert "all_image_file_names" in response.data["detail"]
+
+    def test_all_image_file_names_requires_selective(self):
+        response = self._post_selective(selective=False)
+        assert response.status_code == 400
+        assert "selective" in response.data["detail"]
+
+    def test_selective_without_all_image_file_names_accepted(self):
+        data = self._selective_data()
+        del data["all_image_file_names"]
+        with self.feature("organizations:preprod-snapshots"):
+            response = self.client.post(self._get_create_url(), data, format="json")
+        assert response.status_code == 200
+
+    def test_selective_with_all_image_file_names_accepted(self):
+        response = self._post_selective()
+        assert response.status_code == 200
+
     @patch("sentry.preprod.api.endpoints.preprod_artifact_snapshot.get_preprod_session")
     @patch("sentry.preprod.api.endpoints.preprod_artifact_snapshot.compare_snapshots")
     def test_base_upload_triggers_comparison_for_waiting_head(

tests/sentry/preprod/snapshots/test_auto_approve.py

@@ -86,6 +86,18 @@ def test_skips_changed_with_missing_head_hash(self):
         fps = _build_comparison_fingerprints(manifest)
         assert fps == {ImageFingerprint("has_hash.png", "changed", "def")}
 
+    def test_skipped_images_excluded_from_fingerprints(self):
+        manifest = self._make_manifest(
+            {
+                "changed.png": ComparisonImageResult(
+                    status="changed", head_hash="b", base_hash="c"
+                ),
+                "skipped.png": ComparisonImageResult(status="skipped", base_hash="e"),
+            }
+        )
+        fps = _build_comparison_fingerprints(manifest)
+        assert fps == {ImageFingerprint("changed.png", "changed", "b")}
+
     def test_skips_renamed_with_missing_hash_or_previous_name(self):
         manifest = self._make_manifest(
             {