libs/test/doc/test_organization/decorators.qbk
[/ / 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]