ae01c8387c
- section about command line argument filtering for template test cases - many typos fixes - remove reference to bjam
94 lines
3.8 KiB
Plaintext
94 lines
3.8 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:single_header_customizations Header-only variant customizations]
|
|
|
|
[section:multiple_translation_units Header-only with multiple translation units]
|
|
It is possible to use the header-only variant of the __UTF__ even if the test module has multiple translation
|
|
units:
|
|
|
|
* one translation unit should define __BOOST_TEST_MODULE__ and include `<boost/test/included/unit_test.hpp>`
|
|
* all the other translation units should include `<boost/test/unit_test.hpp>`
|
|
|
|
An example might be the following:
|
|
|
|
* Translation unit 1, defines __BOOST_TEST_MODULE__
|
|
```
|
|
#define BOOST_TEST_MODULE header-only multiunit test
|
|
#include <boost/test/included/unit_test.hpp>
|
|
|
|
BOOST_AUTO_TEST_CASE( test1 )
|
|
{
|
|
int i = 1;
|
|
BOOST_CHECK( i*i == 1 );
|
|
}
|
|
```
|
|
|
|
* Translation unit 2, includes `<boost/test/unit_test.hpp>` instead of `<boost/test/included/unit_test.hpp>`:
|
|
```
|
|
#include <boost/test/unit_test.hpp>
|
|
|
|
BOOST_AUTO_TEST_CASE( test2 )
|
|
{
|
|
int i = 1;
|
|
BOOST_CHECK( i*i == 1 );
|
|
}
|
|
```
|
|
|
|
[endsect] [/section:multiple_translation_units]
|
|
|
|
[section:entry_point Customizing the module's entry point]
|
|
|
|
In this usage variant and in the translation unit containing the definition of __BOOST_TEST_MODULE__,
|
|
you need to define the macros __BOOST_TEST_NO_MAIN__ and
|
|
__BOOST_TEST_ALTERNATIVE_INIT_API__ (their values are irrelevant) prior to including any of the framework's headers.
|
|
Next, you have to define your custom entry point, and invoke the default [link
|
|
boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually with the default [link
|
|
boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test` as argument.
|
|
|
|
[bt_example custom_main..using custom entry point..run-fail]
|
|
|
|
In the above example, a custom entry point was selected because the test module, in addition to command line arguments,
|
|
needs to obtain also the information about environment variables.
|
|
|
|
[note The above example also illustrates that it makes sense to define both __BOOST_TEST_MODULE__ and
|
|
__BOOST_TEST_NO_MAIN__. This way, no `main` is generated by the framework, but the name specified by __BOOST_TEST_MODULE__
|
|
is assigned to the [link boost_test.tests_organization.test_tree.master_test_suite Master test suite].]
|
|
|
|
[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link
|
|
boost_test.adv_scenarios.obsolete_init_func here].]
|
|
|
|
|
|
[endsect] [/section:entry_point]
|
|
|
|
[section:init_func Customizing the module's initialization function]
|
|
|
|
In this usage variant, you do not define macro __BOOST_TEST_MODULE__ and instead provide the definition of function
|
|
`init_unit_test`. This is going to be the custom initialization function. The default [link
|
|
boost_test.adv_scenarios.test_module_runner_overview test runner] will use it to initialize the test module.
|
|
|
|
|
|
[bt_example custom_init..using custom initialization function..run-fail]
|
|
|
|
[note Because we overwrote the default initialization function, it does no longer assign any name to the [link
|
|
boost_test.tests_organization.test_tree.master_test_suite master test suite]. Therefore the default name ("Master Test
|
|
Suite") is used.]
|
|
|
|
For reporting errors that may occur during the initialization,
|
|
|
|
* either you return `false` (valid only for the new API only, see __BOOST_TEST_ALTERNATIVE_INIT_API__)
|
|
* or you raise an exception such as `std::runtime_error` or [classref boost::unit_test::framework::setup_error]
|
|
|
|
An error reported in this function aborts the execution of the test module.
|
|
|
|
[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link
|
|
boost_test.adv_scenarios.obsolete_init_func here].]
|
|
|
|
[endsect] [/section:init_func]
|
|
|
|
[endsect] [/section:single_header_customizations]
|