ceph/src/boost/libs/test/doc/tutorials/hello_world.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:hello A testing framework, what for?]
   9 How should a test program report errors? Displaying an error message is an obvious possibility:
  10
  11 [/snippet9 deleted]
  12 ``
  13 if( something_bad_detected )
  14   std::cout << "something bad has been detected" << std::endl;
  15 ``
  16
  17 But that requires inspection of the program's output after each run to determine if an error occurred. Since test
  18 programs are often run as part of a regression test suite, human inspection of output to detect error messages is time
  19 consuming and unreliable. Test frameworks like GNU/expect can do the inspections automatically, but are overly complex
  20 for simple testing.
  21
  22 A better simple way to report errors is for the test program to return `EXIT_SUCCESS` (normally 0) if the test program
  23 completes satisfactorily, and `EXIT_FAILURE` if an error is detected. This allows a simple regression test script to
  24 automatically and unambiguously detect success or failure. Further appropriate actions such as creating an HTML table or
  25 emailing an alert can be taken by the script, and can be modified as desired without having to change the actual C++
  26 test programs.
  27
  28 A testing protocol based on a policy of test programs returning `EXIT_SUCCESS` or `EXIT_FAILURE` does not require any
  29 supporting tools; the C++ language and standard library are sufficient. The programmer must remember, however, to catch
  30 all exceptions and convert them to program exits with non-zero return codes. The programmer must also remember to not
  31 use the standard library `assert()` macro for test code, because on some systems it results in undesirable side effects
  32 like a message requiring manual intervention.
  33
  34 The Boost Test Library's Unit Test Framework is designed to automate those tasks. The library supplied `main()` relieves
  35 users from messy error detection and reporting duties. Users could use supplied testing tools to perform complex
  36 validation tasks. Let's take a look on the following simple test program:
  37
  38
  39 ``
  40 #include <my_class.hpp>
  41
  42 int main( int, char* [] )
  43 {
  44   my_class test_object( "qwerty" );
  45   return test_object.is_valid() ? EXIT_SUCCESS : EXIT_FAILURE;
  46 }
  47 ``
  48
  49 There are several issues with above test.
  50
  51 # You need to convert `is_valid` result in proper result code.
  52 # Would exception happen in test_object construction of method `is_valid` invocation, the program will crash.
  53 # You won't see any output, would you run this test manually.
  54
  55 The __UTF__ solves all these issues. To integrate with it above program needs to be changed to:
  56
  57 ``
  58 #include <my_class.hpp>
  59 #define __BOOST_TEST_MODULE__ MyTest
  60 #include <boost/test/unit_test.hpp>
  61
  62 __BOOST_AUTO_TEST_CASE__( my_test )
  63 {
  64   my_class test_object( "qwerty" );
  65   BOOST_TEST( test_object.is_valid() );
  66 }
  67 ``
  68
  69 Now, you not only receive uniform result code, even in case of exception, but also nicely formatted output from
  70 __BOOST_TEST__ tool, would you choose to see it. Is there any other ways to perform checks? The following example test
  71 program shows several different ways to detect and report an error in the `add()` function.
  72
  73 [import ../snippet/snippet12.cpp]
  74 [snippet12]
  75
  76
  77 [endsect] [/section:hello]