[/
 / 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]