Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
Declaring and registering test cases with datasets

In order to declare and register a data-driven test-case, the macro BOOST_DATA_TEST_CASE should be used. This macro is 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 */ }

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:

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 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] Tip

A compilation-time check is performed on the coherence of the arity of the dataset and the number of variables var1... varN.

It should be emphasized that this macro does not declares a test case, such as BOOST_AUTO_TEST_CASE, but declares and registers as many test cases as there are samples in the dataset given as argument. Each test case runs on exactly one sample of the dataset.

Exactly as regular test cases, each test - or each sample - is executed within the test body in a guarded manner:

[Caution] Caution

The macro BOOST_DATA_TEST_CASE is available only for compilers with support for variadic macros.