sentry-snapshots-cocoa

Apple/Cocoa 向け Sentry Snapshots

対象範囲

• 目標：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 を渡してください。 既存の生成ツールがない場合に限り、ウィザードでアプリターゲット、ホスト型 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 を使用し、シミュレーターが 1 つのみで、マトリックス／ファンアウト／選択的 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 アップロードには画像名の完全なマニフェストが含まれています。