Testing Async Code with XCTestExpectation

Why it exists

Standard unit tests execute synchronously, finishing as soon as the last line of the function is run. This model breaks when testing asynchronous operations like network calls, as the test would finish and pass before the operation even completes. XCTestExpectation was created to bridge this gap, allowing a test to pause and wait for a result.

The mental model

Think of an XCTestExpectation as a promise you make to the test runner. You tell it, "I expect this specific event to happen." Then you start your asynchronous work. When that work finishes and calls its completion handler, you signal fulfill() on the expectation. The test runner waits a specified amount of time for that signal. If it gets the signal, the test proceeds. If the timeout is hit first, the test fails.

How it works

The process involves three key steps. First, you create an expectation with a clear description, like let expectation = self.expectation(description: "Fetch user profile"). Second, you call your asynchronous method. Inside its completion block, after you've run any assertions, you must call expectation.fulfill(). Third, the final line of your test method must be waitForExpectations(timeout: 5.0). This call blocks the test from finishing until either the expectation is fulfilled or the 5-second timeout expires.

When to use it

Use expectations for testing code that signals completion asynchronously. This is common with older callback-based APIs using completion handlers, the delegate pattern, or NotificationCenter. It's the standard tool for testing asynchronous code that doesn't use Swift's modern concurrency features.

When not to use it

Avoid expectations for purely synchronous code, as it adds needless complexity. For modern Swift code using async/await, you can often write simpler, more readable tests by marking the test function as async and using await on your asynchronous calls. This lets the test suspend and resume naturally without manual expectation management.

One canonical example

Imagine testing a NetworkClient with a function fetch(url:completion:). Your test would create an XCTestExpectation with the description "API fetch completes". It then calls client.fetch(...). Inside the completion handler, you'd assert that the result is successful and then call expectation.fulfill(). Crucially, you must also call fulfill() in the error case to prevent a timeout. The test concludes with waitForExpectations(timeout: 1.0).