In an earlier post on C++ Unit Testing Frameworks, I came across a relatively new framework by the name of UnitTest++. At first glance, this framework appealed to me for a couple of reasons:
- Unlike most of the other frameworks, it is relatively recent, and in development
- One of the originators of the project is the author of the best comparison of C++ unit testing libraries online. The experience of reviewing several other frameworks should inform the design of a new framework.
So, I’ve decided to take a closer look. I’ll start in this post with the basics: how do we write tests, fixtures and suites in UnitTest++? These are the fundamentals of a unit testing library, and should be very simple to use.
First, we need the UnitTest++ distribution. It is available as a simple tarball from SourceForge. Exploding the tarball gives a basic structure with build files at the top level, and child docs and src directories. To build the library itself, on Linux at least, requires a simple make:
jsankey@shiny:~/tools/UnitTest++$ make
src/AssertException.cpp
src/Test.cpp
…
Creating libUnitTest++.a library…
src/tests/Main.cpp
src/tests/TestAssertHandler.cpp
…
Linking TestUnitTest++…
Running unit tests…
Success: 162 tests passed.
Test time: 0.31 seconds.
The primary output is libUnitTest++.a at the top level. This, along with the header files under src (excluding src/test), forms the redistributables needed to build against UnitTest++ in your own project. It is a little awkward that no binary distributions, nor a “dist” or similar Makefile target are available. However, the source tree is so simple that it is not hard to extract what you need.
Armed with the library, the next step is to create out first test case, and run it. UnitTest++ makes use of macros to simplify creating a new test case. It could hardly get an easier:
#include "UnitTest++.h"
TEST(MyTest)
{
CHECK(true);
}
int main(int, char const *[])
{
return UnitTest::RunAllTests();
}
A test case is created using the TEST macro, which takes the case name as an argument. The macro adds the test case to a global list of cases automatically. The body of the test utilises the CHECK macro to assert conditions under test. Various CHECK* macros are available for common cases. Finally, to actually run the test, we call UnitTest::RunAllTests(). This runs all cases using a default reporter that prints a result summary to standard output:
jsankey@shiny:~/repo/utpp$ ./utpp
Success: 1 tests passed.
Test time: 0.00 seconds.
RunAllTests returns the number of failed cases, so using this as the program exit code works well. If we change the check to CHECK(false), we get a failure report:
jsankey@shiny:~/repo/utpp$ ./utpp
utpp.cpp(9): error: Failure in MyTest: false
FAILURE: 1 out of 1 tests failed (1 failures).
Test time: 0.00 seconds.
The next step is to create a test fixture, which allows us to surround our test cases with shared setup/teardown code. This is achieved in UnitTest++ by building upon standard C++ construction/destruction semantics. To create a fixture, you just create a standard C++ struct. The setup and teardown code go in the struct constructor and destructor respectively. Let’s illustrate how this works:
#include <iostream>
#include <string>
#include "UnitTest++.h"
struct MyFixture
{
std::string testData;
MyFixture() :
testData(“my test data”)
{
std::cout << “my setup” << std::endl;
}
~MyFixture()
{
std::cout << “my teardown” << std::endl;
}
};
TEST_FIXTURE(MyFixture, MyTestCase)
{
std::cout << testData << std::endl;
}
int main(int, char const *[])
{
return UnitTest::RunAllTests();
}
Instead of the TEST macro, we use TEXT_FIXTURE to create a test case that uses the fixture struct. The example is artificial, but serves to illustrate the order in which the functions are called. Also of interest is how members of the fixture struct are referenced directly by name within the test case. Under the covers, the TEST_FIXTURE macro derives a type from MyTestFixture, making this possible. Running this new program gives the following:
jsankey@shiny:~/repo/utpp$ ./utpp
my setup
my test data
my teardown
Success: 1 tests passed.
Test time: 0.01 seconds.
The setup and teardown wrap execution of the test case, which has simple access to the data in the fixture. By leveraging construction/destruction, the fixture code is both familiar and concise.
The final step is to organise test cases into suites. UnitTest++ again uses macros to simplify the creation of suites. You simply wrap the tests in the SUITE macro:
#include <iostream>
#include "UnitTest++.h"
SUITE(SuiteOne)
{
TEST(TestOne)
{
std::cout << “SuiteOne::TestOne” << std::endl;
}
TEST(TestTwo)
{
std::cout << “SuiteOne::TestTwo” << std::endl;
}
}
SUITE(SuiteTwo)
{
TEST(TestOne)
{
std::cout << “SuiteTwo:TestOne” << std::endl;
}
}
int main(int, char const *[])
{
return UnitTest::RunAllTests();
}
As shown above, it is possible to have two tests of the same name in different suites. This illustrates the first function of suites: namespacing. Running the above gives:
jsankey@shiny:~/repo/utpp$ ./utpp
SuiteOne::TestOne
SuiteOne::TestTwo
SuiteTwo:TestOne
Success: 3 tests passed.
Test time: 0.01 seconds.
Suites also have another function: they allow you to easily run a group of related tests. We can change our main function to only run SuiteOne (note we also need to include TestReporterStdout.h):
int main(int, char const *[])
{
UnitTest::TestReporterStdout reporter;
return UnitTest::RunAllTests(reporter,
UnitTest::Test::GetTestList(),
“SuiteOne”,
0);
}
Running this new main will only execute SuiteOne:
jsankey@shiny:~/repo/utpp$ ./utpp
SuiteOne::TestOne
SuiteOne::TestTwo
Success: 2 tests passed.
Test time: 0.00 seconds.
So there you have it, a taste of the basics in UnitTest++. The most appealing thing about this library is simplicity: you can tell that the authors have made an effort to keep construction of cases, fixtures and suites as easy as possible. This lets you get on with writing the actual test code. In this overview I have not explored all of the details, most notably the various CHECK macros that test for equality, exceptions and so on. However, as it stands UnitTest++ is quite a simple framework, and there is not a whole lot more to it. Although you may need more features than you currently get out of the box, UnitTest++ is young and thus I expect still growing. The simplicity also makes it an easy target for customisation, which is important given the diversity of C++ environments. I’ll be keeping an eye on UnitTest++ as it evolves, and recommend you take a look yourself.
