mirror of
https://github.com/boostorg/test.git
synced 2026-01-25 18:52:15 +00:00
194 lines
10 KiB
HTML
Executable File
194 lines
10 KiB
HTML
Executable File
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
|
<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.76.1">
|
|
<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/doc/img/boost.test.logo.png"></a></td>
|
|
<td valign="middle" align="left"> > <a href="../utf.html">The Unit Test Framework</a><a href="../execution-monitor.html">
|
|
>
|
|
</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/src/images/prev.png" alt="Prev"></a><a href="new-year-resolution.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
|
</div></td>
|
|
</tr></table>
|
|
<hr>
|
|
<div class="section">
|
|
<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 class="orderedlist" type="1">
|
|
<li class="listitem">You need to convert is_valid result in proper result code.</li>
|
|
<li class="listitem">Would exception happen in test_object construction of method is_valid invocation, the program will crash.</li>
|
|
<li class="listitem">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-2012 Gennadiy Rozental</div></td>
|
|
</tr></table>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="intro-in-testing.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utf/tutorials.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="new-year-resolution.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
|
|
</div>
|
|
</body>
|
|
</html>
|