Contents

fulfillment(of:timeout:enforceOrder:)

Waits on a group of expectations for up to the specified timeout, optionally enforcing their order of fulfillment.

Declaration

@discardableResult @nonobjc func fulfillment(of expectations: [XCTestExpectation], timeout seconds: TimeInterval = .infinity, enforceOrder enforceOrderOfFulfillment: Bool = false) async -> XCTWaiter.Result

Parameters

  • expectations:

    An array of expectations the test must satisfy.

  • seconds:

    The time, in seconds, the test allows for the fulfillment of the expectations. The default timeout allows the test to run until it reaches its execution time allowance.

  • enforceOrderOfFulfillment:

    If True, the test must fulfill the expectations in the order they appear in the array.

Return Value

A value describing the outcome of waiting for expectations.

Discussion

Use this concurrency-safe alternative to wait(for:timeout:enforceOrder:) from async Swift functions. A call to wait(for:timeout:enforceOrder:) runs synchronously and blocks the calling thread, which can cause deadlocks or priority inversions.

The following example demonstrates how to wait on exceptions in a test using concurrency:

func testSprockets() async throws {
    // The test allows 60 seconds total for execution.
    self.executionTimeAllowance = 60

    let sprocket = MySprocket()
    
    let sprocketLoaded = expectation(description: "sprocket loaded")
    sprocket.load() { toothCount in
        if toothCount == 6 {
            sprocketLoaded.fulfill()
        }
    }
    await fulfillment(of: [sprocketLoaded])

    let orbitWobbled = expectation(that: \.orbitAngle.doubleValue, on: sprocket, willEqual: 90.0)
    Task {
        sprocket.wobbleOrbit()
    }
    await fulfillment(of: [orbitWobbled])
}

Expectations can only appear in the array once. The call may return before the timeout if the test fulfills all the expectations you provide.

See Also

Waiting for Expectations