test/doc/src/minimal-testing.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE part PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"  "../../../../tools/boostbook/dtd/boostbook.dtd" [
 <!ENTITY mtf "minimal testing facility">
]>
<section id="minimal">
 <title>Boost Test Library: The minimal testing facility</title>
 <titleabbrev>Minimal testing facility</titleabbrev>

 <section id="minimal.intro">
  <title>Introduction</title>

  <para role="first-line-indented">
   <firstterm>Boost.Test minimal testing facility</firstterm> provides the functionality previously implemented by the 
   original version of Boost.Test. As the name suggest, it provides only minimal basic facilities for test creation. It 
   have no configuration parameters (either command line arguments or environment variables) and it supplies 
   a limited set of <link linkend="minimal.tools">testing tools</link> which behaves similarly to ones defined amount 
   the Unit Test Framework <link linkend="utf.user-guide.testing-tools">Testing tools</link>. The &mtf; supplies its own function 
   main() (so can not be used for multi unit testing) and will execute the test program in a monitored environment.
  </para>

  <para role="first-line-indented">
   As it follows from the name this component provides only minimal set of the testing capabilities and as a general 
   rule the Unit Test Framework should be preferred. In a majority of the cases it provides you with much wider set of 
   testing tools (and other goods), while still being as easy to set up.
  </para>
 </section>
 
 <section id="minimal.usage">
  <title>Usage</title>

  <para role="first-line-indented">
   The only change (other then including <ulink url="../../../../boost/test/minimal.hpp">
   <filename>boost/test/minimal.hpp</filename></ulink>) you need to make, to integrate your test module with &mtf; is 
   the signature of your function main(). It should look like this:
  </para>
  
  <programlisting>int test_main( int argc, char* argv[] )
{
  ...
}</programlisting>

  <para role="first-line-indented">
   Once you apply the change test automatically starts running in monitored environment. Also you can start using 
   <link linkend="minimal.tools">testing tools</link> provided by the &mtf; and get uniform errors reporting.
  </para>
 </section>
 
 <section id="minimal.example">
  <title>Example</title>

  <para role="first-line-indented">
    Following example illustrates different approaches you can employ to detect and report errors using different 
    testing tools
  </para>
  
  <btl-example name="example27">
   <title>Minimal testing facility application</title>

   <annotations>
    <annotation id="snippet18.ann-1" coords="1">
     <para role="first-line-indented">
      This approach uses the BOOST_CHECK tool, which displays an error message on std::cout that includes the 
      expression that failed, the source file name, and the source file line number. It also increments the error count. 
      At program termination, the error count will be displayed automatically by the &mtf;.
     </para>
    </annotation>

    <annotation id="snippet18.ann-2" coords="1">
     <para role="first-line-indented">
      This approach using the BOOST_REQUIRE tool, is similar to #1, except that after displaying the error, an 
      exception is thrown, to be caught by the &mtf;. This approach is suitable when writing an explicit test program,
      and the error would be so severe as to make further testing impractical. BOOST_REQUIRE differs from the C++ 
      Standard Library's assert() macro in that it is always generated, and channels error detection into the uniform
      reporting procedure.
     </para>
    </annotation>

    <annotation id="snippet18.ann-3" coords="1">
     <para role="first-line-indented">
      This approach is similar to #1, except that the error detection is coded separately. This is most useful when 
      the specific condition being tested is not indicative of the reason for failure.
     </para>
    </annotation>

    <annotation id="snippet18.ann-4" coords="1">
     <para role="first-line-indented">
      This approach is similar to #2, except that the error detection is coded separately. This is most useful when 
      the specific condition being tested is not indicative of the reason for failure.
     </para>
    </annotation>

    <annotation id="snippet18.ann-5" coords="1">
     <para role="first-line-indented">
      This approach throws an exception, which will be caught and reported by the &mtf;. This approach is suitable
      for both production and test code, in libraries or not. The error message displayed when  the exception is
      caught  will be most meaningful if the exception is derived from <classname>std::exception </classname>, or is a
      char* or <classname>std::string</classname>.
     </para>
    </annotation>

    <annotation id="snippet18.ann-6" coords="1"> <!-- TO FIX: all the coords -->
     <para role="first-line-indented">
      This approach uses the BOOST_CHECK_MESSAGE tool, is similar to approach #1, except that similar to the approach #3
      displays an alternative error message specified as a second argument.
     </para>
    </annotation>
   </annotations>
  </btl-example>
 </section>
 
 <section id="minimal.tools">
  <title>Provided testing tools</title>

  <para role="first-line-indented">
   The &mtf; supplies following four tools:
  </para>
  
  <inline-synopsis>
   <macro name="BOOST_CHECK" kind="functionlike" ref-id="none">
     <macro-parameter name="predicate"/>
   </macro>
   <macro name="BOOST_REQUIRE" kind="functionlike" ref-id="none">
     <macro-parameter name="predicate"/>
   </macro>
   <macro name="BOOST_ERROR" kind="functionlike" ref-id="none">
     <macro-parameter name="message"/>
   </macro>
   <macro name="BOOST_FAIL" kind="functionlike" ref-id="none">
     <macro-parameter name="message"/>
   </macro>
  </inline-synopsis>
  
  <para role="first-line-indented">
   Their behavior is modeled after the <link linkend="utf.user-guide.testing-tools.reference">similarly named tools</link> 
   implemented by the Unit Test Framework.
  </para>
 </section>
 
 <section id="minimal.impl">
  <title>Implementation</title>

  <para role="first-line-indented">
   The &mtf; is implemented inline in one header <ulink url="../../../../boost/test/minimal.hpp">
   <filename>boost/test/minimal.hpp</filename></ulink>. There are no special compilation instructions for this component.
  </para>
 
  <para role="first-line-indented">
   There is a single unit test program that validates &mtf; functionality: minimal_test <!-- TO FIX: link to test -->
  </para>
 </section>
</section>