Status & Roadmap
Authors & License
Funding Ultimate++
Search on this site

SourceForge.net Logo

UnitTest++ in brief



For background, goals and license details, see:

The UnitTest++ home page

Noel Llopis' announcement

The documentation, while sparse, aims to be practical, so it should give you enough info to get started using UnitTest++ as fast as possible.

This text is almost identical copy of original docs/UnitTest++.html file made by Noel Llopis, I (Peter "Ped" Helcmanovsky) made only some U++ related changes to it - to make it more relevant for U++ users.


U++ wrapper

The U++ version of UnitTest++ consists of two packages:

UnitTest++ is the actual unit testing library. This is the package which you should add to your current project, if you want to use unit testing.

UnitTestTest is the package containing tests of UnitTest++. This is standalone runnable package which was used to develop the UnitTest++ (and verify U++ wrapper). Use this one to test the main package works as expected, when you do custom changes to main library or just read the source to get some inspiration how the library can be used.

Using UnitTest++

The U++ version of UnitTest++ comes with UnitTestTest package, which is a full test suite using UnitTest++. This is a great place to learn techniques for testing. There is one sample .cpp file: UnitTestTest/TestUnitTest++.cpp. It covers most of UnitTest++'s features in an easy-to-grasp context, so start there if you want a quick overview of typical usage.

Getting started

Create new package based on Core console project (in an assembly where bazaar package nest is defined). Add bazaar package UnitTest++ to it. Now adjust the cpp file to look like this:



#include <Core/Core.h>

#include <UnitTest++/UnitTest++.h>









    UPP::SetExitCode( UnitTest::RunAllTests() );


UnitTest++.h is a facade header for UnitTest++, so including that should get you all features of the library. All classes and free functions are placed in namespace UnitTest, so you need to either qualify their full names (as with RunAllTests() in the example) or add a using namespace UnitTest; statement in your .cpp files. Note that any mention of UnitTest++ functions and classes in this document assume that the UnitTest namespace has been opened.


Building this application and running it should produce the following output (details may vary):


.\some_test.cpp(5): error: Failure in FailSpectacularly: false

FAILED: 1 out of 1 tests failed (1 failures).

Test time: 0.00 seconds.


