1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<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="../../btl1.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 previosly by the original version of Boost.Test.
As the name sujest it provides only minimal basic facilities
for test creation. It does not have any configuration parameters (either
command line arguments or environment variables ) and it supply very limited
set of test tools that behave similarly to ones defined in the <A href="../test_tools/index.html">Test
Tools</A>. Minimal testing facility supply it's own fhe function main()
(so could not be used for multiunit testing) and execute the test
program in a monitored environment.</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"> Minimal testing facility supply
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. Follow the links to see more detailed descriptions. </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> © <A name="Copyright">Copyright</A> <A href="mailto:boost-test%20at%20emailaccount%20dot%20com%20%28please%20unobscure%29">Gennadiy Rozental</A> 2001-2006. <BR>
Distributed under the Boost Software License, Version 1.0.
(See accompanying file <A href="../../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy at
<A href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</A>)</P>
<P>Revised: <!-- #BeginDate format:Sw1 -->8 March, 2006<!-- #EndDate --> </P>
</DIV>
</DIV>
</BODY>
</HTML>
|
