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:single_header_customizations Header-only variant customizations] 9 10[section:multiple_translation_units Header-only with multiple translation units] 11It is possible to use the header-only variant of the __UTF__ even if the test module has multiple translation 12units: 13 14* one translation unit should define __BOOST_TEST_MODULE__ and include `<boost/test/included/unit_test.hpp>` 15* all the other translation units should include `<boost/test/unit_test.hpp>` 16 17An example might be the following: 18 19* Translation unit 1, defines __BOOST_TEST_MODULE__ 20 ``` 21 #define BOOST_TEST_MODULE header-only multiunit test 22 #include <boost/test/included/unit_test.hpp> 23 24 BOOST_AUTO_TEST_CASE( test1 ) 25 { 26 int i = 1; 27 BOOST_CHECK( i*i == 1 ); 28 } 29 ``` 30 31* Translation unit 2, includes `<boost/test/unit_test.hpp>` instead of `<boost/test/included/unit_test.hpp>`: 32 ``` 33 #include <boost/test/unit_test.hpp> 34 35 BOOST_AUTO_TEST_CASE( test2 ) 36 { 37 int i = 1; 38 BOOST_CHECK( i*i == 1 ); 39 } 40 ``` 41 42[endsect] [/section:multiple_translation_units] 43 44[section:entry_point Customizing the module's entry point] 45 46In this usage variant and in the translation unit containing the definition of __BOOST_TEST_MODULE__, 47you need to define the macros __BOOST_TEST_NO_MAIN__ and 48__BOOST_TEST_ALTERNATIVE_INIT_API__ (their values are irrelevant) prior to including any of the framework's headers. 49Next, you have to define your custom entry point, and invoke the default [link 50boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually with the default [link 51boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test` as argument. 52 53[bt_example custom_main..using custom entry point..run-fail] 54 55In the above example, a custom entry point was selected because the test module, in addition to command line arguments, 56needs to obtain also the information about environment variables. 57 58[note The above example also illustrates that it makes sense to define both __BOOST_TEST_MODULE__ and 59__BOOST_TEST_NO_MAIN__. This way, no `main` is generated by the framework, but the name specified by __BOOST_TEST_MODULE__ 60is assigned to the [link boost_test.tests_organization.test_tree.master_test_suite Master test suite].] 61 62[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link 63boost_test.adv_scenarios.obsolete_init_func here].] 64 65 66[endsect] [/section:entry_point] 67 68[section:init_func Customizing the module's initialization function] 69 70In this usage variant, you do not define macro __BOOST_TEST_MODULE__ and instead provide the definition of function 71`init_unit_test`. This is going to be the custom initialization function. The default [link 72boost_test.adv_scenarios.test_module_runner_overview test runner] will use it to initialize the test module. 73 74 75[bt_example custom_init..using custom initialization function..run-fail] 76 77[note Because we overwrote the default initialization function, it does no longer assign any name to the [link 78boost_test.tests_organization.test_tree.master_test_suite master test suite]. Therefore the default name ("Master Test 79Suite") is used.] 80 81For reporting errors that may occur during the initialization, 82 83* either you return `false` (valid only for the new API only, see __BOOST_TEST_ALTERNATIVE_INIT_API__) 84* or you raise an exception such as `std::runtime_error` or [classref boost::unit_test::framework::setup_error] 85 86An error reported in this function aborts the execution of the test module. 87 88[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link 89boost_test.adv_scenarios.obsolete_init_func here].] 90 91[endsect] [/section:init_func] 92 93[endsect] [/section:single_header_customizations] 94