Test-suites and test cases define a hierarchy called the test tree, which is useful for organizing tests. These organization defines an implicit grouping of test unit following the subtrees extracted from the test tree, by just designing a node on the test tree. Being able to design a group of tests enable, for instance, to execute this group of test only (covered in this section).

However, the subtrees might not reflect all the possible grouping of test units the usage of the test module would require ^[5].

The Unit Test Framework provides a flexible way of grouping test units by the use of labels, using the decorator label. It is possible to associate more than one label with a test unit.

Labels can be associated to test cases and test suites. For the latter, the label is inherited by all the nodes in the subtree defined by the labelled test suite: decorating a test suite with label L is equivalent to decorating every test unit inside with L.

	Tip
	it is possible to list all labels of a test module from the CLI by using the --list_labels switch

Example: decorator label

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

BOOST_AUTO_TEST_CASE(test1,
  * utf::label("l1"))
{
  BOOST_TEST(false);
}

BOOST_AUTO_TEST_CASE(test2,
  * utf::label("l1")
  * utf::label("l2"))
{
  BOOST_TEST(false);
}

BOOST_AUTO_TEST_CASE(test3)
{
  BOOST_TEST(false);
}

> decorator_04
Running 3 test cases...
test.cpp(8): error: in "test1": check false has failed
test.cpp(15): error: in "test2": check false has failed
test.cpp(20): error: in "test3": check false has failed

*** 3 failures are detected in the test module "decorator_04"


> decorator_04 --run_test=@l1
Running 2 test cases...
test.cpp(8): error: in "test1": check false has failed
test.cpp(15): error: in "test2": check false has failed

*** 2 failures are detected in the test module "decorator_04"


> decorator_04 --run_test=@l2
Running 1 test case...
test.cpp(15): error: in "test2": check false has failed

*** 1 failure is detected in the test module "decorator_04"