| <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> |
