Testing async code in Swift - Deep Dive

Overview - Testing async code

What is it?

Testing async code means checking that parts of your program that run tasks in the background or wait for things to finish work correctly. Async code lets your app do other things while waiting, like loading data from the internet. Testing it ensures your app handles these waits and responses without errors or delays. It helps catch bugs that happen only when tasks take time or happen out of order.

Why it matters

Without testing async code, apps can crash, freeze, or show wrong data because they don't handle waiting properly. Users might see broken screens or slow responses. Testing async code makes apps smooth and reliable, especially when dealing with network calls, databases, or animations. It saves time and frustration by catching hidden timing bugs early.

Where it fits

Before testing async code, you should understand basic Swift programming and how async/await works. After learning async testing, you can explore advanced concurrency patterns and performance testing. This topic fits in the journey after learning Swift concurrency and before mastering complex app testing strategies.

Mental Model

Core Idea

Testing async code means waiting for background tasks to finish and then checking their results, just like waiting for a cake to bake before tasting it.

Think of it like...

Imagine you order a pizza delivery. You don't just check the empty box immediately; you wait until the pizza arrives before opening and checking it. Testing async code is like waiting for the pizza delivery to complete before inspecting the pizza quality.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Start test    │──────▶│ Wait for async│──────▶│ Check results │
│ function call │       │ task to finish│       │ and assert    │
└───────────────┘       └───────────────┘       └───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding async basics in Swift

Concept: Learn what async functions are and how they let code wait without blocking the app.

In Swift, async functions let you write code that pauses to wait for something, like data from the internet, without freezing the app. You mark functions with 'async' and call them with 'await' to pause until they finish.

Result

You can write code that waits for tasks to complete smoothly, improving app responsiveness.

Understanding async basics is key because testing depends on knowing when and how code waits for tasks.

2

Foundation

Why test async code differently

Concept: Async code runs over time, so tests must wait for completion before checking results.

Unlike normal code that runs straight through, async code takes time. Tests must pause and wait for async tasks to finish before verifying outcomes. Otherwise, tests might check too early and fail incorrectly.

Result

Tests that handle async code correctly wait for tasks, avoiding false failures.

Knowing that async tests must wait prevents common mistakes where tests run too fast and miss results.

3

Intermediate

Using XCTest async/await support

🤔Before reading on: do you think XCTest can directly await async functions or needs special callbacks? Commit to your answer.

Concept: XCTest in Swift supports async/await, letting tests call async functions naturally and wait for them.

XCTest now allows test functions to be marked with 'async' and use 'await' inside. This means you can write tests that look like normal code but wait for async tasks to finish before asserting results.

Result

Tests become simpler and clearer, matching the async code style.

Understanding XCTest's async support unlocks writing clean, readable async tests without complex workarounds.

4

Intermediate

Handling timeouts and expectations

🤔Before reading on: do you think tests wait forever for async tasks or have limits? Commit to your answer.

Concept: Tests use expectations with timeouts to avoid waiting forever if async tasks hang or fail.

XCTest provides 'expectation' objects to wait for async events. You set a timeout so tests fail if the async task takes too long. This prevents tests from hanging and helps catch slow or stuck code.

Result

Tests reliably detect when async tasks complete or fail within expected time.

Knowing how to use expectations and timeouts helps write robust tests that handle real-world delays gracefully.

5

Advanced

Testing async code with concurrency and cancellation

🤔Before reading on: do you think async tests automatically handle task cancellation? Commit to your answer.

Concept: Tests must handle concurrency and cancellation to avoid leaks and false positives.

Async tasks can be cancelled or run concurrently. Tests should check that cancellation works and that concurrent tasks don't interfere. Using Swift's Task APIs inside tests helps control and observe these behaviors.

Result

Tests verify that async code behaves correctly under cancellation and concurrency.

Understanding concurrency and cancellation in tests prevents subtle bugs and resource leaks in production code.

6

Expert

Avoiding flakiness in async tests

🤔Before reading on: do you think async tests always produce the same result every run? Commit to your answer.

Concept: Async tests can be flaky due to timing issues; experts design tests to be stable and deterministic.

Flaky tests fail sometimes and pass other times, often due to race conditions or timing. Experts use techniques like mocking, controlling async timing, and isolating dependencies to make tests reliable. They avoid real network calls and use test doubles.

Result

Tests become trustworthy and maintainable, reducing false alarms and wasted debugging.

Knowing how to prevent flakiness is crucial for maintaining confidence in async test suites over time.

Under the Hood

When an async function is called, Swift creates a suspended task that runs in the background. The test function marked async awaits this task's completion. XCTest manages the test lifecycle, pausing the test until the awaited async code finishes or a timeout occurs. Internally, Swift uses continuations and task schedulers to resume code when async work completes, allowing tests to synchronize with these events.

Why designed this way?

