Test module's initialization

In order for a unit test module to successfully link and execute, it has to have access to the test module's initialization function. the module's initialization function is called only once during the execution of the program, just before the test module runner is run. By default, the Unit Test Framework provides a default definition of initialization function. The only thing you have to do is to instruct the framework in which translation unit (cpp file) it needs to provide the definition. You do it by defining macro BOOST_TEST_MODULE in the designated file. The default implementation assigns the name to the test module as well as the master test suite. The name to be assigned is specified by the value of the macro BOOST_TEST_MODULE.

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

There is practically no need to ever alter the default behavior of the test module's initialization function. The Unit Test Framework provides superior tools for performing customization tasks:

for automatic registration of test cases and test suites in the test tree, see section Tests organization;
in order to assign the custom name to the master test suite define macro BOOST_TEST_MODULE to desired value;
in order to access the command-line parameters (except the ones consumed by the Unit Test Framework), use the interface of the master test suite;
in order to perform a global initialization of the state required by the test cases, global fixtures offer a superior alternative: you can specify global set-up and tear-down in one place, allow access to the global data from every test case, and guarantee that clean-up and tear-down is repeated each time the tests are re-run during the execution of the program;
if the need for custom module initialization is only driven by legacy code (written against old versions of the Unit Test Framework), it is recommended to update your program's code.

The default initialization function provided by the framework is defined with the following signature in the global namespace:

bool init_unit_test();

Return value true indicates a successful initialization. Value false indicates initialization failure.

For overriding the default definition:

see here, for header-only usage variant,
see here, for static library usage variant,
see here, for shared library usage variant.

Boost C++ Libraries

Test module's initialization