CppUnit is a C++ unit testing framework, similar to JUnit for Java. We will be using the latest stable version, release 1.10.2. This page is not a guide to unit testing, but rather an example of how to use CppUnit for unit testing in C++.

Unit tests are code, separate and independent from the code it tests, that can be run automatically.

There are several parts of unit testing. We'll go over how to create each in CppUnit. Let's use a class called CartesianComplex, representing complex numbers of the form

    a + bi
where a and b are real numbers and i is the imaginary number unit where i * i = -1. The value a is the real part and b is the complex part. Our class will handle the basic math operations (addition, subtraction, multiplication and division). More can be found at the Wikipedia entry or about.com entry.

We begin with the the test suite. It is a collection of tests run together as a unit. The basic collection of tests is the TestCase class. Our test class will extend CppUnit's TestCase class.

class TestCartesianComplex : public  CppUnit::TestCase
TestCase has a virtual method void runTest() we must override. Our tests are called from inside the runTest() method. Each test (a function) handles a small part of the test, and combined the functions test the whole thing. The test function names begin with "test". Adding these functions to the test case can be a little errorprone, but fortunately CppUnit has helper macros. First we create a suite to run the tests. This is private.
    CPPUNIT_TEST_SUITE( TestCartesianComplex );
Now we add the tests.
        CPPUNIT_TEST( testAccessors );
        CPPUNIT_TEST( testEqualityOperators );
        CPPUNIT_TEST( testPrint );
Now we need public declarations of the test functions.
    void testAccessors( );
    void testEqualityOperators( );
    void testPrint( );
Finally, outside the class declaration (but inside the .h), we need to register the test suite. Notice that the registration name matched the class name. We'll see the importance of this name registration later.
Now we must define the functionality of the methods listed in the .h file. The function runTest() is handled by the macros. We define the rest in the .C file. There are different types of asserts we can use in our test functions. Some of the most common are:
The next part is the test runner. It runs all the test suites and collects the results. When the tests are run, it'll give you a message. If they all pass, you get an OK message. If one of them fails, it'll tell you the name of the test case, the name of the source file and the line number. We also have a TestResult class which is the controller or event manager and a TestResultCollector class that listens for tests being run. All of this goes in int main().
    TestResult controller;

    TestResultCollector result;
    controller.addListener( &result );

    TestRunner runner;
    runner.addTest( TestFactoryRegistry::getRegistry().makeTest() );

    return result.wasSuccessful() ? 0 : 1;
You can add fancy stuff like a listener to print dots as the tests are run.
    cout << "" << testPath;
    runner.run( controller, testPath );
    cerr << endl;
Let's take a look at the Makefile. We need some new flags at the top of the file. These flags will be used to tell the compiler where to find the CppUnit headers and declarations. CppUnit is already installed on the UNC CS department Unix machines.
CPPOFLAGS   = -I/opt/cppunit/cppunit/include -L/opt/cppunit/cppunit/lib
CPPOBJFLAGS = -I/opt/cppunit/cppunit/include -L/opt/cppunit/cppunit/lib -lcppunit -ldl

TestCartesianComplex.o: CartesianComplex.o TestCartesianComplex.h TestCartesianComplex.C
	${C} ${CPPOFLAGS} -I${L} -c TestCartesianComplex.C

test.obj: test.C TestCartesianComplex.o
	${C} ${CPPOBJFLAGS} -I${L} -o test.obj test.C TestCartesianComplex.o CartesianComplex.o
Now we want to add some tests for the math functions, but they are going to be their own suite. We'll call it TestCartesianComplexMath. Our TestCase will have several instances of CartesianComplex that will be needed by all tests in the test case. CppUnit has a special class, called a fixture, for just this purpose. TestFixture is a subclass of TestCase test cases.
class TestCartesianComplexMath : public CppUnit::TestFixture
Make the commonly used variables private.
CartesianComplex *cc0_0, *cc1_0, *cc0_1;
There are two virtual functions that we must overwrite. Declare them public along with the test functions.
    void setUp( );
    void tearDown( );

    void testAddition( );
    void testSubtraction( );
    void testMultiplication( );
    void testDivision( );
The setUp( ) function is automatically called before each test function, while tearDown( ) is automatically called at the end of each test function. The private variables should be created and destroyed in the respective TestFixture function.

The only change we need to make in the Makefile is the linking of the files. Since we used the helper macro for test suite registration, test.C will automatically call all linked and registered TestCase classes.

test.obj: test.C TestCartesianComplex.o TestCartesianComplexMath.o
    ${C} ${CPPOBJFLAGS} -I${L} -o test.obj test.C TestCartesianComplex.o TestCartesianComplexMath.o CartesianComplex.o
There are many features and things you can do with CppUnit. This is but a small sample of what is available.

Useful Links:

Demo Class Files