Use consistent naming between confirmAlwaysPasses and the related configuration trait

Stop unnecessarily waiting after the last polling attempt has finished.
Allow for subsequent polling configuration traits which specified nil for a value to fall back to earlier polling configuration traits before falling back to the default.

Author: younata

Sources/Testing/Polling/Polling.swift

@@ -21,11 +21,13 @@ internal let defaultPollingConfiguration = (
 ///     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.
+///     ``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.
+///   - 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
@@ -86,11 +88,13 @@ public struct PollingFailedError: Error {}
 ///     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.
+///     ``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.
+///   - 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
@@ -158,14 +162,15 @@ public func confirmPassesEventually<R>(
 ///     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
+///     ``ConfirmAlwaysPassesConfigurationTrait`` added to the test or suite.
+///     If no ``ConfirmAlwaysPassesConfigurationTrait`` 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.
+///   - 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
+///     ``ConfirmAlwaysPassesConfigurationTrait`` added to the test or suite.
+///     If no ``ConfirmAlwaysPassesConfigurationTrait`` 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.
@@ -191,12 +196,12 @@ public func confirmAlwaysPasses(
     pollingIterations: getValueFromPollingTrait(
       providedValue: maxPollingIterations,
       default: defaultPollingConfiguration.maxPollingIterations,
-      \ConfirmPassesAlwaysConfigurationTrait.maxPollingIterations
+      \ConfirmAlwaysPassesConfigurationTrait.maxPollingIterations
     ),
     pollingInterval: getValueFromPollingTrait(
       providedValue: pollingInterval,
       default: defaultPollingConfiguration.pollingInterval,
-      \ConfirmPassesAlwaysConfigurationTrait.pollingInterval
+      \ConfirmAlwaysPassesConfigurationTrait.pollingInterval
     ),
     comment: comment,
     sourceLocation: sourceLocation
@@ -228,16 +233,13 @@ public func confirmAlwaysPasses(
 private func getValueFromPollingTrait<TraitKind, Value>(
   providedValue: Value?,
   default: Value,
-  _ keyPath: KeyPath<TraitKind, 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]
+  let possibleTraits = test.traits.compactMap { $0 as? TraitKind }
+  let traitValues = possibleTraits.compactMap { $0[keyPath: keyPath] }
+  return traitValues.last ?? `default`
 }
 
 /// A type to record the last value returned by a closure returning an optional
@@ -397,12 +399,16 @@ private struct Poller {
     isolation: isolated (any Actor)? = #isolation,
     expression: @escaping () async -> Bool
   ) async -> PollResult {
-    for _ in 0..<pollingIterations {
+    for iteration in 0..<pollingIterations {
       if let result = await pollingBehavior.processFinishedExpression(
         expressionResult: expression()
       ) {
         return result
       }
+      if iteration == (pollingIterations - 1) {
+        // don't bother sleeping if it's the last iteration.
+        break
+      }
       do {
         try await Task.sleep(for: pollingInterval)
       } catch {

Sources/Testing/Traits/PollingConfigurationTrait.swift

@@ -8,36 +8,38 @@
 /// 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``
+/// To add this trait to a test, use the
+/// ``Trait/confirmPassesEventuallyDefaults`` function.
 @_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 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
+    self.maxPollingIterations = maxPollingIterations
+    self.pollingInterval = pollingInterval
   }
 }
 
 /// A trait to provide a default polling configuration to all usages of
-/// ``confirmPassesAlways`` within a test or suite.
+/// ``confirmAlwaysPasses`` within a test or suite.
 ///
-/// To add this trait to a test, use the ``Trait/pollingConfirmationAlways``
+/// To add this trait to a test, use the ``Trait/confirmAlwaysPassesDefaults``
+/// function.
 @_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 struct ConfirmAlwaysPassesConfigurationTrait: 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
+    self.maxPollingIterations = maxPollingIterations
+    self.pollingInterval = pollingInterval
   }
 }
 
@@ -52,7 +54,8 @@ extension Trait where Self == ConfirmPassesEventuallyConfigurationTrait {
   ///     `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.
+  ///     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,
@@ -67,7 +70,7 @@ extension Trait where Self == ConfirmPassesEventuallyConfigurationTrait {
 
 @_spi(Experimental)
 @available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
-extension Trait where Self == ConfirmPassesAlwaysConfigurationTrait {
+extension Trait where Self == ConfirmAlwaysPassesConfigurationTrait {
   /// Specifies defaults for ``confirmPassesAlways`` in the test or suite.
   ///
   /// - Parameters:
@@ -76,13 +79,14 @@ extension Trait where Self == ConfirmPassesAlwaysConfigurationTrait {
   ///     `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.
+  ///     If nil, polling will wait at least 1 millisecond between polling
+  ///     attempts.
   ///     `pollingInterval` must be greater than 0.
-  public static func confirmPassesAlwaysDefaults(
+  public static func confirmAlwaysPassesDefaults(
     maxPollingIterations: Int? = nil,
     pollingInterval: Duration? = nil
   ) -> Self {
-    ConfirmPassesAlwaysConfigurationTrait(
+    ConfirmAlwaysPassesConfigurationTrait(
       maxPollingIterations: maxPollingIterations,
       pollingInterval: pollingInterval
     )

Tests/TestingTests/PollingTests.swift

@@ -179,7 +179,7 @@ struct PollingTests {
 
     @Suite(
       "Configuration traits",
-      .confirmPassesAlwaysDefaults(maxPollingIterations: 100)
+      .confirmAlwaysPassesDefaults(maxPollingIterations: 100)
     )
     struct WithConfigurationTraits {
       @Test("When no test or callsite configuration provided, uses the suite configuration")
@@ -194,7 +194,7 @@ struct PollingTests {
 
       @Test(
         "When test configuration porvided, uses the test configuration",
-        .confirmPassesAlwaysDefaults(maxPollingIterations: 10)
+        .confirmAlwaysPassesDefaults(maxPollingIterations: 10)
       )
       func testUsesTestConfigurationOverSuiteConfiguration() async {
         let incrementor = Incrementor()
@@ -206,7 +206,7 @@ struct PollingTests {
 
       @Test(
         "When callsite configuration provided, uses that",
-        .confirmPassesAlwaysDefaults(maxPollingIterations: 10)
+        .confirmAlwaysPassesDefaults(maxPollingIterations: 10)
       )
       func testUsesCallsiteConfiguration() async {
         let incrementor = Incrementor()
@@ -218,10 +218,11 @@ struct PollingTests {
     }
   }
 
-  @Suite("Duration Tests", .disabled("time-sensitive")) struct DurationTests {
+  @Suite("Duration Tests", .disabled("time-sensitive"))
+  struct DurationTests {
     @Suite("confirmPassesEventually")
     struct PassesOnceBehavior {
-      let delta = Duration.seconds(6)
+      let delta = Duration.milliseconds(100)
 
       @Test("Simple passing expressions") func trivialHappyPath() async {
         let duration = await Test.Clock().measure {
@@ -237,10 +238,11 @@ struct PollingTests {
           }
           #expect(issues.count == 1)
         }
-        #expect(duration.isCloseTo(other: .seconds(60), within: delta))
+        #expect(duration.isCloseTo(other: .seconds(2), within: delta))
       }
 
-      @Test("When the value changes from false to true during execution") func changingFromFail() async {
+      @Test("When the value changes from false to true during execution")
+      func changingFromFail() async {
         let incrementor = Incrementor()
 
         let duration = await Test.Clock().measure {
@@ -256,18 +258,36 @@ struct PollingTests {
         #expect(await incrementor.count == 2)
         #expect(duration.isCloseTo(other: .zero, within: delta))
       }
+
+      @Test("Doesn't wait after the last iteration")
+      func lastIteration() async {
+        let duration = await Test.Clock().measure {
+          let issues = await runTest {
+            await confirmPassesEventually(
+              maxPollingIterations: 10,
+              pollingInterval: .seconds(1) // Wait a long time to handle jitter.
+            ) { false }
+          }
+          #expect(issues.count == 1)
+        }
+        #expect(
+          duration.isCloseTo(
+            other: .seconds(9),
+            within: .milliseconds(500)
+          )
+        )
+      }
     }
 
     @Suite("confirmAlwaysPasses")
     struct PassesAlwaysBehavior {
-      // use a very generous delta for CI reasons.
-      let delta = Duration.seconds(6)
+      let delta = Duration.milliseconds(100)
 
       @Test("Simple passing expressions") func trivialHappyPath() async {
         let duration = await Test.Clock().measure {
           await confirmAlwaysPasses { true }
         }
-        #expect(duration.isCloseTo(other: .seconds(60), within: delta))
+        #expect(duration.isCloseTo(other: .seconds(1), within: delta))
       }
 
       @Test("Simple failing expressions") func trivialSadPath() async {
@@ -279,6 +299,22 @@ struct PollingTests {
         }
         #expect(duration.isCloseTo(other: .zero, within: delta))
       }
+
+      @Test("Doesn't wait after the last iteration")
+      func lastIteration() async {
+        let duration = await Test.Clock().measure {
+          await confirmAlwaysPasses(
+            maxPollingIterations: 10,
+            pollingInterval: .seconds(1) // Wait a long time to handle jitter.
+          ) { true }
+        }
+        #expect(
+          duration.isCloseTo(
+            other: .seconds(9),
+            within: .milliseconds(500)
+          )
+        )
+      }
     }
   }
 }