CPUnit project page

CPUnit is a unit test framework for C++ applications and programs. It is very much inspired by the elegance of JUnit, althoug, since C++ is a language quite different from Java, both the implementation and the way tests are written differ. (For instance, tests in CPUnit are never encapsulated in a class, but rather a namespace). The similarity is in the ease of use, the minimality of coding required to write good tests and user friendly command line options for test execution.

Contents:

Motivation and main features

I was looking for a good xUnit-based test framework for my C++ code, and after ten years of Java programming, I have been quite spoiled using JUnit. After having browsed the web for some time, I realized two things:

1. Due to the lack of flexibility in C++ compared to Java, you cannot "have it all" (as you can in JUnit).
2. None of the frameworks I looked at (and I shall not claim to have looked at all of them) satisfied my primary list of requirements.

Main features

1. Minimal amount of code required to write a test
2. Automatic test registration
3. Support for suites/grouping of tests
4. Support for fixtures
5. Scalable to large projects with many modules
6. Possibility to run subsets of the tests using wildcards

Limitations

• Exceptions
• STL
• Templates
• Streams

A mininal example

The below code snippet demonstrates the least amount of code required to write an executable test in CPUnit:

        #include <cpunit>
        
        using namespace cpunit;

        CPUNIT_GTEST(example_test) {
           const int expected = 33;
           const int actual   = i1;
           assert_equals("The two integers should be equal.", expected, actual);
        }
      

• The CPUnit header files are located at "/include"
• The CPUnit library is located at "/lib"
• The CPUnit library is named "CPUnit"

        >g++ -I/include -L/lib -lCPUnit -o testExecutable TestDemo.cpp 
        >./testExecutable
      

        >g++ -I/include -L/lib -lCPUnit -o testExecutable TestDemo.cpp 
        >./testExecutable
        .
        
	Time: 0.010

        OK (1 tests)
        >
      

Introducing suites

If you want to write more than just a few tests, it is handy to group the tests into suites. In CPUnit, suites are equivalent to namespaces of tests, and modifying the above example into using suites turns out as follows:

        #include <cpunit>
        
        namespace DemoTest {

           using namespace cpunit;

           CPUNIT_TEST(DemoTest, example_test) {
              const int i1 = 33;
              const int i2 = i1;
              assert_equals("The two integers should be equal.", i1, i2);
           }

           CPUNIT_TEST(DemoTest, example_test_two) {
              const int i1 = 33;
              const int i2 = 34;
              assert_true("The two integers should be different.", i1 != i2);
           }
        }
      

        >g++ -I/include -L/lib -lCPUnit -o testExecutable TestDemo.cpp 
        >./testExecutable
        ..
        
	Time: 0.018

        OK (2 tests)
        > 
      

Using fixtures

It is not uncommon that several tests in one suite operate on the same type of test data. To reduce the amount of code in the tests, this common code can be placed directly in the suite (namespace). In the following example, we shall write a test to verify that std::sort works for integers:

        #include <cpunit>
        #include <algorithm>
        #include <vector>
        
        namespace SortTest {
        
           using namespace cpunit;

           const int length = 3;
           const int data[length] = {3, 1, 2};
           std::vector input(data, data+length);

           CPUNIT_TEST(SortTest, test_sort) {
              // Construct the expected result
              const int expected_data[length] = {1, 2, 3};
              std::vector expected(expected_data, expected_data + length);

              // Sort and then test the actual result
              std::sort(input.begin(), input.end());
              assert_equals("std::sort failed.", expected, input);
           }
	   
           // Construct a reverse comparator for the next test.
           struct RevCmp {
              bool operator () (int i1, int i2) {
                 return i2 < i1;
              }
           };

           CPUNIT_TEST(SortTest, test_reverse_sort) {
           // Construct the expected result
           const int expected_data[length] = {2, 3, 1};
           std::vector expected(expected_data, expected_data + length);

           // Sort and then test the actual result
           std::sort(input.begin(), input.end(), RevCmp());
           assert_equals("std::sort reversely failed.", expected, input);
        }
     }
   

        #include <cpunit>
        #include <algorithm>
        #include <vector>
        
        namespace SortTest {
        
           using namespace cpunit;

           const int length = 3;
           const int data[length] = {3, 1, 2};
           std::vector input;
          
           CPUNIT_SET_UP(SortTest) {
              input = std::vector(data, data + length);
           }

           CPUNIT_TEAR_DOWN(SortTest) {
              input.clear();
           }

           CPUNIT_TEST(SortTest, test_sort) {
           // Construct the expected result
           const int expected_data[length] = {1, 2, 3};
           std::vector expected(expected_data, expected_data + length);

           // Sort and then test the actual result
           std::sort(input.begin(), input.end());
              assert_equals("std::sort failed.", expected, input);
           }
	   
           // Construct a reverse comparator for the next test.
           struct RevCmp {
              bool operator () (int i1, int i2) {
                 return i2 < i1;
              }
           };

           CPUNIT_TEST(SortTest, test_reverse_sort) {
           // Construct the expected result
           const int expected_data[length] = {2, 3, 1};
           std::vector expected(expected_data, expected_data + length);

           // Sort and then test the actual result
           std::sort(input.begin(), input.end(), RevCmp());
           assert_equals("std::sort reversely failed.", expected, input);
        }
     }
     

Testing for expected exceptions

Sometimes, you want to check that your code really does throw an exception. You can register this type of tests using the CPUNIT_TEST_EX and CPUNIT_TEST_EX_ANY macros:

      CPUNIT_TEST_EX_ANY(MyStuffTest, test_that_that_exception_really_comes) {
        throw "The '*_ANY' macro registers a test that succeeds whatever is thrown";
      }

      CPUNIT_TEST_EX(MyStuffTest, test_for_particular_exception, MyException) {
        // This macro registers a test that succeeds only if a test of
        // the type 'MyException' is thrown.
      }
      

