the Compartmented Robust Posix C++ Unit Test system

Test basics

With crpcut it is easy to write tests. All that is required is to write test bodies following the TEST(name, ...) macro, and a main() function that runs the tests by calling crpcut::run().

By writing:

     
     #include <crpcut.hpp>
     #include <iostream>
     #include <ostream>
     
     TEST(bare_minimum)
     {
     }
     
     TEST(print_a_message)
     {
       std::cout << "hello world, I am " << __PRETTY_FUNCTION__ << std::endl;
     }
     
     TEST(information)
     {
       INFO << "This is also a test" << std::endl
            << "Using the INFO macro";
       INFO << "for output";
     }
     
     int main(int argc, char *argv[])
     {
       return crpcut::run(argc, argv);
     }

you define three tests named bare_minimum, print_a_message, and information, and also ask crpcut to run the tests from the main() function. All three tests will succeed, since they do nothing wrong.

To build the program, make sure you have the correct include path to reach <crpcut.hpp>. Link your test program with -lcrpcut or -lcrpcut_basic.

Running the test program with the -l / --list (list) command line flag, will list all tests:


     !bare_minimum
     !print_a_message
     !information

The exclamation marks indicate that the tests are critical.

Running the test program with an empty parameter list runs all tests:


     3 test cases selected
     
                    Sum   Critical   Non-critical
     PASSED   :       3          3              0

which isn't too exciting for this program.

Running the test program with the -v / --verbose command line flag, will list the output of all tests, including those that pass:


     PASSED!: bare_minimum
     ===============================================================================
     PASSED!: print_a_message
     stdout-------------------------------------------------------------------------
     hello world, I am virtual void print_a_message::test()
     
     ===============================================================================
     PASSED!: information
     info---------------------------------------------------------------------------
     samples/bare-minimum.cpp:43
     This is also a test
     Using the INFO macro
     -------------------------------------------------------------------------------
     info---------------------------------------------------------------------------
     samples/bare-minimum.cpp:45
     for output
     ===============================================================================
     3 test cases selected
     
                    Sum   Critical   Non-critical
     PASSED   :       3          3              0

As can be seen, crpcut captures stdout and adds as a log item for the test. It does the same for stderr. The log items are only shown if the test fails, or when run in verbose mode with the -v / --verbose command line flag.

The INFO macro is used like an output stream to print information that can be useful for understanding what happens in a test. Each INFO statement will always give a separate log item for the test, unlike stdout and stderr which can behave differently from run to run, depending on buffering and scheduling. INFO can be used also for types that has no output stream operator. For those, a hex dump will be displayed for the object's memory region.

A test is a class, and the test body is the body of the member function test(). A test succeeds if it returns from the function body without having explicitly failed, or if it has left files behind in its working directory (for example a core dump.) Each test process runs in its own working directory.

Another macro that can be useful is DISABLED_TEST(name, ...). A disabled test will never be listed, and never a candidate for running, but it will be compiled. If a test for some reason can't be used right now, but it is intended to be, DISABLED_TEST(name, ...) will keep the error reports clean, and will prevent code-rot in the test code, since it will be compiled. As a reminder, disabled tests are shown in the test summary.