Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the master branch, built from commit 8d02ed770b.
PrevUpHomeNext

A testing framework, what for?

How should a test program report errors? Displaying an error message is an obvious possibility:

if( something_bad_detected )
  std::cout << "something bad has been detected" << std::endl;

But that requires inspection of the program's output after each run to determine if an error occurred. Since test programs are often run as part of a regression test suite, human inspection of output to detect error messages is time consuming and unreliable. Test frameworks like GNU/expect can do the inspections automatically, but are overly complex for simple testing.

A better simple way to report errors is for the test program to return EXIT_SUCCESS (normally 0) if the test program completes satisfactorily, and EXIT_FAILURE if an error is detected. This allows a simple regression test script to automatically and unambiguously detect success or failure. Further appropriate actions such as creating an HTML table or emailing an alert can be taken by the script, and can be modified as desired without having to change the actual C++ test programs.

A testing protocol based on a policy of test programs returning EXIT_SUCCESS or EXIT_FAILURE does not require any supporting tools; the C++ language and standard library are sufficient. The programmer must remember, however, to catch all exceptions and convert them to program exits with non-zero return codes. The programmer must also remember to not use the standard library assert() macro for test code, because on some systems it results in undesirable side effects like a message requiring manual intervention.

The Boost Test Library's Unit Test Framework is designed to automate those tasks. The library supplied main() relieves users from messy error detection and reporting duties. Users could use supplied testing tools to perform complex validation tasks. Let's take a look on the following simple test program:

#include <my_class.hpp>

int main( int, char* [] )
{
  my_class test_object( "qwerty" );
  return test_object.is_valid() ? EXIT_SUCCESS : EXIT_FAILURE;
}

There are several issues with above test.

  1. You need to convert is_valid result in proper result code.
  2. Would exception happen in test_object construction of method is_valid invocation, the program will crash.
  3. You won't see any output, would you run this test manually.

The Unit Test Framework solves all these issues. To integrate with it above program needs to be changed to:

#include <my_class.hpp>
#define BOOST_TEST_MODULE MyTest
#include <boost/test/unit_test.hpp>

BOOST_AUTO_TEST_CASE( my_test )
{
  my_class test_object( "qwerty" );
  BOOST_TEST( test_object.is_valid() );
}

Now, you not only receive uniform result code, even in case of exception, but also nicely formatted output from BOOST_TEST tool, would you choose to see it. Is there any other ways to perform checks? The following example test program shows several different ways to detect and report an error in the add() function.

#define BOOST_TEST_MODULE MyTest
#include <boost/test/unit_test.hpp>

int add( int i, int j ) { return i + j; }

BOOST_AUTO_TEST_CASE(my_test)
{
  // six ways to detect and report the same error:

  // continues on error
  BOOST_TEST( add(2, 2) == 4 );          1

  // throws on error
  BOOST_TEST_REQUIRE( add(2, 2) == 4 );  2

  //continues on error
  if (add(2, 2) != 4)
    BOOST_ERROR( "Ouch..." );            3

  // throws on error
  if (add(2, 2) != 4)
    BOOST_FAIL( "Ouch..." );             4

  // throws on error
  if (add(2, 2) != 4)
    throw "Ouch...";                     5

  // continues on error
  BOOST_TEST( add(2, 2) == 4,            6
              "2 plus 2 is not 4 but " << add(2, 2));
}

1

This approach uses tool BOOST_TEST, which displays an error message (by default on std::cout) that includes the expression that failed, as well as the values on the two side of the equation, the source file name, and the source file line number. It also increments the error count. At program termination, the error count will be displayed automatically by the Unit Test Framework.

2

This approach uses tool BOOST_TEST_REQUIRE, is similar to approach #1, except that after displaying the error, an exception is thrown, to be caught by the Unit Test Framework. This approach is suitable when writing an explicit test program, and the error would be so severe as to make further testing impractical.

3

This approach is similar to approach #1, except that the error detection and error reporting are coded separately. This is most useful when the specific condition being tested requires several independent statements and/or is not indicative of the reason for failure.

4

This approach is similar to approach #2, except that the error detection and error reporting are coded separately. This is most useful when the specific condition being tested requires several independent statements and/or is not indicative of the reason for failure.

5

This approach throws an exception, which will be caught and reported by the Unit Test Framework. The error message displayed when the exception is caught will be most meaningful if the exception is derived from std::exception, or is a char* or std::string.

6

This approach uses tool BOOST_TEST with additional message argument, is similar to approach #1, except that similar to the approach #3 displays an alternative error message specified as a second argument.


PrevUpHomeNext