Boost C++ Libraries

In order to declare and register a data-driven test-case, the macros BOOST_DATA_TEST_CASE or BOOST_DATA_TEST_CASE_F should be used. Those two forms are equivalent, with the difference that BOOST_DATA_TEST_CASE_F supports fixtures.

Those macros are variadic and can be used in the following forms:

BOOST_DATA_TEST_CASE(test_case_name, dataset) { /* dataset1 of arity 1 */ }
BOOST_DATA_TEST_CASE(test_case_name, dataset, var1) { /* datasets of arity 1 */ }
BOOST_DATA_TEST_CASE(test_case_name, dataset, var1, ..., varN) { /* datasets of arity N  */ }

BOOST_DATA_TEST_CASE_F(fixture, test_case_name, dataset) { /* dataset1 of arity 1 with fixture */ }
BOOST_DATA_TEST_CASE_F(fixture, test_case_name, dataset, var1) { /* dataset1 of arity 1 with fixture */ }
BOOST_DATA_TEST_CASE_F(fixture, test_case_name, dataset, var1, ..., varN) { /* dataset1 of arity N with fixture */ }

The first form of the macro is for datasets of arity 1. The value of the sample being executed by the test body is available through the automatic variable sample (xrange is as its name suggests a range of values):

BOOST_DATA_TEST_CASE( test_case_arity1_implicit, data::xrange(5) )
{
  BOOST_TEST((sample <= 4 && sample >= 0));
}

The second form is also for datasets of arity 1, but instead of the variable sample, the current sample is brought into var1:

BOOST_DATA_TEST_CASE( test_case_arity1, data::xrange(5), my_var )
{
  BOOST_TEST((my_var <= 4 && my_var >= 0));
}

The third form is an extension of the previous form for datasets of arity N. The sample being a polymorphic tuple, each of the variables var1, ..., varN corresponds to the index 1, ... N of the the sample:

// The following definition of the dataset test case throws an exception before the
// test module starts (zip of non infinite or singleton datasets of different length)
BOOST_DATA_TEST_CASE( test_case_arity2, data::xrange(2) ^ data::xrange(5), apples, potatoes)
{
  BOOST_TEST((apples <= 1 && apples >= 0));
  BOOST_TEST((potatoes <= 4 && potatoes >= 0));
}

The next three forms of declaration, with BOOST_DATA_TEST_CASE_F, are equivalent to the previous ones, with the difference being in the support of a fixture that is execute before the test body for each sample. The fixture should follow the expected interface as detailed here.

The arity of the dataset and the number of variables should be exactly the same, the first form being a short-cut for the case of arity 1.

	Tip
	A compilation-time check is performed on the coherence of the arity of the dataset and the number of variables var1... varN. For compilers without C++11 support, the maximal supported arity is controlled by the macro BOOST_TEST_DATASET_MAX_ARITY, that can be overridden prior to including the Unit Test Framework headers.

	Caution
	The macros BOOST_DATA_TEST_CASE and BOOST_DATA_TEST_CASE_F are available only for compilers with support for variadic macros.

Samples and test tree

It should be emphasized that those macros do not declare a single test case (as BOOST_AUTO_TEST_CASE would do) but declare and register as many test cases as there are samples in the dataset given in argument. Each test case runs on exactly one sample of the dataset.

More precisely, what

BOOST_DATA_TEST_CASE(test_case_name, dataset)

does is the following:

This make it easy to:

Exactly as regular test cases, each test case (associated to a specific sample) is executed in monitored manner: