From e212c79e4418b28e992b921cc672badf871f51ad Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Fri, 29 May 2026 14:43:58 +0100 Subject: [PATCH] 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 0d3f6057b9644f..407ac819218f88 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 00000000000000..f9e59a5ab0eb1f --- /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 a38cd9771ebc03..98b5c0f754e729 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