Re: [boost] Formal review: New Boost.Test Library

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-12-01 18:21:12

Some comments on the documentation:

"Execution Monitor - a basic exception and error detection and reporting
facility for use in both production and test programs. The Execution Monitor
allows monitoring of the provided function execution while all runtime
exceptions are being caught and reported. "

This sounds like you're saying that the user provides a "function execution"
which is then monitored. I suggest:

Execution Monitor - a basic exception and error reporting facility for use
in both production and test programs. The Execution Monitor calls a
user-supplied function and reports all runtime exceptions.

==========
"Unit Test Framework - a framework that simplifies writing and organizing
test cases. The framework allows writing test cases as a simple free
function or a class method and
organizing them into the test suites tree. The framework provides a facility
to manage a log report level and a result report level. "

Should say: "supports test cases written as simple free functions or member
functions and organizes them into a tree of test suites"

==========
"The Boost Test Library's Execution Monitor allows a controlled run of a
provided function, relieving users from a messy error detection. All symbols
in the Execution Monitor library are located in the namespace boost. To use
the Execution Monitor you should inherit from the boost::execution_monitor
and overwrite the virtual method int execution_monitor::function(). To start
the monitored function you should call the method
execution_monitor::execute( timeout ). "

Instead:

Execution Monitor calls a user-supplied function in a controlled
environment, relieving users from messy error detection. All symbols in the
Execution Monitor library are located in namespace boost. To use the
Execution Monitor, derive a class from boost::execution_monitor and override
the virtual function
    int execution_monitor::function()
To start the monitored function, call the execution_monitor's
xecute( timeout ) member function."

=============

I could go on; most of what I'm pointing out are understandable English
usage errors and awkwardnesses (is that a word? Even if it is, it's
awkward!)  I will volunteer to edit a few of the pages; if you can find a
few more strong English speakers to do the same, these issues could be
easily cleaned up.

=============

Hmm, is tiemeout a type or a parameter name? What type is it really?

=======
Does execution_monitor install a terminate handler, so that problems like
exceptions thrown during stack unwinding can at least be hinted at?
=========
In test_tools.htm, you mention std::assert(), which (sadly) doesn't exist.
=========
BOOST_CHECKPOINT( message ) - to be used to mark a test flow with a check
points. The checkpoint can help to locate a source of a runtime exception.
    Example: test.cpp
       int test_main( int, char* [] )
      {
          BOOST_CHECKPOINT( "Going to throw an exception" );
          throw "some error";
          return 0;
       }
    Output:
        Exception in test_main : C string:some_error
        test.cpp(3) : last checkpoint: Going to throw an exception

Have you considered supplying BOOST_THROW(...) instead?

=========

-Dave