ae01c8387c
- section about command line argument filtering for template test cases - many typos fixes - remove reference to bjam
47 lines
2.4 KiB
Plaintext
47 lines
2.4 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003 Boost.Test contributors
|
|
/
|
|
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
/]
|
|
|
|
[section:obsolete_init_func The obsolete initialization function]
|
|
|
|
For backwards compatibility, the __UTF__ 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 __UTF__ required of the programmer to implement it. It was intended to initialize and return
|
|
the __master_test_suite__. No [link ref_BOOST_AUTO_TEST_CASE 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.
|
|
|
|
[bt_example custom_obsolete_init..using obsolete initialization function..run-fail]
|
|
|
|
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 __UTF__ 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
|
|
[memberref boost::unit_test::test_suite::add `test_suite::add`] as illustrated
|
|
[link ref_BOOST_TEST_CASE here]. The current framework does no longer treat the
|
|
null-pointer value as failure.
|
|
# You signal the failure by throwing [classref 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 [link boost_test.tests_organization.fixtures
|
|
fixtures] (including [link boost_test.tests_organization.fixtures.global global fixtures]) for other set-up. ]
|
|
|
|
[endsect] [/section:obsolete_init_func]
|