skip to content

In Swift Testing, how do you verify a callback-based uploader's events with confirmation(), and why does a callback arriving after the closure returns fail?

level: seniorimportance: nice to knowfreq 30%

answer

  1. counting events, not waiting
  2. checked when the closure returns
  3. keep the body suspended
  4. exact count unless a range

basics

~20 s

Call confirmation(expectedCount:) and invoke the Confirmation it passes inside the callback. The count is checked as soon as the closure returns, without waiting, so the body must await the work's completion, or late callbacks are never counted.

solid answer

~40 s

`confirmation("progress reported", expectedCount: 2) { progress in … }` hands the closure a `Confirmation`; you call `progress()` from the uploader's event handler each time the event happens. When the closure returns, Swift Testing compares the count with `expectedCount` (1 by default, exact unless you pass a range) and records an issue if they differ. Crucially, `confirmation()` **does not wait or time out**: if the uploader calls back later on a background queue, the closure has already returned, the count is 0, and the test fails with "Confirmation was confirmed 0 times, but expected to be confirmed 1 time". So keep the body suspended until the work is done, typically by awaiting a checked continuation resumed by the completion event. If the API is already `async`, skip confirmations and just `await` the result.

code

swift · 14 lines
swift
import Foundation
import Testing
@testable import Exchange

struct UploaderLateCallbackTests {
    @Test func finishes() async {
        let uploader = Uploader()   // calls back later on a background queue
        await confirmation("upload finished") { finished in
            uploader.upload(Data()) { event in
                if case .finished = event { finished() }
            }
        }   // returns before the callback runs
    }
}

go deeper

for a junior

Recall that confirmation() passes a value you call when the event happens, and that the expected count defaults to one.

for a middle

Explain that the count is checked when the closure returns, why a background callback arriving later yields zero, and how a continuation keeps the body open.

for a senior

Show how you design these tests for production callback code: exact counts versus ranges, zero-count assertions that await completion, and when to replace confirmations with an async API.

for a principal

Weigh converting callback APIs to async against keeping confirmation-based tests, since the API shape decides how simple and stable the whole test suite can be.

## Why plain `await` is not always enough Swift Testing is built on Swift concurrency: when the code under test is `async`, you mark the test `async`, `await` the call and `#expect` on the result. Many iOS codebases still have APIs that report through **callbacks or delegates**: an uploader that emits progress events and then a completion, a coordinator that notifies an observer. A test for those needs to check that an **event happened**, and how many times. That is what **confirmations** are for. ## How `confirmation()` works You call the global function `confirmation(_:expectedCount:isolation:sourceLocation:_:)` and pass a closure. Swift Testing hands that closure a **`Confirmation`** value, which you call like a function (`progress()`, or `progress(count: 3)`) every time the expected event occurs: - **`expectedCount`** defaults to **1** and is matched **exactly**: two calls when one was expected is a failure, just like zero calls. - **`expectedCount: 0`** asserts that an event **does not** happen while the closure runs, such as an error callback. - Since **Swift 6.1**, `expectedCount` can also be a **range with a lower bound**: `1...` means at least once, `1...5` means between one and five times. Forms without a lower bound such as `...5` are declared unavailable, because the library could not tell whether zero calls is a failure. - `Confirmation` is `Sendable`, so calling it from a background queue is fine. The optional first argument is a comment (`"progress reported"`) that appears under the failure in the report. ## The scope rule that trips people up The count is checked **when the closure returns**, not later and not after a timeout. The documentation is explicit that confirmations do not block or suspend the caller while waiting; the confirmation is expected to happen **before `confirmation()` returns**. In the failing example the closure starts the upload and returns at once; the uploader calls back a moment later on a background queue, after the check, so the report reads: ``` Confirmation was confirmed 0 times, but expected to be confirmed 1 time ``` There is no timeout to raise. The fix is structural: the body must stay suspended until the work it observes is finished. ## Making the body wait | Situation | Approach | |---|---| | The API is `async` | `await` it and `#expect` on the result; no confirmation needed | | One completion callback, no other events | wrap it in a checked continuation and `await` it | | Repeated events, then a completion | confirmation for the events, a continuation awaiting the completion inside the body | | An event must never fire | `expectedCount: 0`, with the body awaiting completion | In the working example the body awaits `withCheckedContinuation`; the uploader's `.finished` event resumes it, so the closure returns only after both progress events have been counted. Continuations themselves are a Swift concurrency feature; here they only keep the closure open. ## Pitfalls 1. **Treating it as a waiter with a timeout.** It never waits; a late callback means zero confirmations. 2. **A trivially passing zero.** `expectedCount: 0` with a body that returns before the work runs passes even if the event would have fired; it needs the same await. 3. **Over-counting.** Progress handlers that fire a variable number of times fail an exact count; use a range such as `1...` on Swift 6.1 or later. 4. **Resuming a continuation twice.** Resuming a checked continuation more than once is a runtime trap that takes down the test process; if the completion can fire twice, guard it. 5. **Using confirmations where `await` would do.** If the uploader gains an `async` API, the test becomes a plain `await` plus `#expect`. 6. **Counting the wrong thing.** Confirm the event the requirement names (a progress report, a completion), not an internal helper call, so a refactor of the uploader's internals does not break the test. ## Reading the failure The issue text gives both numbers, so it tells you which way the test is wrong: - **"confirmed 0 times"** with a callback API almost always means the closure returned too early. - **More confirmations than expected** means the event fires more often than the requirement says, or the count should be a range. - **The comment line** under the issue (`↳ upload finished`) identifies which confirmation failed when a test has several.

  • How do you assert in Swift Testing that the uploader never reports an error event?
    Wrap the run in `confirmation("error reported", expectedCount: 0) { errored in … }` and call `errored()` from the error handler. The body must still await the upload's completion, for example through a continuation; otherwise it returns before any event could fire and the zero count passes trivially.
  • Progress fires a different number of times depending on chunk size; how do you keep the test stable?
    On Swift 6.1 or later, pass a range with a lower bound, such as `expectedCount: 1...`, meaning at least once. An exact integer would fail whenever the chunking changes. A form without a lower bound like `...5` is unavailable, because the library could not tell whether zero events should fail.
  • If the uploader gains an async upload(_:) method, do you still need confirmation()?
    Not for the result: mark the test `async`, `await` the call and `#expect` on what it returns or throws. Confirmations remain useful only for events that are delivered separately from the return value, such as progress callbacks.

It is a head count taken when the meeting-room door closes: whoever signed the sheet before the door shut is counted, and anyone arriving later is not, so you keep the door open (await) until everyone you expect has arrived.

  • confirmation() waits with a timeout until the callback fires.
  • Calling a Confirmation more often than expectedCount is harmless.
  • Callback-based code cannot be tested with Swift Testing at all.
  • expectedCount: 0 proves the event never fires even if the body returns immediately.
  • A Confirmation must only be called on the main actor.

Assumes Swift Testing in Swift 6.4; confirmation() has existed since Swift 6.0, and range values for expectedCount arrived in Swift 6.1.