Testing completion handler APIs with Swift Testing – Donny Wals

The Swift testing framework is an extremely great tool that enables us to write down extra expressive exams with handy and fashionable APIs.

That is my first submit about Swift Testing, and I’m primarily writing it as a result of I needed to write down about one thing that I encountered not too way back once I tried to make use of Swift testing on a code base the place I had each async code in addition to older completion handler based mostly code.

The async code was very simple to check attributable to how Swift Testing is designed, and I shall be writing extra about that sooner or later.

The completion handler base code was just a little bit tougher to check, primarily as a result of I used to be changing my code from XCTest with take a look at expectations to regardless of the equal can be in Swift testing.

Understanding the issue

After I began studying Swift testing, I truly checked out Apple’s migration doc and I discovered that there’s an one thing that’s speculated to be analogous to the expectation object, which is the affirmation object. The examples from Apple have one little caveat in there.

The Swift Testing instance seems just a little bit like this:

// After
struct FoodTruckTests {
  @Take a look at func truckEvents() async {
    await affirmation("…") { soldFood in
      FoodTruck.shared.eventHandler = { occasion in
        if case .soldFood = occasion {
          soldFood()
        }
      }
      await Buyer().purchase(.soup)
    }
    ...
  }
  ...
}

Now, as you possibly can see within the code above, the instance that Apple has exhibits that now we have a operate and a name to the affirmation operate in there, which is how we’re supposed to check our async code.

They name their previous completion handler based mostly API and within the occasion handler closure they name their affirmation closure (referred to as soldFood within the instance).

After calling setting the occasion handler they await Buyer().purchase(.soup).

And that is actually the place Apple needs us to pay shut consideration as a result of within the migration doc, they point out that we wish to catch an occasion that occurs throughout some asynchronous course of.

The await that they’ve as the ultimate line of that affirmation closure is de facto the important thing a part of how we must be utilizing affirmation.

After I tried emigrate my completion handler based mostly code that I examined with XCTestExpectation, I did not have something to await. My unique testing code regarded just a little bit like this:

func test_valueChangedClosure() {
  let anticipate = expectation(description: "Anticipated synchronizer to finish")

  let synchronizer = Synchronizer()
  synchronizer.onComplete = {
    XCTAssert(synchronizer.newsItems.rely == 2)
    anticipate.fulfill()
  }

  synchronizer.synchronize()
  waitForExpectations(timeout: 1)
}

Primarily based on the migration information and skimming the examples I although that the next code can be the Swift Testing equal:

@Take a look at func valueChangedClosure() async {    
  await affirmation("Synchronizer completes") { @MainActor verify in
    synchronizer.onComplete = {
      #anticipate(synchronizer.newsItems.rely == 2)
      verify()
    }

    synchronizer.synchronize()
  }
}

My code ended up trying fairly much like Apple’s code however the important thing distinction is the final line in my affirmation. I’m not awaiting something.

The outcome when working that is at all times a failing take a look at. The take a look at shouldn’t be ready for me to name the verify closure in any respect. That await proper on the finish in Apple’s pattern code is just about wanted for this API to be usable as a alternative of your expectations.

What Apple says within the migration information if you fastidiously learn is definitely that the entire confirmations should be referred to as earlier than your closure returns:

Confirmations operate equally to the expectations API of XCTest,
nonetheless, they don’t block or droop the caller whereas ready for a
situation to be fulfilled. As an alternative, the requirement is predicted to be confirmed (the equal of fulfilling an expectation) earlier than affirmation() returns

So at any time when that affirmation closure returns, Swift Testing expects that now we have confirmed all of our confirmations. In a standard completion handler-based setup, this would possibly not be the case since you’re not awaiting something as a result of you do not have something to await.

This was fairly difficult to determine.

Write a take a look at for completion handler code

The answer right here is to not use a affirmation object right here as a result of what I believed would occur, is that the affirmation would act just a little bit like a continuation within the sense that the Swift take a look at would look ahead to me to name that affirmation.

This isn’t the case.

So what I’ve actually discovered is that one of the best ways to check your completion handler-based APIs is to make use of continuations.

You should use a continuation to wrap your name to the completion handler-based API after which within the completion handler, do all your assertions and resume your continuation. This may then resume your take a look at and it’ll full your take a look at.

Right here’s what that appears like for instance:

@Take a look at func valueChangedClosure() async {
    await withCheckedContinuation { continuation in
        synchronizer.onComplete = {
            #anticipate(synchronizer.newsItems.rely == 2)
            continuation.resume()
        }

        synchronizer.synchronize()
    }
}

This strategy works very nicely for what I wanted, and it permits me to droop the take a look at whereas my callback based mostly code is working.

It is the best strategy I may provide you with, which is often an excellent signal. However when you have another approaches that you just desire, I’d love to listen to about them, particularly when it pertains to testing completion handler APIs. I do know this isn’t a full-on alternative for all the pieces that we will do with expectations, however for the completion handler case, I feel it is a fairly good alternative.

When to not use continuations for testing completion handler code

The strategy of testing outlined above assumes that our code is considerably freed from sure bugs the place the completion handler isn’t referred to as. Our continuation does not do something to stop our take a look at from hanging eternally which may (let’s be sincere, will) be a problem for sure situations.

There are code snippets on the market that can get you the flexibility to deal with timeouts, just like the one discovered on this gist that was shared with me by Alejandro Ramirez.

I have never executed in depth testing with this snippet but however a few preliminary exams look good to me.