Writing Unit Tests for WiteBox

NOTE: This document assumes you have already installed WiteBox in your iPhone project. If you haven't, please consult the document Setting Up WiteBox.

Writing unit tests for WiteBox is extremely simple and similar to how they are done for xUnit and other unit testing systems.

Where Should They Be Located?

Before you write any unit tests, it's best to prepare your project for where they will live. I prefer to create a new directory on my filesystem and import it into the project, but simply creating a new Group might be enough for you. Some developers even intermix the test cases with the code.

Organize it however you want because WiteBox will automatically search for the unit tests and doesn't care where they are located. When WiteBox is run, it will search your classes for anything that extends TestCase, therefore as long as you have imported the class into your project and it's associated with the WiteBox target, it will be run.

Setting Up Your First Test Case

Now, let's write a test case!

First, create your class:

1. Right-click the group you want to add the test case to and select Add -> New File....
2. On the right, select iPhone -> Cocoa Touch Class and select Objective-C class as a template. If given the option, make your new class a subclass of NSObject. Hit Next.
3. Choose whatever filename you'd like. I calls my test case classes something like CollectionTests.m or MathLibTests.m.
4. If you'd like, uncheck the box that says Also create "untitled.h". It's usually not necessary and keeping header files in sync with their implementations is sort of a nuisance with test cases anyway.
5. Make sure that your unit testing application is the only one checked in Targets.
6. Hit Finish and you're class is created.
7. Open up your new class and make it subclass TestClass. If you get a warning about a missing interface file (if you chose not to create the .h file), create one right above the implementation.
8. You're now ready to write your tests!

Here's what your file should look like:

//
//  MyTests.m
//
//  Created by Your Name on MM/DD/YYYY.
//  Copyright 2009 Your Company. All rights reserved.
//

#import "TestCase.h"

@interface MyTests : TestCase {}
@end

@implementation MyTests

@end

Writing Your First Unit Tests

With your test case ready, you're now ready to write some tests! In general, you should group your tests into test cases by function. You can group together only those tests that test out a certain class, or you can group them so that they test a set of classes found in a single package. It's up to you.

In our case, we'll do some NSString tests to help us verify its functionality.

The following code is pretty standard unit testing material. If there's anything you don't understand, please consult the online resources in the reference section or the excellent book, Test Driven Development: By Example by Kent Beck.

Here we populate our test case with unit tests:

//
//  MyTests.m
//
//  Created by Your Name on MM/DD/YYYY.
//  Copyright 2009 Your Company. All rights reserved.
//

#import "TestCase.h"

@interface MyTests : TestCase {}
@end

@implementation MyTests

- (void)testStringFormatting {
	NSString *name = @"Earl";
	
	// create the string
	NSString *formattedString = [NSString stringWithFormat:@"My name is %@.", name];
	
	// test the substitution
	assertEqualObjects(@"My name is Earl.", formattedString); 
}

- (void)testStringLength {
	NSString *alphabet = @"ABCDEFGHIJKLMNOPQRSTUVWXYZ";
	
	// test the length
	assertEqual(26U, [alphabet length]);
}

- (void)testPrefixAndSuffix {
	NSString *urlString = @"http://raptureinvenice.com";
	
	// test the url
	assertTrue([urlString hasPrefix:@"http://"]);
	assertFalse([urlString hasSuffix:@".html"]);
}

@end

Note the expected value, 26U. This is an unsigned 26. The reason why we append the U is because the length method of NSString returns an unsigned int. The assert methods in WiteBox are strict comparisons. This is intentional as unit tests are meant to test your code and that includes verifying the type. Also, your unit tests will act as documentation to those who use your code, and these reminders may help to prevent comparisons of unsigned ints to -1 and the like.

See the WiteBox Cheat Sheet for more information on constant modifiers.

You can also add hooks to be called at special points in the testing process. The methods, setUp and tearDown, are called at the beginning and end of testing a test case respectively. Then there are setUpTest: and tearDownTest: which are called before and after each individual test. Finally, you can disable test case, usually for temporary reasons, by implementing an isEnabled method that returns NO (false).

For a full list of asserts and hooks, see the WiteBox Cheat Sheet.

Running the Tests

Make sure your Active Target is your WiteBox target and run the application. If you copied the above, you should see all tests passing except for one. Click the test case to show all the specific unit tests that ran. You can also click the specific unit test that failed to see more information about expected and actual values.

And that's all you need to know. :-) And if you'd like, try your hand at fixing the test so that it passes!

NOTE: Ordinarily, this is not how test-driven development works. The tests should always be written to work, and if the test fails it means your own code failed. However, I wanted you to see what failed tests look like.

Resources

Here are some links to good tutorials that explain unit testing:

• Wikipedia: Test-drive Development
• Write Maintainable Unit Tests That Will Save You Time And Tears