Add traits for configuring polling

Author: younata

Sources/Testing/Polling/Polling.swift

@@ -8,11 +8,29 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
+@available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
+internal let defaultPollingConfiguration = (
+  maxPollingIterations: 1000,
+  pollingInterval: Duration.milliseconds(1)
+)
+
 /// Confirm that some expression eventually returns true
 ///
 /// - Parameters:
 ///   - comment: An optional comment to apply to any issues generated by this
 ///     function.
+///   - maxPollingIterations: The maximum amount of times to attempt polling.
+///     If nil, this uses whatever value is specified under the last
+///     ``ConfirmPassesEventuallyConfigurationTrait`` added to the test or suite.
+///     If no ``ConfirmPassesEventuallyConfigurationTrait`` has been added, then
+///     polling will be attempted 1000 times before recording an issue.
+///     `maxPollingIterations` must be greater than 0.
+///   - pollingInterval: The minimum amount of time to wait between polling attempts.
+///     If nil, this uses whatever value is specified under the last
+///     ``ConfirmPassesEventuallyConfigurationTrait`` added to the test or suite.
+///     If no ``ConfirmPassesEventuallyConfigurationTrait`` has been added, then
+///     polling will wait at least 1 millisecond between polling attempts.
+///     `pollingInterval` must be greater than 0.
 ///   - isolation: The actor to which `body` is isolated, if any.
 ///   - sourceLocation: The source location to whych any recorded issues should
 ///     be attributed.
