[boost] [test] self-registration facilities

From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2005-12-14 13:05:55

Hi,

This message should serve as a temporary source of information regarding 
self registration faculties of Boost.Test. I will include the complete docs 
in next update.

Here is the list of all available macros:

----------------------------------------------------
BOOST_AUTO_TEST_CASE( test_name )
----------------------------------------------------

Simple free function like test case. Use like this:

BOOST_AUTO_TEST_CASE( test )
{
   // test body
}

----------------------------------------------------
BOOST_FIXTURE_TEST_CASE( test_name, F )
----------------------------------------------------

Simple free function like test case. Employs struct F as a fixture. Use like 
this:

struct F {
    F() { /* setup here */}
    ~F() { /* teardown here */}

    int i;
};

BOOST_FIXTURE_TEST_CASE( test, F )
{
   // test body
   // i could be referenced here
}

----------------------------------------------------
BOOST_AUTO_TEST_CASE_EXPECTED_FAILURES( test_name, n )
----------------------------------------------------

Use this to specify number of expected failures in test case. Use like this

BOOST_AUTO_TEST_CASE_EXPECTED_FAILURES( test1, 1 )

BOOST_AUTO_TEST_CASE( test1 )
{
    BOOST_CHECK( 2 == 1 );
}

----------------------------------------------------
BOOST_AUTO_TEST_CASE_TEMPLATE( test_name, type_name, type_list )
----------------------------------------------------

Free function test case template for generating a test case for each type in 
type list. Use like this:

typedef boost::mpl::list<char,int,float,double> test_types;

BOOST_AUTO_TEST_CASE_TEMPLATE( test, T, test_types )
{
    // Body here; T is type under test
}

----------------------------------------------------
BOOST_AUTO_TEST_SUITE( suite_name )
BOOST_AUTO_TEST_SUITE_END()
----------------------------------------------------

By default all test cases are registered in master test suite. There macros 
are used for constructing hierarchical test tree like this:

BOOST_AUTO_TEST_SUITE( suite1 );

// this test case belongs to suite1 test suite
BOOST_AUTO_TEST_CASE( test1 )
{
  // body here
}

BOOST_AUTO_TEST_SUITE_END();

----------------------------------------------------
BOOST_FIXTURE_TEST_SUITE( suite_name, F )
----------------------------------------------------

Similar to the BOOST_AUTO_TEST_SUITE, but force all the test cases within 
this test suite to use struct F as a fixture.

BOOST_FIXTURE_TEST_SUITE( s, F )

// this test case use F as a fixture
BOOST_AUTO_TEST_CASE( test1 )
{
    // body here
}

BOOST_AUTO_TEST_SUITE_END()

----------------------------------------------------
BOOST_GLOBAL_FIXTURE( F )
----------------------------------------------------

Facilitate an ability to do global setup/teardown. Setup is invoked before 
any testing is started. Teardown - when all is done. Use like this:

struct MyConfig {
    MyConfig() { std::cout << "global setup\n"; }
    ~MyConfig() { std::cout << "global teardown\n"; }
};

BOOST_GLOBAL_FIXTURE( MyConfig )

You may have as many global fixtures as you want.

To automatically setup init function define BOOST_TEST_MAIN in you main test 
module (in only one module in multi module test program)

Alternatively you could define it explicitly. For example you could use it 
to rename a master test suite.

Regards,

Gennadiy