]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2003 Boost.Test contributors | |
3 | / | |
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) | |
6 | /] | |
7 | ||
8 | [section:test_module_init_overview Test module's initialization] | |
9 | ||
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__. | |
11 | ||
12 | [important | |
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. | |
15 | ] | |
16 | ||
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: | |
18 | ||
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. | |
24 | ||
25 | The default initialization function provided by the framework is defined with the following signature in the global namespace: | |
26 | ||
27 | ``` | |
28 | bool init_unit_test(); | |
29 | ``` | |
30 | ||
31 | Return value `true` indicates a successful initialization. Value `false` indicates initialization failure. | |
32 | ||
33 | For overriding the default definition: | |
34 | ||
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. | |
38 | ||
39 | [endsect] [/section:test_module_init_overview] |