Skip to content

Commit e212c79

Browse files
cameroncookecodex
cameroncooke
and
codex
committed
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 <noreply@openai.com>
1 parent 14000e6 commit e212c79

3 files changed

Lines changed: 122 additions & 4 deletions

File tree

‎docs/platforms/apple/common/snapshots/index.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,14 @@ class YourAppSnapshotTest: SnapshotTest {
3636
}
3737
```
3838

39-
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:
39+
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:
4040

4141
```bash
4242
export TEST_RUNNER_SNAPSHOTS_EXPORT_DIR="$PWD/snapshot-images"
4343
```
4444

45+
To customize per-preview metadata in those sidecars, see [SnapshotPreviews Metadata](/platforms/apple/snapshots/snapshotpreviews-metadata/).
46+
4547
Continue to [Step 2](#step-2-test-locally).
4648

4749
### Generate Snapshots From an Existing Snapshot Tool

‎docs/platforms/apple/common/snapshots/snapshotpreviews-metadata.mdx‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: SnapshotPreviews Metadata
3+
sidebar_title: SnapshotPreviews Metadata
4+
sidebar_order: 4951
5+
sidebar_section: features
6+
description: Add tags, context, and diff thresholds to SnapshotPreviews sidecar metadata.
7+
early_access: true
8+
---
9+
10+
<Include name="feature-available-for-user-group-early-adopter" />
11+
12+
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.
13+
14+
For the platform-agnostic sidecar schema, see [Uploading Snapshots](/product/snapshots/uploading-snapshots/#json-metadata).
15+
16+
## Add Per-Preview Metadata
17+
18+
Link the `SnapshotPreferences` target to the app target that contains your previews, then import it where you define previews.
19+
20+
Use modifiers on a preview view to add metadata:
21+
22+
```swift
23+
import SnapshotPreferences
24+
25+
#Preview("Billing page") {
26+
BillingView()
27+
.snapshotTags([
28+
"surface": "billing",
29+
"team": "growth",
30+
])
31+
.snapshotAdditionalContext([
32+
"component": "BillingView",
33+
"variant": [
34+
"plan": "team",
35+
"trial": true,
36+
],
37+
])
38+
.snapshotDiffThreshold(0.01)
39+
}
40+
```
41+
42+
## SnapshotPreviews Modifiers
43+
44+
| Modifier | Description |
45+
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
46+
| `.snapshotTags([String: String])` | Adds top-level `tags` to the sidecar for filtering or grouping snapshots. |
47+
| `.snapshotAdditionalContext([String: Any])` | Adds arbitrary key-value context to the sidecar `context` object. Values can be strings, numbers, booleans, or nested objects. |
48+
| `.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. |
49+
50+
## Generated Sidecar Metadata
51+
52+
SnapshotPreviews generates default sidecar metadata for each preview. The exact values depend on the preview and simulator, but the sidecar can look like this:
53+
54+
```json
55+
{
56+
"display_name": "Billing page",
57+
"group": "Checkout Preview",
58+
"tags": {
59+
"surface": "billing",
60+
"team": "growth"
61+
},
62+
"diff_threshold": 0.01,
63+
"context": {
64+
"test_name": "-[YourAppSnapshotTest portrait-Checkout Preview-1-6]",
65+
"accessibility_enabled": false,
66+
"component": "BillingView",
67+
"variant": {
68+
"plan": "team",
69+
"trial": true
70+
},
71+
"preview": {
72+
"container_display_name": "Checkout Preview",
73+
"container_type_name": "YourApp.CheckoutPreview",
74+
"display_name": "Billing page",
75+
"index": 1,
76+
"orientation": "portrait",
77+
"preferred_color_scheme": "dark"
78+
},
79+
"simulator": {
80+
"device_name": "iPhone 17 Pro",
81+
"model_identifier": "iPhone18,1"
82+
}
83+
}
84+
}
85+
```
86+
87+
## Generated Context Keys
88+
89+
SnapshotPreviews can generate these `context` keys:
90+
91+
- `test_name`
92+
- `accessibility_enabled`
93+
- `simulator.device_name`
94+
- `simulator.model_identifier`
95+
- `preview.index`
96+
- `preview.display_name`
97+
- `preview.container_type_name`
98+
- `preview.container_display_name`
99+
- `preview.preferred_color_scheme`
100+
- `preview.orientation`
101+
- `preview.line`
102+
103+
Additional context is merged into the generated `context` object. If a custom key matches a generated key, the custom value overrides the generated value.

‎docs/product/snapshots/uploading-snapshots/index.mdx‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,15 +48,28 @@ You can include an optional JSON file to add metadata to each image:
4848
{
4949
"display_name": "Billing Page",
5050
"group": "Settings",
51-
"diff_threshold": 0.01
51+
"tags": {
52+
"surface": "billing",
53+
"team": "growth"
54+
},
55+
"diff_threshold": 0.01,
56+
"context": {
57+
"component": "BillingPage",
58+
"variant": {
59+
"plan": "team",
60+
"trial": true
61+
}
62+
}
5263
}
5364
```
5465

5566
| Field | Type | Description |
5667
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
57-
| `display_name` | string | Human-readable label shown in the comparison. viewer. |
58-
| `group` | string | Groups related snapshots in the UI. sidebar. |
68+
| `display_name` | string | Human-readable label shown in the comparison viewer. |
69+
| `group` | string | Groups related snapshots in the UI sidebar. |
70+
| `tags` | object | String key-value pairs for filtering or grouping snapshots. |
5971
| `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. |
72+
| `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. |
6073

6174
### Supported Formats
6275

0 commit comments

Comments
 (0)