SnapshotPreviews Metadata
Add tags, context, and diff thresholds to SnapshotPreviews sidecar metadata.
This feature is available only if you're in the Early Adopter program. Features available to Early Adopters are still in-progress and may have bugs. We recognize the irony.
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.
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:
import SnapshotPreferences
#Preview("Billing page") {
BillingView()
.snapshotTags([
"surface": "billing",
"team": "growth",
])
.snapshotAdditionalContext([
"component": "BillingView",
"variant": [
"plan": "team",
"trial": true,
],
])
.snapshotDiffThreshold(0.01)
.snapshotCanvasTheme(.dark)
}
import SnapshotPreferences
#Preview("Billing page") {
BillingView()
.snapshotTags([
"surface": "billing",
"team": "growth",
])
.snapshotAdditionalContext([
"component": "BillingView",
"variant": [
"plan": "team",
"trial": true,
],
])
.snapshotDiffThreshold(0.01)
.snapshotCanvasTheme(.dark)
}
| 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. |
.snapshotCanvasTheme(SnapshotCanvasTheme) | Sets the top-level canvas_theme (.light or .dark) used behind the image in Sentry's web UI. Display metadata only; it doesn't change the rendered snapshot image. |
SnapshotPreviews generates default sidecar metadata for each preview. The exact values depend on the preview and simulator, but the sidecar can look like this:
{
"display_name": "Billing page",
"group": "Checkout Preview",
"tags": {
"surface": "billing",
"team": "growth"
},
"diff_threshold": 0.01,
"canvas_theme": "dark",
"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"
}
}
}
{
"display_name": "Billing page",
"group": "Checkout Preview",
"tags": {
"surface": "billing",
"team": "growth"
},
"diff_threshold": 0.01,
"canvas_theme": "dark",
"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"
}
}
}
SnapshotPreviews automatically generates these context keys:
test_nameaccessibility_enabledsimulator.device_namesimulator.model_identifierpreview.indexpreview.display_namepreview.container_type_namepreview.container_display_namepreview.preferred_color_schemepreview.orientationpreview.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.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").