Independent unit tests are the simplest to create and use, but they have a couple of drawbacks. An independent unit test bundle includes both the tests and the code to be tested. All are compiled and linked into the unit test bundle. At build time, the bundle is loaded and all of the tests are executed.

The advantage to independent unit tests, and where they get their name, is that the target and unit test bundle are entirely self-contained. All of the code to be tested is compiled by the target. That is, the target is independent of any other applications or products that your project produces. In fact, the code doesn't even need to be compiled elsewhere. You could, conceivably, create a project that only tests code and produces no products whatsoever.

The disadvantage is that the code being tested is compiled separately from the same code that gets compiled when your application is built. One consideration is the fact that the code could be compiled differently for the unit test bundle and the application. Build-setting differences between the unit test target and your application's target could easily cause subtle differences in the code the compiler produces, which means that your tests are not actually testing the same code that will run in your application. For most code, this probably won't matter, but a difference in, say, the signedness of character variables, optimization, or the size of enums could cause your tests to miss bugs in your application's code or fail tests that should pass. If you are rigorous, or just paranoid, you'll want to test the actual code that your final application will be executing — not just a reasonable facsimile.

The other, potential, disadvantage to recompiling all of the same code is that it takes time. All of the code you intend to test will have to be compiled twice — once for the application and again for the unit test bundle. If your code base is large, or it depends on a lot of other code that must be compiled, then compiling everything twice will slow down your builds.

Dependent unit tests perform their tests on the actual code produced by your product. A dependent unit test bundle contains only the test code. When it comes time to perform your unit tests, the program or library that your project produced is loaded into memory along with the unit test bundle. The references in the unit test bundle are linked to the actual classes and functions in your application and then executed. The unit test bundle depends on another product to accomplish its purpose.

As you might guess, there's more than just a little sleight of hand involved here. The unit test framework uses two techniques, depending on what kind of product you're testing. The method used to test libraries, frameworks, and independent unit tests is pretty straightforward: the unit test target executes a testing program that loads the unit test bundle (containing the test code and possibly some code to be tested) along with any dynamic libraries or frameworks that need testing. The tests are executed and the testing utility exits.

Testing an application is decidedly more bizarre. The unit test target runs a script that launches the actual executable produced by your project. Before the executable is started, several special environment variables are configured. These settings are picked up by the system's dynamic library loader and cause it to alter the normal sequence of binding and framework loading that occurs at run time. The settings instruct the loader to first load a special unit test framework into the application's address space. This process is known as bundle injection. The testing framework causes your unit test bundle to also be loaded into memory. Initialization code in your unit test bundle intercepts the execution of your application, preventing it from running normally. Instead, the unit test bundle's code links directly to the functions defined in the application and executes all of the tests. It then forces the application to terminate.

However convoluted, the beauty of this process is that your unit tests will test the actual, binary code of your application; the same code that will run when your application launches normally. The disadvantage is that this process is complex and requires a number of concessions from your application. Mostly these are restrictions on how your application is built. In the case of some C/C++ applications, you are also required to add code to your application to support dependent unit testing.

The iPhone SDK supports unit testing too. The techniques are very similar to the Objective-C unit testing under Mac OS X — in fact, they both use the same testing framework — but with the following differences:

Except for those configuration differences, you can follow the guidelines and instructions for writing Objective-C unit tests when developing for the iPhone, substituting the terms "independent test" and "dependent test" with "logic test" and "application test."

Unit tests are part of the build process. Target dependencies are used to integrate unit tests into your build. What target dependencies you create (if any) will depend on the kind of unit test you are creating.

Independent unit tests require no special configuration. All you need to do is make the source code for both the tests and the code to be tested members of the target. The compiler build settings for the target should match those of your product target as closely as possible, so that the code produced when you're compiling the unit test target is as close as possible to the code that will be compiled into your final product.

Add the source files to the target by dragging them into the Compile Sources phase of the unit test target, or by opening their Info window and adding them to the unit test target in the Targets tab. You can add the source for the actual tests in a similar manner (if the tests already exist), or by adding them to the unit test target when you create them. The section "Creating a Unit Test" shows how to write and add a new test.

The target SDK for an iPhone logic test (independent unit test) must be set to the iPhone Simulator.

A dependent unit test needs to know where to load the application or libraries to be tested.

Testing an iPhone application is different from testing a Mac OS X application, and requires a different organization in Xcode. In Mac OS X development (described in the previous section), you tell the unit test bundle what product you want tested. It takes on the responsibility of loading that target, injecting itself into the application, and performing its tests.

