From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2006-05-12 17:58:54
"Juergen Hunold" <hunold_at_[hidden]> wrote in message
news:200605122018.34853.hunold_at_ive-mbh.de...
> Hi Gennadyi !
> I'd be very interested to know how to "init" a custom test case with
> the dll.
> Testcases using the "AUTO_TEST" makros just work fine, but I can't
> figure out how to run my existing (read 1.33.1) based custom test cases
> with dlls. This would be nice to have.
> Especially because I could finish my patches for Boost.Build V2 support
> for dynamic linking on Win32...
Here some extract from draft version of upcoming Boost.Test docs:
The framework initialization
Let's consider different usage scenarios and how the framework
initialization is done in each case.
Static library or "included" Framework
Statically build version on the Unit Test Framework and "included" header
contains function main() implementation inside library code (Unless you
defined BOOST_TEST_NO_MAIN during library compilation). So the only
function that needs to be implemented by the user is test tree
initialization function. In older versions of the framework all the test
tree construction was placed on users shoulders. Later versions introduced
an ability to implement self registerring test cases and test suites. This
later option made explicit test tree initilization function redundant in
most cases. But you may still want to implement one in case you choose to
use test case creation tools that require explicit registration or if you
need to perform some custom framework initialization. With new design
original initilization function signature became inconvinient and
unnessesary unsafe. So an alternatice initialization function signature was
introduced. This change is not backward compartible though. So for now the
framework is still using original initilization function signature by
default. To switch to use alternative new one you need to define
BOOST_TEST_ALTERNATIVE_INIT_API. The plan for the next release is to switch
default from the the original to new signature. Ultimately old initilization
function signature will be depricated and removed.
Original (default) initilization function signature
To integrate test program with the Unit Test Framework user should provide
the function with the following specification:
boost::unit_test::test_suite* init_unit_test_suite ( int argc, char*
argv[] )
This function primary responsibility is to create and register all test
cases and test suites. The result value of this function is ignored
(accordingly null value is not considerred to be an error). So don't return
constructed test suites. Instead register them using framework::add
interface with master test suite instance. The only way to report
initialization error is to throw a framework::setup_error exception. Pair of
arguments argc, argv presents command line arguments specified during test
module invocation. It's guarantied that any framework-specific command line
arguments are excluded.
Alternative initilization function signature
To integrate test program with the Unit Test Framework user should provide
the function with the following specification:
bool init_unit_test()
This function primary responsibility is to create and register test cases
and test suites that require manual registration. The result value of this
function indicate whether or not initilization was successfull. To register
test cases or test suites in a master test suite use framework::add
interface. To access command line arguments use
framework::master_test_suite() properties argc and argv (.argc or .argv
accordingly). It's guarantied that any framework-specific command line
arguments are excluded. Note that this interface for runtime parameter
access is temporary. It's planed to be updated once runtime parameters
support rework is completed.
Automatic generation of test tree initilization function
In most cases you don't need to do any custom frameowrk initilization and
all your test cases and test suites are self registerring. In this case you
don't really have a need for initialization function. The Unit Test
Framework provides a way to automatically generate empty initialization
function. To do so you need to define BOOST_TEST_MAIN before including
boost/test/unit_test.hpp header. The value of this define is ignored.
Alternatively you could define BOOST_TEST_MODULE to be equal to any string
(not nesseserily in quotes). This macro will cause the same result as
BOOST_TEST_MAIN, and in addition the value of this macro will became the
name of the master test suite. Note though that for test module consisting
from multiple test files you need to define theses macros only in a single
file. Otherwise you will recieve multiple instances of the initilization
function.
Dynamic Library
Due to some portability limitation users of dynamically build library are
required to employ new alternative initilization function signature.
BOOST_TEST_MAIN/BOOST_TEST_MODULE still could be used to generate empty
instance of initilization function. Unfortunately there is no portable way
to place main function body into library. So users are require to implement
their own function main() that invokes function unit_test_main somewhere in
test module body. In majority of the cases this function would look like
plain forward. To automate this task for the users the framework implements
this simple forwarding version in case if either BOOST_TEST_MAIN or
BOOST_TEST_MODULE is defined. This way in most cases single define provides
both required functions default implementation. Unfortunately this also
means that if you need just one of them you will have to implement both.
User's supplied function main()
In case if you for any reason couldn't use library supplied function
main() you could call function unit_test_main from within your own main
function. This function performs all nessesary tasks. You still need to
supply the test tree initialization function though.
> > Also you could look into dll example in libs/test/example directory
> Which one do you mean ?
> There is no file with "dll" or "shared" in its name :-))
Check Jamfile. Some of the examples built in dynamic link mode
Gennadiy