Coin Test-Suite Instructions

The test-suite uses an in-tree, minimal test runner (`testsuite/CoinTest.h`)
that provides a small subset of Boost.Test-style macros (e.g.
`BOOST_AUTO_TEST_CASE`, `BOOST_CHECK_MESSAGE`).

Test-code is written in the implementation file of the component to
be tested.  The test-code is wrapped inside a define-wrapper like this:

  #ifdef COIN_TEST_SUITE

  BOOST_AUTO_TEST_CASE(name)
  {
    // test-code ...
  }

  #endif // COIN_TEST_SUITE

Note the comment behind the #endif-directive.  It is necessary to
include the COIN_TEST_SUITE token for the extractor to be able to
detect the end of the testsuite block.

One Coin-component implementation file may have multiple test-suite
blocks, it is not limited to one.

You can also add/implement utility functions outside the
BOOST_AUTO_TEST_CASE blocks to structure code better.

Every file that includes test-suite blocks need to have as the first
#include-file the header that declares the component implemented in
the cpp-file.  Otherwise the test-suite part won't be able to compile.
You can add #include-directives in the COIN_TESTSUITE_BLOCK though,
and get compilation to work that way.

Only public parts of the API can be tested in this test-suite because
it is built separately outside Coin and then linked with Coin.

When a new cpp-file gets its first test-case, the test-suite does not
are discovered by the CMake-based testsuite extractor (`testsuite/CMakeLists.txt`)
and compiled into the `CoinTests` executable.
The thing that doesn't get updated automatically is the *list* of
files that actually contain test-case code, which you must trigger
manual updating of by running "make makefile-update" as mentioned above.

Run the tests by running "make testsuite-run" in the top-level directory,
or by running "make" in the testsuite directory (after building Coin, of 
course).

If the test-suite crashes (as opposed to just reporting errors),
running "make verbose" might be helpful to figure out exactly which
test-case is the one that causes the problem, or "make debug" to make
the testsuite run in gdb so you end up in the debugger when the
testsuite crashes.  This works only on platforms that use gcc and gdb
as the compiler/debugger suite (Linux, OS X, unixes...) and is not
supported on Windows for now.

That's it.

/2008-11-16 larsa
