Adding a New XCTestCase Subclass

To add a new test case, go to File ➤ New ➤ File and select “Unit Test Case Class” (see Figure 3-1).

After tapping “Next”, give a name for the test class and choose its location in your project just like any other file.

Notice that, in the last step, you need to choose the test target this test class belongs to (Figure 3-2) – this is extremely important since test classes cannot be part of your executable target.

Class Method setUp()

Method setUpWithError () throw

After class method setup(), XCTest locates all the methods in the class that start with “test” and don’t have any arguments.

For each one of those methods, XCTest calls setUpWithError() function before it runs the test method itself. This is the place where you can prepare any instance variables you have instead of duplicating those steps in every test method.

Also, an instance method setup() is called after each setUpWithError() call.

If setUpWithError() throws, it means that the test that follows it will fail as well.

Test Methods

A test method passes if it doesn’t have any failed assertions or crashes. We’ll talk about how to write test methods later in this chapter.

Teardown Block

You can add as many teardown blocks as you want, and it’s explicit for changes made at this function only. To create a teardown code that runs after each method, you need to override the tearDownWithError() method .

Method tearDownWithError() throw

tearDownWithError method runs after each test method whether it failed or passed. We use this method to clean up any side effect your test method might have caused, and in most cases, it should be the inverse function of setUpWithError() method.

Just like setUpWithError() and setup(), tearDownWithError() is called before “tearDown()”. They are both valid so that you can use them in your projects.

Class Method tearDown()

How It All Fits Together

Confused? Well, that sounds normal. But setting up the initial state for a test and cleaning it up afterward are crucial steps to achieve stability in your test run.

This is why I created Figure 3-4 to show you how it looks from above.

XCTest Creates an XCTestCase Instance for Every Test Method

Some may think that before a test case class starts its execution, XCTest creates an instance of this class and just runs all the tests one by one. While that makes sense in standard classes, this is not the case in XCTest classes.

When Xcode starts its test suite, it actually creates an XCTestCase instance for every test method and adds it to its test runner queue before the test execution even begins.

Let’s say you have a test class named “LoginTests” with four different test methods. When the test run begins, XCTest creates four instances of LoginTests class, one for each test method, and adds them to the test runner. Those four instances get deallocated at the end of the run, only after all the other tests finished their execution.

And this is important because it can give you a sense about how states are managed during the test run execution. For example, you cannot share an instance variable value across different test methods, since each one of those methods has its own class instance.

And regarding memory management, you need to remember that none of the class instances get deallocated until the end of the test run. This means you need to pay attention to what you are doing in the setup and tearDown methods and make sure to release and reset any data that can affect other test methods.

Creating a Custom Assertion

Believe it or not, there are cases when the existing assertions are not the precise and convenient tool for validating your tests.

Luckily, there’s a way of creating your custom assertions and making your testing code much cleaner.

I’m In. How to Write My Own Assertion?

The basic method of writing your own assertion is, well, a new method in your tests.

Let’s look at the following example:

  func testPersonFetcher_getPersonByID_checkProperties() {

        // arrange

        PersonDataBase().insertNewPerson(newPerson: Person(firstName: "Tyler", lastName: "Butler"))

        let personFetcher = PersonFetcher()

        // act

        let person = personFetcher.getPerson(byID: "me")!

        // assert

        XCTAssertEqual(person.firstName, "Tyler")

        XCTAssertEqual(person.lastName, "Butler")

    }

In this test method, we are fetching a “Person” object and check its first and last name. Now let’s say for the sake of our example that we want to bundle those two assertions to one function that checks both first and last name. We can create a function that gets three arguments, the “Person” object, first name, and last name, as strings and run those two assertions:

    func checkPersonValues(person: Person, firstName : String, lastName : String) {

        XCTAssertEqual(person.firstName, firstName)

        XCTAssertEqual(person.lastName, lastName)

    }

    func testPersonFetcher_getPersonByID_checkProperties() {

        // arrange

        PersonDataBase().insertNewPerson(newPerson: Person(firstName: "Tyler", lastName: "Butler"))

        let personFetcher = PersonFetcher()

        // act

        let person = personFetcher.getPerson(byID: "me")!

        // assert

        checkPersonValues(person: person, firstName: "Tyler", lastName: "Butler")

    }