UnitTest++ attempts to report every failure in an IDE-friendly format, depending on platform (e.g. you can double-click it in Visual Studio's error list.) The exit code will be the number of failed tests, so that a failed test run always returns a non-zero exit code.

Test macros

To add a test, simply put the following code in a .cpp file of your choice:






The TEST macro contains enough machinery to turn this slightly odd-looking syntax into legal C++, and automatically register the test in a global list. This test list forms the basis of what is executed by RunAllTests().


If you want to re-use a set of test data for more than one test, or provide setup/teardown for tests, you can use the TEST_FIXTURE macro instead. The macro requires that you pass it a class name that it will instantiate, so any setup and teardown code should be in its constructor and destructor.


struct SomeFixture


    SomeFixture() { /* some setup */ }

    ~SomeFixture() { /* some teardown */ }


    int testData;



TEST_FIXTURE(SomeFixture, YourTestName)


    int temp = testData;



Note how members of the fixture are used as if they are a part of the test, since the macro-generated test class derives from the provided fixture class.

Suite macros

Tests can be grouped into suites, using the SUITE macro. A suite serves as a namespace for test names, so that the same test name can be used in two difference contexts.













This will place the tests into a C++ namespace called YourSuiteName, and make the suite name available to UnitTest++. RunAllTests() can be called for a specific suite name, so you can use this to build named groups of tests to be run together.

Simple check macros

In test cases, we want to check the results of our system under test. UnitTest++ provides a number of check macros that handle comparison and proper failure reporting.


The most basic variety is the boolean CHECK macro:


CHECK(false); // fails


It will fail if the boolean expression evaluates to false.


For equality checks, it's generally better to use CHECK_EQUAL:


CHECK_EQUAL(10, 20); // fails

CHECK_EQUAL("foo", "bar"); // fails


Note how CHECK_EQUAL is overloaded for C strings, so you don't have to resort to strcmp or similar. There is no facility for case-insensitive comparison or string searches, so you may have to drop down to a plain boolean CHECK with help from the CRT:


CHECK(std::strstr("zaza", "az") != 0); // succeeds


For floating-point comparison, equality isn't necessarily well-defined, so you should prefer the CHECK_CLOSE macro:


CHECK_CLOSE(3.14, 3.1415, 0.01); // succeeds


All of the macros are tailored to avoid unintended side-effects, for example:




    int i = 4;

    CHECK_EQUAL(5, ++i); // succeeds

    CHECK_EQUAL(5, i); // succeeds



The check macros guarantee that the ++i expression isn't repeated internally, as demonstrated above.

Array check macros

There is a set of check macros for array comparison as well:


const float oned[2] = { 10, 20 };

CHECK_ARRAY_EQUAL(oned, oned, 2); // succeeds

CHECK_ARRAY_CLOSE(oned, oned, 2, 0.00); // succeeds


const float twod[2][3] = { {0, 1, 2}, {2, 3, 4} };

CHECK_ARRAY2D_CLOSE(twod, twod, 2, 3, 0.00); // succeeds


The array equal macro compares elements using operator==, so CHECK_ARRAY_EQUAL won't work for an array of C strings, for example.


The array close macros are similar to the regular CHECK_CLOSE macro, and are really only useful for scalar types, that can be compared in terms of a difference between two array elements.


Note that the one-dimensional array macros work for std::vector as well, as it can be indexed just as a C array.

Exception check macros

Finally, there's a CHECK_THROW macro, which asserts that its enclosed expression throws the specified type:


struct TestException {};

CHECK_THROW(throw TestException(), TestException); // succeeds


UnitTest++ natively catches exceptions if your test code doesn't. So if your code under test throws any exception UnitTest++ will fail the test and report either using the what() method for std::exception derivatives or just a plain message for unknown exception types.


Should your test or code raise an irrecoverable error (an Access Violation on Win32, for example, or a signal on Linux), UnitTest++ will attempt to map them to an exception and fail the test, just as for other unhandled exceptions.

Time constraints

UnitTest++ can fail a test if it takes too long to complete, using so-called time constraints.


They come in two flavors; local and global time constraints.


Local time constraints are limited to the current scope, like so:




    // Lengthy setup...





        // Do time-critical stuff



    // Lengthy teardown...



The test will fail if the "Do time-critical stuff" block takes longer than 50 ms to complete. The time-consuming setup and teardown are not measured, since the time constraint is scope-bound. It's perfectly valid to have multiple local time constraints in the same test, as long as there is only one per block.


A global time constraint, on the other hand, requires that all of the tests in a test run are faster than a specified amount of time. This allows you, when you run a suite of tests, to ask UnitTest++ to fail it entirely if any test exceeds the global constraint. The max time is passed as a parameter to an overload of RunAllTests().


If you want to use a global time constraint, but have one test that is notoriously slow, you can exempt it from inspection by using the UNITTEST_TIME_CONSTRAINT_EXEMPT macro anywhere inside the test body.






    // Oh boy, this is going to take a while



Test runners

The RunAllTests() function has an overload that lets you customize the behavior of the runner, such as global time constraints, custom reporters, which suite to run, etc.


int RunAllTests(TestReporter& reporter, TestList const& list, char const* suiteName, int const maxTestTimeInMs);


If you attempt to pass custom parameters to RunAllTests(), note that the list parameter should have the value Test::GetTestList().


The parameterless RunAllTests() is a simple wrapper for this one, with sensible defaults.

Example setup

How to create a new test project varies depending on your environment, but here are some directions on common file structure and usage.


The general idea is that you keep one Main.cpp file with the entry-point which calls RunAllTests().


Then you can simply compile and link new .cpp files at will, typically one per test suite.


  + ShaverTests/


  +- Main.cpp


  +- TestBrush.cpp   

  +- TestEngine.cpp

  +- TestRazor.cpp   


Each of the Test*.cpp files will contain one or more TEST macro incantations with the associated test code. There are no source-level dependencies between Main.cpp and Test*.cpp, as the TEST macro handles the registration and setup necessary for RunAllTests() to find all tests compiled into the same final executable.


UnitTest++ does not require this structure, even if this is how the library itself does it. As long as your test project contains one or more TESTs and calls RunAllTests() at one point or another, it will be handled by UnitTest++.


It's common to make the generated executable start as a post-build step, so that merely building your test project will run the tests as well. Since the exit code is the count of failures, a failed test will generally break the build, as most build engines will fail a build if any step returns a non-zero exit code.


Best practices to use UnitTest++ together with U++

For a complex modular application using several packages as modules, I'm following these patterns.

Packages organization

Each production package (module) has "test" package counterpart, for example with package MainAccounting I do create package MainAccountingTests as well. The test package contains at least one cpp file, for example:


#include <MainAccounting/MainAccounting.h>    //MainAccounting package API definition

#include <UnitTest++/UnitTest++.h>


void MainAccountingTestsCPP() {}    //linking hack, each new CPP test file has it


SUITE(MainAccounting_tests) {

    TEST(MainAccounting_Instantiate) {

        MainAccounting macc;



The test package also does add UnitTest++ package from bazaar, and original MainAccounting package, and ideally nothing else. Because other non test packages should be already added in MainAccounting package.


Then I do have a ProjectTestsAll package, where I add all the module-test packages, Core package and UnitTest++ package. This package contains ordinary console application main:


#include <Core/Core.h>

#include <UnitTest++/UnitTest++.h>

#define RUN_IN_RELEASE(x) extern void x(); x()




    //HACK: force all CPP files with tests to link and run tests in Release compilation mode.

    RUN_IN_RELEASE( MainAccountingTestsCPP );


    UPP::SetExitCode( UnitTest::RunAllTests() );



There's a dummy empty function in each tests.cpp file, because otherwise the tests are lost in release mode linking (in debug mode it works without the hack).


Where is the main

The "main" running tests is in the above mentioned piece of code, in ProjectTestsAll package. What about the main of the application itself?


If you can have a single "ProjectApp" package adding all other modules (packages) and containing just a bare minimum of code to run the app, then by omitting this package from TestsAll you avoid any linking conflicts with multiple main entry points.


If your main package is larger, and does contain also functions you want to test, you should add a "UNITTEST" flag into main configuration of TestsAll package (Project/Main package configuration, edit the main line, or add first if none exists), then in the main package enclose the real application "main" inside #ifndef flagUNITTEST / #endif directives, and add also main package to TestsAll.


This way you select the ProjectTestsAll package while doing TDD (test driven development) or when you want to run tests, hit run and the tests are failing (or running). Once you are satisfied with all tests and you want to run actual application, switch to main Project package containing the real main, and run it.


Other remarks

Don't forget to run tests in all possible compiler configurations, which should be supported. I.e. both release and debug mode, and in case you use more compilers (MSCC vs GCC/MINGW), use both also to run tests. At least once per couple of days, but I think doing this daily is the right way (or having continuous integration server doing automated builds all the time). This will give you chance to catch subtle incompatibilities very early, and it will often help to discover nasty bugs which are hiding in particular mode/compiler combination, and will be revealed only in different combination.


GUI testing

I'm sorry if you find this too much "console" oriented: I didn't personally need to test any GUI parts of application (a mix of GUI main package solving layout and GUI functions + independent module doing the internals did solve this for me sufficiently), and so far I'm not sure even where to start with GUI testing.


This area is open for anyone who want to improve U++ tools and has some great ideas.

Do you want to contribute?