libs/test/doc/test_organization/decorators.qbk

   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:decorators Decorators]
   9
  10 "Decorator" is a uniform mechanism for updating various attributes of the automatically registered test units. These
  11 attributes affect how the test tree is processed during the execution of the test module and include test unit
  12 description, floating-point tolerance and the number of expected failures among others. They are listed in detail in
  13 the following sections.
  14
  15 [h4 Test case decorators]
  16
  17 You can apply more than one decorator to the same test unit. A list of decorators is applied to a test case by specifying
  18 it as the second argument to macro __BOOST_AUTO_TEST_CASE__ or the third argument to macro __BOOST_FIXTURE_TEST_CASE__.
  19
  20 [bt_example decorator_01..Test unit decorators..run]
  21
  22 Each decorator in the list is preceded by an asterisk (`*`); the subsequent syntax resembles a function call and is
  23 specified in detail for each decorator. If there is more than one decorator in the list, they are concatenated with no
  24 additional separator; each asterisk indicates the beginning of a decorator. In the above example, test case `test_case1`
  25 has one associated ['decorator:] __decorator_label__. This means that when test units are filtered based on label, this
  26 test case will match to label `"trivial"`. Test case `test_case2` has three associated decorators: two of type `label`
  27 and one of type `description`.
  28
  29 [/ ############################]
  30 [section Suite-level decorators]
  31
  32 Similarly to test case it is possible to apply list of decorators to test suite. It is done by specifying a list of
  33 decorators as the second argument to the macro __BOOST_AUTO_TEST_SUITE__ or the third argument to the macro
  34 __BOOST_FIXTURE_TEST_SUITE__.
  35
  36 [bt_example decorator_02..Test suite decorators..run]
  37
  38 How a test suite decorator affects the processing of the test units inside of it varies with the decorator
  39 and is described for each decorator in subsequent sections. For instance, the function of the decorator in the above
  40 example is that when tests are filtered by label `"trivial"`, every test unit in suite `suite1` will be run.
  41
  42 Similar to C++ namespace test suite can be closed and reopened within the same test file or span more than one file
  43 and you are allowed to apply different decorators in each point, where test suite is opened. If this is the case,
  44 the list of decorators applied to the test suite is the union of decorators specified in each place. Here an example.
  45
  46 [bt_example decorator_03..Decorators on multiple suite openings..run]
  47
  48 In the above example, the scope of test suite `suite1` is opened three times. This results in a test suite containing
  49 three test cases and associated with two __decorator_label__ decorators. Therefore running tests by label `"trivial"` as
  50 well as by label `"simple"` both result in executing all three test cases from the suite.
  51
  52 [caution The above syntax for decorators requires that the compiler supports variadic macros (added in C++11). If you
  53 intend for your test program to also work for compilers without variadic macros, use explicit decorator syntax,
  54 described below.]
  55
  56 [endsect]
  57
  58 [/ ############################]
  59 [section Explicit decorator declaration]
  60
  61 There is another way of associating a decorator set with test units. Macro __BOOST_TEST_DECORATOR__ indicates that its set
  62 of decorators is to be applied to the test unit or /test case sequence/ that immediately follows the declaration.
  63
  64 [bt_example decorator_00..explicit decorator declaration..run]
  65
  66 In the above example a decorator is applied to a [link boost_test.tests_organization.test_cases.test_case_generation
  67 data-driven test case]. Macro __BOOST_DATA_TEST_CASE__ cannot take the decorator set as one of its arguments, therefore
  68 the explicit decorator declaration is used. Macro __BOOST_DATA_TEST_CASE__ generates a sequence of 4 test cases. The
  69 decorator set is applied to each of them.
  70
  71 Another use case for the explicit decorator declaration is when you intend for your test program to compile also on
  72 compilers without variadic macros. In this case it is recommended that you use the more verbose syntax. It is summarized
  73 in the following table:
  74
  75 [table
  76   [[Test unit to register][Concise syntax][Universal syntax]]
  77   [[test case][```
  78 BOOST_AUTO_TEST_CASE(test_case, *decor1() *decor2())
  79 {
  80   // assertions
  81 }
  82   ```][```
  83 BOOST_TEST_DECORATOR(*decor1() *decor2())
  84 BOOST_AUTO_TEST_CASE(test_case)
  85 {
  86   // assertions
  87 }
  88   ```]]
  89
  90   [[test case with fixture][```
  91 BOOST_FIXTURE_TEST_CASE(test_case, Fx, *decor1() *decor2())
  92 {
  93   // assertions
  94 }
  95   ```][```
  96 BOOST_TEST_DECORATOR(*decor1() *decor2())
  97 BOOST_FIXTURE_TEST_CASE(test_case, Fx)
  98 {
  99   // assertions
 100 }
 101   ```]]
 102
 103   [[test suite][```
 104 BOOST_AUTO_TEST_SUITE(test_suite, *decor1() *decor2())
 105
 106   // test units
 107
 108 BOOST_AUTO_TEST_SUITE_END()
 109   ```][```
 110 BOOST_TEST_DECORATOR(*decor1() *decor2())
 111 BOOST_AUTO_TEST_SUITE(test_suite)
 112
 113   // test units
 114
 115 BOOST_AUTO_TEST_SUITE_END()
 116   ```]]
 117
 118 [[test suite with fixture][```
 119 BOOST_FIXTURE_TEST_SUITE(test_suite, Fx, *decor1() *decor2())
 120
 121   // test units
 122
 123 BOOST_AUTO_TEST_SUITE_END()
 124   ```][```
 125 BOOST_TEST_DECORATOR(*decor1() *decor2())
 126 BOOST_FIXTURE_TEST_SUITE(test_suite, Fx)
 127
 128   // test units
 129
 130 BOOST_AUTO_TEST_SUITE_END()
 131   ```]]
 132
 133 [[data-driven test case][```
 134 // not doable
 135   ```][```
 136 BOOST_TEST_DECORATOR(*decor1() *decor2())
 137 BOOST_DATA_TEST_CASE(test_case, data, var)
 138 {
 139   // assertions
 140 }
 141   ```]]
 142
 143 [[test case template][```
 144 // not doable
 145   ```][```
 146 BOOST_TEST_DECORATOR(*decor1() *decor2())
 147 BOOST_AUTO_TEST_CASE_TEMPLATE(test_case, T, type_list)
 148 {
 149   // assertions
 150 }
 151   ```]]
 152
 153 [[test case template with fixture][```
 154 // not doable
 155   ```][```
 156 BOOST_TEST_DECORATOR(*decor1() *decor2())
 157 BOOST_FIXTURE_TEST_CASE_TEMPLATE(test_case, T, type_list, Fx)
 158 {
 159   // assertions
 160 }
 161   ```]]
 162 ]
 163
 164 Throughout the reminder of this documentation we use only the concise syntax.
 165
 166 [endsect]
 167
 168
 169 [endsect] [/ section decorators]
 170
 171 [/EOF]