@@ -26,16 +44,24 @@
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 public func confirmPassesEventually(
   _ comment: Comment? = nil,
-  maxPollingIterations: Int = 1000,
-  pollingInterval: Duration = .milliseconds(1),
+  maxPollingIterations: Int? = nil,
+  pollingInterval: Duration? = nil,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> Bool
 ) async {
   let poller = Poller(
     pollingBehavior: .passesOnce,
-    pollingIterations: maxPollingIterations,
-    pollingInterval: pollingInterval,
+    pollingIterations: getValueFromPollingTrait(
+      providedValue: maxPollingIterations,
+      default: defaultPollingConfiguration.maxPollingIterations,
+      \ConfirmPassesEventuallyConfigurationTrait.maxPollingIterations
+    ),
+    pollingInterval: getValueFromPollingTrait(
+      providedValue: pollingInterval,
+      default: defaultPollingConfiguration.pollingInterval,
+      \ConfirmPassesEventuallyConfigurationTrait.pollingInterval
+    ),
     comment: comment,
     sourceLocation: sourceLocation
   )
@@ -58,6 +84,18 @@ public struct PollingFailedError: Error {}
 /// - Parameters:
 ///   - comment: An optional comment to apply to any issues generated by this
 ///     function.
+///   - maxPollingIterations: The maximum amount of times to attempt polling.
+///     If nil, this uses whatever value is specified under the last
+///     ``ConfirmPassesEventuallyConfigurationTrait`` added to the test or suite.
+///     If no ``ConfirmPassesEventuallyConfigurationTrait`` has been added, then
+///     polling will be attempted 1000 times before recording an issue.
+///     `maxPollingIterations` must be greater than 0.
+///   - pollingInterval: The minimum amount of time to wait between polling attempts.
+///     If nil, this uses whatever value is specified under the last
+///     ``ConfirmPassesEventuallyConfigurationTrait`` added to the test or suite.
+///     If no ``ConfirmPassesEventuallyConfigurationTrait`` has been added, then
+///     polling will wait at least 1 millisecond between polling attempts.
+///     `pollingInterval` must be greater than 0.
 ///   - isolation: The actor to which `body` is isolated, if any.
 ///   - sourceLocation: The source location to whych any recorded issues should
 ///     be attributed.
@@ -77,17 +115,25 @@ public struct PollingFailedError: Error {}
 @discardableResult
 public func confirmPassesEventually<R>(
   _ comment: Comment? = nil,
-  maxPollingIterations: Int = 1000,
-  pollingInterval: Duration = .milliseconds(1),
+  maxPollingIterations: Int? = nil,
+  pollingInterval: Duration? = nil,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> R?
 ) async throws -> R where R: Sendable {
   let recorder = PollingRecorder<R>()
   let poller = Poller(
     pollingBehavior: .passesOnce,
-    pollingIterations: maxPollingIterations,
-    pollingInterval: pollingInterval,
+    pollingIterations: getValueFromPollingTrait(
+      providedValue: maxPollingIterations,
+      default: defaultPollingConfiguration.maxPollingIterations,
+      \ConfirmPassesEventuallyConfigurationTrait.maxPollingIterations
+    ),
+    pollingInterval: getValueFromPollingTrait(
+      providedValue: pollingInterval,
+      default: defaultPollingConfiguration.pollingInterval,
+      \ConfirmPassesEventuallyConfigurationTrait.pollingInterval
+    ),
     comment: comment,
     sourceLocation: sourceLocation
   )
@@ -110,6 +156,18 @@ public func confirmPassesEventually<R>(
 /// - Parameters:
 ///   - comment: An optional comment to apply to any issues generated by this
 ///     function.
+///   - maxPollingIterations: The maximum amount of times to attempt polling.
+///     If nil, this uses whatever value is specified under the last
+///     ``ConfirmPassesAlwaysConfigurationTrait`` added to the test or suite.
+///     If no ``ConfirmPassesAlwaysConfigurationTrait`` has been added, then
+///     polling will be attempted 1000 times before recording an issue.
+///     `maxPollingIterations` must be greater than 0.
+///   - pollingInterval: The minimum amount of time to wait between polling attempts.
+///     If nil, this uses whatever value is specified under the last
+///     ``ConfirmPassesAlwaysConfigurationTrait`` added to the test or suite.
+///     If no ``ConfirmPassesAlwaysConfigurationTrait`` has been added, then
+///     polling will wait at least 1 millisecond between polling attempts.
+///     `pollingInterval` must be greater than 0.
 ///   - isolation: The actor to which `body` is isolated, if any.
 ///   - sourceLocation: The source location to whych any recorded issues should
 ///     be attributed.
@@ -122,16 +180,24 @@ public func confirmPassesEventually<R>(
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 public func confirmAlwaysPasses(
   _ comment: Comment? = nil,
-  maxPollingIterations: Int = 1000,
-  pollingInterval: Duration = .milliseconds(1),
+  maxPollingIterations: Int? = nil,
+  pollingInterval: Duration? = nil,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> Bool
 ) async {
   let poller = Poller(
     pollingBehavior: .passesAlways,
-    pollingIterations: maxPollingIterations,
-    pollingInterval: pollingInterval,
+    pollingIterations: getValueFromPollingTrait(
+      providedValue: maxPollingIterations,
+      default: defaultPollingConfiguration.maxPollingIterations,
+      \ConfirmPassesAlwaysConfigurationTrait.maxPollingIterations
+    ),
+    pollingInterval: getValueFromPollingTrait(
+      providedValue: pollingInterval,
+      default: defaultPollingConfiguration.pollingInterval,
+      \ConfirmPassesAlwaysConfigurationTrait.pollingInterval
+    ),
     comment: comment,
     sourceLocation: sourceLocation
   )
@@ -144,48 +210,34 @@ public func confirmAlwaysPasses(
   }
 }
 
-/// Confirm that some expression always returns a non-optional value
+/// A helper function to de-duplicate the logic of grabbing configuration from
+/// either the passed-in value (if given), the hardcoded default, and the
+/// appropriate configuration trait.
 ///
-/// - Parameters:
-///   - comment: An optional comment to apply to any issues generated by this
-///     function.
-///   - isolation: The actor to which `body` is isolated, if any.
-///   - sourceLocation: The source location to whych any recorded issues should
-///     be attributed.
-///   - body: The function to invoke.
+/// The provided value, if non-nil is returned. Otherwise, this looks for
+/// the last `TraitKind` specified, and if one exists, returns the value
+/// as determined by `keyPath`.
+/// If no configuration trait has been applied, then this returns the `default`.
 ///
-/// - Returns: The value from the last time `body` was invoked.
-///
-/// - Throws: A `PollingFailedError` will be thrown if `body` ever returns a
-///   non-optional value
-///
-/// Use polling confirmations to check that an event while a test is running in
-/// complex scenarios where other forms of confirmation are insufficient. For
-/// example, confirming that some state does not change.
-@_spi(Experimental)
-@available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
-public func confirmAlwaysPasses<R>(
-  _ comment: Comment? = nil,
-  maxPollingIterations: Int = 1000,
-  pollingInterval: Duration = .milliseconds(1),
-  isolation: isolated (any Actor)? = #isolation,
-  sourceLocation: SourceLocation = #_sourceLocation,
-  _ body: @escaping () async throws -> R?
-) async {
-  let poller = Poller(
-    pollingBehavior: .passesAlways,
-    pollingIterations: maxPollingIterations,
-    pollingInterval: pollingInterval,
-    comment: comment,
-    sourceLocation: sourceLocation
-  )
-  await poller.evaluate(isolation: isolation) {
-    do {
-      return try await body() != nil
-    } catch {
-      return false
-    }
+/// - Parameters:
+///   - providedValue: The value provided by the test author when calling
+///     `confirmPassesEventually` or `confirmAlwaysPasses`.
+///   - default: The harded coded default value, as defined in
+///     `defaultPollingConfiguration`
+///   - keyPath: The keyPath mapping from `TraitKind` to the desired value type.
+private func getValueFromPollingTrait<TraitKind, Value>(
+  providedValue: Value?,
+  default: Value,
+  _ keyPath: KeyPath<TraitKind, Value>
+) -> Value {
+  if let providedValue { return providedValue }
+  guard let test = Test.current else { return `default` }
+  guard let trait = test.traits.compactMap({ $0 as? TraitKind }).last else {
+    print("No traits of type \(TraitKind.self) found. Returning default.")
+    print("Traits: \(test.traits)")
+    return `default`
   }
+  return trait[keyPath: keyPath]
 }
 
 /// A type to record the last value returned by a closure returning an optional
@@ -321,6 +373,8 @@ private struct Poller {
     isolation: isolated (any Actor)?,
     _ body: @escaping () async -> Bool
   ) async {
+    precondition(pollingIterations > 0)
+    precondition(pollingInterval > Duration.zero)
     let result = await poll(
       expression: body
     )

Sources/Testing/Traits/PollingConfigurationTrait.swift

@@ -0,0 +1,90 @@
+//
+//  PollingConfiguration.swift
+//  swift-testing
+//
+//  Created by Rachel Brindle on 6/6/25.
+//
+
+/// A trait to provide a default polling configuration to all usages of
+/// ``confirmPassesEventually`` within a test or suite.
+///
+/// To add this trait to a test, use the ``Trait/pollingConfirmationEventually``
+@_spi(Experimental)
+@available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
+public struct ConfirmPassesEventuallyConfigurationTrait: TestTrait, SuiteTrait {
+  public var maxPollingIterations: Int
+  public var pollingInterval: Duration
+
+  public var isRecursive: Bool { true }
+
+  public init(maxPollingIterations: Int?, pollingInterval: Duration?) {
+    self.maxPollingIterations = maxPollingIterations ?? defaultPollingConfiguration.maxPollingIterations
+    self.pollingInterval = pollingInterval ?? defaultPollingConfiguration.pollingInterval
+  }
+}
+
+/// A trait to provide a default polling configuration to all usages of
+/// ``confirmPassesAlways`` within a test or suite.
+///
+/// To add this trait to a test, use the ``Trait/pollingConfirmationAlways``
+@_spi(Experimental)
+@available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
+public struct ConfirmPassesAlwaysConfigurationTrait: TestTrait, SuiteTrait {
+  public var maxPollingIterations: Int
+  public var pollingInterval: Duration
+
+  public var isRecursive: Bool { true }
+
+  public init(maxPollingIterations: Int?, pollingInterval: Duration?) {
+    self.maxPollingIterations = maxPollingIterations ?? defaultPollingConfiguration.maxPollingIterations
+    self.pollingInterval = pollingInterval ?? defaultPollingConfiguration.pollingInterval
+  }
+}
+
+@_spi(Experimental)
+@available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
+extension Trait where Self == ConfirmPassesEventuallyConfigurationTrait {
+  /// Specifies defaults for ``confirmPassesEventually`` in the test or suite.
+  ///
+  /// - Parameters:
+  ///   - maxPollingIterations: The maximum amount of times to attempt polling.
+  ///     If nil, polling will be attempted up to 1000 times.
+  ///     `maxPollingIterations` must be greater than 0.
+  ///   - pollingInterval: The minimum amount of time to wait between polling
+  ///     attempts.
+  ///     If nil, polling will wait at least 1 millisecond between polling attempts.
+  ///     `pollingInterval` must be greater than 0.
+  public static func confirmPassesEventuallyDefaults(
+    maxPollingIterations: Int? = nil,
+    pollingInterval: Duration? = nil
+  ) -> Self {
+    ConfirmPassesEventuallyConfigurationTrait(
+      maxPollingIterations: maxPollingIterations,
+      pollingInterval: pollingInterval
+    )
+  }
+}
+
+@_spi(Experimental)
+@available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
+extension Trait where Self == ConfirmPassesAlwaysConfigurationTrait {
+  /// Specifies defaults for ``confirmPassesAlways`` in the test or suite.
+  ///
+  /// - Parameters:
+  ///   - maxPollingIterations: The maximum amount of times to attempt polling.
+  ///     If nil, polling will be attempted up to 1000 times.
+  ///     `maxPollingIterations` must be greater than 0.
+  ///   - pollingInterval: The minimum amount of time to wait between polling
+  ///     attempts.
+  ///     If nil, polling will wait at least 1 millisecond between polling attempts.
+  ///     `pollingInterval` must be greater than 0.
+  public static func confirmPassesAlwaysDefaults(
+    maxPollingIterations: Int? = nil,
+    pollingInterval: Duration? = nil
+  ) -> Self {
+    ConfirmPassesAlwaysConfigurationTrait(
+      maxPollingIterations: maxPollingIterations,
+      pollingInterval: pollingInterval
+    )
+  }
+}