Master Test Suite

As defined in introduction section the master test suite is a root node of a test tree. Each test module built with the UTF always has the master test suite defined. The UTF maintain the master test suite instance internally. All other test units are registered as direct or indirect children of the master test suite.

namespace boost {
namespace unit_test {
class master_test_suite_t : public test_suite {
public:
   int argc;
   char** argv;
};

} // namespace unit_test

} // namespace boost

To access single instance of the master test suite use the following interface:

namespace boost {
namespace unit_test {
namespace framework {

master_test_suite_t& master_test_suite();

} // namespace framework
} // namespace unit_test
} // namespace boost

Command line arguments access interface

Master test suite implemented as an extension to the regular test suite, since it maintains references to the command line arguments passed to the test module. To access the command line arguments use

boost::unit_test::framework::master_test_suite().argc
boost::unit_test::framework::master_test_suite().argv

In below example references to the command line arguments are accessible either as an initialization function parameters or as members of the master test suite. Both references point to the same values. A test module that uses the alternative initialization function specification can only access command line arguments through the master test suite.

	Note
	This interface for runtime parameter access is temporary. It's planned to be updated once runtime parameters support is redesigned.

Returning to the free function example, let's modify initialization function to check for absence of any test module arguments.

Example 18. Command line access in initialization function

#include <boost/test/included/unit_test.hpp>
using namespace boost::unit_test;

//____________________________________________________________________________//

void free_test_function()
{
    BOOST_CHECK( true /* test assertion */ );
}

//____________________________________________________________________________//

test_suite*
init_unit_test_suite( int argc, char* argv[] ) 
{
    if( framework::master_test_suite().argc > 1 )
        return 0;

    framework::master_test_suite().
        add( BOOST_TEST_CASE( &free_test_function ) );

    return 0;
}

//____________________________________________________________________________//

Source code | Show output

> example 1
Test setup error: test tree is empty

Naming

The master test suite is created with default name "Master Test Suite". There are two methods two reset the name to a different value: using the macro BOOST_TEST_MODULE and from within the test module initialization function. Former is used for test modules that don't have the manually implemented initialization function. Following examples illustrate these methods.

Example 19. Naming master test suite using the macro BOOST_TEST_MODULE

If the macro BOOST_TEST_MODULE is defined, the test module initialization function is automatically generated and the macro value becomes the name of the master test suite. The name may include spaces.

#define BOOST_TEST_DYN_LINK
#define BOOST_TEST_MODULE my master test suite name
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( free_test_function )
{
    BOOST_CHECK( true /* test assertion */ );
}

//____________________________________________________________________________//

Source code | Show output

> example --log_level=test_suite
Running 1 test case...
Entering test suite "my master test suite name"
Entering test case "free_test_function"
Leaving test case "free_test_function"; testing time: 1ms
Leaving test suite "my master test suite name"

*** No errors detected

Example 20. Naming master test suite explicitly in the test module initialization function

Without the BOOST_TEST_MAIN and the BOOST_TEST_MODULE flags defined, the test module initialization function has to be manually implemented. The master test suite name can be reset at any point within this function.

#include <boost/test/included/unit_test.hpp>
using namespace boost::unit_test;

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( free_test_function )
{
    BOOST_CHECK( true /* test assertion */ );
}

//____________________________________________________________________________//

test_suite*
init_unit_test_suite( int argc, char* argv[] ) 
{
    framework::master_test_suite().p_name.value = "my master test suite name";

    return 0;
}

//____________________________________________________________________________//

Source code | Show output

> example --log_level=test_suite
Running 1 test case...
Entering test suite "my master test suite name"
Entering test case "free_test_function"
Leaving test case "free_test_function"; testing time: 1ms
Leaving test suite "my master test suite name"

*** No errors detected