]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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] |