Test suites with automated registration

| > The Unit Test Framework > User's guide > Test organization > Test suite > Automated registration |

###### Test suites with automated registration

The solution the UTF presents for automated test suite creation and registration is designed to facilitate multiple points of definition, arbitrary test suites depth and smooth integration with automated test case creation and registration. This facility should significantly simplify a test tree construction process in comparison with manual explicit registration case.

The implementation is based on the order of file scope variables definitions within a single compilation unit. The semantic of this facility is very similar to the namespace feature of C++, including support for test suite extension. To start test suite use the macro BOOST_AUTO_TEST_SUITE. To end test suite use the macro BOOST_AUTO_TEST_SUITE_END. The same test suite can be restarted multiple times inside the same test file or in a different test files. In a result all test units will be part of the same test suite in a constructed test tree.

    BOOST_AUTO_TEST_SUITE(test_suite_name)
    BOOST_AUTO_TEST_SUITE_END()

Test units defined in between test suite start and end declarations become members of the test suite. A test unit always becomes the member of the closest test suite declared. Test units declared at a test file scope become members of the master test suite. There is no limit on depth of test suite inclusion.

Example 16. Test suites with automated registration

This example creates a test tree that matches exactly the one created in the manual test suite registration example. As you can see test tree construction in this example is more straightforward and automated.

    #define BOOST_TEST_MODULE example
    #include <boost/test/included/unit_test.hpp>

    BOOST_AUTO_TEST_SUITE( test_suite1 )

    BOOST_AUTO_TEST_CASE( test_case1 )
    {
        BOOST_WARN( sizeof(int) < 4 );
    }

    BOOST_AUTO_TEST_CASE( test_case2 )
    {
        BOOST_REQUIRE_EQUAL( 1, 2 );
        BOOST_FAIL( "Should never reach this line" );
    }

    BOOST_AUTO_TEST_SUITE_END()
    BOOST_AUTO_TEST_SUITE( test_suite2 )

    BOOST_AUTO_TEST_CASE( test_case3 )
    {
        BOOST_CHECK( true );
    }

    BOOST_AUTO_TEST_CASE( test_case4 )
    {
        BOOST_CHECK( false );
    }

    BOOST_AUTO_TEST_SUITE_END()

`Source code` | | | `Show output`

    > example
    Running 4 test cases...
    test.cpp(12): fatal error in "test_case2": critical check 1 == 2 failed [1 != 2]
    test.cpp(27): error in "test_case4": check false failed

    *** 2 failures detected in test suite "example"

Example 17. Example of test suite extension using automated registration facility

In this example test suite test_suite consists of two parts. Their definition is remote and is separated by another test case. In fact these parts may even reside in different test files. The resulting test tree remains the same. As you can see from the output both test_case1 and test_case2 reside in the same test suite test_suite.

    #define BOOST_TEST_MODULE example
    #include <boost/test/included/unit_test.hpp>

    BOOST_AUTO_TEST_SUITE( test_suite )

    BOOST_AUTO_TEST_CASE( test_case1 )
    {
        BOOST_ERROR( "some error 1" );
    }

    BOOST_AUTO_TEST_SUITE_END()

    BOOST_AUTO_TEST_CASE( test_case_on_file_scope )
    {
        BOOST_CHECK( true );
    }

    BOOST_AUTO_TEST_SUITE( test_suite )

    BOOST_AUTO_TEST_CASE( test_case2 )
    {
        BOOST_ERROR( "some error 2" );
    }

    BOOST_AUTO_TEST_SUITE_END()

`Source code` | | | `Show output`

    >example --report_level=detailed
    Running 3 test cases...
    test.cpp(8): error in "test_case1": some error 1
    test.cpp(23): error in "test_case2": some error 2

    Test suite "example" failed with:
      1 assertion out of 3 passed
      2 assertions out of 3 failed
      1 test case out of 3 passed
      2 test cases out of 3 failed

      Test suite "test_suite" failed with:
        2 assertions out of 2 failed
        2 test cases out of 2 failed

        Test case "test_case1" failed with:
          1 assertion out of 1 failed

        Test case "test_case2" failed with:
          1 assertion out of 1 failed

      Test case "test_case_on_file_scope" passed with:
        1 assertion out of 1 passed