mirror of
https://github.com/boostorg/test.git
synced 2026-01-26 07:02:12 +00:00
100 lines
8.1 KiB
HTML
100 lines
8.1 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>Minimal testing facility</TITLE>
|
|
<LINK rel="stylesheet" type="text/css" href="../../style/btl.css" media="screen">
|
|
<LINK rel="stylesheet" type="text/css" href="../../style/btl-print.css" media="print">
|
|
<META http-equiv="Content-Language" content="en-us">
|
|
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
</HEAD>
|
|
<BODY>
|
|
<DIV class="header"> <A href="../../index.html">Boost.Test</A> > <A href="../index.html">Components</A>
|
|
> <SPAN class="current_article">The minimal testing facility</SPAN> </DIV>
|
|
<DIV class="body"> <IMG src='../../btl.gif' width='252' height='43' alt="Boost Test logo">
|
|
<H1>Boost Test Library: The minimal testing facility</H1>
|
|
<P class="page-toc"> <A href="#Introduction">Introduction</A><BR>
|
|
<A href="#Usage">Usage</A><BR>
|
|
<A href="#Example">Example</A><BR>
|
|
<A href="#Tools">Provided Test Tools </A><BR>
|
|
<A href="#Implementation">Implementation</A><BR>
|
|
<A href="#Test">Tests</A></P>
|
|
<H2><A name="Introduction">Introduction</A></H2>
|
|
<P class="first_line_indented">Boost Test minimal testing facility provides the functionality provided
|
|
before by the original version of Boost Test. The same as the <A href="../test_exec_monitor/index.html">Test
|
|
Execution Monitor</A> it causes the test program to run in a monitored environment. In addition it
|
|
defines several simple test tools that behave similarly to ones defined in <A href="../test_tools/index.html">Test
|
|
Tools</A>. Minimal testing facility does not require linking with external components, so could be
|
|
a component of choice for simple and quick testing needs. Unlike original Boost Test version macro
|
|
BOOST_INCLUDE_MAIN is not used. The function main() is included unconditionally. One consequence is
|
|
that minimal testing could not be used for multiunit testing. You will need to use other Boost Test
|
|
components for that purpose.</P>
|
|
<P class="first_line_indented"></P>
|
|
<H2><A name="Usage">Usage</A></H2>
|
|
<P class="first_line_indented">The only change (other then include <A href="../../../../../boost/test/minimal.hpp">boost/test/minimal.hpp</A>)
|
|
you need to make, to integrate your test module with Minimal testing facility is the signature of your function main().
|
|
It should look like this:</P>
|
|
<P class="indented">int test_main( int argc, char* argv[] )</P>
|
|
<P class="first_line_indented">After that you will automatically start running your tests in monitored environment. Also
|
|
you can start using test tools provided by minimal testing facility and get uniform errors reporting.</P>
|
|
<H2><A name="Example">Example</A></H2>
|
|
<PRE class="code">#<SPAN class="reserv-word">include</SPAN> <<A href="../../../../../boost/test/minimal.hpp">boost/test/minimal.hpp</A>>
|
|
|
|
<SPAN class="cpp-type">int</SPAN> add( <SPAN class="cpp-type">int</SPAN> i, <SPAN class="cpp-type">int</SPAN> j ) { <SPAN class="reserv-word">return</SPAN> i+j; }
|
|
|
|
<SPAN class="cpp-type">int</SPAN> test_main( <SPAN class="cpp-type">int</SPAN>, <SPAN class="cpp-type">char </SPAN>*[] ) <SPAN class="comment">// note the name!</SPAN>
|
|
{
|
|
// six ways to detect and report the same error:
|
|
BOOST_CHECK( add( <SPAN class="literal">2</SPAN>,<SPAN class="literal">2</SPAN> ) == <SPAN class="literal">4</SPAN> ); <SPAN class="comment">// #1 continues on error</SPAN>
|
|
BOOST_REQUIRE( add( <SPAN class="literal">2</SPAN>,<SPAN class="literal">2</SPAN> ) == <SPAN class="literal">4</SPAN> ); <SPAN class="comment">// #2 throws on error</SPAN>
|
|
<SPAN class="reserv-word">if</SPAN>( add( <SPAN class="literal">2</SPAN>,<SPAN class="literal">2</SPAN> ) != <SPAN class="literal">4</SPAN> )
|
|
BOOST_ERROR( <SPAN class="literal">"Ouch..."</SPAN> ); <SPAN class="comment">// #3 continues on error</SPAN>
|
|
<SPAN class="reserv-word">if</SPAN>( add( <SPAN class="literal">2</SPAN>,<SPAN class="literal">2</SPAN> ) != <SPAN class="literal">4</SPAN> )
|
|
BOOST_FAIL( <SPAN class="literal">"Ouch..."</SPAN> ); <SPAN class="comment">// #4 throws on error</SPAN>
|
|
<SPAN class="reserv-word">if</SPAN>( add( <SPAN class="literal">2</SPAN>,<SPAN class="literal">2</SPAN> ) != <SPAN class="literal">4</SPAN> ) throw <SPAN class="literal">"Oops..."</SPAN>; <SPAN class="comment">// #5 throws on error</SPAN>
|
|
|
|
<SPAN class="reserv-word">return</SPAN> add( <SPAN class="literal">2</SPAN>, <SPAN class="literal">2</SPAN> ) == <SPAN class="literal">4</SPAN> ? <SPAN class="literal">0</SPAN> : <SPAN class="literal">1</SPAN>; <SPAN class="comment">// #6 returns error code</SPAN>
|
|
}</PRE>
|
|
<P><B>Approach #1</B> 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 an error count. At program termination,
|
|
the error count will be displayed automatically by the Minimal testing facility.</P>
|
|
<P><B>Approach #2</B> using the BOOST_REQUIRE tool, is similar to #1, except that after displaying the error, an exception
|
|
is thrown, to be caught by the Minimal testing facility. This approach is suitable when writing a 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 Minimal testing facility
|
|
reporting procedure.</P>
|
|
<P><B>Approaches #3 and #4</B> are similar to #1 and #2 respectively, 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.</P>
|
|
<P><B>Approach #5</B> throws an exception, which will be caught and reported by the Minimal testing facility. 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 std::exception, or is a char* or std::string.</P>
|
|
<P><B>Approach #6</B> uses a return value to inform the caller of the error. This approach is particularly suitable for
|
|
integrating existing test code with the test tools library. Although it works fine with the Minimal testing facility libraries,
|
|
and is very useful for running existing code under them, most C++ experts prefer using exceptions for error reporting.</P>
|
|
<H2><A name="Tools">Provided Test Tools</A></H2>
|
|
<P class="first_line_indented">Unlike the <A href="../test_exec_monitor/index.html">Test Execution Monitor</A> that support complete
|
|
set of test tools implemented in a <A href="../test_tools/index.html">Test Tools</A> component, Minimal testing facility supply
|
|
only following four tools:</P>
|
|
<P class="indented"><A href="../test_tools/reference/index.html">BOOST_CHECK( predicate )<BR>
|
|
BOOST_REQUIRE( predicate )<BR>
|
|
BOOST_ERROR( message )<BR>
|
|
BOOST_FAIL( message )</A></P>
|
|
<P class="first_line_indented">Their behavior is similar to ones defined in Test Tools component. Follows the links to see
|
|
more detailed descriptions. Old Boost Test tools names are supported either, but will be deprecated in a future.</P>
|
|
<H2><A name="Implementation">Implementation</A></H2>
|
|
|
|
<P class="indented">The minimal testing component implemented inline in one header <A href="../../../../../boost/test/minimal.hpp">boost/test/minimal.hpp</A>.
|
|
There is no special compilation instructions for this component.</P>
|
|
<H2><A name="Test">Tests</A></H2>
|
|
<P class="indented"><A href="../../tests/minimal_test.html">minimal_test</A></P>
|
|
</DIV>
|
|
<DIV class="footer">
|
|
<DIV class="footer-body">
|
|
<P>Copyright © <A href='mailto:rogeeff@emailaccount.com'>Gennadiy Rozental</A> 2001-2003.<BR>
|
|
Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears
|
|
in all copies. This document is provided "as is" without express or implied warranty and with no claim as to its suitability
|
|
for any purpose.</P>
|
|
<P>Revised: 9 June, 2003</P>
|
|
</DIV>
|
|
</DIV>
|
|
</BODY>
|
|
</HTML>
|