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_suite Test suite] 9If you consider test cases as leaves on the test tree, the test suite can be considered as branch and the /master 10test suite/ as the /root/. Unlike real trees though, our tree in many cases consists only of leaves attached 11directly to the root. This is common for all test cases to reside directly in the master test suite. If you do 12want to construct a hierarchical test suite structure the __UTF__ provides both manual and automated 13test suite creation and registration facilities: 14 15# Test suite with automated registration 16# Manually registered test suite 17 18In addition the __UTF__ presents a notion of the 19[link boost_test.tests_organization.test_tree.master_test_suite Master test suite]. 20The most important reason to learn about this component is that it provides an ability to access 21command line arguments supplied to a test module. 22 23[#ref_BOOST_AUTO_TEST_SUITE][h3 Automated registration] 24The solution the __UTF__ presents for automated test suite creation and registration is designed to facilitate 25multiple points of definition, arbitrary test suites depth and smooth integration with automated test case creation 26and registration. This facility should significantly simplify a test tree construction process in comparison with 27manual explicit registration case. 28 29 30The implementation is based on the order of file scope variables definitions within a single compilation unit. 31The semantic of this facility is very similar to the namespace feature of C++, including support for test suite 32extension. To start test suite use the macro __BOOST_AUTO_TEST_SUITE__. To end test suite use the macro 33__BOOST_AUTO_TEST_SUITE_END__. The same test suite can be restarted multiple times inside the same test file or in a 34different test files. In a result all test units will be part of the same test suite in a constructed test tree. 35 36`` 37 BOOST_AUTO_TEST_SUITE(test_suite_name); 38 BOOST_AUTO_TEST_SUITE_END(); 39`` 40 41Test units defined in between test suite start and end declarations become members of the test suite. A test 42unit always becomes the member of the closest test suite declared. Test units declared at a test file scope 43become members of the master test suite. There is no limit on depth of test suite inclusion. 44 45 46This example creates a test tree that matches exactly the one created in the manual test suite registration 47example. 48 49[bt_example example12..Test suites with automated registration..run-fail] 50 51As you can see test tree construction in this example is more straightforward and automated. 52 53In the example below, the test suite `test_suite` consists of two parts. Their definition is remote and is separated by another 54test case. In fact these parts may even reside in different test files. The resulting test tree remains the same. As 55you can see from the output both `test_case1` and `test_case2` reside in the same test suite `test_suite`. 56 57[bt_example example53..Test suite extension using automated registration facility..run-fail] 58 59[h3 Test suites with manual registration] 60To create a test suite manually you need to 61 62# create an instance of [classref boost::unit_test::test_suite] class, 63# register it in test tree, and 64# populate it with test cases (or lower level test suites). 65 66[#ref_test_case_registration][h4 Test unit registration interface] 67 68 69The __UTF__ models the notion of test case container - test suite - using class [classref boost::unit_test::test_suite]. For 70complete class interface reference check advanced section of this documentation. Here you should only be 71interested in a single test unit registration interface: 72 73`` 74 void test_suite::add( test_unit* tc, counter_t expected_failures = 0, int timeout = 0 ); 75`` 76 77The first parameter is a pointer to a newly created test unit. The second optional parameter - 78expected_failures - defines the number of test assertions that are expected to fail within the test unit. By 79default no errors are expected. 80 81[caution 82 Be careful when supplying a number of expected failures for test suites. By default the __UTF__ calculates the 83 number of expected failures in test suite as the sum of appropriate values in all test units that constitute 84 it. And it rarely makes sense to change this. 85] 86 87The third optional parameter - `timeout` - defines the timeout value for the test unit. As of now the __UTF__ 88isn't able to set a timeout for the test suite execution, so this parameter makes sense only for test case 89registration. By default no timeout is set. See the method 90[memberref boost::unit_test::test_suite::add] for more details about the timeout value. 91 92To register group of test units in one function call, the [classref boost::unit_test::test_suite `test_suite`] class provides another 93[memberref boost::unit_test::test_suite::add `add`] interface covered in the advanced section of this documentation. 94 95 96[#ref_BOOST_TEST_SUITE][h4 Test suite instance construction] 97 98 99To create a test suite instance manually, employ the macro __BOOST_TEST_SUITE__. It hides all implementation 100details and you only required to specify the test suite name: 101 102`` 103 BOOST_TEST_SUITE(test_suite_name); 104`` 105 106__BOOST_TEST_SUITE__ creates an instance of the class `boost::unit_test::test_suite` and returns a pointer to the 107constructed instance. Alternatively you can create an instance of class `boost::unit_test::test_suite` yourself. 108 109[caution `boost::unit_test::test_suite` instances have to be allocated on the heap and the compiler won't allow you 110 to create one on the stack. 111] 112 113Newly created test suite has to be registered in a parent one using the `add` interface. Both test suite creation and 114registration is performed in the test module initialization function. 115 116The example below creates a test tree, which can be represented by the following hierarchy: 117 118[$images/class-hier.jpg] 119 120[bt_example example11..Manually registered test suites..run] 121 122[endsect] [/ test suite] 123 124[/EOF] 125