![[Level:16]](http://www.gilgil.net/modules/point/icons/default/16.gif "Point:23265point (7%), Level:16/30"){kind=icon}
gilgil | > The Unit Test Framework > User's guide > Runtime configuration > Run by name |   |
In regular circumstances test module execution initiates testing of all test units manually or automatically registered in master test suite. The UTF provides an ability to run specific set of test unit as well. It can be single test case, single test suite or some combination of test cases and suites. The tests units to run are selected by the runtime parameter run_test. In the following examples I select tests to run using command line arguments, but the same filter expression can be used as an appropriate environment variable value.
Filter expressions are specified in a form a/b/c, where a, b and c are filters for corresponding levels of test tree. Symbol '*' can be used at the beginning, at the end and as the level filter itself as an asterisk. Symbol ',' is used to create list of test units residing on the same level in test tree.
Let's consider following test module consisting from several test suites and test cases.
#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>
BOOST_AUTO_TEST_CASE( testA )
{
}
BOOST_AUTO_TEST_CASE( testB )
{
}
BOOST_AUTO_TEST_SUITE( s1 )
BOOST_AUTO_TEST_CASE( test1 )
{
}
BOOST_AUTO_TEST_CASE( lest2 )
{
}
BOOST_AUTO_TEST_SUITE_END()
BOOST_AUTO_TEST_SUITE( s2 )
BOOST_AUTO_TEST_CASE( test1 )
{
}
BOOST_AUTO_TEST_CASE( test11 )
{
}
BOOST_AUTO_TEST_SUITE( in )
BOOST_AUTO_TEST_CASE( test )
{
}
BOOST_AUTO_TEST_SUITE_END()
BOOST_AUTO_TEST_SUITE_END()
Run single test case by specifying it's name.
>example --log_level=test_suite --run_test=testA Running 1 test case... Entering test suite "example" Entering test case "testA" Test case testA doesn't include any assertions Leaving test case "testA" Leaving test suite "example" *** No errors detected
Running multiple test cases residing within the same test suite by listing their names in coma separated list.
>example --log_level=test_suite --run_test=testA,testB Running 2 test case... Entering test suite "example" Entering test case "testA" Test case testA doesn't include any assertions Leaving test case "testA" Entering test case "testB" Test case testA doesn't include any assertions Leaving test case "testB" Leaving test suite "example" *** No errors detected
Incorrect test case name may lead to no test to be run.
>example --log_level=test_suite --run_test=testC Test setup error: no test cases matching filter
Test unit name can refer to a test suite as well. All test units within the referred test suites are going to be run.
>example --log_level=test_suite --run_test=s1 Running 2 test cases... Entering test suite "example" Entering test suite "s1" Entering test case "test1" Test case test1 doesn't include any assertions Leaving test case "test1" Entering test case "lest2" Test case lest2 doesn't include any assertions Leaving test case "lest2" Leaving test suite "s1" Leaving test suite "example" *** No errors detected
Using '/' as levels separator you can refer to any test unit inside a test tree.
>example --log_level=test_suite --run_test=s2/in/test Running 1 test case... Entering test suite "example" Entering test suite "s2" Entering test suite "in" Entering test case "test" Test case test doesn't include any assertions Leaving test case "test" Leaving test suite "in" Leaving test suite "s2" Leaving test suite "example" *** No errors detected
The UTF supports simple regular expression-like '*' wildcard. Single '*' match any name of test unit. Accordingly expression 's1/*' is equivalent to the expression 's1' and matches all test units inside test suite s1. Similarly expression '*/test1' refers to all test units named test1 that reside in master test suite's direct child suites.
>example --log_level=test_suite --run_test=*/test1 Running 2 test cases... Entering test suite "example" Entering test suite "s1" Entering test case "test1" Test case test1 doesn't include any assertions Leaving test case "test1" Leaving test suite "s1" Entering test suite "s2" Entering test case "test1" Test case test1 doesn't include any assertions Leaving test case "test1" Leaving test suite "s2" Leaving test suite "example" *** No errors detected
The UTF allows to match specific prefix in test unit names. For example, expression 's2/test*' filters out only test units in test suite s2 with name that starts with 'test'. This avoids running test suite s2/in.
>example --log_level=test_suite --run_test=s2/test* Running 2 test cases... Entering test suite "example" Entering test suite "s2" Entering test case "test1" Test case test1 doesn't include any assertions Leaving test case "test1" Entering test case "test11" Test case test11 doesn't include any assertions Leaving test case "test11" Leaving test suite "s2" Leaving test suite "example" *** No errors detected
The UTF allows to match specific suffix in test unit names. For example, expression '*/*1' filters out test units with name that ends with '1' and reside in master test suite's direct child suites.
>example --log_level=test_suite --run_test=*/*1 Running 2 test cases... Entering test suite "example" Entering test suite "s2" Entering test case "test1" Test case test1 doesn't include any assertions Leaving test case "test1" Entering test case "test11" Test case test11 doesn't include any assertions Leaving test case "test11" Leaving test suite "s2" Leaving test suite "example" *** No errors detected
Finally, the UTF allows to match specific substring in test unit names.
>example --log_level=test_suite --run_test=s1/*est* Running 2 test cases... Entering test suite "example" Entering test suite "s1" Entering test case "test1" Test case test1 doesn't include any assertions Leaving test case "test1" Entering test case "lest2" Test case lest2 doesn't include any assertions Leaving test case "lest2" Leaving test suite "s1" Leaving test suite "example" *** No errors detected
