2 / Copyright (c) 2003 Boost.Test contributors
4 / Distributed under the Boost Software License, Version 1.0. (See accompanying
5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8 [section:test_module_init_overview Test module's initialization]
10 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 [link boost_test.adv_scenarios.test_module_runner_overview ['test module runner]] is run. By default, the __UTF__ 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 [link ref_test_module test module] as well as the [link boost_test.tests_organization.test_suite.master_test_suite master test suite]. The name to be assigned is specified by the value of the macro __BOOST_TEST_MODULE__.
13 For a test module consisting of multiple source files you have to define __BOOST_TEST_MODULE__ in a single test file only.
14 Otherwise you end up with multiple instances of the initialization function.
17 There is practically no need to ever alter the default behavior of the test module's initialization function. The __UTF__ provides superior tools for performing customization tasks:
19 * for automatic registration of test cases and test suites in the test tree, see section [link boost_test.tests_organization Tests organization];
20 * in order to assign the custom name to the master test suite define macro __BOOST_TEST_MODULE__ to desired value;
21 * in order to access the command-line parameters (except the ones consumed by the __UTF__), use the interface of the [link boost_test.tests_organization.test_suite.master_test_suite master test suite];
22 * in order to perform a global initialization of the state required by the test cases, [link boost_test.tests_organization.fixtures.global 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;
23 * if the need for custom module initialization is only driven by legacy code (written against old versions of the __UTF__), it is recommended to update your program's code.
25 The default initialization function provided by the framework is defined with the following signature in the global namespace:
28 bool init_unit_test();
31 Return value `true` indicates a successful initialization. Value `false` indicates initialization failure.
33 For overriding the default definition:
35 * [link boost_test.adv_scenarios.single_header_customizations.init_func see here], for single header usage variant,
36 * [link boost_test.adv_scenarios.static_lib_customizations.init_func see here], for static library usage variant,
37 * [link boost_test.adv_scenarios.shared_lib_customizations.init_func see here], for shared library usage variant.
39 [endsect] [/section:test_module_init_overview]