Polling confirmations (under Experimental spi) #1115

younata · 2025-05-15T06:19:55Z

This implements polling confirmations, as described in ST-NNNN.

Motivation:

Being able to monitor changes in the background is something of immense value. Swift Testing already provides an API for this in the confirmation api. However, I've found the confirmation to be hard to work with at times - it requires you to set up a callback for when something changes, which is not always possible or even the right thing to do. Polling provides a very general approach to monitoring all kinds of changes.

Modifications:

This adds a new set of macros for handling polling. A new public enum for the 2 separate polling behaviors, and new types to actually implement polling. All under the experimental spi.

Checklist:

Code and documentation should follow the style of the Style Guide.
If public symbols are renamed or modified, DocC references should be updated.

Sources/Testing/Polling/Polling.swift

Tests/TestingTests/PollingTests.swift

Sources/Testing/Issues/Issue.swift

plemarquand

Overall looking really great. Just one comment and a bunch of documentation nits.

Tests/TestingTests/PollingTests.swift

Sources/Testing/Traits/PollingConfigurationTrait.swift

Tests/TestingTests/PollingTests.swift

Sources/Testing/Polling/Polling.swift

Sources/Testing/Confirmations/Polling.swift

stmontgomery · 2025-10-06T13:45:23Z

Sources/Testing/Polling/Polling.swift

+
+/// A type describing why polling failed
+@_spi(Experimental)
+public enum PollingFailureReason: Sendable, Codable {


I think this PollingFailureReason enum would feel more natural nested within PollingFailedError, and then its name could be simplified to Reason (or fully-qualified, PollingFailedError.Reason).

Or could PollingFailedError be the enum itself, then we don't need a nested type? (Either way we've got a public enum here.)

Preliminary implementation of polling expectations Make Polling into a function along the lines of Confirmation Additionally, make PollingBehavior an implementation detail of polling, instead of exposed publicly Removes any timeouts involved for polling, as they become increasingly unreliable as the system runs more and more tests Take in configuration arguments, add polling interval Add traits for configuring polling 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. Add requirePassesEventually and requireAlwaysPasses These two mirror their confirm counterparts, only throwing an error (instead of recording an issue) when they fail. Rewrite confirmPassesEventually when returning an optional to remove the PollingRecorder actor. Now, this uses a separate method for evaluating polling to remove that actor. Clean up the duplicate Poller.evaluate/Poller.poll methods Removed the duplicate poll method, and made evaluate-returning-bool into a wrapper for evaluate-returning-optional 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 Rename to actually use the confirmation name Follow more english-sentence-like guidance for function naming Simplify the polling confirmation API down to just 2 public functions, 1 enum, and 1 error type. Always throw an error when polling fails, get rid of the separate issue recording. Use a single polling confirmation configuration trait Instead of mulitple traits per stop condition, just have a single trait per stop condition.

… confirmation failed

Mark defaultPollingConfiguration as private Add polling files to CMakeLists Move Polling and Confirmations.swift to a new Confirmations directory Rename PollingFailureReason to PallingFailedError.Reason

younata requested review from briancroom, grynspan, stmontgomery and suzannaratcliff as code owners May 15, 2025 06:19

grynspan assigned younata May 18, 2025

grynspan added enhancement New feature or request public-api Affects public API api-proposal API proposal PRs (documentation only) issue-handling Related to Issue handling within the testing library macros 🔭 Related to Swift macros such as @Test or #expect labels May 18, 2025