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