Configure polling confirmations as timeout & polling interval

This is less direct, but much more intuitive for test authors.
Also add exit tests confirming that these values are non-negative

Author: younata

Sources/Testing/Polling/Polling.swift

@@ -10,7 +10,7 @@
 
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 internal let defaultPollingConfiguration = (
-  maxPollingIterations: 1000,
+  pollingDuration: Duration.seconds(1),
   pollingInterval: Duration.milliseconds(1)
 )
 
@@ -23,12 +23,14 @@ public struct PollingFailedError: Error, Equatable {}
 /// - Parameters:
 ///   - comment: An optional comment to apply to any issues generated by this
 ///     function.
-///   - maxPollingIterations: The maximum amount of times to attempt polling.
+///   - pollingDuration: The expected length of time to continue polling for.
+///     This value may not correspond to the wall-clock time that polling lasts for, especially
+///     on highly-loaded systems with a lot of tests running.
 ///     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.
+///     polling will be attempted for about 1 second before recording an issue.
 ///     `maxPollingIterations` must be greater than 0.
 ///   - pollingInterval: The minimum amount of time to wait between polling
 ///     attempts.
@@ -50,18 +52,18 @@ public struct PollingFailedError: Error, Equatable {}
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 public func confirmPassesEventually(
   _ comment: Comment? = nil,
-  maxPollingIterations: Int? = nil,
+  pollingDuration: Duration? = nil,
   pollingInterval: Duration? = nil,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> Bool
 ) async {
   let poller = Poller(
     pollingBehavior: .passesOnce,
-    pollingIterations: getValueFromPollingTrait(
-      providedValue: maxPollingIterations,
-      default: defaultPollingConfiguration.maxPollingIterations,
-      \ConfirmPassesEventuallyConfigurationTrait.maxPollingIterations
+    pollingDuration: getValueFromPollingTrait(
+      providedValue: pollingDuration,
+      default: defaultPollingConfiguration.pollingDuration,
+      \ConfirmPassesEventuallyConfigurationTrait.pollingDuration
     ),
     pollingInterval: getValueFromPollingTrait(
       providedValue: pollingInterval,
@@ -85,12 +87,14 @@ public func confirmPassesEventually(
 /// - Parameters:
 ///   - comment: An optional comment to apply to any issues generated by this
 ///     function.
-///   - maxPollingIterations: The maximum amount of times to attempt polling.
+///   - pollingDuration: The expected length of time to continue polling for.
+///     This value may not correspond to the wall-clock time that polling lasts for, especially
+///     on highly-loaded systems with a lot of tests running.
 ///     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.
+///     polling will be attempted for about 1 second before recording an issue.
 ///     `maxPollingIterations` must be greater than 0.
 ///   - pollingInterval: The minimum amount of time to wait between polling
 ///     attempts.
@@ -115,18 +119,18 @@ public func confirmPassesEventually(
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 public func requirePassesEventually(
   _ comment: Comment? = nil,
-  maxPollingIterations: Int? = nil,
+  pollingDuration: Duration? = nil,
   pollingInterval: Duration? = nil,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> Bool
 ) async throws {
   let poller = Poller(
     pollingBehavior: .passesOnce,
-    pollingIterations: getValueFromPollingTrait(
-      providedValue: maxPollingIterations,
-      default: defaultPollingConfiguration.maxPollingIterations,
-      \ConfirmPassesEventuallyConfigurationTrait.maxPollingIterations
+    pollingDuration: getValueFromPollingTrait(
+      providedValue: pollingDuration,
+      default: defaultPollingConfiguration.pollingDuration,
+      \ConfirmPassesEventuallyConfigurationTrait.pollingDuration
     ),
     pollingInterval: getValueFromPollingTrait(
       providedValue: pollingInterval,
@@ -153,12 +157,14 @@ public func requirePassesEventually(
 /// - Parameters:
 ///   - comment: An optional comment to apply to any issues generated by this
 ///     function.
-///   - maxPollingIterations: The maximum amount of times to attempt polling.
+///   - pollingDuration: The expected length of time to continue polling for.
+///     This value may not correspond to the wall-clock time that polling lasts for, especially
+///     on highly-loaded systems with a lot of tests running.
 ///     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.
+///     polling will be attempted for about 1 second before recording an issue.
 ///     `maxPollingIterations` must be greater than 0.
 ///   - pollingInterval: The minimum amount of time to wait between polling
 ///     attempts.
@@ -186,18 +192,18 @@ public func requirePassesEventually(
 @discardableResult
 public func confirmPassesEventually<R>(
   _ comment: Comment? = nil,
-  maxPollingIterations: Int? = nil,
+  pollingDuration: Duration? = nil,
   pollingInterval: Duration? = nil,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> sending R?
 ) async throws -> R {
   let poller = Poller(
     pollingBehavior: .passesOnce,
-    pollingIterations: getValueFromPollingTrait(
-      providedValue: maxPollingIterations,
-      default: defaultPollingConfiguration.maxPollingIterations,
-      \ConfirmPassesEventuallyConfigurationTrait.maxPollingIterations
+    pollingDuration: getValueFromPollingTrait(
+      providedValue: pollingDuration,
+      default: defaultPollingConfiguration.pollingDuration,
+      \ConfirmPassesEventuallyConfigurationTrait.pollingDuration
     ),
     pollingInterval: getValueFromPollingTrait(
       providedValue: pollingInterval,
@@ -226,11 +232,13 @@ 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.
+///   - pollingDuration: The expected length of time to continue polling for.
+///     This value may not correspond to the wall-clock time that polling lasts for, especially
+///     on highly-loaded systems with a lot of tests running.
 ///     If nil, this uses whatever value is specified under the last
 ///     ``ConfirmAlwaysPassesConfigurationTrait`` added to the test or suite.
 ///     If no ``ConfirmAlwaysPassesConfigurationTrait`` has been added, then
-///     polling will be attempted 1000 times before recording an issue.
+///     polling will be attempted for about 1 second before recording an issue.
 ///     `maxPollingIterations` must be greater than 0.
 ///   - pollingInterval: The minimum amount of time to wait between polling
 ///     attempts.
@@ -251,18 +259,18 @@ public func confirmPassesEventually<R>(
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 public func confirmAlwaysPasses(
   _ comment: Comment? = nil,
-  maxPollingIterations: Int? = nil,
+  pollingDuration: Duration? = nil,
   pollingInterval: Duration? = nil,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> Bool
 ) async {
   let poller = Poller(
     pollingBehavior: .passesAlways,
-    pollingIterations: getValueFromPollingTrait(
-      providedValue: maxPollingIterations,
-      default: defaultPollingConfiguration.maxPollingIterations,
-      \ConfirmAlwaysPassesConfigurationTrait.maxPollingIterations
+    pollingDuration: getValueFromPollingTrait(
+      providedValue: pollingDuration,
+      default: defaultPollingConfiguration.pollingDuration,
+      \ConfirmAlwaysPassesConfigurationTrait.pollingDuration
     ),
     pollingInterval: getValueFromPollingTrait(
       providedValue: pollingInterval,
@@ -286,11 +294,13 @@ public func confirmAlwaysPasses(
 /// - Parameters:
 ///   - comment: An optional comment to apply to any issues generated by this
 ///     function.
-///   - maxPollingIterations: The maximum amount of times to attempt polling.
+///   - pollingDuration: The expected length of time to continue polling for.
+///     This value may not correspond to the wall-clock time that polling lasts for, especially
+///     on highly-loaded systems with a lot of tests running.
 ///     If nil, this uses whatever value is specified under the last
 ///     ``ConfirmAlwaysPassesConfigurationTrait`` added to the test or suite.
 ///     If no ``ConfirmAlwaysPassesConfigurationTrait`` has been added, then
-///     polling will be attempted 1000 times before recording an issue.
+///     polling will be attempted for about 1 second before recording an issue.
 ///     `maxPollingIterations` must be greater than 0.
 ///   - pollingInterval: The minimum amount of time to wait between polling
 ///     attempts.
@@ -314,18 +324,18 @@ public func confirmAlwaysPasses(
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 public func requireAlwaysPasses(
   _ comment: Comment? = nil,
-  maxPollingIterations: Int? = nil,
+  pollingDuration: Duration? = nil,
   pollingInterval: Duration? = nil,
   isolation: isolated (any Actor)? = #isolation,
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> Bool
 ) async throws {
   let poller = Poller(
     pollingBehavior: .passesAlways,
-    pollingIterations: getValueFromPollingTrait(
-      providedValue: maxPollingIterations,
-      default: defaultPollingConfiguration.maxPollingIterations,
-      \ConfirmAlwaysPassesConfigurationTrait.maxPollingIterations
+    pollingDuration: getValueFromPollingTrait(
+      providedValue: pollingDuration,
+      default: defaultPollingConfiguration.pollingDuration,
+      \ConfirmAlwaysPassesConfigurationTrait.pollingDuration
     ),
     pollingInterval: getValueFromPollingTrait(
       providedValue: pollingInterval,
@@ -466,8 +476,8 @@ private struct Poller {
   /// while the expression continues to pass)
   let pollingBehavior: PollingBehavior
 
-  // How many times to poll
-  let pollingIterations: Int
+  // Approximately how long to poll for
+  let pollingDuration: Duration
   // Minimum waiting period between polling
   let pollingInterval: Duration
 
@@ -526,9 +536,16 @@ private struct Poller {
     isolation: isolated (any Actor)?,
     _ body: @escaping () async -> sending R?
   ) async -> R? {
-    precondition(pollingIterations > 0)
+    precondition(pollingDuration > Duration.zero)
     precondition(pollingInterval > Duration.zero)
+    precondition(pollingDuration > pollingInterval)
+    let durationSeconds = Double(pollingDuration.components.seconds) + Double(pollingDuration.components.attoseconds) * 1e-18
+    let intervalSeconds = Double(pollingInterval.components.seconds) + Double(pollingInterval.components.attoseconds) * 1e-18
+
+    let pollingIterations = max(Int(durationSeconds / intervalSeconds), 1)
+
     let (result, value) = await poll(
+      pollingIterations: pollingIterations,
       expression: body
     )
     if let issue = result.issue(
@@ -552,12 +569,14 @@ private struct Poller {
   ///   `.passesOnce`
   ///
   /// - Parameters:
+  ///   - pollingIterations: The maximum amount of times to continue polling.
   ///   - expression: An expression to continuously evaluate
   ///   - behavior: The polling behavior to use
   ///   - timeout: How long to poll for unitl the timeout triggers.
   /// - Returns: The result of this polling and the most recent value if the
   ///   result is .finished, otherwise nil.
   private func poll<R>(
+    pollingIterations: Int,
     isolation: isolated (any Actor)? = #isolation,
     expression: @escaping () async -> sending R?
   ) async -> (PollResult, R?) {

Sources/Testing/Traits/PollingConfigurationTrait.swift

@@ -13,13 +13,13 @@
 @_spi(Experimental)
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 public struct ConfirmPassesEventuallyConfigurationTrait: TestTrait, SuiteTrait {
-  public var maxPollingIterations: Int?
+  public var pollingDuration: Duration?
   public var pollingInterval: Duration?
 
   public var isRecursive: Bool { true }
 
-  public init(maxPollingIterations: Int?, pollingInterval: Duration?) {
-    self.maxPollingIterations = maxPollingIterations
+  public init(pollingDuration: Duration?, pollingInterval: Duration?) {
+    self.pollingDuration = pollingDuration
     self.pollingInterval = pollingInterval
   }
 }
@@ -32,13 +32,13 @@ public struct ConfirmPassesEventuallyConfigurationTrait: TestTrait, SuiteTrait {
 @_spi(Experimental)
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
 public struct ConfirmAlwaysPassesConfigurationTrait: TestTrait, SuiteTrait {
-  public var maxPollingIterations: Int?
+  public var pollingDuration: Duration?
   public var pollingInterval: Duration?
 
   public var isRecursive: Bool { true }
 
-  public init(maxPollingIterations: Int?, pollingInterval: Duration?) {
-    self.maxPollingIterations = maxPollingIterations
+  public init(pollingDuration: Duration?, pollingInterval: Duration?) {
+    self.pollingDuration = pollingDuration
     self.pollingInterval = pollingInterval
   }
 }
@@ -49,20 +49,22 @@ 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.
+  ///   - pollingDuration: The expected amount of times to continue polling for.
+  ///     This value may not correspond to the wall-clock time that polling lasts for, especially
+  ///     on highly-loaded systems with a lot of tests running.
+  ///     if nil, polling will be attempted for approximately 1 second.
+  ///     `pollingDuration` 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,
+    pollingDuration: Duration? = nil,
     pollingInterval: Duration? = nil
   ) -> Self {
     ConfirmPassesEventuallyConfigurationTrait(
-      maxPollingIterations: maxPollingIterations,
+      pollingDuration: pollingDuration,
       pollingInterval: pollingInterval
     )
   }
@@ -74,20 +76,22 @@ extension Trait where Self == ConfirmAlwaysPassesConfigurationTrait {
   /// 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.
+  ///   - pollingDuration: The expected amount of times to continue polling for.
+  ///     This value may not correspond to the wall-clock time that polling lasts for, especially
+  ///     on highly-loaded systems with a lot of tests running.
+  ///     if nil, polling will be attempted for approximately 1 second.
+  ///     `pollingDuration` 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 confirmAlwaysPassesDefaults(
-    maxPollingIterations: Int? = nil,
+    pollingDuration: Duration? = nil,
     pollingInterval: Duration? = nil
   ) -> Self {
     ConfirmAlwaysPassesConfigurationTrait(
-      maxPollingIterations: maxPollingIterations,
+      pollingDuration: pollingDuration,
       pollingInterval: pollingInterval
     )
   }