Test module initialization or ready, set

There are two tasks that you may need to perform before actual testing can start:

The test tree needs to be built (unless you are using automated test units registration).
Custom test module initialization needs to be performed. This includes initialization of the code under test and custom tune-up of the UTF parameters (for example the test log or the test results report output streams redirection).

The function dedicated for this purpose is called the test module initialization function. Alternatively you can employ global fixtures, covered in details, including differences in two approaches, in the section called “Fixtures”.

The UTF requires you to implement the test module initialization function. The test runner supplied with the static library or single-header variants of the UTF requires the specific function specification. The test runner supplied with the dynamic library variant of the UTF requires the specific initialization function signature only.

For many test modules you don't need to do any custom initialization and test tree construction is automated. In this case you don't really need the initialization function and the UTF provides a way to automatically generate an empty one for you.

Original design of the UTF supported the manual test tree construction only. Later versions introduced the automated registration of test units. In later versions of the UTF the original initialization function specification became inconvenient and unnecessary unsafe. So the alternative initialization function specification was introduced. This change is not backward compatible. The test runners supplied with the static library and single-header variants of the UTF by default still require original initialization function specification, but support compilation flags that switch to the alternative one. The test runner supplied with dynamic library variant of the UTF requires new specification and doesn't support original one. The plan is to deprecate the original initialization function specification in one of the future releases and ultimately to stop supporting it.

The initialization function invocation is monitored by the UTF the same way as all the test cases. An unexpected exception or system error detected during initialization function invocation is treated as initialization error and is reported as such.

Original initialization function signature and name

The original design of the UTF initialization requires you to implement the function with the following specification:

boost::unit_test::test_suite* init_unit_test_suite( int argc, char* argv[] );

In original design of the UTF this function was intended to initialize and return a master test suite. The null value was considered an initialization error. The current design of the UTF maintains master test suite instance internally and does not treat the null result value as an initialization error. In fact it's recommended to return null value always and register test units in the master test suite using the regular test suite add interface. The only way to indicate an initialization error is to throw the boost::unit_test::framework::setup_error exception.

The initialization function parameters argc, argv provide the command line arguments specified during test module invocation. It's guarantied that any framework-specific command line arguments are excluded. To be consisted with the alternative initialization function specification it's recommended though to access the command line arguments using the master test suite interface.

Alternative initialization function signature and name

The alternative design of the UTF initialization requires you to implement a function with the following specification:

bool init_unit_test();

The result value of this function indicates whether or not initialization was successful. To register test units in a master test suite use the test suite add interface. To access command line arguments use the master test suite interface. It's guarantied that any framework-specific command line arguments are excluded.

Initialization function signature access

The test runner interface needs to refer to the initialization function signature. The UTF provides the typedef that resolves to proper signature in all configurations:

namespace boost {
namespace unit_test {
#ifdef BOOST_TEST_ALTERNATIVE_INIT_API
typedef bool        (*init_unit_test_func)();
#else
typedef test_suite* (*init_unit_test_func)( int, char* [] );
#endif
}
}

Automated generation of the test module initialization function

To automatically generate an empty test module initialization function you need to define BOOST_TEST_MAIN before including the boost/test/unit_test.hpp header. The value of this define is ignored. Alternatively you can define the macro BOOST_TEST_MODULE to be equal to any string (not necessarily in quotes). This macro causes the same result as BOOST_TEST_MAIN, and in addition the macro value becomes the name of the master test suite.

	Important
	For a test module consisting of multiple source files you have to define these flags in a single test file only. Otherwise you end up with multiple instances of the initialization function.