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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Hello the testing world or beginner's introduction into testing using the Unit Test Framework</title>
<link rel="stylesheet" href="../../style/style.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
<link rel="home" href="../index.html" title="Boost Test Library">
<link rel="up" href="../utf/tutorials.html" title="The unit test framework tutorials">
<link rel="prev" href="intro-in-testing.html" title="Introduction into testing or why testing is worth the effort">
<link rel="next" href="new-year-resolution.html" title='Boost.Test driven development or "getting started" for TDD followers'>
<script language="JavaScript1.2" src="../../js/boost-test.js"></script>
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table width="100%"><tr>
<td width="10%"><a href="../index.html"><img alt="Home" width="229" height="61" border="0" src="../../../../../libs/test/docbook/img/boost.test.logo.png"></a></td>
<td valign="middle" align="left"> > <a href="../utf.html">The Unit Test Framework</a> > <a href="../utf/tutorials.html">Tutorials</a><a href="../utf/compilation.html">
>
</a><b>Hello the testing world</b>
</td>
<td><div class="spirit-nav">
<a href="intro-in-testing.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a href="new-year-resolution.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
</div></td>
</tr></table>
<hr>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="tutorial.hello-the-testing-world"></a>Hello the testing world or beginner's introduction into testing using the Unit Test Framework</h4></div></div></div>
<p class="first-line-indented">
How should a test program report errors? Displaying an error message is an obvious possibility:
</p>
<pre class="programlisting">if( 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
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 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="programlisting">#include <my_class.hpp>
int main( int, char* [] )
{
my_class test_object( "qwerty" );
return test_object.is_valid() ? EXIT_SUCCESS : EXIT_FAILURE;
}
</pre>
<p class="first-line-indented">
There are several issues with above test.
</p>
<div class="orderedlist"><ol type="1">
<li>You need to convert is_valid result in proper result code.</li>
<li>Would exception happen in test_object construction of method is_valid invocation, the program will crash.</li>
<li>You won't see any output, would you run this test manually.</li>
</ol></div>
<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="programlisting">#include <my_class.hpp>
#define BOOST_TEST_MODULE MyTest
#include <boost/test/unit_test.hpp>
BOOST_AUTO_TEST_CASE( my_test )
{
my_class test_object( "qwerty" );
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>
<div class="programlistingco">
<pre class="programlisting">#define BOOST_TEST_MODULE MyTest
#include <boost/test/unit_test.hpp>
int add( int i, int j ) { return i+j; }
BOOST_AUTO_TEST_CASE( my_test )
{
// seven ways to detect and report the same error:
BOOST_CHECK( add( 2,2 ) == 4 ); // #1 continues on error
BOOST_REQUIRE( add( 2,2 ) == 4 ); // #2 throws on error
if( add( 2,2 ) != 4 )
BOOST_ERROR( "Ouch..." ); // #3 continues on error
if( add( 2,2 ) != 4 )
BOOST_FAIL( "Ouch..." ); // #4 throws on error
if( add( 2,2 ) != 4 ) throw "Ouch..."; // #5 throws on error
BOOST_CHECK_MESSAGE( add( 2,2 ) == 4, // #6 continues on error
"add(..) result: " << add( 2,2 ) );
BOOST_CHECK_EQUAL( add( 2,2 ), 4 ); // #7 continues on error
}
</pre>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="snippet12.ann-1"></a>(1)</p></td>
<td valign="top" align="left"><p class="first-line-indented">
This approach 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 the error
count. At program termination, the error count will be displayed automatically by the Unit Test Framework.
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="snippet12.ann-2"></a>(2)</p></td>
<td valign="top" align="left"><p class="first-line-indented">
This approach 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 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 Unit Test Framework reporting procedure.
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="snippet12.ann-3"></a>(3)</p></td>
<td valign="top" align="left"><p class="first-line-indented">
This approach is similar to approach #1, 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></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="snippet12.ann-4"></a>(4)</p></td>
<td valign="top" align="left"><p class="first-line-indented">
This approach is similar to approach #2, 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></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="snippet12.ann-5"></a>(5)</p></td>
<td valign="top" align="left"><p class="first-line-indented">
This approach 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></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="snippet12.ann-6"></a>(6)</p></td>
<td valign="top" align="left"><p class="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.
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="snippet12.ann-7"></a>(7)</p></td>
<td valign="top" align="left"><p class="first-line-indented">
This approach 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></td>
</tr>
</table></div>
</div>
<p></p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright 2001-2007 Gennadiy Rozental</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="intro-in-testing.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utf/tutorials.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="new-year-resolution.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
