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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML>
<HEAD>
<TITLE>Hello The Testing world</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="../usage/recomendations.html">Tutorials
and usage recommendations</A> > <SPAN class="current_article">Hello
the Testing World</SPAN> </DIV>
<DIV class="body"> <IMG src='../btl1.gif' width='252' height='43' alt="Boost Test logo">
<H1>Hello the Testing World</H1>
<P class="first-line-indented">How should a test program report errors? Displaying
an error message is an obvious possibility:</P>
<PRE class="code"><SPAN class="reserv-word">if</SPAN>( something_bad_detected )
std::cout << "something bad has been detected" << std::endl;</PRE>
<P class="first-line-indented">But that requires inspection of the program's
output after each run to determine if an error occurred. Since test programs
are often run as part of a regression test suite, human inspection of output
to detect error messages is too time consuming and unreliable. Test frameworks
like GNU/expect can do the inspections automatically, but are overly complex
for simple testing.</P>
<P class="first-line-indented">A better simple way to report errors is for
the test program to return EXIT_SUCCESS (normally 0) if the test program
completes satisfactorily, and EXIT_FAILURE if an error is detected. This
allows a simple regression test script to automatically and unambiguous detect
success or failure. Further appropriate actions such as creating an HTML
table or emailing an alert can be taken by the script, and can be modified
as desired without having to change the actual C++ test programs.</P>
<P class="first-line-indented">A testing protocol based on a policy of test
programs returning EXIT_SUCCESS or EXIT_FAILURE does not require any supporting
tools; the C++ language and standard library are sufficient. The programmer
must remember, however, to catch all exceptions and convert them to program
exits with non-zero return codes. The programmer must also remember to not
use the standard library assert() macro for test code, because on some systems
it results in undesirable side effects like a message requiring manual intervention.</P>
<P class="first-line-indented">The Boost Test Library's Unit Test Framework
is designed <A href="../execution_monitor/index.html"></A> to automate those
tasks. The library supplied main() relieves users from messy error detection
and reporting duties. Users could use supplied testing tools to perform complex
validation tasks. Let's take a look on the following simple test program:</P>
<PRE class="code">#<SPAN class="reserv-word">include</SPAN> <<SPAN class="literal">my_class.hpp</SPAN>>
<SPAN class="cpp-type">int</SPAN> main( <SPAN class="cpp-type">int</SPAN>, <SPAN class="cpp-type">char</SPAN>* [] )
{
my_class test_object( <SPAN class="literal">"qwerty"</SPAN> );
<SPAN class="reserv-word">return</SPAN> test_object.is_valid() ? EXIT_SUCCESS : EXIT_FAILURE;
}
</PRE>
<P class="first-line-indented">There are several issues with above test.</P>
<OL>
<LI>You need to convert is_valid result in proper result code.</LI>
<LI>Would exception happened in test_object construction of method is_valid
invocation, the program will crash.</LI>
<LI>You wont see any output, would you run this test manually.</LI>
</OL>
<P class="first-line-indented">The Unit Test Framework solves all these issues.
To integrate with it above program needs to be changed to: </P>
<PRE class="code">#<SPAN class="reserv-word">include</SPAN> <<SPAN class="literal">my_class.hpp</SPAN>>
#<SPAN class="reserv-word">define</SPAN> BOOST_TEST_MODULE MyTest
#<SPAN class="reserv-word">include</SPAN> <<SPAN class="literal">boost/test/unit_test.hpp</SPAN>>
BOOST_AUTO_TEST_CASE( my_test )
{
my_class test_object( <SPAN class="literal">"qwerty"</SPAN> );
BOOST_CHECK( test_object.is_valid() );
}
</PRE>
<P class="first-line-indented">Now, you not only receive uniform result code,
even in case of exception, but also nicely formatted output from BOOST_CHECK
tool, would you choose to see it. Is there any other ways to perform checks?
The following example test program shows several different ways to detect
and report an error in the add() function.</P>
<PRE class="code">#<SPAN class="reserv-word">define</SPAN> BOOST_TEST_MODULE MyTest
#<SPAN class="reserv-word">include</SPAN> <<SPAN class="literal">boost/test/unit_test.hpp</SPAN>>
<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; }
BOOST_AUTO_TEST_CASE( my_test )
{
<SPAN class="comment">// seven ways to detect and report the same error:</SPAN>
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"> "Ouch..."</SPAN>;<SPAN class="comment"> // #5 throws on error</SPAN>
BOOST_CHECK_MESSAGE( add( <SPAN class="literal">2</SPAN>,<SPAN class="literal">2</SPAN> ) == <SPAN class="literal">4</SPAN>, <SPAN class="literal"><SPAN class="comment"> // #6 continues on error</SPAN>
"add(..) result: "</SPAN> << add( <SPAN class="literal">2</SPAN>,<SPAN class="literal">2</SPAN> ) );
BOOST_CHECK_EQUAL( add( <SPAN class="literal">2</SPAN>,<SPAN class="literal">2</SPAN> ), <SPAN class="literal">4</SPAN> ); <SPAN class="comment">// #7 continues on error</SPAN>
}</PRE>
<P><B>Approach #1</B> uses the BOOST_CHECK tool, which displays an error message
(by default 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 Unit Test Framework.</P>
<P><B>Approach #2</B> uses the BOOST_REQUIRE tool, is similar to approach #1,
except that after displaying the error, an exception is thrown, to be caught
by the Unit Test Framework. 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 Unit Test Framework reporting procedure.</P>
<P><B>Approaches #3 and #4</B> are similar to approaches #1 and #2 respectively,
except that the error detection and error reporting are coded separately.
This is most useful when the specific condition being tested requires several
independent statements and/or 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 Unit Test Framework. 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 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.</P>
<P><B>Approach #7</B> uses the BOOST_CHECK_EQUAL tool and functionally is similar
to approach #1. This approach is most attractive for checking equality of
two variables, since in case of error it shows mismatched values.</P>
<P>TODO: some finishing statements here </P>
</DIV>
<DIV class="footer">
<DIV class="footer-body">
<P> © <A name="Copyright">Copyright</A> <A href='mailto:boost-test at emailaccount dot com (please unobscure)'>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 -->28 February, 2006<!-- #EndDate -->
</P>
</DIV>
</DIV>
</BODY>
</HTML>
|
