boost/test
2
0
Fork 0
mirror of https://github.com/boostorg/test.git synced 2026-01-26 07:02:12 +00:00
Code Issues Projects Releases Wiki Activity
Files
c800fa7cab6e8564d3ece25bbbb6af535bc8cca7
test/doc/test_tools.htm
Gennadiy Rozental 5eadea67ec reload after style change 
menu active area repaired


[SVN r14959]
2002-08-19 18:05:56 +00:00

465 lines
21 KiB
HTML
Raw Blame History

<html>
<head>
<title>Test Tools</title>
<script language="javascript">var viso_path="js-lib"</script>
<script language="javascript" src="js-lib/core.js" > </script>
<script language="JavaScript">
JS.include( "btl.js" );
</script>
<script>put_screen_style();</script>
<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 onload="btl_menu_init()">
<div align="center">
<table class="body-table" cellspacing="3" >
<tr>
<td id="body">
<script language="Javascript">btl_header();</script>
<h1 align="center">Boost Test Library: Test Tools</h1>
<p class="page-toc">
<a href="#Introduction">Introduction</a><br>
<a href="#Benifits">Benefits</a><br>
<a href="#Specification">Specification</a><br></p>
<p class="page-toc-indented">
<a href="#BOOST_CHECKPOINT">BOOST_CHECKPOINT</a><br>
<a href="#BOOST_WARN">BOOST_WARN</a><br>
<a href="#BOOST_CHECK">BOOST_CHECK</a><br>
<a href="#BOOST_CHECK_EQUAL">BOOST_CHECK_EQUAL</a><br>
<a href="#BOOST_CHECK_CLOSE_tolerance">BOOST_CHECK_CLOSE</a><br>
<a href="#BOOST_REQUIRE">BOOST_REQUIRE</a><br>
<a href="#BOOST_MESSAGE">BOOST_MESSAGE</a><br>
<a href="#BOOST_CHECK_MESSAGE">BOOST_WARN_MESSAGE</a><br>
<a href="#BOOST_CHECK_MESSAGE">BOOST_CHECK_MESSAGE</a><br>
<a href="#BOOST_CHECK_MESSAGE">BOOST_REQUIRE_MESSAGE</a><br>
<a href="#BOOST_CHECK_PREDICATE">BOOST_CHECK_PREDICATE</a><br>
<a href="#BOOST_REQUIRE_PREDICATE">BOOST_REQUIRE_PREDICATE</a><br>
<a href="#BOOST_ERROR">BOOST_ERROR</a><br>
<a href="#BOOST_FAIL">BOOST_FAIL</a><br>
<a href="#BOOST_CHECK_THROW">BOOST_CHECK_THROW</a><br>
<a href="#BOOST_CHECK_EQUAL_COLLECTIONS">BOOST_CHECK_EQUAL_COLLECTIONS</a><br>
<a href="#BOOST_IS_DEFINED">BOOST_IS_DEFINED</a><br>
<a href="output_test_stream.htm">output_test_stream</a><br>
<a href="#Deprecated">Depricated Boost.Test v1 test tools</a>
</p>
<p class="page-toc">
<a href="#Examples">Example and Test Programs</a><br>
<a href="#Design">Design</a>
</p>
<h2><a name="Introduction">Introduction</a></h2>
<p class="1-line-indented"> Boost Test Library's Test Tools supply a toolbox to ease a creation and a maintenance of test programs.
The toolbox supplied in a form of macros and function declarations. While the functions can be called directly,
the usual way to use Test Tools is via convenience macros. All macros arguments are calculated once, so it's safe to
pass complex expressions in their place. All macros provide an error location: a
file name and a line number. Boost Test Library's Test Tools are intended for test code rather than library or
production code, where throwing exceptions, using assert(), or BOOST_STATIC_ASSERT() may be more suitable ways to
detect and report errors.
<script language="Javascript">put_ref_to_top()</script>
To use the Test Tools you need to link with either the <a href="prg_exec_monitor.htm">Program Execution Monitor</a> or the
<a href="unit_test_framework.htm">Unit Test Framework</a>.
</p>
<h2><a name="Benifits">Benefits</a></h2>
<p class="1-line-indented">Using of Test Tools simplify writing of test program and provide a uniform
error reporting mechanism.</p>
<h2><a name="Specification">Specification</a></h2>
<p><b><a name="BOOST_CHECKPOINT">BOOST_CHECKPOINT</a>( message )</b> - to be used to
mark a test flow with a check points. The checkpoint can help to locate a source of
a runtime exception.</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
BOOST_CHECKPOINT( <span class="literal">&quot;Going to throw an exception&quot;</span> );
<span class="reserv-word">throw</span> <span class="literal">&quot;some error&quot;</span>;
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">
Exception in test_main : C string:some_error<br>
test.cpp(2) : last checkpoint: Going to throw an exception
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_WARN">BOOST_WARN</a>( predicate )</b> - to be used to
perform a weak validation of the the predicate. If predicate is true, the tool produces
a conformation message in other case it produces a warning message in
a form &quot;warning in ...: condition &lt;predicate&gt; is not satisfied&quot;</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
BOOST_WARN( <span class="reserv-word">sizeof</span>(<span class="cpp-type">int</span>) == <span class="reserv-word">sizeof</span>(<span class="cpp-type">short</span>) );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">test.cpp(2) : warning in test_main: condition sizeof(int) == sizeof(short) is not satisfied
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_CHECK">BOOST_CHECK</a>( predicate )</b> - to be used to validate
the predicate value. If predicate is true, the tool produces a conformation message (note here
and further: to manage what massages appear in the test output stream set the proper log level)
in other case it produces an error message in a form &quot;error in ...: test &lt;predicate&gt; fail&quot;</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">int</span> i=<span class="literal">2</span>;
BOOST_CHECK( i == <span class="literal">1</span> );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">test.cpp(3) : error in test_main: test i==1 failed
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_CHECK_EQUAL">BOOST_CHECK_EQUAL</a>( left, right )</b> - the same as BOOST_CHECK( left == right ). The tools allows to see mismatched
values.<br>
<br>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">int</span> i = <span class="literal">2</span>;
<span class="cpp-type">int</span> j = <span class="literal">1</span>;
BOOST_CHECK_EQUAL( i, j );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output"> test.cpp(4) : error in test_main: test i == j failed [2 != 1]
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_CHECK_CLOSE_tolerance">BOOST_CHECK_CLOSE</a>( left, right, tolerance_src )</b>
- to be used to check for the strong relationship defined by the predicate
<a href="floating_point_comparison.htm">close_at_tolerance</a>( tolerance_src )
between <i>left</i> and <i>right</i>. To check for the weak relationship use
<a href="#BOOST_CHECK_PREDICATE">BOOST_CHECK_PREDICATE</a>. Note that you need
to include <a href="../../../boost/test/detail/floating_point_comparison.hpp">
detail/floating_point_comparison.hpp</a> yourself to use this tool since it
depend on this file that does not get included automatically to minimize code
dependency.<br>
<br>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">double</span> v1 = <span class="literal">1.23456e-10</span>;
<span class="cpp-type">double</span> v2 = <span class="literal">1.23457e-10</span>;
BOOST_CHECK_CLOSE( v1, v2, <span class="literal">1e-6</span> ); <span class="comment">// should fail at tolerance supplied</span>
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">test.cpp(4) : error in test_main: test v1 (==) v2 failed [1.23456e-10 != 1.23457e-10 (1e-06)]
</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">double</span> v1 = <span class="literal">4.1;</span>
v1 = v1 * v1;
BOOST_CHECK_CLOSE( v1, <span class="literal">16.81</span>, <span class="literal">1</span>+<span class="literal">2</span> );
<span class="comment">// 1(arithmetic operation) +
// 2(decimal to binary conversions) -
// number of rounding errors; should pass</span>
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_REQUIRE">BOOST_REQUIRE</a>( predicate )</b> - to be used to validate
the predicate value. If predicate is <i>true</i>, the tool produces a conformation message in other case
it produces an error message in a form &quot;fatal error in ...: test &lt;predicate&gt; fail&quot;
and then abort the current test case processing.</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">int</span> i = <span class="literal">3</span>;
BOOST_REQUIRE( i &gt; <span class="literal">5</span> );
BOOST_CHECK( i == <span class="literal">6</span> ); <span class="comment">// will never reach this check</span>
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">test.cpp(3) : fatal error in test_main: test i&gt;5 failed
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_MESSAGE">BOOST_MESSAGE</a>( message )</b> - to be used to
print the message in the test output stream. The message argument can be of any type and can
be a result of concatenations using the operator &lt;&lt;.</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="reserv-word">struct</span> A {
<span class="reserv-word">friend</span> <span class="cpp-type">std::ostream</span>&amp; <span class=keyword>operator</span>&lt;&lt;( <span class="cpp-type">std::ostream</span>&amp; str, A <span class=keyword>const</span>&amp; a ) {
str &lt;&lt; <span class="literal">&quot;struct A&quot;</span>;
<span class="reserv-word">return</span> str;
}
};
<span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
BOOST_MESSAGE( <span class="literal">&quot;Starting test&quot;</span> );
<span class="cpp-type">int</span> i = <span class="literal">2</span>;
BOOST_MESSAGE( <span class="literal">&quot;i=&quot;</span> &lt;&lt; i );
BOOST_MESSAGE( <span class="literal">&quot;still testing...&quot;</span> );
<span class="reserv-word">struct</span> A a;
BOOST_MESSAGE( a &lt;&lt; <span class="literal">'.'</span> );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">Starting test</font><br>
i=2<br>
still testing...<br>
struct A.
<script language="Javascript">put_ref_to_top()</script></p>
<p><b><a name="BOOST_CHECK_MESSAGE">BOOST_WARN_MESSAGE</a>( predicate, message )<br>
BOOST_CHECK_MESSAGE( predicate, message )<br> <a name="BOOST_CHECK_MESSAGE">BOOST_REQUIRE_MESSAGE</a>( predicate, message )</b> -
this group of tools works the same way as their non _MESSAGE form. The only difference is
test instead of generating of an error/confirm message these macros use the supplied one.</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test.cpp( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">double</span> res = sin( <span class="literal">45</span> );
BOOST_CHECK_MESSAGE( res &gt; <span class="literal">3</span>, <span class="literal">&quot;Why not?!?!&quot;</span> );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">test.cpp(3) : error in test_main: Why not?!?!
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_CHECK_PREDICATE">BOOST_CHECK_PREDICATE</a>( prediate,
number_of_arguments, arguments_list )</b> - to be used to validate the supplied
predicate. If predicate produces <i> true</i> value, the tool produces a conformation message in other case it produces an error message in
a form &quot;error in ...: test &lt;predicate&gt;( arguments_list ) fail for
(arguments values)&quot;. Right now only unary and binary predicates are
supported.</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">bool</span> is_even( <span class="cpp-type">int</span> i ) {
<span class="reserv-word">return</span> i%<span class="literal">2</span> == <span class="literal">0</span>;
}
<span class="cpp-type">int</span> test.cpp( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">int</span> i = <span class="literal">17</span>;
BOOST_CHECK_PREDICATE( &amp;is_even, <span class="literal">1</span>, (i) );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">test.cpp(3) : error in test_main: test &amp;is_even(i) failed for 17
</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test.cpp( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">int</span> i = <span class="literal">17</span>;
BOOST_CHECK_PREDICATE( std::not_equal_to&lt;<span class="cpp-type">int</span>&gt;(), <span class="literal">2</span>, (i,<span class="literal">17</span>) );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">test.cpp(3) : error in test_main: test std::not_equal_to&lt;int&gt;()(i, 17) failed for (17, 17)
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_REQUIRE_PREDICATE">BOOST_REQUIRE_PREDICATE</a>( prediate, number_of_arguments, arguments_list )</b> - to be used to validate the supplied
predicate. If predicate produces <i> true</i> value, the tool produces a conformation message in other case it produces an error message in
a form &quot;error in ...: test &lt;predicate&gt;( arguments_list ) fail for (arguments values)&quot; and abort current test case processing. Right now only
unary and binary predicates are supported.</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test.cpp( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">double</span> fp1 = <span class="literal">1.23456e-10</span>;
<span class="cpp-type">double</span> fp2 = <span class="literal">1.23457e-10</span>;
<span class="cpp-type">double</span> epsilon = <span class="literal">8.1e-6</span>;
<span class="comment">// check weak closeness </span>
BOOST_CHECK_PREDICATE( close_at_tolerance&lt;double&gt;( epsilon, <span class="reserv-word">false</span> ),
<span class="literal">2</span>, ( fp1, fp2 ) ); <span class="comment">// should pass</span>
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<script language="Javascript">put_ref_to_top()</script>
<p>Output:</p>
<p><b><a name="BOOST_ERROR">BOOST_ERROR</a>( message ) </b>- the
same as BOOST_CHECK_MESSAGE( false, message ); to be used for an unconditional
error message<br>
<b><a name="BOOST_FAIL">BOOST_FAIL</a>( message )</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- the same as BOOST_REQUIRE_MESSAGE( false, message ); to be used for
an unconditional error message and the current test case aborting</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
BOOST_ERROR( <span class="literal">&quot;Nothing to test&quot;</span> );
BOOST_FAIL( <span class="literal">&quot;Test is not ready yet&quot;</span> );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}
</pre>
<p>Output:</p>
<p class="test-output">
test.cpp(3) : error in test_main: Nothing to test<br>
test.cpp(4) : fatal error in test_main: Test is not ready yet
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_CHECK_THROW">BOOST_CHECK_THROW</a>( statement, exception ) </b>-
to be used to perform an error detection check The tool executes the supplied
statement and check that it throw the supplied exception.
</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="reserv-word">class</span> my_exception{};
<span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">int</span> i = <span class="literal"> 0</span>;
BOOST_CHECK_THROW( i++, my_exception );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}</pre>
<p>Output:</p>
<p class="test-output">test.cpp(4) : error in test_main: exception my_exception expected
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_CHECK_EQUAL_COLLECTIONS">BOOST_CHECK_EQUAL</a>_COLLECTIONS( left_begin, left_end, right_begin )</b>
- to be used to perform an element comparison of two collections
</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
<span class="cpp-type">int</span> col1 [] = { <span class="literal">1</span>, <span class="literal">2</span>, <span class="literal">3</span>, <span class="literal">4</span>, <span class="literal">5</span>, <span class="literal">6</span>, <span class="literal">7</span> };
<span class="cpp-type">int</span> col2 [] = { <span class="literal">1</span>, <span class="literal">2</span>, <span class="literal">4</span>, <span class="literal">4</span>, <span class="literal">5</span>, <span class="literal">7</span>, <span class="literal">7</span> };
BOOST_CHECK_EQUAL_COLLECTIONS( col1, col1+<span class="literal">7</span>, col2);
<span class="reserv-word">return</span> <span class="literal">0</span>;
}</pre>
<p>Output:</p>
<p class="test-output">test.cpp(4) : error in test_main: test {col1, col1+7} == {col2,...} failed [3 != 4]<br>
test.cpp(4) : error in test_main: test {col1, col1+7} == {col2,...} failed [6 != 7]
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><b><a name="BOOST_IS_DEFINED">BOOST_IS_DEFINED</a>( symbol )</b> - to be used to check whether or not the supplied symbol is defined.</p>
<p>Example: test.cpp</p>
<pre class="code"><span class="cpp-type">int</span> test_main( <span class="cpp-type">int</span>, <span class="cpp-type">char</span>* [] ) {
BOOST_CHECK( BOOST_IS_DEFINED(SYMBOL1) );
BOOST_CHECK( BOOST_IS_DEFINED(SYMBOL2(arg)) );
<span class="reserv-word">return</span> <span class="literal">0</span>;
}</pre>
<p>Output:</p>
<p class="test-output">test.cpp(2) : error in test_main: test BOOST_IS_DEFINED(SYMBOL1) failed<br>
test.cpp(3) : error in test_main: test BOOST_IS_DEFINED(SYMBOL2(arg)) failed
<script language="Javascript">put_ref_to_top()</script>
</p>
<p><a name="Deprecated"><b>Depricated Boost.Test v1 test tools</b></a>
<p class="1-line-indented">Here is the list of depricated test tools used in Boost.Test
version 1 and their new analogs:</p>
<div align="center">
<table class="depreciated-tools-list" cellspacing="0" >
<thead>
<tr>
<td align="center"><font size="4">Old tool </font> </td>
<td align="center"><font size="4">New analog tool</font></td>
</tr>
</thead>
<tbody>
<tr>
<td><b>BOOST_TEST</b>( predicate ) </td>
<td><b>BOOST_CHECK</b>( predicate )</td>
</tr>
<tr>
<td><b>BOOST_CRITICAL_TEST</b>( predicate ) </td>
<td><b>BOOST_REQUIRE</b>( predicate )</td>
</tr>
<tr>
<td><b>BOOST_CRITICAL_ERROR</b>( message )
</td>
<td><b>BOOST_FAIL</b>( message )</td>
</tr>
</tbody>
</table>
</div>
<p>The main reasons for making these changes were conciseness and uniformity. Old
deprecated names are still accepted but may be excluded in a future releases.
Thanks for Ullrich Koethe, who originally proposed new names.<p>
<h2><a name="Examples">Examples and Test Programs</a></h2>
<p class="indented"><a href="../example/test_exec_example.cpp">test_exec_example.cpp</a><br>
<a href="../test/test_exec_fail2.cpp">test_exec_fail2.cpp</a><br>
<a href="../test/test_exec_fail3.cpp">test_exec_fail3.cpp</a><br>
<a href="../test/test_tools_test.cpp">test_tools_test.cpp</a>
</p>
<h2><a name="Design">Design</a></h2>
<p class="1-line-indented">The <a href="test_lib_design.htm">Boost Test Library Design</a>
document describes the relationship between Boost Test Library components.
<script language="Javascript">put_ref_to_top()</script>
</p>
<hr>
<p><EFBFBD>
<script language="Javascript">contact_addess()</script>
<script language="Javascript">get_copyright_date()</script>
</p>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED"
S-Format="%d %b %Y" startspan -->15 Aug 2002<!--webbot bot="Timestamp" endspan i-checksum="14763" -->
</p>
</td>
</tr>
</table>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink