123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124 |
- [/
- / 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_suite Test suite]
- If you consider test cases as leaves on the test tree, the test suite can be considered as branch and the /master
- test suite/ as the /root/. Unlike real trees though, our tree in many cases consists only of leaves attached
- directly to the root. This is common for all test cases to reside directly in the master test suite. If you do
- want to construct a hierarchical test suite structure the __UTF__ provides both manual and automated
- test suite creation and registration facilities:
- # Test suite with automated registration
- # Manually registered test suite
- In addition the __UTF__ presents a notion of the
- [link boost_test.tests_organization.test_tree.master_test_suite Master test suite].
- The most important reason to learn about this component is that it provides an ability to access
- command line arguments supplied to a test module.
- [#ref_BOOST_AUTO_TEST_SUITE][h3 Automated registration]
- The solution the __UTF__ presents for automated test suite creation and registration is designed to facilitate
- multiple points of definition, arbitrary test suites depth and smooth integration with automated test case creation
- and registration. This facility should significantly simplify a test tree construction process in comparison with
- manual explicit registration case.
- The implementation is based on the order of file scope variables definitions within a single compilation unit.
- The semantic of this facility is very similar to the namespace feature of C++, including support for test suite
- extension. To start test suite use the macro __BOOST_AUTO_TEST_SUITE__. To end test suite use the macro
- __BOOST_AUTO_TEST_SUITE_END__. The same test suite can be restarted multiple times inside the same test file or in a
- different test files. In a result all test units will be part of the same test suite in a constructed test tree.
- ``
- BOOST_AUTO_TEST_SUITE(test_suite_name);
- BOOST_AUTO_TEST_SUITE_END();
- ``
- Test units defined in between test suite start and end declarations become members of the test suite. A test
- unit always becomes the member of the closest test suite declared. Test units declared at a test file scope
- become members of the master test suite. There is no limit on depth of test suite inclusion.
- This example creates a test tree that matches exactly the one created in the manual test suite registration
- example.
- [bt_example example12..Test suites with automated registration..run-fail]
- As you can see test tree construction in this example is more straightforward and automated.
- In the example below, the test suite `test_suite` consists of two parts. Their definition is remote and is separated by another
- test case. In fact these parts may even reside in different test files. The resulting test tree remains the same. As
- you can see from the output both `test_case1` and `test_case2` reside in the same test suite `test_suite`.
- [bt_example example53..Test suite extension using automated registration facility..run-fail]
- [h3 Test suites with manual registration]
- To create a test suite manually you need to
- # create an instance of [classref boost::unit_test::test_suite] class,
- # register it in test tree, and
- # populate it with test cases (or lower level test suites).
- [#ref_test_case_registration][h4 Test unit registration interface]
- The __UTF__ models the notion of test case container - test suite - using class [classref boost::unit_test::test_suite]. For
- complete class interface reference check advanced section of this documentation. Here you should only be
- interested in a single test unit registration interface:
- ``
- void test_suite::add( test_unit* tc, counter_t expected_failures = 0, int timeout = 0 );
- ``
- The first parameter is a pointer to a newly created test unit. The second optional parameter -
- expected_failures - defines the number of test assertions that are expected to fail within the test unit. By
- default no errors are expected.
- [caution
- Be careful when supplying a number of expected failures for test suites. By default the __UTF__ calculates the
- number of expected failures in test suite as the sum of appropriate values in all test units that constitute
- it. And it rarely makes sense to change this.
- ]
- The third optional parameter - `timeout` - defines the timeout value for the test unit. As of now the __UTF__
- isn't able to set a timeout for the test suite execution, so this parameter makes sense only for test case
- registration. By default no timeout is set. See the method
- [memberref boost::unit_test::test_suite::add] for more details about the timeout value.
- To register group of test units in one function call, the [classref boost::unit_test::test_suite `test_suite`] class provides another
- [memberref boost::unit_test::test_suite::add `add`] interface covered in the advanced section of this documentation.
- [#ref_BOOST_TEST_SUITE][h4 Test suite instance construction]
- To create a test suite instance manually, employ the macro __BOOST_TEST_SUITE__. It hides all implementation
- details and you only required to specify the test suite name:
- ``
- BOOST_TEST_SUITE(test_suite_name);
- ``
- __BOOST_TEST_SUITE__ creates an instance of the class `boost::unit_test::test_suite` and returns a pointer to the
- constructed instance. Alternatively you can create an instance of class `boost::unit_test::test_suite` yourself.
- [caution `boost::unit_test::test_suite` instances have to be allocated on the heap and the compiler won't allow you
- to create one on the stack.
- ]
- Newly created test suite has to be registered in a parent one using the `add` interface. Both test suite creation and
- registration is performed in the test module initialization function.
- The example below creates a test tree, which can be represented by the following hierarchy:
- [$images/class-hier.jpg]
- [bt_example example11..Manually registered test suites..run]
- [endsect] [/ test suite]
- [/EOF]
|