Boost C++ Libraries

As defined in introduction section the master test suite is the root node of the test tree. Each test module built with the Unit Test Framework always has the (unique) master test suite defined. The Unit Test Framework 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
{
  /// implementation details
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.

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

Example: Command line access in initialization function

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

void free_test_function()
{
  BOOST_TEST( 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;
}

> example 1
Test setup error: test tree is empty

Naming the Master test suite

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: Naming master test suite using the macro BOOST_TEST_MODULE

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

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

> 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

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.

Example: Naming master test suite explicitly in the test module initialization function

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

BOOST_AUTO_TEST_CASE( free_test_function )
{
  BOOST_TEST( 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;
}

> 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

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.