feat(core): Freeze UIActivityIndicatorView spinners during snapshots (#279)

* feat(core): Freeze UIActivityIndicatorView spinners during snapshots

Disabling UIView and SwiftUI animations does not stop UIActivityIndicatorView,
which drives its own layer animation. Indeterminate spinners, including the
default SwiftUI ProgressView, were captured mid-rotation and produced flaky
diffs.

Swizzle startAnimating to a no-op from RenderingStrategy.setup so every
rendering path skips spinners. Because hidesWhenStopped defaults to true, the
indicator is hidden rather than frozen at a fixed frame. This matches the
behavior the hosted Emerge runner previously injected outside the library.

* feat(core): Add opt-out for spinner freezing and exclude watchOS

Set EMERGE_DISABLE_FREEZE_SPINNERS=1 to keep UIActivityIndicatorView animating,
mirroring the existing EMERGE_DISABLE_FIX_TIME opt-out for the clock hook.

watchOS ships UIKit without UIActivityIndicatorView, so guard the swizzle the
same way other UIKit-only code in this target does. Mark the replacement
method dynamic to follow the standard swizzling idiom.

* test(demo): Add loading indicator preview to MultiModuleDemo

Add a ModuleA preview containing an indeterminate ProgressView so the CI
snapshot upload renders a spinner case. With spinner freezing in place the
image contains only the label, and any regression shows up as a diff.

* ref(core): Use snapshot-specific spinner control names

Replace company-branded names in the new spinner opt-out and swizzled
selector. Keep the Objective-C hook product-specific to avoid collisions,
and update the environment-variable test and documentation together.

Author: NicoHinderling

Examples/MultiModuleDemo/ModuleA/ModuleAViews.swift

@@ -29,6 +29,19 @@ public struct ModuleALabel: View {
   }
 }
 
+public struct ModuleALoadingIndicator: View {
+  public init() {}
+
+  public var body: some View {
+    VStack(spacing: 12) {
+      ProgressView()
+      Text("Loading")
+        .font(.subheadline)
+    }
+    .padding()
+  }
+}
+
 #Preview("ModuleA Button") {
   ModuleAButton()
 }
@@ -42,3 +55,7 @@ public struct ModuleALabel: View {
   ModuleALabel()
     .preferredColorScheme(.dark)
 }
+
+#Preview("ModuleA Loading Indicator") {
+  ModuleALoadingIndicator()
+}

Examples/MultiModuleDemo/MultiModuleDemoTests/ModuleFilterAssertionTests.swift

@@ -14,7 +14,7 @@ final class ModuleFilterAssertionTests: XCTestCase {
       excludedModules: nil
     )
 
-    XCTAssertEqual(previews.count, 8)
+    XCTAssertEqual(previews.count, 9)
     XCTAssertTrue(previews.contains { $0.typeName.hasPrefix("ModuleA.") })
     XCTAssertTrue(previews.contains { $0.typeName.hasPrefix("ModuleB.") })
     XCTAssertTrue(previews.contains { $0.typeName.hasPrefix("ModuleC.") })

README.md

@@ -220,6 +220,8 @@ Display names should be unique within each `PreviewProvider`, or within a file w
 
 Snapshot previews should be deterministic. Avoid live network calls, timers, animations that do not settle, locale-dependent data, and dates generated from the current clock. Prefer fixed fixtures and mocked dependencies so the same preview renders the same pixels in Xcode, local test runs, and CI.
 
+During snapshot rendering, `UIActivityIndicatorView.startAnimating()` is a no-op, so indeterminate spinners (including SwiftUI's default `ProgressView`) never start and are hidden instead of being captured mid-rotation. Set `SNAPSHOTS_DISABLE_FREEZE_SPINNERS=1` in the test environment to opt out.
+
 ### Detecting the snapshot environment
 
 Set `SNAPSHOTS_RUNNING_FOR_PREVIEWS=1` in your unit test scheme to mirror the variable Xcode sets when rendering live previews. You can then disable preview-unfriendly behavior (logging, analytics, network calls) with a single check:

Sources/SnapshotPreviewsCore/ActivityIndicatorFreezing.swift

@@ -0,0 +1,27 @@
+#if canImport(UIKit) && !os(watchOS)
+import UIKit
+import ObjectiveC
+
+enum ActivityIndicatorFreezing {
+  private static let installed: Void = {
+    guard
+      let original = class_getInstanceMethod(UIActivityIndicatorView.self, #selector(UIActivityIndicatorView.startAnimating)),
+      let replacement = class_getInstanceMethod(UIActivityIndicatorView.self, #selector(UIActivityIndicatorView.snapshotPreviews_frozenStartAnimating))
+    else { return }
+    method_exchangeImplementations(original, replacement)
+  }()
+
+  static func isEnabled(environment: [String: String] = ProcessInfo.processInfo.environment) -> Bool {
+    environment["SNAPSHOTS_DISABLE_FREEZE_SPINNERS"] != "1"
+  }
+
+  static func install() {
+    guard isEnabled() else { return }
+    _ = installed
+  }
+}
+
+private extension UIActivityIndicatorView {
+  @objc dynamic func snapshotPreviews_frozenStartAnimating() {}
+}
+#endif

Sources/SnapshotPreviewsCore/RenderingStrategy.swift

@@ -68,6 +68,9 @@ private let testHandler: NSObject.Type? = NSClassFromString("EMGTestHandler") as
 
 extension RenderingStrategy {
   static func setup() {
+    #if canImport(UIKit) && !os(watchOS)
+    ActivityIndicatorFreezing.install()
+    #endif
     testHandler?.perform(NSSelectorFromString("setup"))
   }
 }

Tests/SnapshotPreviewsTests/ActivityIndicatorFreezingTests.swift

@@ -0,0 +1,25 @@
+#if canImport(UIKit) && !os(watchOS)
+import XCTest
+import UIKit
+@testable import SnapshotPreviewsCore
+
+final class ActivityIndicatorFreezingTests: XCTestCase {
+  @MainActor
+  func testStartAnimatingIsNoOpAfterRenderingSetup() {
+    UIKitRenderingStrategy.setup()
+
+    let indicator = UIActivityIndicatorView(style: .medium)
+    indicator.startAnimating()
+
+    XCTAssertFalse(indicator.isAnimating)
+  }
+
+  func testFreezingIsEnabledByDefault() {
+    XCTAssertTrue(ActivityIndicatorFreezing.isEnabled(environment: [:]))
+  }
+
+  func testFreezingIsDisabledByEnvironmentVariable() {
+    XCTAssertFalse(ActivityIndicatorFreezing.isEnabled(environment: ["SNAPSHOTS_DISABLE_FREEZE_SPINNERS": "1"]))
+  }
+}
+#endif