Home > The Unit Test Framework > User's guide > Supplied test runners >
PrevNext

The supplied test runners or where is the entrance?

All usage variants of the UTF, excluding the external test runner, supply the test runner in a form of free function named unit_test_main with the following signature:

int unit_test_main( init_unit_test_func init_func, int argc, char* argv[] );

To invoke the test runner you are required to supply the pointer to the test module initialization function as the first argument to the test runner function. In majority of the cases this function is invoked directly from test executable entry point - function main(). In most usage variants the UTF can automatically generate default function main() implementation as either part of the library or test module itself. Since the function main needs to refer to the initialization function by name, it is predefined by the default implementation and you are required to match both specific signature and name, when implementing initialization function. If you for any reason prefer more flexibility you can opt to implement the function main() yourself, in which case it's going to be your responsibility to invoke the test runner, but the initialization function name is not enforces the UTF. See below for flags that needs to be defined/undefined in each usage variant to enable this.

[Warning] Warning

In spite syntactic similarity the signatures of the test runner function in fact are different for different usage variants. The cause is different signature of the test module initialization function referred by the typedef init_unit_test_func. This makes static and dynamic library usage variants incompatible and they can't be easily switched on a fly.

Static library variant of the UTF

By default this variant supplies the function main() as part of static library. If this is for any reason undesirable you need to define the flag BOOST_TEST_NO_MAIN during the library compilation and the function main() implementation won't be generated.

In addition to the initialization function signature requirement default function main() implementation assumes the name of initialization function is init_unit_test_suite

Dynamic library variant of the UTF

Unlike the static library variant function main() can't reside in the dynamic library body. Instead this variant supplies default function main() implementation as part of the header boost/test/unit_test.hpp to be generated as part of your test file body. The function main() is generated only if either the BOOST_TEST_MAIN or the BOOST_TEST_MODULE flags are defined during a test module compilation. For single-file test module flags can be defined either in a test module's makefile or before the header boost/test/unit_test.hpp inclusion. For a multi-file test module flags can't be defined in makefile and have to be defined in only one of the test files to avoid duplicate copies of the function main().

[Important] Important

The same flags also govern generation of an empty test module initialization function. This means that if you need to implement either function main() or initialization function manually, you can't define the above flags and are required to manually implement both of them.

Single-header variant of the UTF

By default this variant supplies function main() as part of the header boost/test/included/unit_test.hpp to be generated as part of your test file body. If this is for any reason undesirable you need to define the flag BOOST_TEST_NO_MAIN during test module compilation and the function main() implementation won't be generated.

Generated exit status values

Once testing is finished, all supplied test runners report the results and returns an exit status value. Here are the summary of all possible generated values:

Table 4. Generated exit status values

Value Meaning
boost::exit_success No errors occurred during the test or the success result code was explicitly requested with the no_result_code parameter.
boost::exit_test_failure Non-fatal errors detected and no uncaught exceptions were thrown during testing or the UTF fails during initialization.
boost::exit_exception_failure Fatal errors were detected or uncaught exceptions thrown during testing.


PrevUpHomeNext