sentry-snapshots-cocoa

Sentry Snapshots for Apple/Cocoa

范围

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

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

检测

在调用向导前，只需完成足以确定流程的检测：

# 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
find . \( -name Package.swift -o -name Package.resolved -o -path '*/project.pbxproj' \) -print0 2>/dev/null | xargs -0 grep -lE "swift-snapshot-testing|SnapshotTesting|assertSnapshot|__Snapshots__|TEST_RUNNER_SNAPSHOT_TESTING_RECORD" 2>/dev/null

# 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"

记录：现有 SnapshotPreviews 设置、现有快照生成器/库、已知的输出目录、Xcode 项目目录、CI 提供商、Fastlane 和 Sentry 身份验证信息。 对于每个 .xcodeproj 匹配项，记录其所在目录以供 --xcode-project-dir 使用； 如果 find 输出 ./MyApp/MyApp.xcodeproj，则传入 ./MyApp，而不是 bundle 路径。 仅当不存在现有生成器时，才让向导检测应用目标、托管 XCTest 目标和 Swift 预览。

流程选择

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

1. 选择或创建图像生成器：
   • 优先选择用户指定的生成器；
   • 存在多个生成器但用户未选择 -> 询问；
   • 已有非 SnapshotPreviews 生成器 -> 保留；
   • 已有 SnapshotPreviews -> 使用；
   • 不存在生成器 -> 默认针对 Sentry Snapshots 或 Apple 快照测试设置 SnapshotPreviews。
2. 对于 SnapshotPreviews，如果没有 .xcodeproj 宿主应用或没有托管 XCTest 目标，则在设置/验证/CI 前停止。 保留其他生成器时不受此限制。
3. 对于设置或验证：
   • 已有非 SnapshotPreviews 生成器 -> 阅读 references/snapshots.md；
   • 已有 SnapshotPreviews -> 阅读 references/snapshot-previews.md 和 references/snapshots.md；
   • 设置新的 SnapshotPreviews -> 阅读 references/wizard-setup.md；
   • 如果向导报告没有 Swift 预览 -> 先询问是否添加预览或选择其他生成器。
4. 仅在图像生成器已存在后，才配置 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。

可选参考资料

需求	阅读
设置第一方 SnapshotPreviews、消歧或手动备用方案	references/wizard-setup.md
SnapshotPreviews 元数据、渲染偏好、选择性渲染或 SnapshotPreviews 专属故障排查	references/snapshot-previews.md
使用 Fastlane、sentry-cli、清单、CI 说明或上传故障排查，将任何已生成的快照图像上传到 Sentry	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

完成检查

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