Setting Up OCUnit Unit Testing in Xcode 4

May 15th, 2012

Filed under: Xcode | 1 comment

Xcode ships with OCUnit, which allows you to unit test Objective-C code. This post shows you how to setup Xcode 4 so you can unit test Cocoa and iOS applications.

Create an Appropriate Project

The easiest way to add unit testing support in Xcode 4 is to create a project that uses the Cocoa or Cocoa Touch frameworks, such as a Cocoa or iOS application. When you select an appropriate project and click the Next button, you should see an Include Unit Tests checkbox.

Xcode4NewProjectIncludeUnitTests

When you select the Include Unit Tests checkbox, Xcode adds a unit test bundle target and a unit testing class to your project. Xcode also does most of the setup work for you. It configures the necessary build settings for unit testing and adds a target dependency so your application target builds when you build the unit test target.

Running Unit Tests After Building Your Project

Adding a unit test bundle when you create an Xcode project takes care of most of the build settings for you. There is one build setting you may have to setup manually. If you want Xcode to run your unit tests when you build the project, you must set the Test After Build build setting to YES. My Xcode 4: Accessing Build Settings post has detailed information on accessing build settings.

Adding Unit Test Classes to Your Project

While Xcode adds a test case class to your project when you create a new project and select the Include Unit Tests checkbox, you’ll eventually need to add more classes for unit testing. Choose File > New > File to add a unit testing class to your project. Select either Cocoa under Mac OS X or Cocoa Touch under iOS on the left side of the New File Assistant. Select Objective-C test case class from the list of file templates. Click the Next button. Enter the name of your class in the Class text field. The name of the class is also the name of the file. Click the Next button. Choose a location to save the file. Click the Create button to create the file.

Make sure the class you create is added to the unit test target, not the application target.

AddFileToUnitTestTarget

If you mistakenly add the unit test class to the wrong target, select the file from the project navigator and open the file inspector by choosing View > Utilities > Show File Inspector. Use the checkboxes in the Target Membership section to ensure the unit test class is a member of the unit testing target, not the application target. 

Configuring Your Scheme for Testing

Click the name of the scheme in the Scheme menu and choose Edit Scheme to open the scheme editor. Select the Test step from the left side of the scheme editor.

SchemeEditorUnitTesting

The scheme editor allows you to choose a build configuration to use for unit testing, the debugger to use to debug unit tests, and the unit tests to run. Xcode is setup initially to run all unit tests.

Running Unit Tests

Xcode provides three ways of running unit tests. If you set the Test After Build build setting to YES, choosing Product > Build for Testing builds your project and runs the unit tests. The results of the unit tests appear in the build results window, which you can access from the log navigator. Choose View > Navigators > Show Log Navigator to show the log navigator. Select a build from the log navigator to show the build results window. 

The second way to run your unit tests is to choose Product > Test (or click the Run button and choose Test). When you choose Product > Test, Xcode builds your project and runs the tests. Use the log navigator to view the results of the unit tests. The final way to run your unit tests is to choose Product > Perform Action > Test Without Building, which runs unit tests without building the project.

Adding Unit Test Support to an Existing Project

To add unit test support to an existing project, you must add a unit test target to your project. Select the name of your project from the project navigator to open the project editor. Click the Add Target button at the bottom of the editor. Select the Other group under either Mac OS X or iOS. Select Unit Testing Bundle (either Cocoa or Cocoa Touch) from the target list.

AddUnitTestTarget

Click the Next button. Enter a name for your target in the Product Name text field. Click the Finish button to finish creating the unit test target.

Adding a unit test target to an existing Xcode project requires more setup work than creating a new project does. You must add a target dependency to the unit test target. You also must configure build settings for the unit test bundle.

Adding Target Dependencies

Adding a target dependency allows Xcode to build your application when you build the unit test target. Select the unit test target from the project editor. Click the Build Phases button at the top of the project editor. Click the disclosure triangle next to the Target Dependencies build phase. Click the + button to add a dependency. Select the application target from the target list.

UnitTestTargetDependency

Configuring the Unit Test Bundle

If you are unit testing an application, you must configure the unit test bundle. There are two build settings you must configure: Bundle Loader and Test Host. The Bundle Loader build setting is in the Linking collection, and the Test Host build setting is in the Unit Testing collection. You must set the value of these build settings to the location of the application’s executable file. For an application named MyApp, the value of the Bundle Loader and Test Host build settings would be the following:

$(BUILT_PRODUCTS_DIR)/MyApp.app/Contents/MacOS/MyApp (Mac)
$(BUILT_PRODUCTS_DIR)/MyApp.app/MyApp (iOS)

iOS applications running in the simulator should leave the Test Host build setting blank. The simulator does not support application-hosted unit tests. If you set the Test Host build setting, you will get a warning when building the unit testing target and the tests will not run.

Tags: ,


One thought on “Setting Up OCUnit Unit Testing in Xcode 4

  1. Steffen says:

    The note about Bundle Loader helped me move on, although I had to give it many tries to find the right naming for my environment. Thank you!

Leave a Reply

Your email address will not be published. Required fields are marked *