In iPhone development, the roles of the application and unit test bundle are reversed. You create a custom version of your application that includes the unit test bundle product. You load and run your test app on your iPhone or iPod Touch device like any other app. Once started, your app loads the unit test bundle, which takes over and performs its tests.

To configure an iPhone app for unit testing, follow these steps:

Unlike all other kinds of unit tests, iPhone application tests aren't run during the build phase. You must build and run your test application, which downloads both it and the unit tests to your iPhone for execution. This introduces a number of limitations to using iPhone application tests:

You might be scratching your head about the last one. You're probably asking "If the unit test code can't link to the code in the application, what use is it?"

One solution is to include the code in both targets. At run time only one implementation of the class will be used — most likely the one in the application (because it loaded first), but the Objective-C run time doesn't specifically guarantee this. Regardless, this is an acceptable solution in most cases and gives your unit tests direct access to iPhone hardware and its application environment.

Another solution is introspection. Instead of referring to application classes directly, do it indirectly in the case where the test will be running on an actual iPhone. Listing 20-1 shows an example. This code will compile, link, and run — as long as something in the same process actually implements the SieveOfEratosthenes class, which our application does.

- (void)setUp
{
#if TARGET_OS_IPHONE
    testSieve = [[NSClassFromString(@"SieveOfEratosthenes") alloc]
                 initWithMaxPrime:UNIT_TEST_MAX_PRIMES];
#else
    testSieve = [[SieveOfEratosthenes alloc]
                 initWithMaxPrime:UNIT_TEST_MAX_PRIMES];
#endif
    STAssertNotNil(testSieve,@"Unable to create SieveOfEratosthenes");
}

If a group of tests — defined as all of the tests in a TestCase class — deal with a similar set of data or environment, the construction and destruction of that data can be placed in two special methods: setUp and tearDown. The setUp method is called before each test is started, and the tearDown method is called after each test is finished. Override these methods if you want to initialize values or create common data structures that all, or at least two, of the tests will use. The typical use for setUp and tearDown is to create a working instance of an object that the tests will exercise, as illustrated in Listing 20-3. The test class defines a single instance variable that is initialized by setUp and destroyed by tearDown. Each test is free to use the object in the instance variable as the subject of its tests.

For Objective-C tests, the methods your test class should override are -(void)setUp and -(void)teardown. For C/C++ tests, the functions to override are void TestCase::setup() and void TestCase::tearDown().

SieveOfEratosthenesTests.h
#define UNIT_TEST_MAX_PRIMES  100000

@interface SieveOfEratosthenesTests : SenTestCase
{
    SieveOfEratosthenes* testSieve;
}
SieveOfEratosthenesTests.m
@implementation SieveOfEratosthenesTests

- (void)setUp
{
    testSieve = [[SieveOfEratosthenes alloc]
                 init:UNIT_TEST_MAX_PRIMES];
}

- (void)tearDown
{
    [testSieve release];
    testSieve = nil;
}

- (void)testInvalidNumbers
{
    // These should all return NO
    STAssertFalse([testSieve isPrimeInMap:-1],
                  @"-1 is not a prime number");
    STAssertFalse([testSieve isPrimeInMap:0],
                  @"0 is not a prime number");
    STAssertFalse([testSieve isPrimeInMap:1],
                  @"1 is not a prime number");
}

The setUp and tearDown methods are called before and after every test. This allows tests to perform destructive tests on the object — that is, tests that alter the object's state — because the object will be destroyed at the end of the test and re-created anew before the next test is run.

Unit test classes have standard constructor and destructor methods. Do not use the constructor to create test data. If your test structures are expensive to create and destroy, you may be tempted to create them in the constructor and let them persist for the duration of the test class. Don't do this. Your next approach might be to turn the setUp method into a factory that creates a singleton object when called the first time. Sorry, but that probably won't work either. Some testing frameworks create a separate instance of the test class for each test.

Instead, make a single test that creates the expensive object and then calls a series of subtests itself. Remember not to name your Objective-C subtests "test..." or the testing framework will run them again.

Because so many of the minor details of creating tests for Objective-C and C/C++ differ, the steps for creating your own tests have been separated into the following two sections, "Objective-C Tests" and "C++ Tests."

To create an Objective-C test class and add it to a unit test target, start by selecting the File

Figure 20-3. FIGURE 20-3

Click the Next button and give the test case class and file a name. The name should be descriptive of its purposes, such as StudentTests for a set of tests that validate the Student class. Make sure you create a matching .h file. Select the working project and add the test to the desired unit test target, as shown in Figure 20-4, making sure you don't include the test class file in any other target. Click the Finish button.

Figure 20-4. FIGURE 20-4

