Important built-in assert functions

Each test needs to assert some expected behavior. The use of the XCTAssert functions tells Xcode what is expected.

The most important assert functions are:

• XCTAssertTrue(_:_:file:line:): This asserts that an expression is true
• XCTAssertFalse(_:_:file:line:): This asserts that an expression is false
• XCTAssertEqual(_:_:_:file:line:): This asserts that two expressions are equal
• XCTAssertEqualWithAccuracy(_:_:accuracy:_:file:line:): This asserts that two expressions are the same, taking into account the accuracy defined in the accuracy parameter
• XCTAssertNotEqual(_:_:_:file:line:): This asserts that two expressions are not equal
• XCTAssertNil(_:_:file:line:): This asserts that an expression is a nil
• XCTAssertNotNil(_:_:file:line:): This asserts that an expression is not nil
• XCTFail(_:file:line:): This always fails

Note that all the XCTAssert functions could be written using XCTAssertTrue(_:_:file:line:). For example, these two lines of code are equivalent to each other:

// This assertion is equivalent to... 
XCTAssertEqual(2, 1+1, "2 should be the same as 1+1") 

 
// ...this assertion 
XCTAssertTrue(2 == 1+1, "2 should be the same as 1+1") 

But you should use the more precise assertions whenever possible. The reason is, the log output of the more precise assertion methods tells you exactly what happened in case of a failure. For example, look at the log output of the following two assertions:

XCTAssertEqual(2, 1, "foo")
// Output:
// XCTAssertEqual failed: ("2") is not equal to ("1") - foo


XCTAssertTrue(2 == 1, "bar")
// Output:
// XCTAssertTrue failed - bar

In the first case, you don't need to look at the test to understand what happened. The log tells you exactly what went wrong.

In all the XCTAssert functions, the last three parameters are optional. To take a look at an example for the use of all the parameters, let's check out what a failing test looks like in Xcode. Open FirstDemoTests.swift, and change the expected number of vowels from 3 to 4:

XCTAssertEqual(numberOfVowels, 4, 
               "should find 4 vowels in Dominik") 

Now, run the tests. The test fails. You will see something like this:

Xcode tells you that something went wrong with this test. Next, to the test function in the preceding screenshot, there is a red diamond with an x on line number 24. The same symbol is in the line that actually failed. On the right is the explanation of what actually went wrong, followed by the string you provided in the XCTAssertEqual function. In this case, the first parameter, numberOfVowels, is 3; and the second parameter is 4. As 3 is not equal to 4, the test fails.

As mentioned earlier, XCTAssertEqual(...) has two more parameters--file and line. These parameters allow you to alter what is printed in the debug console in case of a test failure. Navigate to View | Debug Area | Activate Console and open the debug console. If the debug area is split in half, click on the second right-most button in the bottom-right corner to hide the variables' view:

We have only one test at the moment, and the debug output is already kind of messy. Later in this chapter, we will learn that there is a better UI for the same information in Xcode.

There is one line in the output that shows the failing test:

/Users/dom/Documents/TDD_book/edition_03/code/FirstDemo/FirstDemoTests/FirstDemoTests.swift:31: error: -[FirstDemoTests.FirstDemoTests test_NumberOfVowels_WhenPassedDominik_ReturnsThree] : XCTAssertEqual failed: ("3") is not equal to ("4") - should find 4 vowels in Dominik

The output starts with the file and line where the failing tests are located. With the file and line parameter of the XCTAssert functions, we can alter what is printed there. Go back to the test method, and replace the assertion with this:

XCTAssertEqual(numberOfVowels, 4, 
               "should find 4 vowels in Dominik", 
               file: "FirstDemoTests.swift", line: 24) 

The test method starts at line number 24.

With this change, the output is as follows:

FirstDemoTests.swift:24: error: -[FirstDemoTests.FirstDemoTests test_NumberOfVowels_WhenPassedDominik_ReturnsThree] : XCTAssertEqual failed: ("3") is not equal to ("4") - should find 4 vowels in Dominik

The debug output of the test now shows the filename and line number that we specified in the assertion function. This doesn't sound like a useful feature, but later in the book, you will see an example where this really shines.

Before we move on with the introduction to TDD, change the test so that it passes again.