Using CxxTest in Project Builder

Synopsis

Integrating CxxTest into a Project Builder project is outlined below.

Project Builder Instructions

To add CxxTest to an existing Project Builder project, follow these steps:

• Download CxxTest and extract it into a sub-directory within your project. In this example, I assume the directory is called cxxtest.

• Create a new target that will build the test runner. To add a new target, use Project->New Target... and select "Application" for the type of new target. In general, it should have a similar setup to your main application target (ie: same frameworks, search paths, compiler settings, etc), but lack any source files that are not in your library.

• Add the cxxtest directory to the search path under "Headers" in the target settings.

• Create the test header file, which contains the test code as inline functions. This header file will be used to build the source file using a build script. Example:

  #ifndef __SAMPLETEST_H
  #define __SAMPLETEST_H
  
  #include <cxxtest/TestSuite.h>
  
  //
  // An example test suite as a starting point. Remove the inline methods and write
  // your own tests.
  // 
  
  class SampleTest : public CxxTest::TestSuite
  {
  public:
      void testExample1()
      {
  	TS_ASSERT_EQUALS( 5, 5 );
  	TS_ASSERT_EQUALS( 'a', 'A' );
      }
  
      void testExampleN()
      {
  	TS_ASSERT_EQUALS( 1.0, 1.0 );
      }
  };
  
  
  #endif // __SAMPLETEST_H
  

• Create a build script that will transform the header created in step 3 into source code that can be compiled. The build script can be written in any scripting language available for Mac OS X, though all it really needs to do is execute:

  ./cxxtest/cxxtestgen.pl --error-printer -o UnitTest.cpp UnitTest.h

  Where UnitTest.h is the header created in Step 3, and UnitTest.cpp is the source code file that will be generated. If you named the directory containing the CxxTest files something other than "cxxtest", you will need to adjust the command line accordingly.

  Don't Forget: You'll need to make the build script executable, so open a Terminal window (Applications->Utilities->Terminal), change directories to your project directory and run:

  chmod u+x buildScript.pl

  where buildScript.pl is the name of your build script.

  Note: You can skip this step if you have a really simple project and only a few test headers to build test source from. For a simple case, you can substitute the command line above for the script in the next step.

• Add a new Build Phase to the testing target to run the build script. To do this, open the test target settings, then select "Build Phases". Then click on Project->New Build Phase->New Shell Script Build Phase. A new section will appear in the "Build Phases" list called "Shell Script Files". Set the shell to "/bin/sh" and on the line below, put the path (relative to the project directory) and name of the build script.

• Create an empty UnitTest.cpp and add it to the testing target in Project Builder.

That's it! When you build the test target, it will run the shell script to build the test source code from the test header you wrote. Then Project Builder will compile and link the TestRunner source and produce an app that will run the tests. For the sample code given above, the following results would be given by the TestRunner:

Running 2 test(s)
In UnitTest::testExample1:
UnitTest.h:16: Expected ('a' == 'A', found ('a' != 'A')
.
Failed 1 of 2 tests
Success rate: 50%

UnitTest has exited with status 0

While the sample code is really simple and does not test anything non-trivial, you get the idea. The output is not glamorous, but it does get the job done. Perhaps someone will build a GUI reporting interface for this tool like what is available for JUnit.

Useful Links

• CxxTest
• XProgramming.com - Information on Extreme Programming, including Unit Tests
• JUnit - Unit testing for Java.