www.hans-eric.com

This is a Quick Start Guide that shows how to get you started with Acceptance Test Driven Development for the iPhone, usingUISpec and XCode 4.0. (There’s also an XCode 3-version of this tutorial.)

The following were used in the creation of this tutorial:

• XCode 4.0
• iOS SDK 4.3
• UISpec version 1.1 (subversion revision 82)

Suggestions on how to improve this guide are much welcome, in which case you can use the comment form at the end of this page.

Step 1: Create a New XCode Project

1. Start XCode and create a new View-based Application project.
   
2. Name the product HelloUISpec, and give it a company identifier. If you’re not planning on using the built in OCTest for your unit testing you should uncheck the Include Unit Tests checkbox. In this tutorial I’ll leave it checked.
3. Create a new folder called Code in your home directory, make sure it’s selected and click the Create button. XCode will create a project folder named HelloUISpec under the Code folder.
   
   
4. Set iPhone 4.3 Simulator as the active Scheme, then Run the empty application to make sure the new project was set up correctly.
   If nothing went wrong the simulator window should be displayed. You may then close it (using cmd-Q).
   

Step 2: Install UISpec

1. Open a Terminal Window and navigate to the Code directory:
   cd ~/Code
2. Checkout the UISpec code from subversion with this command:
   svn co http://uispec.googlecode.com/svn/trunk/ UISpec
   
3. Close the Terminal Window and go back to XCode.
4. Create a new target for your acceptance tests by right clicking the HelloUISpec target, and choose Duplicate in the context menu.
   
5. Click the Duplicate only button on the following dialog.
   
6. Change the name of the new target, from “HelloUISpec copy” to “HelloUISpecAcceptanceTests”
7. Change the Product Name setting (for the new target) to HelloUISpecAcceptanceTests. The Product Name setting is found on the Build Settings tab, under the Packaging section.
   
8.  Change the name of the HelloUISpec copy scheme to HelloUISpecAcceptanceTests by clicking on the Scheme control on the tool bar, selecting Manage Schemes… from the context menu.
   
   
9. Add a reference to the UISpec project by right clicking HelloUISpec (the root node in your project) and choosing Add Files to “HelloUISpec”…
   
   In the dialog shown, navigate to ~/Code/UISpec/XCode/UISpec and select the file UISpec.xcodeproj. Make sure that only the HelloUISpecAcceptanceTest checkbox is checked, and click Add.
   
10. Add a direct dependency to UISpec by selecting the HelloUISpecAcceptanceTests, go to the Build Phases page, expand the Target Dependencies section, click on the plus (+) button.
    
11. Add a dependency to UISpecs static library by expanding the Link Binary With Libraries section on the Build Phases pane, select the libUISpec.a node and click Add.
    
12. Add the path to UISpec header files by selecting the HelloUISpecAcceptanceTests target node, on the Build Settings pane, change the value of Header Search Paths to UISpec’s headers directory:~/Code/UISpec/headers
    
    Note! In order to find the Header Search Paths property, you’ll need to change filter mode from Basic to All in the upper left corner of the pane.
    As a tip, an easy way to find Header Search Paths in the list of settings is to use the search control.
13. Add the RUN_ACCEPTANCE_TESTS define to both the Debug and the Release version of the Preprocessor Macros build setting (which you’ll find in the GCC 4.2 – Preprocessing section).
    
14. Replace the project’s main.m file with the following code:

    #import <UIKit/UIKit.h>
    #ifdef RUN_ACCEPTANCE_TESTS
    #import "UISpec.h"
    #endif
    
    int main(int argc, char *argv[]) {
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    #ifdef RUN_ACCEPTANCE_TESTS
      [UISpec runSpecsAfterDelay:3];
    #endif
    
      int retVal = UIApplicationMain(argc, argv, nil, nil);
      [pool release];
      return retVal;
    }
    

    

15. Change the active scheme to HelloUISpecAcceptanceTests iPhone 4.3 Simulator.
    
    As you can see, XCode has added a couple of new schemes (UISpec and Specs). You may want to remove these in the Manage Schemes… dialog.
16. Build and Run.
    Now, your project is ready for the next step, which, if you’re a good TDD practitioner, is to write a failing acceptance test.

Step 3: Write a Failing Test

1. Add a new group to your project by right clicking the project root node (HelloUISpec) and selecting New Group.
   Name the new group “Acceptance Test Cases”.
   
2. Add a new test case file by right clicking the new “Acceptance Test Cases” group and selecting Add/New File…
   
   
   Select the Objective-C class template and click Next.
   
   Leave NSObject as the type of Subclass.
   
   Enter DescribeHelloWorld as the name and make sure Acceptance Tests is the only designated target.
   
3. Delete the DescribeHelloWorld.h file that XCode automatically created for you in the Acceptance Test Cases group.
4. Replace the content of DescribeHelloWorld.m with the following code:

   #import	"UISpec.h"
   #import "UIQuery.h"
   
   @interface DescribeHelloWorld: NSObject <UISpec> {
   }
   @end
   
   @implementation DescribeHelloWorld
   
   -(void)itShouldSayHelloWorld {
   	UIQuery *app = [UIQuery withApplication];
   	[expectThat([app.label text:@"Hello World!"]) should].exist;
   }
   @end
   

   

5. Hit the Build and Run button and keep an eye on the Debug Console. The program halts on an exception and the message in the debug view is ugly, but what it tells us indirectly is that no label was found within the application.
   
   
   Now it’s time to make the test pass.

Step 4: Make the Test Pass

1. Start Interface Builder by selecting the file HelloUISpecViewController.xib under the HelloUISpec file group.
   
2. Bring out the utilities window by using the View control on the tool bar, or by using the View|Utilities|Show Utilities from the application menu.
   
   Select the Object library in the bottom part of the utilities window.
   
   Find the Label control in the list of objects (hint: use the search field) and add a new label by dragging and dropping onto the view. Change the text of the label to read “Hello World!”.
   
3. Hit the Build and Run button and keep an eye on the Debug Console. It should now show a message that informs us that there were no failures.