sentry-snapshots-cocoa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sentry Snapshots for Apple/Cocoa

Scope

适用范围

Goal: generate Apple snapshot images and upload them to Sentry Snapshots.
Detect existing snapshot generation first, including Point-Free
```
swift-snapshot-testing
```
; preserve it when it already emits or can emit PNGs or JPEGs.
Use the Sentry Wizard
```
appleSnapshots
```
flow only when setting up Sentry’s first-party SnapshotPreviews solution.
Use manual setup only if the wizard is unavailable, cannot resolve targets non-interactively after disambiguation, or fails after explicit disambiguation.
Package-only SwiftPM: stop and ask for the host app/test target; standalone
```
swift test
```
rendering is not supported.

目标：生成Apple快照图片并上传至Sentry Snapshots。
首先检测现有的快照生成工具，包括Point-Free的
```
swift-snapshot-testing
```
；若该工具已支持输出或可配置输出PNG或JPEG格式，则保留现有配置。
仅在配置Sentry官方的SnapshotPreviews方案时，使用Sentry Wizard的
```
appleSnapshots
```
流程。
仅当Wizard不可用、无法在消歧义后以非交互方式解析目标，或明确消歧义后仍失败时，才使用手动配置方式。
纯SwiftPM包项目：停止操作并询问宿主应用/测试目标；不支持独立的
```
swift test
```
渲染方式。

Detect

检测环节

Do only enough detection to route before calling the wizard:

bash

undefined

仅进行必要的检测以确定后续流程，再调用Wizard：

bash

undefined

SnapshotPreviews (Sentry first-party) -> prefer wizard / SnapshotPreviews routing

SnapshotPreviews（Sentry官方方案）-> 优先使用Wizard / SnapshotPreviews流程

find . ( -name Package.swift -o -name Package.resolved -o -path '*/project.pbxproj' ) -print0 2>/dev/null | xargs -0 grep -lE "SnapshotPreviews" 2>/dev/null

Point-Free swift-snapshot-testing -> preserve generator, swift-snapshot-testing CI path

Point-Free swift-snapshot-testing -> 保留生成器，采用swift-snapshot-testing的CI流程

Required wizard input

Wizard所需的输入信息

find . -name '*.xcodeproj' -print 2>/dev/null | head -20

Workflow shape

工作流形态

ls fastlane/Fastfile Gemfile 2>/dev/null

Sentry auth presence only -> never print secret values

仅检查Sentry认证是否存在 -> 绝不打印密钥值

[ -n "$SENTRY_AUTH_TOKEN" ] && echo "SENTRY_AUTH_TOKEN=set" || echo "SENTRY_AUTH_TOKEN=unset" [ -n "$SENTRY_ORG" ] && echo "SENTRY_ORG=set" || echo "SENTRY_ORG=unset" [ -n "$SENTRY_PROJECT" ] && echo "SENTRY_PROJECT=set" || echo "SENTRY_PROJECT=unset"


Record: existing SnapshotPreviews setup, existing snapshot generator/library, output
directory if known, Xcode project directory, CI provider, Fastlane, and Sentry auth.
For each `.xcodeproj` match, record the containing directory for `--xcode-project-dir`;
if `find` prints `./MyApp/MyApp.xcodeproj`, pass `./MyApp`, not the bundle path.
Let the wizard detect app targets, hosted XCTest targets, and Swift previews only when
no existing generator is present.


记录：现有SnapshotPreviews配置、现有快照生成器/库、已知的输出目录、Xcode项目目录、CI提供商、Fastlane以及Sentry认证信息。对于每个匹配的`.xcodeproj`，记录其所在目录作为`--xcode-project-dir`的参数；若`find`输出`./MyApp/MyApp.xcodeproj`，则传入`./MyApp`而非bundle路径。仅当不存在现有生成器时，才让Wizard检测应用目标、托管的XCTest目标和Swift预览。

Route

流程路由

Resolve routing in this order; setup is the primary path and CI is optional follow-up.

Select or create the image generator:
- named generator wins;
- multiple existing generators with no user choice -> ask;
- existing non-SnapshotPreviews generator -> preserve it;
- existing SnapshotPreviews -> use it;
- no existing generator -> set up SnapshotPreviews by default for Sentry Snapshots or Apple snapshot testing.
For SnapshotPreviews, stop before setup/verification/CI if there is no
```
.xcodeproj
```
host app or no hosted XCTest target. These stops do not apply when preserving another generator.
For setup or verification:
- existing non-SnapshotPreviews generator -> read
```
references/snapshots.md
```
  ;
- existing SnapshotPreviews -> read
```
references/snapshot-previews.md
```
  and
```
references/snapshots.md
```
  ;
- new SnapshotPreviews setup -> read
```
references/wizard-setup.md
```
  ;
