Boost C++ Libraries

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.

Example: Test suite decorators

#define BOOST_TEST_MODULE decorator_02
#include <boost/test/included/unit_test.hpp>
namespace utf = boost::unit_test;

BOOST_AUTO_TEST_SUITE(suite1, * utf::label("trivial"))

  BOOST_AUTO_TEST_CASE(test_case1)
  {
    BOOST_TEST(true);
  }

  BOOST_AUTO_TEST_CASE(test_case2)
  {
    BOOST_TEST(1 == 1);
  }

BOOST_AUTO_TEST_SUITE_END()

> decorator_02 --run_test=@trivial
Running 2 test cases...

*** No errors detected

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.

Example: Decorators on multiple suite openings

#define BOOST_TEST_MODULE decorator_03
#include <boost/test/included/unit_test.hpp>
namespace utf = boost::unit_test;

BOOST_AUTO_TEST_SUITE(suite1, * utf::label("trivial"))

  BOOST_AUTO_TEST_CASE(test_case1)
  {
    BOOST_TEST(true);
  }

BOOST_AUTO_TEST_SUITE_END()

BOOST_AUTO_TEST_SUITE(suite1, * utf::label("simple"))

  BOOST_AUTO_TEST_CASE(test_case2)
  {
    BOOST_TEST(true);
  }

BOOST_AUTO_TEST_SUITE_END()

BOOST_AUTO_TEST_SUITE(suite1)

  BOOST_AUTO_TEST_CASE(test_case3)
  {
    BOOST_TEST(true);
  }

BOOST_AUTO_TEST_SUITE_END()

> decorator_03 --run_test=@trivial
Running 3 test cases...

*** No errors detected


> decorator_03 --run_test=@simple
Running 3 test cases...

*** No errors detected

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 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.