list_content - 1.82.0

`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:

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

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:

the master test suite is represented as an ellipse
a test unit (suite, case) is in a rounded rectangle
test unit declaration location, labels, expected failures, timeouts are appended,
a green box indicates that the test unit that is enabled, otherwise its color is yellow,
a plain black arrow goes from a test unit to each of its children, following the test tree (the arrow pointing to the child),
a dashed red arrow indicates a runtime dependence on test units, the arrow pointing to the parent in the dependency graph.

Acceptable values

Enumeration names:

HRF (default)
DOT

Command line syntax

--list_content[=<format>]

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, s2/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

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, s2/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*

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*