confirmation(_:expectedCount:isolation:sourceLocation:_:)

Confirm that some event occurs during the invocation of a function.

Declaration

func confirmation<R>(_ comment: Comment? = nil, expectedCount: Int = 1, isolation: isolated (any Actor)? = #isolation, sourceLocation: SourceLocation = #_sourceLocation, _ body: (Confirmation) async throws -> sending  R) async rethrows -> R

Parameters

comment:
An optional comment to apply to any issues generated by this function.
expectedCount:
The number of times the expected event should occur when body is invoked. The default value of this argument is 1, indicating that the event should occur exactly once. Pass 0 if the event should never occur when body is invoked.
isolation:
The actor to which body is isolated, if any.
sourceLocation:
The source location to which any recorded issues should be attributed.
body:
The function to invoke.

Mentioned in

Return Value

Whatever is returned by body.

Discussion

Use confirmations to check that an event occurs while a test is running in complex scenarios where #expect() and #require() are insufficient. For example, a confirmation may be useful when an expected event occurs:

In a context that cannot be awaited by the calling function such as an event handler or delegate callback;
More than once, or never; or
As a callback that is invoked as part of a larger operation.

To use a confirmation, pass a closure containing the work to be performed. The testing library will then pass an instance of Confirmation to the closure. Every time the event in question occurs, the closure should call the confirmation:

let n = 10
await confirmation("Baked buns", expectedCount: n) { bunBaked in
  foodTruck.eventHandler = { event in
    if event == .baked(.cinnamonBun) {
      bunBaked()
    }
  }
  await foodTruck.bake(.cinnamonBun, count: n)
}

When the closure returns, the testing library checks if the confirmation’s preconditions have been met, and records an issue if they have not.