From 9cceb749a86cfe8040525d41ff12d3b1b1b51d5c Mon Sep 17 00:00:00 2001 From: "cameron.cooke" Date: Fri, 12 Jun 2026 09:52:13 +0000 Subject: [PATCH 1/2] docs(readme): give JSON sidecar schema its own linkable section Co-Authored-By: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d2e0fe8..fca3cb3 100644 --- a/README.md +++ b/README.md @@ -94,9 +94,13 @@ These modes are mutually exclusive. If `TEST_RUNNER_SNAPSHOTS_ALL_IMAGE_NAMES_FI For every rendered preview, two files are written: - **`.png`** — the rendered preview image. -- **`.json`** — metadata sidecar used by Sentry Snapshots. +- **`.json`** — metadata sidecar used by Sentry Snapshots. See [JSON sidecar schema](#json-sidecar-schema) for field details. -The sidecar includes: +No Xcode code-coverage data (`.profraw` / `.profdata`) is written by the exporter — only the PNGs and sidecars. If you need code coverage from the same test run, enable it on the scheme as usual; coverage output goes to the `.xcresult` bundle independently. + +### JSON sidecar schema + +Each `.json` sidecar contains the following fields: | Field | Description | | --- | --- | @@ -123,8 +127,6 @@ import SnapshotPreferences } ``` -No Xcode code-coverage data (`.profraw` / `.profdata`) is written by the exporter — only the PNGs and sidecars. If you need code coverage from the same test run, enable it on the scheme as usual; coverage output goes to the `.xcresult` bundle independently. - ### 2. Upload to Sentry Choose one of the upload options below. From f7a3ba7ef1d2ea650e142e62fdc8d47f2b223f5d Mon Sep 17 00:00:00 2001 From: "cameron.cooke" Date: Fri, 12 Jun 2026 10:10:12 +0000 Subject: [PATCH 2/2] docs(readme): move env vars and JSON schema sections after upload steps Co-Authored-By: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> --- README.md | 86 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index fca3cb3..31f0ef7 100644 --- a/README.md +++ b/README.md @@ -77,20 +77,6 @@ xcodebuild test \ -destination 'platform=iOS Simulator,name=iPhone 15 Pro' ``` -### Environment variables - -SnapshotPreviews supports these test-runner environment variables: - -| Variable | Description | -| --- | --- | -| `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR` | Writes rendered snapshot PNGs and JSON sidecars to the given directory instead of attaching PNGs to the `.xcresult` bundle. | -| `TEST_RUNNER_SNAPSHOTS_ALL_IMAGE_NAMES_FILE` | Writes all discovered logical `.png` image names to the given file, then returns without rendering previews. Used to support selective testing workflows. | - -These modes are mutually exclusive. If `TEST_RUNNER_SNAPSHOTS_ALL_IMAGE_NAMES_FILE` is set, SnapshotPreviews writes image names only and does not render or export snapshot images. - -> [!NOTE] -> The `TEST_RUNNER_` prefix is how Xcode forwards an environment variable from `xcodebuild` into the test runner process. Inside the runner, SnapshotPreviews reads the variable without that prefix. - For every rendered preview, two files are written: - **`.png`** — the rendered preview image. @@ -98,34 +84,7 @@ For every rendered preview, two files are written: No Xcode code-coverage data (`.profraw` / `.profdata`) is written by the exporter — only the PNGs and sidecars. If you need code coverage from the same test run, enable it on the scheme as usual; coverage output goes to the `.xcresult` bundle independently. -### JSON sidecar schema - -Each `.json` sidecar contains the following fields: - -| Field | Description | -| --- | --- | -| `display_name` | Snapshot name shown in Sentry. Generated from the preview name, file path, and module so exported filenames stay stable and unambiguous. | -| `group` | Grouping key Sentry uses to organize related snapshots. Generated from the preview name, file path, and module. | -| `diff_threshold` | Allowed visual difference for this snapshot. See details below. | -| `tags` | Optional key-value pairs used to filter and group snapshots in Sentry. | -| `context` | Supporting metadata such as test name, simulator info, orientation, color scheme, source line, preview attributes, and any custom context you add. These fields are surfaced on the snapshot detail page in Sentry's UI. | - -SnapshotPreviews adds these `context` keys by default when values are available: `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`, and `preview.line`. - -Use `.snapshotAdditionalContext(...)` to add custom fields to `context`. Custom context is shallow-merged into the generated context, so a custom key such as `"test_name"` replaces the generated value. Supported custom values are strings, numbers, booleans, and nested objects. - -Use the `.snapshotDiffThreshold(...)` view modifier from the `SnapshotPreferences` product to customize the allowed visual difference for a specific preview. For example, `.snapshotDiffThreshold(0.05)` allows up to a 5% difference for that snapshot. - -```swift -import SnapshotPreferences - -#Preview("Map") { - MapPreview() - .snapshotTags(["screen": "map"]) - .snapshotAdditionalContext(["fixture": "city-route"]) - .snapshotDiffThreshold(0.05) -} -``` +See [Environment variables](#environment-variables) for all supported test-runner variables. ### 2. Upload to Sentry @@ -169,6 +128,49 @@ Use Sentry's Fastlane integration if your CI already uploads Apple artifacts thr See Sentry's [CI integration docs](https://docs.sentry.io/product/snapshots/integrating-into-ci/) for sharding across simulators and base/head SHA pinning. +### Environment variables + +SnapshotPreviews supports these test-runner environment variables: + +| Variable | Description | +| --- | --- | +| `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR` | Writes rendered snapshot PNGs and JSON sidecars to the given directory instead of attaching PNGs to the `.xcresult` bundle. | +| `TEST_RUNNER_SNAPSHOTS_ALL_IMAGE_NAMES_FILE` | Writes all discovered logical `.png` image names to the given file, then returns without rendering previews. Used to support selective testing workflows. | + +These modes are mutually exclusive. If `TEST_RUNNER_SNAPSHOTS_ALL_IMAGE_NAMES_FILE` is set, SnapshotPreviews writes image names only and does not render or export snapshot images. + +> [!NOTE] +> The `TEST_RUNNER_` prefix is how Xcode forwards an environment variable from `xcodebuild` into the test runner process. Inside the runner, SnapshotPreviews reads the variable without that prefix. + +### JSON sidecar schema + +Each `.json` sidecar contains the following fields: + +| Field | Description | +| --- | --- | +| `display_name` | Snapshot name shown in Sentry. Generated from the preview name, file path, and module so exported filenames stay stable and unambiguous. | +| `group` | Grouping key Sentry uses to organize related snapshots. Generated from the preview name, file path, and module. | +| `diff_threshold` | Allowed visual difference for this snapshot. See details below. | +| `tags` | Optional key-value pairs used to filter and group snapshots in Sentry. | +| `context` | Supporting metadata such as test name, simulator info, orientation, color scheme, source line, preview attributes, and any custom context you add. These fields are surfaced on the snapshot detail page in Sentry's UI. | + +SnapshotPreviews adds these `context` keys by default when values are available: `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`, and `preview.line`. + +Use `.snapshotAdditionalContext(...)` to add custom fields to `context`. Custom context is shallow-merged into the generated context, so a custom key such as `"test_name"` replaces the generated value. Supported custom values are strings, numbers, booleans, and nested objects. + +Use the `.snapshotDiffThreshold(...)` view modifier from the `SnapshotPreferences` product to customize the allowed visual difference for a specific preview. For example, `.snapshotDiffThreshold(0.05)` allows up to a 5% difference for that snapshot. + +```swift +import SnapshotPreferences + +#Preview("Map") { + MapPreview() + .snapshotTags(["screen": "map"]) + .snapshotAdditionalContext(["fixture": "city-route"]) + .snapshotDiffThreshold(0.05) +} +``` + ## Tips ### Unique display names