sentry-snapshots-cocoa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sentry Snapshots for Apple/Cocoa

Apple/Cocoa 的 Sentry Snapshots

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.

Snapshot uploads send generated images and metadata to Sentry. Confirm the target organization/project and export directory, and check whether the images contain customer data or other sensitive content before uploading. Upload only the selected snapshot output within the user’s requested scope.

目标：生成 Apple 快照图像并将其上传到 Sentry Snapshots。
首先检测现有的快照生成机制，包括 Point-Free
```
swift-snapshot-testing
```
；如果它已经输出或能够输出 PNG 或 JPEG，则予以保留。
仅当为 Sentry 第一方 SnapshotPreviews 解决方案进行设置时，才使用 Sentry Wizard 的
```
appleSnapshots
```
流程。
仅当 Wizard 不可用、在明确消歧后仍无法以非交互方式解析 targets，或在明确消歧后失败时，才使用手动设置。
仅包含包的 SwiftPM：停止并询问 host app/test target；不支持独立的
```
swift test
```
渲染。

快照上传会将生成的图像和元数据发送到 Sentry。上传前，请确认目标 organization/project 和导出目录，并检查图像是否包含客户数据或其他敏感内容。仅上传用户请求范围内选定的快照输出。

Detect

检测

Do only enough detection to route before calling the wizard:

bash

undefined

仅执行足够的检测以在调用 Wizard 前确定路由：

bash

undefined

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

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

Required wizard input

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

[ -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 检测 app targets、hosted XCTest targets 和 Swift previews。

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
```
host app 或 hosted XCTest target，则在设置、验证或 CI 之前停止。保留其他生成器时，不适用这些停止条件。
对于设置或验证：
- 存在非 SnapshotPreviews 生成器 -> 读取
```
references/snapshots.md
```
  ；
- 存在 SnapshotPreviews -> 读取
```
references/snapshot-previews.md
```
  和
```
references/snapshots.md
```
  ；
- 新建 SnapshotPreviews 设置 -> 读取
```
references/wizard-setup.md
```
  ；
- Wizard 报告没有 Swift previews -> 在添加 previews 或选择其他生成器之前询问用户。
仅在图像生成器存在后处理 GitHub Actions/CI：
- Point-Free
```
swift-snapshot-testing
```
  -> 读取
```
references/github-actions-swift-snapshot-testing.md
```
  和
```
references/snapshots.md
```
  ；
- 其他非 SnapshotPreviews 生成器 -> 读取
```
references/snapshots.md
```
  并适配现有 CI/上传流程；
- SnapshotPreviews、仅一个 simulator、无 matrix/fanout/selective CI -> 读取
```
references/github-actions-simple.md
```
  ；
- SnapshotPreviews 包含多个 simulators、device families、matrix 或任何 selective 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 设置、消歧或手动回退	`references/wizard-setup.md`
SnapshotPreviews 元数据、渲染偏好、选择性渲染或 SnapshotPreviews 专属故障排查	`references/snapshot-previews.md`
使用 Fastlane、 `sentry-cli` 、manifest、CI 备注或上传故障排查，将任何生成的快照图像上传到 Sentry	`references/snapshots.md`
单目标 GitHub Actions 工作流	`references/github-actions-simple.md`
多目标或 fan-out 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
```
sidecar 文件。
上传成功，并打印 Sentry URL 或 snapshot id。
Base branch 上传为完整上传；selective PR 上传包含完整的图像名称 manifest。