Boost.Test > Components > The minimal testing facility
Boost Test logo

Boost Test Library: The minimal testing facility

Introduction
Usage
Example
Provided Test Tools
Implementation
Tests

Introduction

Boost.Test minimal testing facility provides the functionality provided previosly by the original version of Boost.Test. As the name sujest it provides only minimal basic facilities for test creation. It does not have any configuration parameters (either command line arguments or environment variables ) and it supply very limited set of test tools that behave similarly to ones defined in the Test Tools. Minimal testing facility supply it's own fhe function main() (so could not be used for multiunit testing) and execute the test program in a monitored environment.

Usage

The only change (other then include 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[] )

After that you will automatically start running your tests in monitored environment. Also you can start using test tools provided by minimal testing facility and get uniform errors reporting.

Example

#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
}

Approach #1 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 an error count. At program termination, the error count will be displayed automatically by the Minimal testing facility.

Approach #2 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 a 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 Minimal testing facility reporting procedure.

Approaches #3 and #4 are similar to #1 and #2 respectively, 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.

Approach #5 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.

Approach #6 uses a return value to inform the caller of the error. This approach is particularly suitable for integrating existing test code with the test tools library. Although it works fine with the Minimal testing facility libraries, and is very useful for running existing code under them, most C++ experts prefer using exceptions for error reporting.

Provided Test Tools

Minimal testing facility supply following four tools:

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

Their behavior is similar to ones defined in Test Tools component. Follow the links to see more detailed descriptions.

Implementation

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

Tests

minimal_test