The obsolete initialization function

For backwards compatibility, the Unit Test Framework also allows the customization of an initialization function of a different type. This is called the obsolete initialization function. Its signature is:

boost::unit_test::test_suite* init_unit_test_suite(int argc, char* argv[]);

The original design of the Unit Test Framework required of the programmer to implement it. It was intended to initialize and return the master test suite. No automatic test case registration was available at that time. The null-pointer value was considered an initialization error.

In the header-only usage variant, you fall back to the obsolete initialization function signature by omitting the definition of macro BOOST_TEST_ALTERNATIVE_INIT_API in test module code.

Example: using obsolete initialization function

Code
#include <boost/test/included/unit_test.hpp> #include <iostream> BOOST_AUTO_TEST_CASE(test1) { BOOST_TEST(false); } boost::unit_test::test_suite* init_unit_test_suite(int /argc/, char* /argv/[]) { std::cout << "using obsolete init" << std::endl; return 0; }

Code

#include <boost/test/included/unit_test.hpp>
#include <iostream>

BOOST_AUTO_TEST_CASE(test1)
{
  BOOST_TEST(false);
}

boost::unit_test::test_suite* init_unit_test_suite(int /*argc*/, char* /*argv*/[])
{
  std::cout << "using obsolete init" << std::endl;
  return 0;
}

Output
> custom_obsolete_init using obsolete init Running 1 test case... test.cpp(6): error: in "test1": check false has failed *** 1 failure is detected in the test module "Master Test Suite"

In the static-library usage variant, you need to omit the definition of macro BOOST_TEST_ALTERNATIVE_INIT_API in test module and compile the Unit Test Framework static library without the compilation flag BOOST_TEST_ALTERNATIVE_INIT_API (this is the default).

In the shared-library usage variant, it is not possible to use the obsolete initialization function.

Even if you decide to us the obsolete initialization function, it is recommended that:

You always return a null-pointer value and install the master test suite via test_suite::add as illustrated here. The current framework does no longer treat the null-pointer value as failure.
You signal the failure by throwing boost::unit_test::framework::setup_error exception.
You access the command-line arguments through the interface of the master test suite, and ignore the function's arguments argc and argv.

	Caution
	The obsolete initialization function is deprecated as its name indicates. It is recommended to migrate to the new API, and rely on the automated test unit registration and fixtures (including global fixtures) for other set-up.