Boost C++ Libraries

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

list_content

Lists the name of the test units contained in the test module and exits (no test is run).

This command line parameter accepts an optional string value indicating the format of the output. The framework supports the following two formats:

  1. HRF (default), standing for Human Readable Format,
  2. DOT, standing for the Graphviz graph format. This format may be automatically parsed or rendered.
HRF

For HRF, the test tree (test suites and test cases) is presented in a tree like form with each test unit name on a separate line with horizontal indentation in relation to the parent test suite. In addition, test units which are enabled by default have an asterisk * next to the test unit name. For example, the following output:

testsuite1*
    testcase1*
    testcase2
testsuite2*
    testcase3*

represents test module consisting of two test suites: testsuite1 and testsuite2, and three test cases: testcase1, testcase2, and testcase3. The formatting reflects the test-tree: the first two test cases belong to the first test suite and last one belongs to the second. Out of three test cases only two are enabled by default: testcase1 and testcase3. testcase2 is not enabled by default, but can be enabled by using the parameter run_test.

DOT

DOT output generates a graph representing the module's test tree in a dot format. This output includes much more information about the test tree including labels, timeouts, expected failures, and dependencies.

The legend is as follow:

Acceptable values

Enumeration names:

Command line syntax
Environment variable
BOOST_TEST_LIST_CONTENT
Example

The following deliberately complicated example illustrates the purpose of the --list_content directive. The SVG generated from the produced Graphviz/dot file can be downloaded here.

Example: --list_content illustration

Code

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

//// --------------------------------------------------------------------------
// Test suite 1, disabled by default, s1/test2 is explicitely enabled.
BOOST_AUTO_TEST_SUITE( s1,
* utf::disabled()                         // suite is not disabled because of the
* utf::description( "disabled suite 1")   // extra declaration at the end of the file
* utf::label( "label1" )
* utf::label( "label2" ))

BOOST_AUTO_TEST_CASE( test1, // s1/test1
* utf::enabled() * utf::description("enabled"))
{
    BOOST_TEST(true);
}

BOOST_AUTO_TEST_CASE( test2, // s1/test2
* utf::description( "defaulted") * utf::expected_failures( 1 ))
{
    BOOST_TEST(false);
}

BOOST_AUTO_TEST_CASE( test3, // s1/test3
* utf::description( "defaulted"))
{
    BOOST_TEST(false);
}
BOOST_AUTO_TEST_SUITE_END()


//// --------------------------------------------------------------------------
// Test suite 2, disabled by default, s1/test2 is explicitely enabled.
BOOST_AUTO_TEST_SUITE( s2,
* utf::disabled()
* utf::label( "label1" )
* utf::expected_failures( 3 ))

BOOST_AUTO_TEST_CASE( test1, // s2/test1
* utf::description( "defaulted"))
{
    BOOST_TEST(false);
}

boost::test_tools::assertion_result do_it( utf::test_unit_id )
{
   return false;
}

BOOST_AUTO_TEST_CASE( test2, // s2/test2
* utf::enabled()
* utf::description( "enabled w. precondition")
* utf::precondition(do_it))
{
  BOOST_TEST(false);
}

//// --------------------------------------------------------------------------
// Test suite s2/s23, disabled
BOOST_AUTO_TEST_SUITE( s23, * utf::disabled())

BOOST_AUTO_TEST_CASE( test1 ) // s2/s23/test1
{
  BOOST_TEST(false);
}

BOOST_AUTO_TEST_CASE( test2, // s2/s23/test2
* utf::timeout( 10 ))
{
  BOOST_TEST( true );
}

BOOST_AUTO_TEST_CASE( test3, // s2/s23/test3
* utf::enabled()
* utf::depends_on( "s2/test2" ))
{
  BOOST_TEST( true );
}
BOOST_AUTO_TEST_SUITE_END() // s2/s23
BOOST_AUTO_TEST_SUITE_END() // s2



//// --------------------------------------------------------------------------
// Test suite s1 continued
BOOST_AUTO_TEST_SUITE( s1 )
BOOST_AUTO_TEST_SUITE( s14,
* utf::depends_on( "s2/s23/test3" )
* utf::description( "test suite which depends on another test suite"))

BOOST_AUTO_TEST_CASE( test1, // s1/s14/test1
* utf::depends_on( "s2" ))
{
    BOOST_TEST( "s14" == "test" );
}

BOOST_AUTO_TEST_SUITE_END() // s1/s14
BOOST_AUTO_TEST_SUITE_END() // s1

Output

> ./boost_runtime_list_content --list_content
s1*: disabled suite 1
    test1*: enabled
    test2 : defaulted
    test3 : defaulted
    s14 : test suite which depends on another test suite
        test1
s2*
    test1 : defaulted
    test2*: enabled w. precondition
    s23*
        test1
        test2
        test3*


PrevUpHomeNext