Polling Confirmations: Add requirePassesEventually and requireAlwaysPasses

Author: younata

proposals/testing/NNNN-polling-confirmations.md

@@ -68,7 +68,7 @@ await confirmPassesEventually {
 
 ### New confirmation functions
 
-We will introduce 4 new members of the confirmation family of functions to the
+We will introduce 5 new members of the confirmation family of functions to the
 testing library:
 
 ```swift
@@ -111,6 +111,47 @@ public func confirmPassesEventually(
   _ body: @escaping () async throws -> Bool
 ) async
 
+/// 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`.
+@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
+
 /// Confirm that some expression eventually returns a non-nil value
 ///
 /// - Parameters:
@@ -138,7 +179,7 @@ public func confirmPassesEventually(
 /// - 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
@@ -189,6 +230,45 @@ public func confirmAlwaysPasses(
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: @escaping () async throws -> Bool
 ) async
+
+/// 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.
+@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
 ```
 
 ### New Error Type
@@ -197,16 +277,16 @@ A new error type, `PollingFailedError` to be thrown when polling doesn't return
 a non-nil value:
 
 ```swift
-/// A type describing an error thrown when polling fails to return a non-nil
-/// value
-public struct PollingFailedError: Error {}
+/// A type describing an error thrown when polling fails.
+public struct PollingFailedError: Error, Equatable {}
 ```
 
 ### New Issue Kind
 
 A new Issue.Kind, `confirmationPollingFailed` will be added to represent the
-case here confirmation polling fails. This issue kind will be recorded when
-polling fails.
+case where a polling confirmation failed. This issue kind will be recorded when
+`confirmPassesEventually` and `confirmAlwaysPasses` fail, but not when
+`requirePassesEventually` or `requireAlwaysPasses` fail.
 
 ### New Traits