[boost] New Boost Test Library updated and merged in main branch

From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2002-08-11 04:36:00

Hi, everybody

As you know from Beman announcement starting today boost is merged with new
test library(BTL). The major difference in comparison with previous version
is that it is implemented offline and accordingly require linking with
precompiled component of BTL. Exact libraries names will depend on tools you
are using. For example, it could be lib<base library name>.a or <base
library name>.lib. Here couple notes for libraries authors and boost users.

1. Those test modules that were using test_main hook will need to link with
Test Execution Monitor component, base library name - test_exec_monitor. You
will not need to make any code changes, though BOOST_INCLUDE_MAIN variable
is not used any more so it's definition could be safely removed.
2. Those test modules that were using cpp_main hook will need to link with
Program Execution Monitor component, base library name - prg_exec_monitor.
You will need to delete inclusion of <boost/test/cpp_main.cpp> if one was
present. This file does not exist any more. After that it should compile and
link without modification
3. To compile using Boost.Build make sure that you update to latest cvs
state
4. To use new Bemans regression testing make sure that you update to the
latest status/Jamfile. It supposedly include all required libraries for each
test module (be aware that this organization will probably change soon so
that each library home directory will be responsible for supplying Jamfile
with tests descriptions ).
5. For those who are using MSVC I supplied MSVC projects in build directory.
I found it very convenient when using MSVC gui. Look into some of the BTL
examples projects to see how make runtime errors to show at compile time
with an ability to jump through them using regular MSVC mechanism.
6. BTL Jamfile is designed to build 4 different subvariants of components
with <threading>single/multi and <runtime-link>static/dynamic. Note, though,
that in my experience bjam could build additional subversions, that is
unconfirmed bug in Boost.Build v1. Those subvariant will be for default
values of above features.
7. Though it is not required, but I would recommend for those who are using
BOOST_TEST checks, to switch to BOOST_CHECK or even better to
BOOST_CHECK_EQUAL in case if you are checking for equality. It will allow
more verbose error description.
8. Consider using BOOST_CHECK_THROW in case if you need to check that
expression throwing an exception. In all other cases it may not be required
to catch exceptions yourself since the framework will do this for you any
case.
9. If your test_main function looks like one in function/test/function:
#include <boost/test/test_tools.hpp>
...
int test_main(int, char* [])
{
  test_zero_args();
  test_one_arg();
  test_two_args();
  test_emptiness();
  test_member_functions();
  test_ref();
  test_allocator();

  return 0;
}

I would recommend consider switching from Test Execution Monitor to the unit
Test framework component. In above case, instead of that code you will need:

#include <boost/test/unit_test.hpp>
using boost::unit_test_framework::test_suite;

...
test_suite*
init_unit_test_suite( int argc, char * argv[] ) {
    test_suite* test= BOOST_TEST_SUITE( "Boost.Function test suite" );

    test->add( BOOST_TEST_CASE( &test_zero_args ) );
    test->add( BOOST_TEST_CASE( &test_one_arg ) );
    test->add( BOOST_TEST_CASE( &test_two_args ) );
    test->add( BOOST_TEST_CASE( &test_emptiness ) );
    test->add( BOOST_TEST_CASE( &test_member_functions ) );
    test->add( BOOST_TEST_CASE( &test_ref ) );
    test->add( BOOST_TEST_CASE( &test_allocator ) );

    return test;
}

10. Note that BTL as an extension support writing test cases based on
boost::function. You will need to include unit_test_suite_ex.hpp to use
that.

During post review time I was adding several minor modification to the
version that was under review. Those includes:
1. Document content changes (special thanks to Dave A.). This work almost
completed I need to finish BTL testing info page only.
2. Major rework of documentation management, that include using of external
css and javascript files. Particularly all reported problems with printing
should be fixed.
3. When log level is set to high level framework will show compiler,
platform, STL and boost version used for compilation. I also considering
adding timestamps for start and end of each test case.
4. Numerous compatibility issues were resolved. To my knowledge BTL should
compile and work on all compilers I had an access to. Let me know about any
issues.
5. Some of the command line arguments and environment variables names were
changed slightly for uniformity .Consult docs about the values.

This one I wanted to emphasize. Based on post-review discussion with
Fernando Cacciola (thanks Fernando) I significantly changed interpretation
of class member function based test cases. Consult with docs for more
information.

Hopefully in next couple days all issues with regression testing will be
resolved. And I am looking forward for you comments and propositions for
further improvements.

Regards,
Gennadiy.