Modes of execution

Running a subset of the tests

      >./testExecutable "SortTest*"
    

      >./testExecutable "SortTest*test*"
    

      >./testExecutable SortTest::test_reverse_sort SortTest::test_sort
    

If you want to know which tests exists, run

	>./testExecutable -L
      

Verbose and robust mode

By specifying the flag -v (or --verbose) to the test executable, you will have one line printed for each test being executed.
Specifying the flag -a (or --all) will force all tests to be executed, even if there are errors. (Default behaviour is to stop at the first error).

Error message formatting

• p - test suite name
• n - test name
• t - test time
• e - test outcome
• m - error message
• f - file name where test resides
• l - line number in the file where the test resides
• N - newline
• T - tab

      SortTest::test_reverse_sort - ASSERT EQUALS FAILED - std::sort reversely failed. Expected <[2,3,1]>, was <[3,2,1]>. (0.020s)
      (Registered at SortTest.cpp:31)
    

More execution options

Linking sub-projects together

This can be achieved through several means. The below procedure is my way of accomplishing this, and makes use of static linking:

1. Compile each subproject into an archive as follows:

   	    > g++ -c -I/include *.cpp
   	    > ar -rcs libTests.a *.o
   	    >
   	  

2. Link everything together into one large executable:

   	    > g++ -o allTests -L/lib -lCPUnit -Wl,-all_load ./sub_proj_1/libTests.a ... ./sub_proj_n/libTests.a
   	    >
   	  

   The option -Wl,-all_load tells the linker to load all object files from all static libraries. (Default behaviour is to only load object files that are explicitly referenced, which will fail with CPUnit, since the object files contain self registering mechanisms with no external references).

Using with Doxygen

To make sure Doxygen expands the CPUNIT_XXX macros in order to produce proper documentation of your tests, add the following setup in the Doxygen configuration (under preprocessor configuration):

	ENABLE_PREPROCESSING = YES
	MACRO_EXPANSION      = YES
	PREDEFINED           = "CPUNIT_TEST(n,f)='void f()" \
	                       "CPUNIT_GTEST(f)='void f()" \
                               "CPUNIT_SET_UP(f)='void set_up()" \
                               "CPUNIT_TEAR_DOWN(n)='void tear_down()"\
                               "CPUNIT_TEST_EX(n,f,E)='void f()"\
                               "CPUNIT_TEST_EX_ANY(n,f)='void f()"\
                               "CPUNIT_GTEST_EX(f,E)='void f()"\
                               "CPUNIT_GTEST_EX_ANY(f)='void f()"
      

Available asserts

All assert functions are declared in "cpunit_Assert.hpp":

        
       template<class T>
       void assert_equals(const std::string msg, const T &expected, const T &actual);
       
       template<class T>
       void assert_equals(const T &expected, const T &actual);

       template<class T, class Eq>
       void assert_equals(const std::string msg, const T &expected, const T &actual, const Eq &eq);

       template<class T, class Eq>
       void assert_equals(const T &expected, const T &actual, const Eq &eq);
  
       void assert_equals(const std::string msg, const double expected, const double actual, const double error);
       void assert_equals(const double expected, const double actual, const double error);
  
       void assert_true(const std::string msg, const bool statement);
       void assert_true(const bool statement);

       void assert_false(const std::string msg, const bool statement);
       void assert_false(const bool statement);

       void assert_not_null(const std::string msg, const void *data);
       void assert_not_null(const void *data);

       void assert_null(const std::string msg, const void *data);
       void assert_null(const void *data);
       
       void fail(const std::string msg);
       void fail();
      

	struct MyEq {
	   bool operator()(const T &t1, const T &t2) const {
	      // do your comparision here...
	   }
	};
      

Assert macros

In addition to the above assert functions, there are also some simple assert macros available:

	CPUNIT_FAIL     ()
	CPUNIT_FAIL1    ( message )
	CPUNIT_ASSERT   ( predicate )
	CPUNIT_ASSERT1  ( message, predicate )
	CPUNIT_DISPROVE ( predicate )
	CPUNIT_DISPROVE1( message, predicate )
      

	for (int i=0; i<100; ++i) {
          CPUNIT_ASSERT1("Failed for i=" << i, i < 100);
        }
      

Handling custom exceptions

Off the shelf, CPUnit only handles its own exceptions and subclasses of std::exception when running in robust mode (in addition to a catch(...) clause). To add explicit handling of other types of thrown objects, do as follows:

Tricks for more compact code

This section lists some more or less hidden features that will help you spend less symbols when defining your tests.

String concatenation

To steer away from the macro pitfall, (and since I do not like to program everything in upper case), I decided to define all asserts as functions. The downside is that producing assert comments (the first argument for the assert functions taking strings) containing variable information is cumbersome. To alleviate this, I added a macro, CPUNIT_STR, which allows you to write assert comments like this:

       CPUNIT_GTEST(test_stuff) {
	  for (int i=0; i<30; ++i) {
             assert_true(CPUNIT_STR("Statement " << i << " is not valid."), is_valid(i));
          }
       }
	

Macros for scope names

     CPUNIT_TEST(Level1::Level2::Level3::Level4::Level5::GadgetTest, test_stuff) {
        ...
     }
      

#define GADGET_TEST Level1::Level2::Level3::Level4::Level5::GadgetTest

     CPUNIT_TEST(GADGET_TEST, test_stuff) {
        ...
     }
      

Good luck!
-db-