letro/letro-ios
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases 2 Wiki Activity

waitConfirmation implementation (#5130)

Browse Source 
* `waitConfirmation` implementation

* even better docs

* made the body not async since the context of usage did not really require it

* pr suggestions
This commit is contained in:
Mauro
2026-02-23 14:24:19 +01:00
committed by GitHub
parent 3cdb9a2c0e
commit fccca17ecf
8 changed files with 262 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
UnitTests/Sources/EmojiPickerScreenViewModelTests.swift
View File

@@ -25,27 +25,18 @@ struct EmojiPickerScreenViewModelTests {
let reaction = "👋"
let deferred = deferFulfillment(viewModel.actions) { $0 == .dismiss }
try await confirmation { confirmation in
var toggleReactionCalled = false
try await waitForConfirmation(timeout: .seconds(5)) { confirmation in
timelineProxy.toggleReactionToClosure = { toggledReaction, _ in
defer {
confirmation()
toggleReactionCalled = true
}
defer { confirmation() }
#expect(toggledReaction == reaction)
return .success(())
}
context.send(viewAction: .emojiTapped(emoji: .init(id: "wave", value: reaction)))
try await deferred.fulfill()
// Since the reaction is called asynchronously after dismissing the picker
// We need to actively wait for the function to be called before fulfilling the test.
while !toggleReactionCalled {
await Task.yield()
}
}
try await deferred.fulfill()
}
// MARK: - Helpers

8
UnitTests/Sources/NavigationTabCoordinatorTests.swift
View File

@@ -168,17 +168,17 @@ struct NavigationTabCoordinatorTests {
}
@Test
mutating func overlayDismissalCallbackWhenChangingMode() async throws {
mutating func overlayDismissalCallbackWhenChangingMode() async {
let overlayCoordinator = SomeTestCoordinator()
try await confirmation("Callback should not be called when just changing mode",
expectedCount: 0) { confirmation in
await waitForConfirmation("Callback should not be called when just changing mode",
expectedCount: 0,
timeout: .seconds(1)) { confirmation in
navigationTabCoordinator.setOverlayCoordinator(overlayCoordinator) {
confirmation()
}
navigationTabCoordinator.setOverlayPresentationMode(.minimized)
try await Task.sleep(for: .seconds(1))
}
}

13
UnitTests/Sources/PollFormScreenViewModelTests.swift
View File

@@ -162,26 +162,17 @@ struct PollFormScreenViewModelTests {
let deferred = deferFulfillment(viewModel.actions) { $0 == .close }
try await confirmation { confirmation in
var redactReasonCalled = false
await waitForConfirmation(timeout: .seconds(1)) { confirmation in
timelineProxy.redactReasonClosure = { eventID, _ in
defer {
confirmation()
redactReasonCalled = true
}
#expect(eventID == .eventID("foo"))
return .success(())
}
context.alertInfo?.secondaryButton?.action?()
try await deferred.fulfill()
// Since the redactReasonClosure is called asynchronously after closing the alert
// We need to actively wait for the redactReasonClosure to be called before fulfilling the test.
while !redactReasonCalled {
await Task.yield()
}
}
try await deferred.fulfill()
}
// MARK: - Helpers

276
UnitTests/Sources/TestUtilities/DeferredFulfillment.swift Normal file
View File

@@ -0,0 +1,276 @@
//
// Copyright 2025 Element Creations Ltd.
// Copyright 2023-2025 New Vector Ltd.
//
// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
// Please see LICENSE files in the repository root for full details.
//
import Combine
import Testing
struct DeferredFulfillment<T> {
private let closure: () async throws -> T
fileprivate init(_ closure: @escaping () async throws -> T) {
self.closure = closure
}
@discardableResult
func fulfill() async throws -> T {
try await closure()
}
}
private struct DeferredFulfillmentError: Error {
static func noOutput(message: String?, sourceLocation: SourceLocation) -> Self {
defer { Issue.record(Comment(rawValue: message ?? "No Output"), sourceLocation: sourceLocation) }
return .init()
}
static func unexpectedFulfillment(message: String?, sourceLocation: SourceLocation) -> Self {
defer { Issue.record(Comment(rawValue: message ?? "Unexpected Fulfillment"), sourceLocation: sourceLocation) }
return .init()
}
static var empty: Self {
.init()
}
}
/// Test utility that assists in subscribing to a publisher and deferring the fulfilment and results until some other actions have been performed.
/// - Parameters:
/// - publisher: The publisher to wait on.
/// - timeout: A timeout after which we give up.
/// - message: An optional message to include in the error if the condition is never met.
/// - sourceLocation: The source location to attach to any recorded issues.
/// - until: callback that evaluates outputs until some condition is reached
/// - Returns: The deferred fulfilment to be executed after some actions and that returns the result of the publisher.
func deferFulfillment<P: Publisher<P.Output, Never>>(_ publisher: P,
timeout: Duration = .seconds(10),
message: String? = nil,
sourceLocation: SourceLocation = #_sourceLocation,
until condition: @escaping (P.Output) -> Bool) -> DeferredFulfillment<P.Output> {
let (stream, continuation) = AsyncStream<P.Output>.makeStream()
let cancellable = publisher
.sink { _ in
continuation.finish()
} receiveValue: { value in
guard condition(value) else { return }
continuation.yield(value)
continuation.finish()
}
return DeferredFulfillment {
defer { cancellable.cancel() }
return try await withThrowingTaskGroup(of: P.Output.self) { group in
group.addTask {
for await result in stream {
return result
}
guard !Task.isCancelled else {
// Required to avoid a double recording of the issue in the case where the task is cancelled due to timeout.
throw DeferredFulfillmentError.empty
}
throw DeferredFulfillmentError.noOutput(message: message, sourceLocation: sourceLocation)
}
group.addTask {
try await Task.sleep(for: timeout)
throw DeferredFulfillmentError.noOutput(message: message, sourceLocation: sourceLocation)
}
defer { group.cancelAll() }
return try #require(try await group.next())
}
}
}
/// Test utility that assists in observing an async sequence, deferring the fulfilment and results until some condition has been met.
/// - Parameters:
/// - asyncSequence: The sequence to wait on.
/// - timeout: A timeout after which we give up.
/// - message: An optional message to include in the error if the condition is never met.
/// - sourceLocation: The source location to attach to any recorded issues.
/// - until: callback that evaluates outputs until some condition is reached
/// - Returns: The deferred fulfilment to be executed after some actions and that returns the result of the sequence.
func deferFulfillment<Value>(_ asyncSequence: any AsyncSequence<Value, Never>,
timeout: Duration = .seconds(10),
message: String? = nil,
sourceLocation: SourceLocation = #_sourceLocation,
until condition: @escaping (Value) -> Bool) -> DeferredFulfillment<Value> {
let (stream, continuation) = AsyncStream<Value>.makeStream()
let task = Task {
for await value in asyncSequence where condition(value) {
continuation.yield(value)
continuation.finish()
return
}
continuation.finish()
}
return DeferredFulfillment {
defer { task.cancel() }
return try await withThrowingTaskGroup(of: Value.self) { group in
group.addTask {
for await value in stream {
return value
}
guard !Task.isCancelled else {
// Required to avoid a double recording of the issue in the case where the task is cancelled due to timeout.
throw DeferredFulfillmentError.empty
}
throw DeferredFulfillmentError.noOutput(message: message, sourceLocation: sourceLocation)
}
group.addTask {
try await Task.sleep(for: timeout)
throw DeferredFulfillmentError.noOutput(message: message, sourceLocation: sourceLocation)
}
defer { group.cancelAll() }
return try #require(try await group.next())
}
}
}
/// Test utility that assists in subscribing to a publisher and deferring the fulfilment and results until some other actions have been performed.
/// - Parameters:
/// - publisher: The publisher to wait on.
/// - keyPath: the key path for the expected values
/// - transitionValues: the values through which the keypath needs to transition through
/// - timeout: A timeout after which we give up.
/// - sourceLocation: The source location to attach to any recorded issues.
/// - Returns: The deferred fulfilment to be executed after some actions and that returns the result of the publisher.
func deferFulfillment<P: Publisher<P.Output, Never>, K: KeyPath<P.Output, V>, V: Equatable>(_ publisher: P,
keyPath: K,
transitionValues: [V],
timeout: Duration = .seconds(10),
message: String? = nil,
sourceLocation: SourceLocation = #_sourceLocation) -> DeferredFulfillment<P.Output> {
var expectedOrder = transitionValues
return deferFulfillment(publisher, timeout: timeout, message: message, sourceLocation: sourceLocation) { value in
let receivedValue = value[keyPath: keyPath]
if let index = expectedOrder.firstIndex(where: { $0 == receivedValue }), index == 0 {
expectedOrder.remove(at: index)
}
return expectedOrder.isEmpty
}
}
/// Test utility that assists in subscribing to an async sequence and deferring the fulfilment and results until some other actions have been performed.
/// - Parameters:
/// - asyncSequence: The sequence to wait on.
/// - transitionValues: the values through which the sequence needs to transition through
/// - timeout: A timeout after which we give up.
/// - sourceLocation: The source location to attach to any recorded issues.
/// - Returns: The deferred fulfilment to be executed after some actions and that returns the result of the sequence.
func deferFulfillment<Value: Equatable>(_ asyncSequence: any AsyncSequence<Value, Never>,
transitionValues: [Value],
timeout: Duration = .seconds(10),
message: String? = nil,
sourceLocation: SourceLocation = #_sourceLocation) -> DeferredFulfillment<Value> {
var expectedOrder = transitionValues
return deferFulfillment(asyncSequence, timeout: timeout, message: message, sourceLocation: sourceLocation) { value in
if let index = expectedOrder.firstIndex(where: { $0 == value }), index == 0 {
expectedOrder.remove(at: index)
}
return expectedOrder.isEmpty
}
}
/// Test utility that assists in subscribing to a publisher and deferring the failure for a particular value until some other actions have been performed.
/// - Parameters:
/// - publisher: The publisher to wait on.
/// - timeout: A timeout after which we give up.
/// - message: An optional message to include in the error if the condition is unexpectedly met.
/// - sourceLocation: The source location to attach to any recorded issues.
/// - until: callback that evaluates outputs until some condition is reached
/// - Returns: The deferred fulfilment to be executed after some actions. The publisher's result is not returned from this fulfilment.
func deferFailure<P: Publisher<P.Output, Never>>(_ publisher: P,
timeout: Duration,
message: String? = nil,
sourceLocation: SourceLocation = #_sourceLocation,
until condition: @escaping (P.Output) -> Bool) -> DeferredFulfillment<Void> where P.Failure == Never {
let (stream, continuation) = AsyncStream<Void>.makeStream()
let cancellable = publisher
.sink { value in
guard condition(value) else { return }
continuation.yield(())
continuation.finish()
}
return DeferredFulfillment {
defer { cancellable.cancel() }
try await withThrowingTaskGroup(of: Void.self) { group in
// If the condition fires before timeout, that's the unexpected failure.
group.addTask {
for await _ in stream {
throw DeferredFulfillmentError.unexpectedFulfillment(message: message, sourceLocation: sourceLocation)
}
// Stream finished without condition firing — this shouldn't happen
// but is safe to treat as success.
}
// Timeout elapsing without the condition firing = success.
group.addTask {
try await Task.sleep(for: timeout)
}
defer { group.cancelAll() }
return try #require(try await group.next())
}
}
}
/// Test utility that assists in subscribing to an async sequence and deferring the failure for a particular value until some other actions have been performed.
/// - Parameters:
/// - asyncSequence: The sequence to wait on.
/// - timeout: A timeout after which we give up.
/// - message: An optional message to include in the error if the condition is unexpectedly met.
/// - sourceLocation: The source location to attach to any recorded issues.
/// - until: callback that evaluates outputs until some condition is reached
/// - Returns: The deferred fulfilment to be executed after some actions. The sequence's result is not returned from this fulfilment.
func deferFailure<Value>(_ asyncSequence: any AsyncSequence<Value, Never>,
timeout: Duration,
message: String? = nil,
sourceLocation: SourceLocation = #_sourceLocation,
until condition: @escaping (Value) -> Bool) -> DeferredFulfillment<Void> {
let (stream, continuation) = AsyncStream<Void>.makeStream()
let task = Task {
for await value in asyncSequence where condition(value) {
continuation.yield(())
continuation.finish()
return
}
continuation.finish()
}
return DeferredFulfillment {
defer { task.cancel() }
try await withThrowingTaskGroup(of: Void.self) { group in
// If the condition fires before timeout, that's the unexpected failure.
group.addTask {
for await _ in stream {
throw DeferredFulfillmentError.unexpectedFulfillment(message: message, sourceLocation: sourceLocation)
}
}
// Timeout elapsing without the condition firing = success.
group.addTask {
try await Task.sleep(for: timeout)
}
defer { group.cancelAll() }
return try #require(try await group.next())
}
}
}

206
UnitTests/Sources/TestUtilities/WaitingConfirmation.swift Normal file
View File

@@ -0,0 +1,206 @@
//
// Copyright 2026 Element Creations Ltd.
//
// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
// Please see LICENSE files in the repository root for full details.
//
import Synchronization
import Testing
/// A class that provides a mechanism to confirm that a specific action or event
/// has occurred a given number of times within an async context.
///
/// `WaitingConfirmation` is used in conjunction with ``waitForConfirmation(_:expectedCount:isolation:sourceLocation:_:)``
/// to synchronize async test expectations. It bridges between your test code and
/// Swift Testing's `confirmation` mechanism using an `AsyncStream` under the hood.
///
/// You typically interact with this type via its `callAsFunction()` sugar:
/// ```swift
/// await waitForConfirmation { confirmation in
/// sut.onEvent = { confirmation() }
/// sut.triggerEvent()
/// }
/// ```
final class WaitingConfirmation: Sendable {
private let continuation: AsyncStream<Void>.Continuation
private let expectedCount: Int
private let confirmationsCount: Mutex<Int>
fileprivate init(continuation: AsyncStream<Void>.Continuation, expectedCount: Int) {
self.continuation = continuation
self.expectedCount = expectedCount
confirmationsCount = .init(0)
}
/// Confirms that the expected event has occurred once.
///
/// Each call yields a value into the underlying stream, incrementing the confirmation count.
/// When the count reaches `expectedCount`, the stream is finished, unblocking ``waitForConfirmation``.
///
/// This method is thread-safe — the count increment and the finish check are performed
/// atomically inside a `Mutex` lock.
func confirm() {
confirmationsCount.withLock { value in
continuation.yield()
value += 1
if value == expectedCount {
continuation.finish()
}
}
}
/// Allows the instance to be called directly as a function, forwarding to ``confirm()``.
///
/// This enables the ergonomic shorthand `confirmation()` instead of `confirmation.confirm()`.
func callAsFunction() {
confirm()
}
}
/// Waits for a confirmation to be triggered an expected number of times within a synchronous body.
///
/// This is a wrapper around Swift Testing's `confirmation` that removes the need to manually
/// manage an `AsyncStream` at the call site. The body receives a ``WaitingConfirmation`` instance
/// which can be called directly to signal that the expected event occurred.
///
/// The body is synchronous by design — it is intended for setting up mocks and triggering
/// actions that schedule async work, rather than performing async work itself. The async
/// waiting happens internally once the body returns, by draining the stream until all
/// confirmations are received.
///
/// Unlike the timeout variant, this overload does not escape the body closure, which means
/// you can safely capture mutable structs — a common pattern in Swift Testing.
///
/// > **Warning**: This overload has no timeout. If ``WaitingConfirmation/confirm()`` is never called,
/// > the test will hang indefinitely. Prefer the timeout variant when the confirmation
/// > depends on asynchronous work that could silently fail.
///
/// Example:
/// ```swift
/// await waitForConfirmation(expectedCount: 2) { confirmation in
/// sut.onEvent = {
/// confirmation()
/// }
/// sut.triggerEvent()
/// sut.triggerEvent()
/// }
/// ```
///
/// - Parameters:
/// - comment: An optional comment to attach to the confirmation for test reporting.
/// - expectedCount: The number of times ``WaitingConfirmation/confirm()`` must be called.
/// Must be greater than 0, otherwise a test failure is recorded and execution stops.
/// Defaults to `1`.
/// - isolation: The actor isolation context. Defaults to the caller's isolation via `#isolation`.
/// - sourceLocation: The source location for failure reporting. Defaults to the call site via `#_sourceLocation`.
/// - body: A synchronous closure receiving a ``WaitingConfirmation`` instance used to signal
/// event occurrences. The closure may throw, and any thrown errors are rethrown to the caller.
/// Typically used to configure mocks and trigger the action under test.
/// - Returns: The value returned by `body`.
func waitForConfirmation<R>(_ comment: Comment? = nil,
expectedCount: Int = 1,
isolation: isolated (any Actor)? = #isolation,
sourceLocation: SourceLocation = #_sourceLocation,
_ body: (WaitingConfirmation) throws -> sending R) async rethrows -> R {
guard expectedCount > 0 else {
// Or may run indefinitely
Issue.record("Expected count must be greater than 0", sourceLocation: sourceLocation)
preconditionFailure()
}
let (stream, continuation) = AsyncStream.makeStream(of: Void.self)
return try await confirmation(comment,
expectedCount: expectedCount,
isolation: isolation,
sourceLocation: sourceLocation) { confirmation in
let result = try body(.init(continuation: continuation,
expectedCount: expectedCount))
for await _ in stream {
confirmation()
}
return result
}
}
/// Waits for a confirmation to be triggered an expected number of times within a synchronous body,
/// with a timeout.
///
/// This overload behaves like ``waitForConfirmation(_:expectedCount:isolation:sourceLocation:_:)``
/// but races the stream against a timeout. If the timeout expires before all confirmations
/// are received, the stream is forcefully finished and Swift Testing records whatever
/// confirmations were received up to that point — which will cause a test failure if
/// `expectedCount` was not reached.
///
/// The body is synchronous by design — it is intended for setting up mocks and triggering
/// actions that schedule async work, rather than performing async work itself. The async
/// waiting and timeout racing happen internally once the body returns.
///
/// > Note: Because this overload uses `withTaskGroup` internally to race the stream against
/// > the timeout, the `body` closure is implicitly `@escaping`. This is why this is a separate
/// > overload rather than a single function with an optional timeout — keeping them separate
/// > allows the non-timeout variant to avoid `@escaping`, which lets you capture mutable structs
/// > in `body` as is common in Swift Testing.
///
/// Example:
/// ```swift
/// await waitForConfirmation(expectedCount: 1, timeout: .seconds(2)) { confirmation in
/// sut.onNetworkResponse = { confirmation() }
/// sut.startRequest()
/// }
/// ```
///
/// - Parameters:
/// - comment: An optional comment to attach to the confirmation for test reporting.
/// - expectedCount: The number of times ``WaitingConfirmation/confirm()`` must be called.
/// Must be equal to or greater than 0, otherwise a test failure is recorded
/// and execution stops. Defaults to `1`.
/// Pass `0` to assert that the event never fires within the timeout window —
/// useful for verifying that a function does NOT trigger under specific conditions.
/// - timeout: The maximum duration to wait for all confirmations before finishing the stream.
/// - isolation: The actor isolation context. Defaults to the caller's isolation via `#isolation`.
/// - sourceLocation: The source location for failure reporting. Defaults to the call site via `#_sourceLocation`.
/// - body: A synchronous closure receiving a ``WaitingConfirmation`` instance used to signal
/// event occurrences. The closure may throw, and any thrown errors are rethrown to the caller.
/// Typically used to configure mocks and trigger the action under test.
/// - Returns: The value returned by `body`.
func waitForConfirmation<R>(_ comment: Comment? = nil,
expectedCount: Int = 1,
timeout: Duration,
isolation: isolated (any Actor)? = #isolation,
sourceLocation: SourceLocation = #_sourceLocation,
_ body: (WaitingConfirmation) throws -> sending R) async rethrows -> R {
guard expectedCount >= 0 else {
// Or may run indefinitely
Issue.record("Expected count must be equal or greater than 0", sourceLocation: sourceLocation)
preconditionFailure()
}
let (stream, continuation) = AsyncStream.makeStream(of: Void.self)
return try await confirmation(comment,
expectedCount: expectedCount,
isolation: isolation,
sourceLocation: sourceLocation) { confirmation in
let result = try body(.init(continuation: continuation,
expectedCount: expectedCount))
// The reason why I don't add to the task group directly the non timeout implementation
// is that I do not want the body to be marked as @escaping and thus to be able to capture
// even mutable structs which is common in Swift Testing.
await withTaskGroup(of: Void.self) { group in
group.addTask {
for await _ in stream {
confirmation()
}
}
group.addTask {
try? await Task.sleep(for: timeout)
continuation.finish()
}
await group.next()
group.cancelAll()
}
return result
}
}

1
UnitTests/SupportingFiles/target.yml
View File

@@ -52,7 +52,6 @@ targets:
- path: ../../DevelopmentAssets
- path: ../../ElementX/Sources/Other/Extensions/Publisher.swift
- path: ../../ElementX/Sources/Other/Extensions/XCTestCase.swift
- path: ../../ElementX/Sources/Other/DeferredFulfillment.swift
- path: ../../ElementX/Sources/Other/InfoPlistReader.swift
- path: ../../Tools/Scripts/Templates/SimpleScreenExample/Tests/Unit