1[/ 2 / Copyright (c) 2019 Raffi Enficiaud 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:master_test_suite Master test suite] 9 10As defined in introduction section the master test suite is the *root* node of the test tree. Each test module built 11with the __UTF__ always has the (unique) master test suite defined. The __UTF__ maintain the master test suite instance 12internally. All other test units are registered as direct or indirect children of the master test suite. 13 14`` 15namespace boost { 16namespace unit_test { 17class master_test_suite_t : public test_suite 18{ 19 /// implementation details 20public: 21 int argc; 22 char** argv; 23}; 24 25} // namespace unit_test 26} // namespace boost 27`` 28 29 30To access single instance of the master test suite use the following interface: 31 32`` 33namespace boost { 34namespace unit_test { 35namespace framework { 36 37master_test_suite_t& master_test_suite(); 38 39} // namespace framework 40} // namespace unit_test 41} // namespace boost 42`` 43 44 45[h4 Command line arguments access interface] 46 47Master test suite implemented as an extension to the regular test suite, since it maintains references to the 48command line arguments passed to the test module. To access the command line arguments use 49 50`` 51boost::unit_test::framework::master_test_suite().argc 52boost::unit_test::framework::master_test_suite().argv 53`` 54 55In below example references to the command line arguments are accessible either as an initialization function 56parameters or as members of the master test suite. Both references point to the same values. A test module that 57uses the alternative initialization function specification can only access command line arguments through the 58master test suite. 59 60 61Returning to the free function example, let's modify initialization function to check for absence of any 62test module arguments. 63 64[bt_example example13..Command line access in initialization function..run] 65 66[#ref_BOOST_TEST_MODULE][h4 Naming the ['Master test suite]] 67 68The master test suite is created with default name ['Master Test Suite]. There are two methods two 69reset the name to a different value: using the macro __BOOST_TEST_MODULE__ 70and from within the test module initialization function. Former is used for test modules that don't have the 71manually implemented initialization function. Following examples illustrate these methods. 72 73[bt_example example14..Naming master test suite using the macro __BOOST_TEST_MODULE__..run] 74 75If the macro __BOOST_TEST_MODULE__ is defined, the test module initialization 76function is [*automatically generated] and the 77macro value becomes the name of the master test suite. The name may include spaces. 78 79[bt_example example15..Naming master test suite explicitly in the test module initialization function..run] 80 81Without the __BOOST_TEST_MAIN__ and the __BOOST_TEST_MODULE__ flags defined, the test module initialization 82function has to be manually implemented. The master test suite name can be reset at any point within this function. 83 84[endsect] [/ master test suite]