Simple, ha? Not so quickly. Let’s run this test and see Figure 3-7.

Our test failed, but this is not the issue. Do you see the problem here? From the preceding screenshot, we see the two methods – the test method and the assertion method. We also see the failure message, but instead of pointing on the test method, it points on the assertion method!

We see that we have no way of connecting the failure message to the correct test method. Also, in case of several failed test methods, we are going to have multiple failure messages in the same place, one above the other – it’s a testing nightmare!

But fortunately, we have a solution. Let’s look for a second on the XCTAssert function’s signature:

func XCTAssert(_ expression: @autoclosure () throws -> Bool, _ message: @autoclosure () -> String = "", file: StaticString = #file, line: UInt = #line)

As you can see, besides the expression and the message arguments, we also have two more arguments – file and line.

File (String) and Line (UInt) contain the information on where in the code XCTest shows the failure message. By default, both of them have the values of the place where we call the assertion function.

Note

#file and #line are two expressions that are part of the Swift language. You can use them not only in your tests but also in your project code. Swift also has more interesting expressions you can use in your tests and in general, like #function, #column, and more.

So, if we want to show the message on the right place, all we need to do is to pass the #line and #file expression to our final assertion method:

    func checkPersonValues(person: Person, firstName : String, lastName : String, line : UInt = #line, file : StaticString = #file) {

        XCTAssertEqual(person.firstName, firstName, file: file, line:line)

        XCTAssertEqual(person.lastName, lastName, file: file, line:line)

    }

Let me explain what I did here – our custom assertion method has two more arguments, line and file, filled with default values. The default values are the actual place where we call the function. Later then, we pass those two arguments to the assertion methods inside, overriding their default values. I can say we are kind of tricking the system into getting a clear failure message.

Now let’s run our test with our improved assertion method (Figure 3-8).

Great! Now our failure message displayed is in the right place – in the test method and not in the assertion method. Also, we didn’t have to change anything in the test method.

To sum it up, custom assertion methods can help you maintain your testing code easier by making it more readable and less duplicated (DRY). Whenever you feel your assertion code is a little bit complex or confusing, just write your own method. It’s that easy.

Expect, Wait, Fulfill, and Assert

XCTestExpectation Pattern

When we want to create an asynchronous test, we create a XCTestExpectation object. On its initialization, we pass an informative description that can help us understand what expectation was not fulfilled if our test failed.

Before the assertion part, we call waitForExpectations() method. What this method does is to stop the test execution until all the expectations are fulfilled or the timeout was reached.

Fulfill Multiple Times for One Expectation

A good use case for that is a music player that needs to update the progress of the song a few times. The expectation can count the number of times it gets called and then moves on to the assertion part when it reaches a specific number.

Assert When the Expectation Is Not Fulfilled

OK, I need you to stay focused on this one. There are cases when we want to make sure a code is not being executed. In other words, if our expectation is fulfilled, our test fails.

A good use case for isInverted property is permissions handling. We want to make sure parts of our code are not being executed in a specific configuration and states.

Expect Array of Expectations, Ordered

XCTestExpectation Subclasses

Now that you have “wait” + “fulfill” + “assert” tools, basically, every a-sync job can be tested using XCTestExpectation. But Xcode 8.3 brought several improvements in that area in order to make those tasks much easier to build and read.

In this code, we are trying to test if a notification was raised. We add an observer, and when we receive it, we fulfill the expectation. In the following line, we post the notification and wait 0.1 seconds for the expectation for being fulfilled.

In the preceding example, we have some data layers and a UI Screen. The test is to save some data and check if the screen receives a “data updated” notification.

We understand that the posting notification code is inside the data layer and the observer code is inside the UI Screen. So how do we check it?

OK, so we can add some closure or delegate pattern to pass the event from the myScreen class to the test method, but this requires us to change our code only to make our tests easier to test. This may be true in many cases, but not in this case – no one observes this event, only the test method.

Fortunately, we have the ability to observe notification calls in our tests very easily.

As you can see, we are adding expectation(forNotification:). When the notification is raised, the expectation is fulfilled. Notice we are not checking if myScreen receives the notification. This is something you need to do some other way, for example, checking its state.