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