Part III. Boost Test Library: The minimal testing facility

Introduction

Boost.Test minimal testing facility provides the functionality previously implemented by the original version of Boost.Test. As the name suggest, it provides only minimal basic facilities for test creation. It have no configuration parameters (either command line arguments or environment variables) and it supplies a limited set of testing tools which behaves similarly to ones defined amount the Unit Test Framework Testing tools. The minimal testing facility supplies its own function main() (so can not be used for multi unit testing) and will execute the test program in a monitored environment.

As it follows from the name this component provides only minimal set of the testing capabilities and as a general rule the Unit Test Framework should be preferred. In a majority of the cases it provides you with much wider set of testing tools (and other goods), while still being as easy to set up.

Usage

The only change (other then including boost/test/minimal.hpp) you need to make, to integrate your test module with minimal testing facility is the signature of your function main(). It should look like this:

int test_main( int argc, char* argv[] )
{
  ...
}

Once you apply the change test automatically starts running in monitored environment. Also you can start using testing tools provided by the minimal testing facility and get uniform errors reporting.

Example

Following example illustrates different approaches you can employ to detect and report errors using different testing tools

Example 4. Minimal testing facility application

#include <boost/test/minimal.hpp>

//____________________________________________________________________________//

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

//____________________________________________________________________________//

int test_main( int, char *[] )             // note the name!
{
    // six ways to detect and report the same error:
    BOOST_CHECK( add( 2,2 ) == 4 );        // #1 continues on error
    BOOST_REQUIRE( add( 2,2 ) == 4 );      // #2 throws on error
    if( add( 2,2 ) != 4 )
        BOOST_ERROR( "Ouch..." );          // #3 continues on error
    if( add( 2,2 ) != 4 )
        BOOST_FAIL( "Ouch..." );           // #4 throws on error
    if( add( 2,2 ) != 4 ) throw "Oops..."; // #5 throws on error

    return add( 2, 2 ) == 4 ? 0 : 1;       // #6 returns error code
}

//____________________________________________________________________________//

Source code | Show annotations | Show output

(1)	This approach uses the BOOST_CHECK tool, which displays an error message on std::cout that includes the expression that failed, 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 minimal testing facility.
(2)	This approach using the BOOST_REQUIRE tool, is similar to #1, except that after displaying the error, an exception is thrown, to be caught by the minimal testing facility. This approach is suitable when writing an explicit test program, and the error would be so severe as to make further testing impractical. BOOST_REQUIRE differs from the C++ Standard Library's assert() macro in that it is always generated, and channels error detection into the uniform reporting procedure.
(3)	This approach is similar to #1, except that the error detection is coded separately. This is most useful when the specific condition being tested is not indicative of the reason for failure.
(4)	This approach is similar to #2, except that the error detection is coded separately. This is most useful when the specific condition being tested is not indicative of the reason for failure.
(5)	This approach throws an exception, which will be caught and reported by the minimal testing facility. This approach is suitable for both production and test code, in libraries or not. 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 the BOOST_CHECK_MESSAGE tool, is similar to approach #1, except that similar to the approach #3 displays an alternative error message specified as a second argument.

**** no errors detected

Provided testing tools

The minimal testing facility supplies following four tools:

BOOST_CHECK(predicate)
BOOST_REQUIRE(predicate)
BOOST_ERROR(message)
BOOST_FAIL(message)

Their behavior is modeled after the similarly named tools implemented by the Unit Test Framework.

Implementation

The minimal testing facility is implemented inline in one header boost/test/minimal.hpp. There are no special compilation instructions for this component.

There is a single unit test program that validates minimal testing facility functionality: minimal_test