Xcode creates a skeletal test class definition and implementation, similar to the one shown in Listing 20-4. All of your test classes for Objective-C must be direct subclasses of the SenTestCase class.

#import <SenTestingKit/SenTestingKit.h>

@interface StudentTests : SenTestCase {

}

@end

Xcode has created the framework for your class and has already added it to your unit test target. The only thing you need to do now is to write one or more test methods. Each test method:

An example of three such tests is shown in Listing 20-5.

#import "StudentTests.h"

@implementation StudentTests

- (void)setUp
{
    student = [[Student alloc] initWithName:@"Jane Doe"];
    STAssertNotNil(student,@"Unable to create Student");
}

- (void)tearDown
{
    [student release];
    student = nil;
}


- (void)testNameConstructor;
{
    STAssertTrue([[student name] isEqualToString:@"Jane Doe"],
                 @"Student.name property incorrect");
}

- (void)testNamePartsParsing;
{
    STAssertTrue([[student firstName] isEqualToString:@"Jane"],
                 @"Student.firstName parsing incorrect");
    STAssertTrue([[student lastName] isEqualToString:@"Doe"],
                 @"Student.lastName parsing incorrect");
}

- (void)testNamePartsReplacement;
{
    STAssertTrue([[student name] isEqualToString:@"Jane Doe"],
                 @"Student.name property incorrect");

    [student setFirstName:@"John"];
    STAssertTrue([[student name] isEqualToString:@"John Doe"],
                 @"Student.name first name replacement incorrect");

    [student setLastName:@"Smith"];
    STAssertTrue([[student name] isEqualToString:@"John Smith"],
                 @"Student.name last name replacement incorrect");
}
@end

Amazingly, you are all done. The introspective nature of Objective-C allows the unit test framework to discover automatically all classes that are subclasses of SenTestCase in the bundle, and then find all void methods that begin with the name "test." The unit test framework creates your test object and then executes each test method one at a time.

When you write your test, you will employ a set of macros to evaluate the success of each test. If the assertion in the macro fails to meet the expectation, the test fails and a signal with a description of the failure is passed back to the unit test framework. Test failures appear as an error in the build log.

Each macro accepts a description of the failure. The description argument is a Core Foundation format string that may be followed by a variable number of arguments, à la NSLog(description,...) or -[NSString stringWithFormat:format,...]. The unit test macros available are listed in the following table. The STFail macro unconditionally records a failed test. Use it in a block of code where the program flow has already determined that a failure has occurred. All of the other macros are assertion macros. The test is successful if the parameters meet the expectations of the assertion. If they do not, a failure is recorded using the description constructed using the format string (@"..." in the table) and the remaining arguments.

After you have added your tests, you are ready to build the unit test target.

To create a C++ test class, follow the instructions for adding an Objective-C Test Case Class to your project, with the one exception that you'll start by choosing the C++ Test Case Class template from the Carbon group. Once you've selected the correct targets and added the class files to the project, return here.

Xcode creates a skeletal test class definition and implementation, as shown in Listing 20-6. All of your test classes for C++ must be direct subclasses of the TestCase class.

#include <CPlusTest/CPlusTest.h>

class StudentTests : public TestCase {
public:
    StudentTests(TestInvocation* invocation);
    virtual ~StudentTests();
};

Xcode has created the framework for your class and has already added it to your unit test target. The only thing you need to do now is to write one or more test methods. Each test method:

Unlike Objective-C, C++ test method names do not have to conform to any naming convention, but it is more readable if you retain the habit of starting each method name with "test." An example of two such tests is shown in Listing 20-7.

#include "StudentTests.h"

StudentTests::StudentTests(TestInvocation *invocation)
    : TestCase(invocation)
{
}

StudentTests::~StudentTests()
{
}

void StudentTests::testNameConstructor( )
{
    Student student("Jane Doe");
    CPTAssert(strcmp(student.getName(),"Jane Doe")==0);
}

void StudentTests::testNameProperty( )
{
    Student student();
    CPTAssert(student.getName()==NULL)
    student.setName("Jane Doe");
    CPTAssert(strcmp(student.getName(),"Jane Doe")==0);
}

StudentTests studentTestsNameConstructor(TEST_INVOCATION(StudentTests,
                                                        testNameConstructor));
StudentTests studentTestsNameProperty(TEST_INVOCATION(StudentTests,
                                                      testNameProperty));

// Conditional support for C/C++ unit tests
#ifndef UNIT_TEST_SUPPORT
#define UNIT_TEST_SUPPORT   1
#endif

#if UNIT_TEST_SUPPORT
#include <CPlusTest/CPlusTest.h>
#endif

