DEV Community: Clue

Writing better unit tests in Swift: Part Two

Clue — Fri, 16 Mar 2018 10:33:21 +0000

Validating your code with custom assertions

The Problem

In the first part of this series I defined what I think of as a “good” unit test. This is the definition that I ended up at:

If we can agree that a unit test (or, really, any test) is composed of some setup, the action that we’re testing, and then an assertion about the effect of that action, then I would say that, put simply, a “good” unit test is one which makes each of those three components clear.

You might also remember that we finished that post with tests that looked like this:

var sut, other: User!

func test\_equals\_allPropertiesMatch\_isTrue() {
 (sut, other) = (.create(), .create())
 XCTAssertEqual(sut, other)
 XCTAssertEqual(other, sut)
}

func test\_equals\_nameDiffers\_isFalse() {
 (sut, other) = (.create(name: "Jo"), .create())
 XCTAssertNotEqual(sut, other)
 XCTAssertNotEqual(other, sut)
}

We compressed the setup so that the test body contained only the information that was important to the scenario of the test. For example, when all that mattered was that the names of the two user objects differed, we included only that information in the setup.

This goes a great way to improving the overall readability of the test. But there’s even more we can do.

It’s possible that you looked at the above tests and thought “the setup’s okay, but why the heck have you got two asserts there?” Great question! I’m so glad you’re paying attention.

Remember that the above tests are covering the == function on a User type. Without dropping a whole load of maths on you, equality is an example of an “equivalence relation” and one of the important things about being an equivalence relation is the concept of symmetry. Put simply, if I have two instances a and b of some type, it should never be the case that a == b is true but b == a is false. If this is possible, then our definition of equality is flawed. So it makes sense to validate that our custom definition of == is symmetric.

But simply looking at our two asserts there, it’s absolutely not clear that this is the intention. These tests are only really asserting one thing. It’s possible that, with some time and the inclination, other engineers could work out why we added the second assert, but we can definitely do better.

But…how?

The Solution

Let’s start by doing the simplest thing we can possibly think of. We have two lines of code, and we’d like to have only one line of code. The solution? A function!

func assertSymmetricallyEqual(\_ sut: User, \_ other: User) {
 XCTAssertEqual(sut, other)
 XCTAssertEqual(other, sut)
}

(Note: we’re focusing in on testing for equality here, but you can do the exact same thing with non-equality).

Now our test becomes:

var sut, other: User!

func test\_equals\_allPropertiesMatch\_isTrue() {
 (sut, other) = (.create(), .create())
 assertSymmetricallyEqual(sut, other)
}

If we run this test and it passes, everything’s good. But when the assertions fail, Xcode shows the failures in the wrong place.

N.b. I had to change the setup to force the test to break.

Clearly this isn’t acceptable. If we’re trying to diagnose a failing test quickly, we want to be able to see exactly what’s failed and where. More to the point, if two or three tests all fail using this same assert function then we’re going to have a hard time separating the failures out.

Fortunately, the XCTAssertEqual documentation provides a solution. There we can see the Swift declaration of the function, which is as follows:

