Add requirePassesEventually and requireAlwaysPasses

These two mirror their confirm counterparts, only throwing an error (instead of recording an issue) when they fail.

Author: younata

Sources/Testing/Polling/Polling.swift

@@ -14,6 +14,10 @@ internal let defaultPollingConfiguration = (
   pollingInterval: Duration.milliseconds(1)
 )
 
+/// A type describing an error thrown when polling fails.
+@_spi(Experimental)
+public struct PollingFailedError: Error, Equatable {}
+
 /// Confirm that some expression eventually returns true
 ///
 /// - Parameters:
@@ -76,10 +80,73 @@ public func confirmPassesEventually(
   }
 }
 
-/// A type describing an error thrown when polling fails to return a non-nil
-/// value
+/// Require 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.
+///   - body: The function to invoke.
+///
+/// - Throws: A `PollingFailedError` will be thrown if the expression never
+///   returns true.
+///
+/// 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, waiting on some state to change that cannot be easily confirmed
+/// through other forms of `confirmation`.
 @_spi(Experimental)
-public struct PollingFailedError: Error {}
+@available(macOS 13, iOS 17, watchOS 9, tvOS 17, visionOS 1, *)
+public func requirePassesEventually(
+  _ comment: Comment? = nil,
+  maxPollingIterations: Int? = 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
+    ),
+    pollingInterval: getValueFromPollingTrait(
+      providedValue: pollingInterval,
+      default: defaultPollingConfiguration.pollingInterval,
+      \ConfirmPassesEventuallyConfigurationTrait.pollingInterval
+    ),
+    comment: comment,
+    sourceLocation: sourceLocation
+  )
+  let passed = await poller.evaluate(raiseIssue: false, isolation: isolation) {
+    do {
+      return try await body()
+    } catch {
+      return false
+    }
+  }
+  if !passed {
+    throw PollingFailedError()
+  }
+}
 
 /// Confirm that some expression eventually returns a non-nil value
 ///
@@ -108,7 +175,7 @@ public struct PollingFailedError: Error {}
 /// - Returns: The first non-nil value returned by `body`.
 ///
 /// - Throws: A `PollingFailedError` will be thrown if `body` never returns a
-///   non-optional value
+///   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
@@ -215,6 +282,72 @@ public func confirmAlwaysPasses(
   }
 }
 
+/// Require that some expression always 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
+///     ``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.
+///     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 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.
+///   - body: The function to invoke.
+///
+/// - Throws: A `PollingFailedError` will be thrown if the expression ever
+///   returns false.
+///
+/// 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 requireAlwaysPasses(
+  _ comment: Comment? = nil,
+  maxPollingIterations: Int? = 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
+    ),
+    pollingInterval: getValueFromPollingTrait(
+      providedValue: pollingInterval,
+      default: defaultPollingConfiguration.pollingInterval,
+      \ConfirmAlwaysPassesConfigurationTrait.pollingInterval
+    ),
+    comment: comment,
+    sourceLocation: sourceLocation
+  )
+  let passed = await poller.evaluate(raiseIssue: false, isolation: isolation) {
+    do {
+      return try await body()
+    } catch {
+      return false
+    }
+  }
+  if !passed {
+    throw PollingFailedError()
+  }
+}
+
 /// 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.
@@ -368,23 +501,38 @@ private struct Poller {
   /// Evaluate polling, and process the result, raising an issue if necessary.
   ///
   /// - Parameters:
+  ///   - raiseIssue: Whether or not to raise an issue.
+  ///     This should only be false for `requirePassesEventually` or
+  ///     `requireAlwaysPasses`.
+  ///   - isolation: The isolation to use
   ///   - body: The expression to poll
+  ///
+  /// - Returns: Whether or not polling passed.
+  ///
   /// - Side effects: If polling fails (see `PollingBehavior`), then this will
   ///   record an issue.
-  func evaluate(
+  @discardableResult func evaluate(
+    raiseIssue: Bool = true,
     isolation: isolated (any Actor)?,
     _ body: @escaping () async -> Bool
-  ) async {
+  ) async -> Bool {
     precondition(pollingIterations > 0)
     precondition(pollingInterval > Duration.zero)
     let result = await poll(
       expression: body
     )
-    result.issue(
+    if let issue = result.issue(
       comment: comment,
       sourceContext: .init(backtrace: .current(), sourceLocation: sourceLocation),
       pollingBehavior: pollingBehavior
-    )?.record()
+    ) {
+      if raiseIssue {
+        issue.record()
+      }
+      return false
+    } else {
+      return true
+    }
   }
 
   /// This function contains the logic for continuously polling an expression,

Tests/TestingTests/PollingTests.swift

@@ -16,15 +16,20 @@ struct PollingTests {
   struct PassesOnceBehavior {
     @Test("Simple passing expressions") func trivialHappyPath() async throws {
       await confirmPassesEventually { true }
+      try await requirePassesEventually { true }
 
       let value = try await confirmPassesEventually { 1 }
+
       #expect(value == 1)
     }
 
     @Test("Simple failing expressions") func trivialSadPath() async throws {
       let issues = await runTest {
         await confirmPassesEventually { false }
         _ = try await confirmPassesEventually { Optional<Int>.none }
+        await #expect(throws: PollingFailedError()) {
+          try await requirePassesEventually { false }
+        }
       }
       #expect(issues.count == 3)
     }
@@ -122,13 +127,17 @@ struct PollingTests {
 
   @Suite("confirmAlwaysPasses")
   struct PassesAlwaysBehavior {
-    @Test("Simple passing expressions") func trivialHappyPath() async {
+    @Test("Simple passing expressions") func trivialHappyPath() async throws {
       await confirmAlwaysPasses { true }
+      try await requireAlwaysPasses { true }
     }
 
     @Test("Simple failing expressions") func trivialSadPath() async {
       let issues = await runTest {
         await confirmAlwaysPasses { false }
+        await #expect(throws: PollingFailedError()) {
+          try await requireAlwaysPasses { false }
+        }
       }
       #expect(issues.count == 1)
     }