Swift's async/await was designed to simplify asynchronous programming by making async code look like normal sequential code. XCTest adopted async/await to align tests with this style, improving readability and reducing boilerplate. Timeouts and expectations were kept to handle real-world issues like network delays and prevent tests from hanging indefinitely.

┌───────────────┐
│ Test function │
│ marked async  │
└──────┬────────┘
       │ calls async function
       ▼
┌───────────────┐
│ Async task    │
│ runs in       │
│ background    │
└──────┬────────┘
       │ completes
       ▼
┌───────────────┐
│ Test resumes  │
│ after await   │
└──────┬────────┘
       │ asserts results
       ▼
┌───────────────┐
│ Test finishes │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do async tests run instantly without waiting? Commit to yes or no.

Common Belief: Async tests run instantly and don't need to wait for async tasks to finish.

Reality: Async tests must wait for async tasks to complete using await or expectations; otherwise, they check results too early and fail.

Why it matters: Ignoring waiting causes false test failures and confusion about whether code works.

Quick: Can you test async code by just calling it without marking test async? Commit to yes or no.

Common Belief: You can test async code by calling it like normal functions without marking tests async.

Reality: Tests must be marked async and use await to properly handle async code; otherwise, the test ends before async work finishes.

Why it matters: Not marking tests async leads to incomplete tests and missed bugs.

Quick: Is it okay for async tests to wait forever for tasks? Commit to yes or no.

Common Belief: Async tests can wait forever for async tasks to finish without timeouts.

Reality: Tests should use timeouts to fail if async tasks hang, preventing endless test runs.

Why it matters: Without timeouts, tests can freeze CI pipelines and waste developer time.

Quick: Do flaky async tests always mean code is broken? Commit to yes or no.

Common Belief: If async tests are flaky, the code under test is always faulty.

Reality: Flakiness often comes from test design issues like race conditions or external dependencies, not necessarily code bugs.

Why it matters: Misdiagnosing flakiness wastes time fixing code that is actually correct.

Expert Zone

1

Tests should isolate async dependencies by mocking network or database calls to avoid external flakiness.

2

Using Task.sleep or controlled dispatch queues in tests helps simulate timing and concurrency scenarios precisely.

3

Cancellation handling in tests requires careful cleanup to avoid leaking tasks or leaving tests hanging.

When NOT to use

Avoid async/await testing for very low-level concurrency primitives like raw threads or dispatch queues; use specialized concurrency testing tools instead. Also, for UI tests, prefer UI testing frameworks that handle async UI events rather than unit tests.

Production Patterns

In production, async tests are integrated into CI pipelines with strict timeouts and retries. Mocks and stubs replace real services to ensure tests run fast and reliably. Tests often cover cancellation, error handling, and concurrency edge cases to prevent subtle bugs.

Connections

Event-driven programming

Async testing builds on event-driven concepts where code reacts to events over time.

Understanding event-driven programming helps grasp why async code needs waiting and how tests synchronize with events.

Network protocols

Async code often handles network calls; testing async code ensures protocols like HTTP behave correctly in apps.

Knowing network delays and failures helps design better async tests that simulate real-world conditions.

Project management

Testing async code relates to managing tasks and deadlines in projects, ensuring work completes on time.

The concept of waiting for tasks and handling timeouts in code testing parallels managing project milestones and risks.

Common Pitfalls

#1 Not waiting for async tasks in tests causes premature assertions.

Wrong approach:

func testFetch() {
let result = fetchData() // async call without await
XCTAssertEqual(result, expected)
}

Correct approach:

func testFetch() async {
let result = await fetchData()
XCTAssertEqual(result, expected)
}

Root cause:

Misunderstanding that async calls must be awaited to complete before checking results.

#2 Forgetting to mark test functions as async when testing async code.

Wrong approach:

func testLoad() {
let data = await loadData() // error: await in non-async function
XCTAssertNotNil(data)
}

Correct approach:

func testLoad() async {
let data = await loadData()
XCTAssertNotNil(data)
}

Root cause:

Not knowing that await can only be used inside async functions.

#3 Not using timeouts causes tests to hang indefinitely on failed async tasks.

Wrong approach:

let expectation = XCTestExpectation(description: "Wait")
wait(for: [expectation], timeout: .infinity)

Correct approach:

let expectation = XCTestExpectation(description: "Wait")
wait(for: [expectation], timeout: 5.0)

Root cause:

Ignoring the need to limit wait time to catch stuck or slow async operations.

Key Takeaways

Async code runs tasks that take time without blocking the app, so tests must wait for these tasks to finish before checking results.

Swift's XCTest supports async/await, allowing tests to be written clearly and naturally with async functions.

Using expectations and timeouts in tests prevents hanging and helps detect slow or failed async tasks reliably.

Flaky async tests often come from test design issues, not just code bugs, so isolating dependencies and controlling timing is crucial.

Expert async testing includes handling concurrency, cancellation, and preventing flakiness to maintain trustworthy test suites.

Practice

1. What keyword must you add to a Swift test function to test asynchronous code?

easy