int main (int argc, char * const argv[])
{
    //Perform any required initialization here...

#if UNIT_TEST_SUPPORT
    TestRun run;
    // Create a log for writing out test results
    TestLog log(std::cerr);
    run.addObserver(&log);
    // Get all registered tests and run them.
    TestSuite& allTests = TestSuite::allTests();
    allTests.run(run);
    // If the TestSuite ran any tests, log the results and exit.
    if (run.runCount())
        {
        // Log a final message.
        std::cerr << " Ran " << run.runCount()
                  << " tests, " << run.failureCount() << " failed."
                  << std::endl;
        return (0);
        }
    // Otherwise, run the application normally.
#endif
...

UnitTestRunner.h
#include <Carbon/Carbon.h>

class UnitTestRunner
{
private:
    EventLoopTimerUPP timerUPP;
    EventLoopTimerRef timerRef;

public:
    UnitTestRunner();
    virtual ~UnitTestRunner();

protected:
    static void testTimerFired(EventLoopTimerRef timer, void* userData);
    void runTests(EventLoopTimerRef timer);
};

UnitTestRunner.cpp
  #include <CPlusTest/CPlusTest.h>
  #include "UnitTestRunner.h"

  UnitTestRunner installTimer;    // static constructor to create timer

  UnitTestRunner::UnitTestRunner() : timerUPP(NULL), timerRef(NULL)
  {
      // Get the UPP for the static bridge method.
      timerUPP = NewEventLoopTimerUPP(UnitTestRunner::testTimerFired);
      (void)InstallEventLoopTimer(GetMainEventLoop(),0,0,timerUPP,this,&timerRef);
  }

  UnitTestRunner::~UnitTestRunner()
  {
      // Destroy the timer
      if (timerRef != NULL) {
          RemoveEventLoopTimer(timerRef);
          timerRef = NULL;
          }
      if (timerUPP != NULL) {
          DisposeEventLoopTimerUPP(timerUPP);
          timerUPP = NULL;
          }
  }

  // Static method to bridge the call to the local instance.
  void UnitTestRunner::testTimerFired(EventLoopTimerRef timer, void* userData)
  {
      ((UnitTestRunner*)userData)->runTests(timer);
  }

  void UnitTestRunner::runTests(EventLoopTimerRef timer)
  {
      if (timer == timerRef) {
          // We're done with the timer
          RemoveEventLoopTimer(timerRef);
          timerRef = NULL;
          // Create the test run
          TestRun run;
          // Create a log for writing out test results
          TestLog log(std::cerr);
          run.addObserver(&log);
          // Get all registered tests and run them.
          TestSuite& allTests = TestSuite::allTests();
          allTests.run(run);
          // If tests were run, log the results and terminate the application
          if (run.runCount())  {
              // Log a final message.
              std::cerr << " Ran " << run.runCount() << " tests, "
                        << run.failureCount() << " failed."
                        << std::endl;
              QuitApplicationEventLoop();
              }
          // Else, fall through and continue running the application
          }
}

However awkward an iPhone application (dependent) unit test is to set up and use, it is stunningly simple to debug.

Remember that an iPhone application test is a regular copy of your iPhone app that includes a unit testing bundle. To debug your application tests, simply run your test application target under the control of the debugger (Run

Debugging dependent unit tests for an application requires that you reverse the normal order of targets and trick the application target into running your unit tests instead of executing your application normally, all under the control of the debugger. Here's how:

Now build and debug your project. The application target causes the unit tests target to build, but not run (because you disabled the unit test's run script). Note that there's a quirky circular dependency here — the unit test target still tries to link to your application's binary. If your application hasn't been built, the unit test target will fail to build with a link error. That's why I had you perform step 3 before proceeding, so the unit test bundle has a product to satisfy its link phase.

Xcode then launches the executable under the control of the debugger. The environment variables trick the application executable into acting as if it were being run for the purposes of unit testing. The system loads the unit test bundle and executes the tests, allowing you to set breakpoints in the unit test source and debug them.

When you are done debugging your unit tests, reverse the entire process, as follows:

Debugging independent tests is a little simpler. It requires that you create an executable from the unit test bundle so that the debugger knows how to launch it under its control. The executable is actually the test harness utility and its arguments tell it what unit test bundle to load and execute. Follow these steps to create the executable:

Set the active target to the unit test and the active executable to the custom executable you just created. You can now set breakpoints in the unit tests and launch it under the control of the debugger just like any other application. When you are done debugging, restore the run script phase of the unit tests by removing the exit statement in the run script phase. This permits the tests to run during the build phase once again.