mirror of
https://github.com/boostorg/test.git
synced 2026-01-26 19:12:10 +00:00
146 lines
9.4 KiB
HTML
146 lines
9.4 KiB
HTML
<!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>
|