123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171 |
- [/
- / 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:decorators Decorators]
- "Decorator" is a uniform mechanism for updating various attributes of the automatically registered test units. These
- attributes affect how the test tree is processed during the execution of the test module and include test unit
- description, floating-point tolerance and the number of expected failures among others. They are listed in detail in
- the following sections.
- [h4 Test case decorators]
- You can apply more than one decorator to the same test unit. A list of decorators is applied to a test case by specifying
- it as the second argument to macro __BOOST_AUTO_TEST_CASE__ or the third argument to macro __BOOST_FIXTURE_TEST_CASE__.
- [bt_example decorator_01..Test unit decorators..run]
- Each decorator in the list is preceded by an asterisk (`*`); the subsequent syntax resembles a function call and is
- specified in detail for each decorator. If there is more than one decorator in the list, they are concatenated with no
- additional separator; each asterisk indicates the beginning of a decorator. In the above example, test case `test_case1`
- has one associated ['decorator:] __decorator_label__. This means that when test units are filtered based on label, this
- test case will match to label `"trivial"`. Test case `test_case2` has three associated decorators: two of type `label`
- and one of type `description`.
- [/ ############################]
- [section Suite-level decorators]
- Similarly to test case it is possible to apply list of decorators to test suite. It is done by specifying a list of
- decorators as the second argument to the macro __BOOST_AUTO_TEST_SUITE__ or the third argument to the macro
- __BOOST_FIXTURE_TEST_SUITE__.
- [bt_example decorator_02..Test suite decorators..run]
- How a test suite decorator affects the processing of the test units inside of it varies with the decorator
- and is described for each decorator in subsequent sections. For instance, the function of the decorator in the above
- example is that when tests are filtered by label `"trivial"`, every test unit in suite `suite1` will be run.
- Similar to C++ namespace test suite can be closed and reopened within the same test file or span more than one file
- and you are allowed to apply different decorators in each point, where test suite is opened. If this is the case,
- the list of decorators applied to the test suite is the union of decorators specified in each place. Here an example.
- [bt_example decorator_03..Decorators on multiple suite openings..run]
- In the above example, the scope of test suite `suite1` is opened three times. This results in a test suite containing
- three test cases and associated with two __decorator_label__ decorators. Therefore running tests by label `"trivial"` as
- well as by label `"simple"` both result in executing all three test cases from the suite.
- [caution The above syntax for decorators requires that the compiler supports variadic macros (added in C++11). If you
- intend for your test program to also work for compilers without variadic macros, use explicit decorator syntax,
- described below.]
- [endsect]
- [/ ############################]
- [section Explicit decorator declaration]
- There is another way of associating a decorator set with test units. Macro __BOOST_TEST_DECORATOR__ indicates that its set
- of decorators is to be applied to the test unit or /test case sequence/ that immediately follows the declaration.
- [bt_example decorator_00..explicit decorator declaration..run]
- In the above example a decorator is applied to a [link boost_test.tests_organization.test_cases.test_case_generation
- data-driven test case]. Macro __BOOST_DATA_TEST_CASE__ cannot take the decorator set as one of its arguments, therefore
- the explicit decorator declaration is used. Macro __BOOST_DATA_TEST_CASE__ generates a sequence of 4 test cases. The
- decorator set is applied to each of them.
- Another use case for the explicit decorator declaration is when you intend for your test program to compile also on
- compilers without variadic macros. In this case it is recommended that you use the more verbose syntax. It is summarized
- in the following table:
- [table
- [[Test unit to register][Concise syntax][Universal syntax]]
- [[test case][```
- BOOST_AUTO_TEST_CASE(test_case, *decor1() *decor2())
- {
- // assertions
- }
- ```][```
- BOOST_TEST_DECORATOR(*decor1() *decor2())
- BOOST_AUTO_TEST_CASE(test_case)
- {
- // assertions
- }
- ```]]
- [[test case with fixture][```
- BOOST_FIXTURE_TEST_CASE(test_case, Fx, *decor1() *decor2())
- {
- // assertions
- }
- ```][```
- BOOST_TEST_DECORATOR(*decor1() *decor2())
- BOOST_FIXTURE_TEST_CASE(test_case, Fx)
- {
- // assertions
- }
- ```]]
- [[test suite][```
- BOOST_AUTO_TEST_SUITE(test_suite, *decor1() *decor2())
- // test units
- BOOST_AUTO_TEST_SUITE_END()
- ```][```
- BOOST_TEST_DECORATOR(*decor1() *decor2())
- BOOST_AUTO_TEST_SUITE(test_suite)
- // test units
- BOOST_AUTO_TEST_SUITE_END()
- ```]]
- [[test suite with fixture][```
- BOOST_FIXTURE_TEST_SUITE(test_suite, Fx, *decor1() *decor2())
- // test units
- BOOST_AUTO_TEST_SUITE_END()
- ```][```
- BOOST_TEST_DECORATOR(*decor1() *decor2())
- BOOST_FIXTURE_TEST_SUITE(test_suite, Fx)
- // test units
- BOOST_AUTO_TEST_SUITE_END()
- ```]]
- [[data-driven test case][```
- // not doable
- ```][```
- BOOST_TEST_DECORATOR(*decor1() *decor2())
- BOOST_DATA_TEST_CASE(test_case, data, var)
- {
- // assertions
- }
- ```]]
- [[test case template][```
- // not doable
- ```][```
- BOOST_TEST_DECORATOR(*decor1() *decor2())
- BOOST_AUTO_TEST_CASE_TEMPLATE(test_case, T, type_list)
- {
- // assertions
- }
- ```]]
- [[test case template with fixture][```
- // not doable
- ```][```
- BOOST_TEST_DECORATOR(*decor1() *decor2())
- BOOST_FIXTURE_TEST_CASE_TEMPLATE(test_case, T, type_list, Fx)
- {
- // assertions
- }
- ```]]
- ]
- Throughout the reminder of this documentation we use only the concise syntax.
- [endsect]
- [endsect] [/ section decorators]
- [/EOF]
|