ae01c8387c
- section about command line argument filtering for template test cases - many typos fixes - remove reference to bjam
52 lines
3.3 KiB
Plaintext
52 lines
3.3 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003 Boost.Test contributors
|
|
/
|
|
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
/]
|
|
|
|
[section:test_module_init_overview 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
|
|
[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_tree.master_test_suite 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 __UTF__ provides
|
|
superior tools for performing customization tasks:
|
|
|
|
* for automatic registration of test cases and test suites in the test tree, see section [link boost_test.tests_organization 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 __UTF__), use the interface of the
|
|
[link boost_test.tests_organization.test_tree.master_test_suite master test suite];
|
|
* 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;
|
|
* 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.
|
|
|
|
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:
|
|
|
|
* [link boost_test.adv_scenarios.single_header_customizations.init_func see here], for header-only usage variant,
|
|
* [link boost_test.adv_scenarios.static_lib_customizations.init_func see here], for static library usage variant,
|
|
* [link boost_test.adv_scenarios.shared_lib_customizations.init_func see here], for shared library usage variant.
|
|
|
|
[endsect] [/section:test_module_init_overview]
|