From e212c79e4418b28e992b921cc672badf871f51ad Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Fri, 29 May 2026 14:43:58 +0100 Subject: [PATCH 1/2] docs(snapshots): Document SnapshotPreviews metadata Add SnapshotPreviews metadata docs for sidecar files, modifiers, and generated context. Update the generic snapshot upload schema with tags and context while keeping platform-specific details in the Apple docs. Co-Authored-By: OpenAI Codex --- .../apple/common/snapshots/index.mdx | 4 +- .../snapshots/snapshotpreviews-metadata.mdx | 103 ++++++++++++++++++ .../snapshots/uploading-snapshots/index.mdx | 19 +++- 3 files changed, 122 insertions(+), 4 deletions(-) create mode 100644 docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx diff --git a/docs/platforms/apple/common/snapshots/index.mdx b/docs/platforms/apple/common/snapshots/index.mdx index 0d3f6057b9644..407ac819218f8 100644 --- a/docs/platforms/apple/common/snapshots/index.mdx +++ b/docs/platforms/apple/common/snapshots/index.mdx @@ -36,12 +36,14 @@ class YourAppSnapshotTest: SnapshotTest { } ``` -Set `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR` before running the tests so SnapshotPreviews writes images to disk instead of attaching them to the XCTest result bundle: +Set `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR` before running the tests so SnapshotPreviews writes images to disk instead of attaching them to the XCTest result bundle. When this is set, SnapshotPreviews also writes JSON metadata sidecars next to the images: ```bash export TEST_RUNNER_SNAPSHOTS_EXPORT_DIR="$PWD/snapshot-images" ``` +To customize per-preview metadata in those sidecars, see [SnapshotPreviews Metadata](/platforms/apple/snapshots/snapshotpreviews-metadata/). + Continue to [Step 2](#step-2-test-locally). ### Generate Snapshots From an Existing Snapshot Tool diff --git a/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx b/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx new file mode 100644 index 0000000000000..f9e59a5ab0eb1 --- /dev/null +++ b/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx @@ -0,0 +1,103 @@ +--- +title: SnapshotPreviews Metadata +sidebar_title: SnapshotPreviews Metadata +sidebar_order: 4951 +sidebar_section: features +description: Add tags, context, and diff thresholds to SnapshotPreviews sidecar metadata. +early_access: true +--- + + + +SnapshotPreviews writes a JSON metadata sidecar next to each exported image when `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR` is set. Sentry uploads this metadata with the image and uses it to group snapshots, apply local diff thresholds, and provide context for review. + +For the platform-agnostic sidecar schema, see [Uploading Snapshots](/product/snapshots/uploading-snapshots/#json-metadata). + +## Add Per-Preview Metadata + +Link the `SnapshotPreferences` target to the app target that contains your previews, then import it where you define previews. + +Use modifiers on a preview view to add metadata: + +```swift +import SnapshotPreferences + +#Preview("Billing page") { + BillingView() + .snapshotTags([ + "surface": "billing", + "team": "growth", + ]) + .snapshotAdditionalContext([ + "component": "BillingView", + "variant": [ + "plan": "team", + "trial": true, + ], + ]) + .snapshotDiffThreshold(0.01) +} +``` + +## SnapshotPreviews Modifiers + +| Modifier | Description | +| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `.snapshotTags([String: String])` | Adds top-level `tags` to the sidecar for filtering or grouping snapshots. | +| `.snapshotAdditionalContext([String: Any])` | Adds arbitrary key-value context to the sidecar `context` object. Values can be strings, numbers, booleans, or nested objects. | +| `.snapshotDiffThreshold(Float?)` | Adds a local `diff_threshold` for this preview. Sentry reports the image as changed only when the share of changed pixels is greater than this value. | + +## Generated Sidecar Metadata + +SnapshotPreviews generates default sidecar metadata for each preview. The exact values depend on the preview and simulator, but the sidecar can look like this: + +```json +{ + "display_name": "Billing page", + "group": "Checkout Preview", + "tags": { + "surface": "billing", + "team": "growth" + }, + "diff_threshold": 0.01, + "context": { + "test_name": "-[YourAppSnapshotTest portrait-Checkout Preview-1-6]", + "accessibility_enabled": false, + "component": "BillingView", + "variant": { + "plan": "team", + "trial": true + }, + "preview": { + "container_display_name": "Checkout Preview", + "container_type_name": "YourApp.CheckoutPreview", + "display_name": "Billing page", + "index": 1, + "orientation": "portrait", + "preferred_color_scheme": "dark" + }, + "simulator": { + "device_name": "iPhone 17 Pro", + "model_identifier": "iPhone18,1" + } + } +} +``` + +## Generated Context Keys + +SnapshotPreviews can generate these `context` keys: + +- `test_name` +- `accessibility_enabled` +- `simulator.device_name` +- `simulator.model_identifier` +- `preview.index` +- `preview.display_name` +- `preview.container_type_name` +- `preview.container_display_name` +- `preview.preferred_color_scheme` +- `preview.orientation` +- `preview.line` + +Additional context is merged into the generated `context` object. If a custom key matches a generated key, the custom value overrides the generated value. diff --git a/docs/product/snapshots/uploading-snapshots/index.mdx b/docs/product/snapshots/uploading-snapshots/index.mdx index a38cd9771ebc0..98b5c0f754e72 100644 --- a/docs/product/snapshots/uploading-snapshots/index.mdx +++ b/docs/product/snapshots/uploading-snapshots/index.mdx @@ -48,15 +48,28 @@ You can include an optional JSON file to add metadata to each image: { "display_name": "Billing Page", "group": "Settings", - "diff_threshold": 0.01 + "tags": { + "surface": "billing", + "team": "growth" + }, + "diff_threshold": 0.01, + "context": { + "component": "BillingPage", + "variant": { + "plan": "team", + "trial": true + } + } } ``` | Field | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `display_name` | string | Human-readable label shown in the comparison. viewer. | -| `group` | string | Groups related snapshots in the UI. sidebar. | +| `display_name` | string | Human-readable label shown in the comparison viewer. | +| `group` | string | Groups related snapshots in the UI sidebar. | +| `tags` | object | String key-value pairs for filtering or grouping snapshots. | | `diff_threshold` | number | Value from `0.0` to `1.0`. Sentry reports the image as changed only when the share of changed pixels is greater than this value. `0.01` ignores changes of 1% or less. | +| `context` | object | Arbitrary key-value context that tools and LLMs can use to help diagnose changes. Values can be strings, numbers, booleans, or nested objects. | ### Supported Formats From 6bc12affbd9d7a0d2ff44e70492967236387bffc Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 1 Jun 2026 14:58:13 +0000 Subject: [PATCH 2/2] docs(snapshots): Clarify that context keys are automatically generated Change wording from 'can generate' to 'automatically generates' to make it clear that SnapshotPreviews always generates these context keys for every preview, not conditionally. Co-Authored-By: Claude Co-authored-by: Cameron Cooke --- .../apple/common/snapshots/snapshotpreviews-metadata.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx b/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx index f9e59a5ab0eb1..e3eb5ce824dd9 100644 --- a/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx +++ b/docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx @@ -86,7 +86,7 @@ SnapshotPreviews generates default sidecar metadata for each preview. The exact ## Generated Context Keys -SnapshotPreviews can generate these `context` keys: +SnapshotPreviews automatically generates these `context` keys: - `test_name` - `accessibility_enabled`