Minimal testing facility

Boost.Test > Components > The minimal testing facility

# Boost Test Library: The minimal testing facility

## Introduction

Boost Test minimal testing facility provides the functionality provided before by the original version of Boost Test. The same as the Test Execution Monitor it causes the test program to run in a monitored environment. In addition it defines several simple test tools that behave similarly to ones defined in Test Tools. Minimal testing facility does not require linking with external components, so could be a component of choice for simple and quick testing needs. Unlike original Boost Test version macro BOOST_INCLUDE_MAIN is not used. The function main() is included unconditionally. One consequence is that minimal testing could not be used for multiunit testing. You will need to use other Boost Test components for that purpose.

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

Unlike the Test Execution Monitor that support complete set of test tools implemented in a Test Tools component, Minimal testing facility supply only 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. Follows the links to see more detailed descriptions. Old Boost Test tools names are supported either, but will be deprecated in a future.

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