feat(apple): Add interactive Apple Snapshots wizard

CHANGELOG.md

@@ -11,6 +11,7 @@
 
 ### Features
 
+- feat(apple): Add Apple Snapshots wizard for SnapshotPreviews Xcode setup
 - feat(react-router): Use the stabilized instrumentation API (`createSentryServerInstrumentation` + `reactRouterTracingIntegration().clientInstrumentation`) instead of the experimental `useInstrumentationAPI` flag
 - feat(react-router): Use `sentryOnError` on `HydratedRouter` instead of mutating `root.tsx` ErrorBoundary
 

bin.ts

@@ -63,7 +63,7 @@ const PRESELECTED_PROJECT_OPTIONS: Record<string, yargs.Options> = {
 const xcodeProjectDirOption: yargs.Options = {
   default: undefined,
   describe:
-    'Path to the project containing the Xcode project file. Only applies to the Apple wizard.',
+    'Path to the project containing the Xcode project file. Applies to the Apple and Apple Snapshots wizards.',
   type: 'string',
   // This is a hidden option because it is used as an internal option
   hidden: true,

e2e-tests/tests/help-message.test.ts

@@ -29,9 +29,9 @@ describe('--help command', () => {
                                   env: SENTRY_WIZARD_QUIET  [boolean] [default: false]
         -i, --integration         Choose the integration to setup
                                   env: SENTRY_WIZARD_INTEGRATION
-           [choices: "reactNative", "flutter", "ios", "android", "cordova", "angular",
-                   "cloudflare", "electron", "nextjs", "nuxt", "remix", "reactRouter",
-                                                            "sveltekit", "sourcemaps"]
+               [choices: "reactNative", "flutter", "ios", "appleSnapshots", "android",
+            "cordova", "angular", "cloudflare", "electron", "nextjs", "nuxt", "remix",
+                                             "reactRouter", "sveltekit", "sourcemaps"]
         -p, --platform            Choose platform(s)
                                   env: SENTRY_WIZARD_PLATFORM
                                                    [array] [choices: "ios", "android"]

lib/Constants.ts

@@ -3,6 +3,7 @@ export enum Integration {
   reactNative = 'reactNative',
   flutter = 'flutter',
   ios = 'ios',
+  appleSnapshots = 'appleSnapshots',
   android = 'android',
   cordova = 'cordova',
   angular = 'angular',
@@ -67,6 +68,8 @@ export function getIntegrationDescription(type: string): string {
       return 'Configure Source Maps Upload';
     case Integration.ios:
       return 'iOS';
+    case Integration.appleSnapshots:
+      return 'Apple Snapshots';
     case Integration.cloudflare:
       return 'Cloudflare';
     default:
@@ -102,6 +105,8 @@ export function mapIntegrationToPlatform(type: string): string | undefined {
       return 'node-cloudflare-workers';
     case Integration.ios:
       return 'iOS';
+    case Integration.appleSnapshots:
+      return 'iOS';
     default:
       throw new Error(`Unknown integration ${type}`);
   }

src/apple/snapshots/apple-snapshots-wizard.ts

@@ -0,0 +1,165 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// @ts-expect-error - clack is ESM and TS complains about that. It works though
+import clack from '@clack/prompts';
+
+import { withTelemetry } from '../../telemetry';
+import {
+  confirmContinueIfNoOrDirtyGitRepo,
+  printWelcome,
+} from '../../utils/clack';
+import { lookupXcodeProject, selectXcodeTarget } from '../lookup-xcode-project';
+import type { AppleWizardOptions } from '../options';
+import { checkInstalledCLISnapshots } from './snapshots-cli-preflight';
+import { configureSnapshotPreviewsXcodeProject } from './configure-snapshotpreviews-xcode-project';
+import { ensureSnapshotTestFile } from './snapshot-test-file';
+import { resolveSnapshotVerificationSchemeName } from './snapshot-verification-scheme';
+import {
+  SNAPSHOTPREVIEWS_MINIMUM_VERSION,
+  SNAPSHOTPREVIEWS_PACKAGE_URL,
+  SNAPSHOTPREVIEWS_PREFERENCES_PRODUCT,
+  SNAPSHOTPREVIEWS_SNAPSHOT_TESTS_PRODUCT,
+} from './snapshotpreviews-package';
+
+export async function runAppleSnapshotsWizard(
+  options: AppleWizardOptions,
+): Promise<void> {
+  return withTelemetry(
+    {
+      enabled: options.telemetryEnabled,
+      integration: 'appleSnapshots',
+      wizardOptions: options,
+    },
+    () => runAppleSnapshotsWizardWithTelemetry(options),
+  );
+}
+
+async function runAppleSnapshotsWizardWithTelemetry(
+  options: AppleWizardOptions,
+): Promise<void> {
+  const projectDir = options.projectDir ?? process.cwd();
+
+  printWelcome({
+    wizardName: 'Sentry Apple Snapshots Wizard',
+    promoCode: options.promoCode,
+  });
+
+  await confirmContinueIfNoOrDirtyGitRepo({
+    ignoreGitChanges: options.ignoreGitChanges,
+    cwd: projectDir,
+  });
+
+  clack.log.info(
+    [
+      `Apple Snapshots setup will use ${SNAPSHOTPREVIEWS_PACKAGE_URL}`,
+      `${SNAPSHOTPREVIEWS_MINIMUM_VERSION}+ and link`,
+      `${SNAPSHOTPREVIEWS_SNAPSHOT_TESTS_PRODUCT} to the hosted XCTest`,
+      `target and ${SNAPSHOTPREVIEWS_PREFERENCES_PRODUCT} to the selected`,
+      'app target.',
+    ].join(' '),
+  );
+
+  const xcProject = await lookupXcodeProject({ projectDir });
+
+  const appTargetName = await selectXcodeTarget(xcProject, {
+    noTargetMessage: 'No application target found.',
+    promptMessage: 'Which app target should SnapshotPreviews use?',
+  });
+
+  const hostedTestTargetNames =
+    xcProject.getHostedUnitTestTargetNamesForApplicationTarget(appTargetName);
+  const hostedTestTargetName = await selectXcodeTarget(xcProject, {
+    targetNames: hostedTestTargetNames,
+    noTargetMessage: [
+      `No hosted unit-test target was found for ${appTargetName}.`,
+      'Please configure a unit-test target with TEST_HOST pointing at that app target, then run the wizard again.',
+    ].join(' '),
+    promptMessage: 'Which test target should render SnapshotPreviews?',
+  });
+
+  const previewTargetNames = [appTargetName];
+
+  clack.log.info(
+    [
+      `${SNAPSHOTPREVIEWS_PREFERENCES_PRODUCT} will be linked to the selected`,
+      'app target when possible. Import SnapshotPreferences in Swift',
+      'preview files only if you want to use SnapshotPreviews modifiers.',
+    ].join(' '),
+  );
+
+  if (fs.existsSync(path.join(projectDir, 'Package.swift'))) {
+    clack.log.info(
+      [
+        'Detected Package.swift. This wizard does not edit SwiftPM manifests.',
+        `If SwiftPM preview targets use SnapshotPreferences modifiers, add`,
+        `the ${SNAPSHOTPREVIEWS_PREFERENCES_PRODUCT} product dependency to those`,
+        'targets in Package.swift.',
+      ].join(' '),
+    );
+  }
+
+  const packageResult = configureSnapshotPreviewsXcodeProject({
+    xcodeProject: xcProject,
+    hostedTestTargetName,
+    previewTargetNames,
+  });
+
+  if (!packageResult.linked) {
+    clack.log.error(
+      'SnapshotPreviews package products could not be linked to the selected targets. Please check the Xcode project target build phases and try again.',
+    );
+    clack.outro('Apple Snapshots setup did not complete.');
+    return;
+  }
+
+  if (packageResult.failedSnapshotPreferencesTargetNames.length) {
+    clack.log.warn(
+      [
+        `${SNAPSHOTPREVIEWS_PREFERENCES_PRODUCT} could not be linked to`,
+        packageResult.failedSnapshotPreferencesTargetNames.join(', '),
+        'because the target Frameworks build phase could not be updated.',
+        'Apple Snapshots setup will continue; link the product manually if',
+        'you want to use SnapshotPreviews modifiers in Swift previews.',
+      ].join(' '),
+    );
+  }
+
+  const snapshotTestResult = ensureSnapshotTestFile({
+    xcodeProject: xcProject,
+    hostedTestTargetName,
+  });
+  if (!snapshotTestResult.included) {
+    clack.log.error(
+      'SnapshotPreviews test file could not be added to the selected XCTest target. Please check the target Sources build phase and try again.',
+    );
+    clack.outro('Apple Snapshots setup did not complete.');
+    return;
+  }
+
+  if (snapshotTestResult.changed || packageResult.changed) {
+    xcProject.write();
+    clack.log.success('Updated the Xcode project for SnapshotPreviews.');
+  } else {
+    clack.log.info('SnapshotPreviews Xcode project setup is already present.');
+  }
+
+  await checkInstalledCLISnapshots({
+    projectDir,
+    verificationGuidance: {
+      appId: xcProject.getBundleIdentifierForTarget(appTargetName),
+      hostedTestTargetName,
+      projectDir,
+      projectPath: xcProject.xcodeprojPath,
+      schemeName: resolveSnapshotVerificationSchemeName({
+        hostedTestTargetName,
+        xcodeprojPath: xcProject.xcodeprojPath,
+      }),
+      snapshotTestClassName: snapshotTestResult.className,
+    },
+  });
+
+  clack.outro(
+    'Apple Snapshots setup complete. No Sentry auth, DSN, runtime SDK, dSYM, or CI workflow files were configured.',
+  );
+}

src/apple/snapshots/configure-snapshotpreviews-xcode-project.ts

@@ -0,0 +1,77 @@
+import type {
+  SwiftPackageProductSpec,
+  SwiftPackageSpec,
+  XcodeProject,
+} from '../xcode-manager';
+import {
+  SNAPSHOTPREVIEWS_MINIMUM_VERSION,
+  SNAPSHOTPREVIEWS_PACKAGE_URL,
+  SNAPSHOTPREVIEWS_PREFERENCES_PRODUCT,
+  SNAPSHOTPREVIEWS_SNAPSHOT_TESTS_PRODUCT,
+} from './snapshotpreviews-package';
+
+export const snapshotPreviewsPackageSpec: SwiftPackageSpec = {
+  repositoryURL: SNAPSHOTPREVIEWS_PACKAGE_URL,
+  requirement: {
+    kind: 'upToNextMajorVersion',
+    minimumVersion: SNAPSHOTPREVIEWS_MINIMUM_VERSION,
+  },
+  commentName: 'SnapshotPreviews',
+};
+
+export const snapshottingTestsProductSpec: SwiftPackageProductSpec = {
+  package: snapshotPreviewsPackageSpec,
+  productName: SNAPSHOTPREVIEWS_SNAPSHOT_TESTS_PRODUCT,
+};
+
+export const snapshotPreferencesProductSpec: SwiftPackageProductSpec = {
+  package: snapshotPreviewsPackageSpec,
+  productName: SNAPSHOTPREVIEWS_PREFERENCES_PRODUCT,
+};
+
+export function configureSnapshotPreviewsXcodeProject({
+  xcodeProject,
+  hostedTestTargetName,
+  previewTargetNames = [],
+}: {
+  xcodeProject: XcodeProject;
+  hostedTestTargetName: string;
+  previewTargetNames?: string[];
+}): {
+  changed: boolean;
+  failedSnapshotPreferencesTargetNames: string[];
+  linked: boolean;
+} {
+  if (!xcodeProject.getUnitTestTargetNames().includes(hostedTestTargetName)) {
+    return {
+      changed: false,
+      failedSnapshotPreferencesTargetNames: [],
+      linked: false,
+    };
+  }
+
+  const snapshottingTestsResult = xcodeProject.ensureSwiftPackageProductLinked(
+    hostedTestTargetName,
+    snapshottingTestsProductSpec,
+  );
+  const snapshotPreferencesResults = previewTargetNames.map((targetName) => ({
+    result: xcodeProject.ensureSwiftPackageProductLinked(
+      targetName,
+      snapshotPreferencesProductSpec,
+    ),
+    targetName,
+  }));
+  const linkResults = [
+    snapshottingTestsResult,
+    ...snapshotPreferencesResults.map(({ result }) => result),
+  ];
+  const failedSnapshotPreferencesTargetNames = snapshotPreferencesResults
+    .filter(({ result }) => !result.linked)
+    .map(({ targetName }) => targetName);
+
+  return {
+    changed: linkResults.some((result) => result.changed),
+    failedSnapshotPreferencesTargetNames,
+    linked: snapshottingTestsResult.linked,
+  };
+}