func XCTAssertEqual\<T\>(
 \_ expression1: @autoclosure () throws -\> T, 
 \_ expression2: @autoclosure () throws -\> T, 
 \_ message: @autoclosure () -\> String = default, 
**file: StaticString = #file,   
 line: UInt = #line** ) where T : Equatable

I’ve made the two most important lines bold.

Since XCTAssertEqual is a function in Swift (rather than a macro, as it was in Objective-C), there’s a slight trick to get Xcode to render failures in the correct place. When we call XCTAssertEqual the Swift compiler adds the file it was called from (#file), and the line it was called on (#line), to the call as default arguments.

Since our calls to XCTAssertEqual don’t happen on the line we want to see the failure on, we need to put in a bit of extra effort to get everything working. Essentially, we need to tell XCTAssertEqual the correct file and line to show failures on. This should be the #file and #line that our custom assert method is called on. So, following the example from the Apple documentation, we end up with this:

func assertSymmetricallyEqual(
 \_ sut: User, \_ other: User,
 **file: StaticString = #file,  
 line: UInt = #line**  
) {
 XCTAssertEqual(sut, other, **file: file, line: line** )
 XCTAssertEqual(other, sut, **file: file, line: line** )
}

The changes to the method have been marked in bold.

Running the tests again, we get the following result:

Alright! This is exactly what we were looking for. Now the failures show up exactly where we need to see them. 🙌

The Refactor

What we’ve done above is fine, but as soon as we want to assert that more than one type satisfies symmetric equality we’re going to find ourselves with a one way ticket to Duplication Town. 🏘🏘🏘🏘

The solution? For that we can refer back to the documentation from earlier. Swift’s XCTAssertEqual method is generic over some T: Equatable — so let’s just do the exact same thing to our assertSymmetricallyEqual.

func assertSymmetricallyEqual **\<T: Equatable\>** (
 \_ sut: **T** , \_ other: **T** ,
file: StaticString = #file,  
 line: UInt = #line  
) {
 XCTAssertEqual(sut, other, file: file, line: line)
 XCTAssertEqual(other, sut, file: file, line: line)
}

Changes marked in bold again. And look at that! There’s hardly any of them!

Now we have a nice, reusable custom assert that confirms that two instances of an Equatable type are equal. What a time to be alive!

The Bonus

At Clue, we’ve actually taken this pattern a small step further. We have an internal framework which we use for test helpers which are needed across different modules. This framework contains the following struct:

public struct Assert\<T\> {
 private let subject: T?

 init(\_ subject: T?) {
 self.subject = subject
 }
}

“Alright, great,” I hear you cry, “but this does absolutely nothing.” And you’re right! Because the real magic happens in the extensions to this type:

extension Assert where T: Equatable {
 public func symmetricallyEqual(
 to other: T, 
 file: StaticString = #file, 
 line: UInt = #line
 ) {
 XCTAssertEqual(subject, other, file: file, line: line)
 XCTAssertEqual(other, subject, file: file, line: line)
 }
}

And when we need to call this method, it looks like this:

Assert(sut).symmetricallyEqual(to: other)

Beautiful!

And, as a special treat, here’s an example of how we can extend this pattern to other types of assert. Here’s my own personal favourite custom assert function, which lets us assert that a specific error was thrown:

extension Assert where T: Error & Equatable {
 public func isThrownIn(
 \_ expression: @autoclosure () throws -\> (),
 file: StaticString = #file,
 line: UInt = #line
 ) {
 XCTAssertThrowsError(
 try expression(), file: file, line: line
 ) {
 XCTAssertEqual(
 subject, $0 as? T, 
 file: file, line: line
 )
 }
 }
}

(I had to take the indentation to slightly absurd levels to get this to fit in a Medium code block. Sorry!)

We can then use this as follows:

Assert(Errors.someError).isThrownIn(try someMethodThatThrows())

Oooh! ✨

Writing better unit tests in Swift: Part One

Clue — Tue, 27 Feb 2018 09:58:18 +0000

Generating test data with factory methods

The problem

Look, we’re amongst friends here, so I feel I can be totally honest: I’ve written some really awful unit tests in my career. Twenty-line monsters with multiple mocks and asserts and asynchronous expectations. The sort of thing you see in books with titles like “How to Fix the Mess Left by the Idiot Who Worked Here Before.” I’ve also had to maintain that code after I’d written said unit tests and the less said about that the better. So suffice to say I make it a priority now to write “good” unit tests.

Before we get started, I’ll define what I think of as a “good” unit test. If we can agree that a unit test (or, really, any test) is composed of some setup, the action that we’re testing, and then an assertion about the effect of that action, then I would say that, put simply, a “good” unit test is one which makes each of those three components clear.

(Aside: this may differ from your definition of a “good” unit test, and that’s just something we’ll both have to live with.)

Over the course of a few blog posts I’m going to show you some of the things we do at Clue to ensure we’re always trying to write “good” unit tests. In this post we’re going to look at a simple trick we can use to minimise the setup part of our unit tests, while maintaining clarity.

Let’s say we want to unit test the equality method on a simple Swift struct.

struct User: Equatable {
 let name: String
 let email: String
 let needsVerification: Bool

static func ==(lhs: User, rhs: User) -\> Bool {
 return lhs.name == rhs.name
 && lhs.email == rhs.email
 && lhs.needsVerification == rhs.needsVerification
 }
}

There are (countably) infinitely many different argument combinations we could pass into this method for testing. Obviously we can’t test with all of them, so we have to pick a few cases that represent general trends in results. A valid way of unit testing this method (and, indeed, the way I would normally write such a method, using test-driven development) would be to start with the case where all properties of the two Users are equal, and then to test what happens when each individual property differs. This gives us a suite of tests like this:

func test\_equals\_allPropertiesMatch\_isTrue() {
 let sut = User(name: "", email: "", needsVerification: false)
 let other = User(name: "", email: "", needsVerification: false)
 XCTAssertEqual(sut, other)
 XCTAssertEqual(other, sut)
}

func test\_equals\_nameDiffers\_isFalse() {
 let sut = User(name: "Jo", email: "", needsVerification: false)
 let other = User(name: "", email: "", needsVerification: false)
 XCTAssertNotEqual(sut, other)
 XCTAssertNotEqual(other, sut)
}

func test\_equals\_emailDiffers\_isFalse() {
 let sut = User(name: "", email: "A", needsVerification: false)
 let other = User(name: "", email: "", needsVerifiation: false)
 XCTAssertNotEqual(sut, other)
 XCTAssertNotEqual(other, sut)
}

func test\_equals\_needsVerificationDiffers\_isFalse() {
 let sut = User(name: "", email: "", needsVerification: true)
 let other = User(name: "", email: "", needsVerification: false)
 XCTAssertNotEqual(sut, other)
 XCTAssertNotEqual(other, sut)
}

(sut stands for “subject under test” and for some reason it’s the only acronym variable name I’m okay with.)

These aren’t bad unit tests by any stretch of the imagination — in fact they’re basically fine — but they’re also not “good.” Why not?

Let’s look at the setup of our two Users. Each time we create them we have to pass in all of the properties that the init method expects. This is true even if, in the context of the test, we don’t actually care what they are. In the first test, for example, all we care about is that the properties Match — their values could be the names of the Spice Girls in ascending height order, or my favourite Berlin coffee shops (Bonanza & Five Elephant btw), and it would make no difference to the test so long as they were the same. Similarly in the other three tests we only care that one specific property Differs.

Having information in these tests that we don’t care about creates noise, and makes the tests harder to understand. That’s maybe okay for these small examples, but when you’re trying to work out why a more complicated unit test is failing an hour before you cut a release, you’ll be very thankful you cut out as much unnecessary noise as possible.

Wouldn’t it be just super great and awesome and peachy and other superlatives if our tests only contained pertinent information? And, of course, if that wasn’t possible all of this set up would have been for nothing.

The solution

So here’s what we’re going to do: we’re going to extend the User type in our test target in order to add a method that lets us configure a User with the data we care about, while using sensible defaults for the other properties. I tend to call this method create because I think it reads nicely. Whatever you call it, the method should look something like this:

extension User {
 static func create(
 name: String = "",
 email: String = "",
 needsVerification: Bool = false
 ) -\> User {
 return User(
 name: name,
 email: email,
 needsVerification: needsVerification
 )
 }
}

(Don’t worry, I don’t like the way you space out your code either.)

These create methods are really simple — they take in the same arguments as the type’s init method but give each one a default value. As a rule of thumb I’d tend to use "" for String arguments, 0 for numeric ones, false for Bools, etc. Whatever you decide to use, the really important thing is to try and keep it consistent across different create implementations that you write.

(Cool aside: once a few of your types have create methods you can start using the result of calling create without any arguments as default values too. So if you had Account(user: User) then in Account.create you could set the default value for the user argument to be User.create().)

Now, combined with Swift’s type inference abilities we can rewrite the above tests like so:

var sut, other: User!

func test\_equals\_allPropertiesMatch\_isTrue() {
 (sut, other) = (.create(), .create())
 XCTAssertEqual(sut, other)
 XCTAssertEqual(other, sut)
}

func test\_equals\_nameDiffers\_isFalse() {
 (sut, other) = (.create(name: "Jo"), .create())
 XCTAssertNotEqual(sut, other)
 XCTAssertNotEqual(other, sut)
}

func test\_equals\_emailDiffers\_isFalse() {
 (sut, other) = (.create(email: "A"), .create())
 XCTAssertNotEqual(sut, other)
 XCTAssertNotEqual(other, sut)
}

func test\_equals\_needsVerificationDiffers\_isFalse() {
 (sut, other) = (.create(needsVerification: true), .create())
 XCTAssertNotEqual(sut, other)
 XCTAssertNotEqual(other, sut)
}

Pretty nice, right? Now each test only contains the information that’s actually relevant to the specific test case. This is a Good Thing.

Anyway, that’s a brief introduction to writing nice factory methods in Swift. This is obviously just one small way you can improve your unit tests, but you’ve got to start somewhere right? Go forth now, and write unit tests. ✅

(Thanks to Josh Heald. We were pairing when this pattern for writing factory methods initially came together.)

Nicer reuse identifiers with protocols in Swift

Clue — Thu, 07 Dec 2017 10:44:30 +0000

Recently I was going through the motions of setting up a new UICollectionView. I had written a view model for my cells, and I had a UICollectionViewCell subclass all ready to go. All that was left to do was to implement cellForItem(at:).

As an aside: if you’ve not worked with UICollectionView before, but are more of a UITableView kinda person, then you can just replace Collection with Table and Item with Row and this post should still be valid.

As a responsible iOS engineer [citation needed] I knew that the first thing I needed to do here was ask my collectionView to dequeue a cell. And to do that I had to call dequeueReusableCell(withReuseIdentifier:for:), passing a String “reuse identifier.” In order for the collectionView to have any idea what I was talking about, I also had to call register(_:forCellWithReuseIdentifier:) on the collection, so it knew to map this reuse identifier to my UICollectionViewCell subclass.

That subclass looked roughly like this:

final class CustomCollectionViewCell: UICollectionViewCell {

// code etc.

}

Another aside: CustomCollectionViewCell is just an example name. Please never name classes like this.

I decided a sensible reuse identifier for this cell would be "CustomCollectionViewCell". So I used that, and called both the methods. This is what those calls looked like:

// in a set up method
collectionView.register(
 CustomCollectionViewCell.self, 
 forCellWithReuseIdentifier: "CustomCollectionViewCell"
)

// in cellForItem(at:)
collectionView.dequeueReusableCell(
 withReuseIdentifier: "CustomCollectionViewCell"
 for: indexPath
)

This is obviously awful. We’ve got a magic string hanging around there, and it’s in more than one place. Clearly this is in need of some refactoring, so that’s exactly what I did. The first step was simply to move this string into a static constant on the CustomCollectionViewCell class.

final class CustomCollectionViewCell: UICollectionViewCell {

static let reuseIdentifier = "CustomCollectionViewCell"

}

Okay, good start. This means we can access the identifier anywhere in the code using CustomCollectionViewCell.reuseIdentifier. Already a massive improvement over what we had before. But it does present another problem. What if the class name changes later on?

We could just remember to change it, but let’s be real here: we’re humans, and we don’t always remember things like this. Even when it’s staring us right in the face. That’s why we get computers to do this stuff for us. So that leads nicely on to the next question: can we get the compiler to help us?

Well, if the answer was no, this would be an awfully short blog.

So how do we do it? See above, where we passed the reference to the CustomCollectionViewCell type into register(_:forCellWithReuseIdentifier:)? Wouldn’t it be great if we could convert that type into a String somehow and just use that? That would be so great.

(Dramatic pause.)

Yep, of course we can do exactly that. We can replace the bare String in the definition of reuseIdentifier with String(describing: CustomCollectionViewCell.self) and get exactly the same output. Now if the class name changes, the compiler won’t recognise the type there, and will let us know about it. Success!

Okay, right about now you might be looking at what we’ve done so far and thinking: “Matthew, this is great and all, but the title says ‘protocols’ and so far we’ve just pissed about with a bit of refactoring.” And you’re right, for sure. Consider all of the above simply as motivation for what comes next.

So after a while of using String(describing: TypeName.self) to generate reuse identifiers, I started to wonder if there was a way of doing this that would remove the boilerplate of defining a new reuseIdentifier in every cell subclass.

I started by writing the following protocol:

protocol ReuseIdentifying {
 static var reuseIdentifier: String { get }
}

And then extending it like so:

extension ReuseIdentifying {
 static var reuseIdentifier: String {
 return String(describing: /\* er... what goes here? \*/)
 }
}

I got a bit stuck here for a while. I needed a way to dynamically refer to the type that was implementing the protocol. Obviously, using ReuseIdentifying.self wouldn’t work, because that’s just going to return "ReuseIdentifying" every time.

In the past I’ve used Self in protocols to indicate “the implementing type.” So I wondered whether I could get away with something like Self.self. It looks utterly ridiculous, but…

Spoiler: it totally worked.

So here’s the final protocol extension:

extension ReuseIdentifying {
 static var reuseIdentifier: String {
 return String(describing: Self.self)
 }
}

Now by applying that protocol to my CustomCollectionViewCell I can delete the reuseIdentifier definition, and everything works as expected. The returned reuseIdentifier is, as I wanted, "CustomCollectionViewCell".

And there’s even better news: we can go further with this. Let’s say we want every single UICollectionViewCell subclass to have a reuseIdentifier. We don’t actually need to individually apply this protocol. We can just do the following:

extension UICollectionViewCell: ReuseIdentifying {}

Magic! ✨

Open questions

I like to test things, so I wanted to write some unit tests against this protocol extension.

I tried defining a class in the body of a test. Something like:

func test\_reuseIdentifier\_classIsCalledSomeClass\_isSomeClass() {
 class SomeClass: ReuseIdentifying {}
 XCTAssertEqual("SomeClass", SomeClass.reuseIdentifier)
}

As far as I could see, there’s no reason this wouldn’t work. But String(describing:) starts to behave kind of confusingly at this point. The return value from reuseIdentifer is "SomeClass #1".

I thought this might be an issue with having the class defined inside the method, so I moved it up to the file scope and ran the test again. And it worked!

So, if anyone knows why defining the class inside a method leads to the "#1" being appended to the end of the description, I’d be super interested to find out.