- wizard reports no Swift previews -> ask before adding previews or choosing another generator.
For GitHub Actions/CI only after an image generator exists:
- Point-Free
```
swift-snapshot-testing
```
  -> read
```
references/github-actions-swift-snapshot-testing.md
```
  and
```
references/snapshots.md
```
  ;
- other non-SnapshotPreviews generator -> read
```
references/snapshots.md
```
  and adapt existing CI/upload;
- SnapshotPreviews, one simulator only, no matrix/fanout/selective CI -> read
```
references/github-actions-simple.md
```
  ;
- SnapshotPreviews with multiple simulators, device families, matrix, or any selective CI -> read
```
references/github-actions-fanout.md
```
  and
```
references/snapshot-previews.md
```
  .

按以下顺序确定流程路径；配置是主要流程，CI配置为可选后续步骤。

选择或创建图片生成器：
- 指定名称的生成器优先；
- 存在多个现有生成器且用户未选择时 -> 询问用户；
- 存在非SnapshotPreviews的生成器 -> 保留该生成器；
- 存在SnapshotPreviews -> 使用该方案；
- 无现有生成器 -> 默认配置SnapshotPreviews以实现Sentry Snapshots或Apple快照测试。
对于SnapshotPreviews方案，若不存在
```
.xcodeproj
```
宿主应用或托管的XCTest目标，则在配置/验证/CI环节前停止操作。此停止规则不适用于保留其他生成器的场景。
配置或验证环节：
- 存在非SnapshotPreviews生成器 -> 参考
```
references/snapshots.md
```
  ；
- 存在SnapshotPreviews -> 参考
```
references/snapshot-previews.md
```
  和
```
references/snapshots.md
```
  ；
- 新配置SnapshotPreviews -> 参考
```
references/wizard-setup.md
```
  ；
- Wizard检测不到Swift预览 -> 在添加预览或选择其他生成器前询问用户。
仅当图片生成器已存在时，进行GitHub Actions/CI配置：
- Point-Free
```
swift-snapshot-testing
```
  -> 参考
```
references/github-actions-swift-snapshot-testing.md
```
  和
```
references/snapshots.md
```
  ；
- 其他非SnapshotPreviews生成器 -> 参考
```
references/snapshots.md
```
  并适配现有CI/上传流程；
- SnapshotPreviews、仅单个模拟器、无矩阵/扇出/选择性CI -> 参考
```
references/github-actions-simple.md
```
  ；
- SnapshotPreviews、多个模拟器、多设备类型、矩阵或任何选择性CI -> 参考
```
references/github-actions-fanout.md
```
  和
```
references/snapshot-previews.md
```
  。

Optional References

可选参考文档

Need	Read
First-party SnapshotPreviews setup, disambiguation, or manual fallback	`references/wizard-setup.md`
SnapshotPreviews metadata, rendering preferences, selective rendering, or SnapshotPreviews-specific troubleshooting	`references/snapshot-previews.md`
Upload any generated snapshot images to Sentry with Fastlane, `sentry-cli` , manifests, CI notes, or upload troubleshooting	`references/snapshots.md`
One-destination GitHub Actions workflow	`references/github-actions-simple.md`
Multi-destination/fan-out GitHub Actions workflow	`references/github-actions-fanout.md`
Point-Free `swift-snapshot-testing` GitHub Actions workflow	`references/github-actions-swift-snapshot-testing.md`

需求	参考文档
官方SnapshotPreviews配置、消歧义或手动 fallback	`references/wizard-setup.md`
SnapshotPreviews元数据、渲染偏好、选择性渲染或SnapshotPreviews专属故障排查	`references/snapshot-previews.md`
使用Fastlane、 `sentry-cli` 、清单文件将生成的快照图片上传至Sentry，CI注意事项或上传故障排查	`references/snapshots.md`
单目标GitHub Actions工作流	`references/github-actions-simple.md`
多目标/扇出GitHub Actions工作流	`references/github-actions-fanout.md`
Point-Free `swift-snapshot-testing` 的GitHub Actions工作流	`references/github-actions-swift-snapshot-testing.md`

Completion Checks

完成检查

The selected snapshot image generator is documented and preserved or configured according to the route above.
Snapshot generation appears in the relevant local or CI test logs.
Export directory contains
```
.png
```
files and any generated
```
.json
```
sidecars.
Upload succeeds and prints a Sentry URL or snapshot id.
Base branch upload is full; selective PR upload includes the full image-name manifest.

所选快照图片生成器已按上述流程记录并保留或配置完成。
快照生成记录出现在相关的本地或CI测试日志中。
导出目录包含
```
.png
```
文件及所有生成的
```
.json
```
附属文件。
上传成功并输出Sentry URL或快照ID。
基础分支上传为完整快照；选择性PR上传包含完整的图片名称清单。