A. defer

B. await

C. async

D. try

Solution

1. Step 1: Understand async test function requirement

   To test asynchronous code, the test function itself must be marked as asynchronous.

2. Step 2: Identify the correct keyword

   The keyword to mark a function as asynchronous in Swift is async.

3. Final Answer:

   async -> Option C

4. Quick Check:

   async = async [OK]

Hint: Mark test functions with async to test async code [OK]

Common Mistakes:

• Using await instead of async on test function
• Forgetting to mark test function as async
• Using try instead of async
• Confusing defer with async

2. Which of the following is the correct syntax to wait for an async function fetchData() inside a test?

easy

A. let result = await fetchData()

B. let result = async fetchData()

C. await let result = fetchData()

D. fetchData().await()

Solution

1. Step 1: Recall await usage in Swift

   In Swift, to wait for an async function, you use the await keyword before the function call.

2. Step 2: Check correct syntax

   The correct syntax is let result = await fetchData(). The keyword await comes before the function call.

3. Final Answer:

   let result = await fetchData() -> Option A

4. Quick Check:

   await before function call = let result = await fetchData() [OK]

Hint: Put await before async function call to wait [OK]

Common Mistakes:

• Placing await after let or variable
• Using async instead of await before call
• Calling await as a method
• Omitting await keyword

3. Given this test code, what will be printed?

func testFetch() async {
  let data = try? await fetchData()
  print(data == nil ? "No Data" : "Got Data")
}

func fetchData() async throws -> String {
  return "Hello"
}

medium

A. No Data

B. Compilation error

C. Runtime error

D. Got Data

Solution

1. Step 1: Analyze fetchData() behavior

   The function fetchData() is async and throws but always returns "Hello" without throwing an error.

2. Step 2: Understand try? await usage

   The try? await fetchData() will return the string "Hello" wrapped as optional, not nil, because no error is thrown.

3. Step 3: Evaluate print statement

   Since data is not nil, the print outputs "Got Data".

4. Final Answer:

   Got Data -> Option D

5. Quick Check:

   try? await returns value = Got Data [OK]

Hint: try? returns nil only if error thrown, else returns value [OK]

Common Mistakes:

• Assuming try? always returns nil
• Confusing async throws with throwing error always
• Ignoring optional unwrapping
• Expecting compilation error due to async

4. Identify the error in this async test function:

func testDownload() async {
  let result = fetchData()
  XCTAssertEqual(result, "Success")
}

func fetchData() async -> String {
  return "Success"
}

medium

A. XCTAssertEqual cannot compare strings

B. Missing await before fetchData() call

C. Test function should not be async

D. fetchData() must throw an error

Solution

1. Step 1: Check async function call

   The function fetchData() is async, so calling it requires await to get the result.

2. Step 2: Identify missing await

   In the test, fetchData() is called without await, causing a compile error.

3. Final Answer:

   Missing await before fetchData() call -> Option B

4. Quick Check:

   Async calls need await = Missing await before fetchData() call [OK]

Hint: Always await async calls inside async functions [OK]

Common Mistakes:

• Calling async function without await
• Thinking test functions can't be async
• Misusing XCTAssertEqual with strings
• Assuming async functions must throw

5. You want to test an async function loadUser(id:) that throws an error if the user is not found. Which test code correctly checks that an error is thrown for an invalid id?

hard

A. func testLoadUserError() async throws {
do {
_ = try await loadUser(id: -1)
XCTFail("Expected error not thrown")
} catch {
XCTAssertTrue(true)
}
}

B. func testLoadUserError() async {
let user = try await loadUser(id: -1)
XCTAssertNil(user)
}

C. func testLoadUserError() async throws {
let user = await loadUser(id: -1)
XCTAssertNil(user)
}

D. func testLoadUserError() async throws {
_ = try await loadUser(id: -1)
XCTAssertTrue(false)
}

Solution

1. Step 1: Understand error throwing test pattern

   To test that an async function throws, use a do-catch block and call the function with try await.

2. Step 2: Verify correct error handling

   func testLoadUserError() async throws { do { _ = try await loadUser(id: -1) XCTFail("Expected error not thrown") } catch { XCTAssertTrue(true) } } calls loadUser(id: -1) with try await inside do, fails test if no error, and passes if error caught.

3. Step 3: Check other options

   Approaches expecting a nil user incorrectly assume throwing functions return nil instead of throwing. func testLoadUserError() async throws { _ = try await loadUser(id: -1) XCTAssertTrue(false) } fails test unconditionally.

4. Final Answer:

   do { _ = try await loadUser(id: -1) XCTFail("Expected error not thrown") } catch { XCTAssertTrue(true) } -> Option A

5. Quick Check:

   Use do-catch with try await to test errors [OK]

Hint: Use do-catch with try await to test thrown errors [OK]

Common Mistakes:

• Expecting nil instead of catching error
• Omitting try or await keywords
• Failing test unconditionally
• Not marking test async throws