+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Boost Test Library: Execution Monitor Introduction Introduction- The Boost Test Library's Execution Monitor calls a user-supplied
- function in a controlled environment, relieving users from a messy error detection.
- To use the Execution Monitor derive a class from the boost::execution_monitor
- and overwrite the virtual method int execution_monitor::function(). To start the
- monitored function call the execution_monitor::execute( timeout ) member function.
- All symbols in the Execution Monitor implementation are located in the namespace
- boost. The Boost Test Library's Execution Monitor calls a user-supplied
+ function in a controlled environment, relieving users from a messy error detection.
+ To use the Execution Monitor derive a class from the boost::execution_monitor
+ and overwrite the virtual method int execution_monitor::function(). To start the
+ monitored function call the execution_monitor::execute( timeout ) member function.
+ All symbols in the Execution Monitor implementation are located in the namespace
+ boost. Benefits-Controlled execution of error prone functions with a uniform + Controlled execution of error prone functions with a uniform error notification. Specification of boost::execution_monitor-boost::execution_monitor uniformly detects and reports - the occurrence of several types of signals and exceptions, reducing various errors - to a uniform boost::execution_exception + boost::execution_monitor uniformly detects and reports + the occurrence of several types of signals and exceptions, reducing various errors + to a uniform boost::execution_exception which is returned to a caller. Usage:
Effects: -Calls the execution_monitor::function() inside a try/catch block - which may also include other unspecified platform dependent error detection code. - Throws boost::execution_exception on an - uncaught C++ exception, a hardware or software signal, trap, or other exception. - execution_monitor::execute() doesn't consider it an error for the execution_monitor::function() + Calls the execution_monitor::function() inside a try/catch block + which may also include other unspecified platform dependent error detection code. + Throws boost::execution_exception on an + uncaught C++ exception, a hardware or software signal, trap, or other exception. + execution_monitor::execute() doesn't consider it an error for the execution_monitor::function() to return a non-zero value. Returns: - - The integer value returned by the execution_monitor::function(). + + The integer value returned by the execution_monitor::function(). -
+
Specification of boost::execution_exception@@ -76,45 +76,41 @@ char const what() const; }; -Note 1: Only uncaught C++ exceptions are treated as errors. If the application + Note 1: Only uncaught C++ exceptions are treated as errors. If the application catches a C++ exception, it will never reach the boost::execution_monitor. -Note 2: These errors include Unix signals and Windows structured exceptions. + Note 2: These errors include Unix signals and Windows structured exceptions. They are often initiated by hardware traps. -The implementation decides what is a fatal_system_exception - and what is just a system_exception. Fatal errors are so likely to have corrupted - machine state (like a stack overflow or addressing exception) that it is unreasonable - to continue execution. + The implementation decides what is a fatal_system_exception
+ and what is just a system_exception. Fatal errors are so likely to have corrupted
+ machine state (like a stack overflow or addressing exception) that it is unreasonable
+ to continue execution.
The Execution Monitor compilation-To use the Execution Monitor standalone you should include - an execution_monitor.cpp into your project. + To use the Execution Monitor standalone you should include + an execution_monitor.cpp into your project. It is also supplied as a part of all other Boost Test Library's components. Examples-For examples of usage of Execution Monitor see Program - Execution Monitor or Unit Test Framework. + For examples of usage of Execution Monitor see Program + Execution Monitor or Unit Test Framework. Rationale-Sometimes we need to call a function and make sure that - no user or system originated exception are being thrown by it. Also uniform exception - reporting would be convenient. While designing we should be aware that we can be + Sometimes we need to call a function and make sure that + no user or system originated exception are being thrown by it. Also uniform exception + reporting would be convenient. While designing we should be aware that we can be in a situation with no (or almost no) memory available. Design-The Boost Test Library Design
- document describes the relationship between the Execution Monitor and several other
- components. The Boost Test Library Design
+ document describes the relationship between the Execution Monitor and several other
+ components. - |
|
+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Boost Test Library: frequently asked questions
Where is located the latest version of the Boost Test Library?-The latest version of Boost Test Library is available + The latest version of Boost Test Library is available online on www.boost.org. I found a bug. Where could I report it?-Send a bug report to Gennadiy
+ Send a bug report to Gennadiy
Rozental. You can send a request to Gennadiy
+ You can send a request to Gennadiy
Rozental. To create a test case use the macro BOOST_TEST_CASE( test_function
- ). For more details see Unit test
+ To create a test case use the macro BOOST_TEST_CASE( test_function
+ ). For more details see Unit test
framework documentation. To create a test suite use the macro BOOST_TEST_SUITE(
- suite_name ). For more details see Unit
+ To create a test suite use the macro BOOST_TEST_SUITE(
+ suite_name ). For more details see Unit
test framework documentation. Boost Test Library is implemented offline.
- To create a test program you should link with the one of the precompiled
- library components or use "included" version of the component located
- in a boost/test/included directory. For example, to use Test Execution
- Monitor you may either include the <boost/test/test_tools.hpp>
- and link with libtest_exec_monitor.lib or you could include <boost/test/included/test_exec_monitor.hpp>
- in which case you would not need to link with any precompiled component.
- Note also that you should strictly follow specification on integration
- function in other case some compilers may produce linker error like
- this:
-
+ Boost Test Library is implemented offline.
+ To create a test program you should link with the one of the precompiled
+ library components or use "included" version of the component located
+ in a boost/test/included directory. For example, to use Test Execution
+ Monitor you may either include the <boost/test/test_tools.hpp>
+ and link with libtest_exec_monitor.lib or you could include <boost/test/included/test_exec_monitor.hpp>
+ in which case you would not need to link with any precompiled component.
+ Note also that you should strictly follow specification on integration
+ function in other case some compilers may produce linker error like
+ this:
+
Unresolved external 'init_unit_test_suite(int, char * *). The reasons for this error is that in your implementation you should specify second
+ The reasons for this error is that in your implementation you should specify second
argument of init_unit_test_suite exactly as in a specification, i.e.: char* []. Use unit_test_log::instance()->set_log_output( std::ostream&
- ). For more details see Unit test framework
+ Use unit_test_log::instance()->set_log_output( std::ostream&
+ ). For more details see Unit test framework
documentation. Use environment variable BOOST_TEST_LOG_LEVEL to define
- desired log trace level. You still will be able to reset this value from the command
- line. For the list of acceptable values see Unit
+ Use environment variable BOOST_TEST_LOG_LEVEL to define
+ desired log trace level. You still will be able to reset this value from the command
+ line. For the list of acceptable values see Unit
test framework documentation. |
|
+ | |||||||||||||
Floating-point comparison algorithms Introduction Introduction-In most cases it is unreasonable to use an operator=(...) - for a floating-point values equality check The simple solution like abs(f1-f2) - <= e does not work for very small or very big values. This floating-point comparison - algorithm is based on the more confident solution presented by Knuth in [1]. For + In most cases it is unreasonable to use an operator=(...) + for a floating-point values equality check The simple solution like abs(f1-f2) + <= e does not work for very small or very big values. This floating-point comparison + algorithm is based on the more confident solution presented by Knuth in [1]. For a given floating point values u and v and a tolerance e:
Both relationships are commutative but are not transitive. - The relationship defined by inequations (1) is stronger that the relationship - defined by inequations (2) (i.e. (1) => (2) ). Because - of the multiplication in the right side of inequations, that could cause an unwanted - underflow condition, the implementation is using modified version of the inequations - (1) and (2) where all underflow, overflow conditions could be guarded + Both relationships are commutative but are not transitive. + The relationship defined by inequations (1) is stronger that the relationship + defined by inequations (2) (i.e. (1) => (2) ). Because + of the multiplication in the right side of inequations, that could cause an unwanted + underflow condition, the implementation is using modified version of the inequations + (1) and (2) where all underflow, overflow conditions could be guarded safely:
+
How to choose a tolerance-In case of absence of a domain specific requirements the - value of tolerance could be chosen as a sum of the predicted upper limits for "relative - rounding errors" of compared values. The "rounding" is the operation - by which a real value 'x' is represented in a floating-point format with 'p' binary - digits (bits) as the floating-point value 'X'. The "relative rounding error" - is the difference between the real and the floating point values in relation to - real value: |x-X|/|x|. The discrepancy between real and floating point value may + In case of absence of a domain specific requirements the + value of tolerance could be chosen as a sum of the predicted upper limits for "relative + rounding errors" of compared values. The "rounding" is the operation + by which a real value 'x' is represented in a floating-point format with 'p' binary + digits (bits) as the floating-point value 'X'. The "relative rounding error" + is the difference between the real and the floating point values in relation to + real value: |x-X|/|x|. The discrepancy between real and floating point value may be caused by several reasons:
The first two operations proved to have a relative rounding - error that does not exceed 1/2 * "machine epsilon value" for the appropriate - floating point type (represented by std::numeric_limits<FPT>::epsilon()). - conversion to binary presentation, sadly, does not have such requirement. So we - can't assume that float 1.1 is close to real 1.1 with tolerance 1/2 * "machine - epsilon value" for float (though for 11./10 we can). Non arithmetic operations - either do not have a predicted upper limit relative rounding errors. Note that - both arithmetic and non arithmetic operations might also produce others "non-rounding" + The first two operations proved to have a relative rounding + error that does not exceed 1/2 * "machine epsilon value" for the appropriate + floating point type (represented by std::numeric_limits<FPT>::epsilon()). + conversion to binary presentation, sadly, does not have such requirement. So we + can't assume that float 1.1 is close to real 1.1 with tolerance 1/2 * "machine + epsilon value" for float (though for 11./10 we can). Non arithmetic operations + either do not have a predicted upper limit relative rounding errors. Note that + both arithmetic and non arithmetic operations might also produce others "non-rounding" errors, such as underflow/overflow, division-by-zero or 'operation errors'. -All theorems about the upper limit of a rounding error, - including that of 1/2*epsilon, refers only - to the 'rounding' operation, nothing more. This means that the 'operation error', - that is, the error incurred by the operation itself, besides rounding, isn't considered. - In order for numerical software to be able to actually predict error bounds, the - IEEE754 standard requires arithmetic operations to be 'correctly or exactly rounded'. - That is, it is required that the internal computation of a given operation be such - that the floating point result is the exact - result rounded to the number of working bits. In other words, it is required that - the computation used by the operation itself doesn't introduce any additional errors. - The IEEE754 standard does not require same behavior from most non-arithmetic operation. - The underflow/overflow and division-by-zero errors may cause rounding errors with + All theorems about the upper limit of a rounding error, + including that of 1/2*epsilon, refers only + to the 'rounding' operation, nothing more. This means that the 'operation error', + that is, the error incurred by the operation itself, besides rounding, isn't considered. + In order for numerical software to be able to actually predict error bounds, the + IEEE754 standard requires arithmetic operations to be 'correctly or exactly rounded'. + That is, it is required that the internal computation of a given operation be such + that the floating point result is the exact + result rounded to the number of working bits. In other words, it is required that + the computation used by the operation itself doesn't introduce any additional errors. + The IEEE754 standard does not require same behavior from most non-arithmetic operation. + The underflow/overflow and division-by-zero errors may cause rounding errors with unpredictable upper limits. -For a given number of rounding error (in a simple case - it's just a number of floating point constants and arithmetic involved) it is proposed + For a given number of rounding error (in a simple case + it's just a number of floating point constants and arithmetic involved) it is proposed to calculate a tolerance as follows:
where n is number of floating-point rounding errors. -For more reading about floating-point comparison see references + For more reading about floating-point comparison see references at the end. The close_at_tolerance algorithm-The close_at_tolerance - algorithm allows to check the relationship defines by inequations (1) + The close_at_tolerance + algorithm allows to check the relationship defines by inequations (1) or (2). It is implemented as binary predicate. template<typename FPT> class close_at_tolerance @@ -129,47 +129,43 @@ bool operator()( FPT left, FPT right ) const; };- The first constructor allows to specify a tolerance value
- to compare against. The first constructor allows to specify a number of rounding
- errors, in which case a tolerance is computed using expression (3).
- The strong_or_weak switch allows to which relationship is checked. The default
- behavior is to check strong relationship defined by inequations (1).
- The first constructor allows to specify a tolerance value
+ to compare against. The first constructor allows to specify a number of rounding
+ errors, in which case a tolerance is computed using expression (3).
+ The strong_or_weak switch allows to which relationship is checked. The default
+ behavior is to check strong relationship defined by inequations (1).
+ Compilation-The close_at_tolerance algorithm
- is implemented in the header file
- floating_point_comparison.hpp. It is recommended to use test tools wrappers
- located on test_tools.hpp. Note
- that you still need to include
+ The close_at_tolerance algorithm
+ is implemented in the header file
+ floating_point_comparison.hpp. It is recommended to use test tools wrappers
+ located on test_tools.hpp. Note
+ that you still need to include
floating_point_comparison.hpp yourself since it does not get included automatically. Fernando Cacciola for very helpful discussion of floating
+ Fernando Cacciola for very helpful discussion of floating
point arithmetic in the boost forum. [1] Knuth D.E. The art of computer programming (vol II). |
+ Unit Test Framework Extensions+To be supplied. Sorry. + + |
+
Getting started to use unit test framework
Today is a momentous day. Today I am going to start a new life. I am going to stop -eating a greasy food, start attending a fitness club and ... since today I am going to test programs -I am writing. I can start after the last line of a program is completed or, even -better idea, I can write tests while I am coding. And maybe next time I will +eating a greasy food, start attending a fitness club and ... since today I am going to test programs +I am writing. I can start after the last line of a program is completed or, even +better idea, I can write tests while I am coding. And maybe next time I will write tests before the coding during the design stage. I have read a lot of literature on how to write the tests, I have the unit test framework in hand and an idea of new class. So let's get started.
Let say I want to encapsulate an unchangeable C character buffer with a length into the simple class const_string. Rationale: a string class that does not allocate a memory and provide a convenient read-only access to the preallocated -character buffer. I will probably want const_string to have an interface similar to +character buffer. I will probably want const_string to have an interface similar to the class std::string. What will I do first? In my new life I will start with writing a test module for future class const_string. It will look like this:
@@ -50,7 +50,7 @@ init_unit_test_suite( int argc, // EOF -Now I can compile it and link with the unit test framework. Done! I have a +
Now I can compile it and link with the unit test framework. Done! I have a working test program. It is empty, so when I run the program it produces following output:
*** No errors detected
@@ -66,7 +66,7 @@ methods. So my class initial version looks like this: const_string( char const* s ); const_string( char const* s, size_t length ); const_string( char const* begin, char const* end ); - + // Access methods char const* data() const; size_t length() const; @@ -80,32 +80,32 @@ to a test suite. My test program became to look like this:#include <boost/test/unit_test.hpp> using namespace boost::unit_test_framework; -void constructors_test() { +void constructors_test() { const_string cs0( "" ); // 1 // BOOST_CHECK_EQUAL( cs0.length(), (size_t)0 ); BOOST_CHECK( cs0.is_empty() ); - + const_string cs01( NULL ); // 2 // BOOST_CHECK_EQUAL( cs01.length(), (size_t)0 ); BOOST_CHECK( cs01.is_empty() ); - + const_string cs1( "test_string" ); // 3 // BOOST_CHECK_EQUAL( std::strcmp( cs1.data(), "test_string" ), 0 ); BOOST_CHECK_EQUAL( cs1.length(), std::strlen("test_string") ); - + std::string s( "test_string" ); // 4 // const_string cs2( s ); BOOST_CHECK_EQUAL( std::strcmp( cs2.data(), "test_string" ), 0 ); - + const_string cs3( cs1 ); // 5 // BOOST_CHECK_EQUAL( std::strcmp( cs1.data(), "test_string" ), 0 ); - + const_string cs4( "test_string", 4 ); // 6 // BOOST_CHECK_EQUAL( std::strncmp( cs4.data(), "test", cs4.length() ), 0 ); - + const_string cs5( s.data(), s.data() + s.length() ); // 7 // BOOST_CHECK_EQUAL( std::strncmp( cs5.data(), "test_string", cs5.length() ), 0 ); - + const_string cs_array[] = { "str1", "str2" }; // 8 // BOOST_CHECK_EQUAL( cs_array[0], "str1" ); BOOST_CHECK_EQUAL( cs_array[1], "str2" ); @@ -115,7 +115,7 @@ test_suite* init_unit_test_suite( int argc, char* argv[] ) { test_suite* test= BOOST_TEST_SUITE( "const_string test" ); - + test->add( BOOST_TEST_CASE( &constructors_test ) ); return test; @@ -130,7 +130,7 @@ contains and a length. The specification of the class const_string does not cont expected failures, so, though the constructor can fail if I would pass a pointer to an invalid memory, error check control is not performed (can't require what was not promised :-)). But for any valid input it should work. So I am trying to check -a construction for an empty string (1), a NULL string (2) a regular C string(3), +a construction for an empty string (1), a NULL string (2) a regular C string(3), an STL string(4), a copy construction(5) and so on . Well, after fixing all the errors in the implementation (do you write programs without errors from scratch?) I am able to pass this test case and the unit test framework gives me the following report: @@ -206,13 +206,10 @@ ability to make a changes of any complexity without involving a lengthy regressi testing of your whole product. Your test module and the unit test framework will stay behind your back to help you with any occasional errors.
|
+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Boost Test Library"Test everything that could possibly break" XP maxim - Execution
+ Execution
monitor Migration guide Introduction-The Boost Test Library provides a matched set - of components for writing test programs, organizing tests in to simple - test cases and test suites, and controlling their runtime execution. - The Program Execution Monitor is + The Boost Test Library provides a matched set + of components for writing test programs, organizing tests in to simple + test cases and test suites, and controlling their runtime execution. + The Program Execution Monitor is also useful in some production (non-test) environments. -
+
Components
+
FAQDesign-See Boost Test
+ See Boost Test
Library Design. This version of Boost.Test library substitute
- the original testing library used in a Boost. These are several simple
- steps you need to follow to smoothly migrate ot the latest software. If your code were using the original version
- of cpp_main facility, to migrate you will need to delete the inclusion
- of the <boost/test/cpp_main.cpp>, since this file is not present
+ This version of Boost.Test library substitute
+ the original testing library used in a Boost. These are several simple
+ steps you need to follow to smoothly migrate to the latest software. If your code were using the original version
+ of cpp_main facility, to migrate you will need to delete the inclusion
+ of the <boost/test/cpp_main.cpp>, since this file is not present
any more. After that you have following choices: If your code were using the original version
- of test_main and test tools facilitates of Boost.Test library, to migrate
+ If your code were using the original version
+ of test_main and test tools facilitates of Boost.Test library, to migrate
to use of latest one you have following choices: Because the Boost Test Library is critical
- for porting and testing Boost libraries, it has been written to be extremely
- conservative in its use of C++ features, and to keep dependencies to
+ Because the Boost Test Library is critical
+ for porting and testing Boost libraries, it has been written to be extremely
+ conservative in its use of C++ features, and to keep dependencies to
a bare minimum. Tests have been run (and work) under numerous
+ Tests have been run (and work) under numerous
compilers. Original Test Library: Ed Brey, Kevlin Henney, Ullrich Koethe, and
- Thomas Matelich provided very helpful comments during development. Dave
- Abrahams, Ed Brey, William Kempf, Jens Maurer, and Wilka suggested numerous
- improvements during the Formal Review. Jens Maurer was the review manager.
+ Ed Brey, Kevlin Henney, Ullrich Koethe, and
+ Thomas Matelich provided very helpful comments during development. Dave
+ Abrahams, Ed Brey, William Kempf, Jens Maurer, and Wilka suggested numerous
+ improvements during the Formal Review. Jens Maurer was the review manager.
Beman Dawes is the developer and maintainer. Second Release: Beman Dawes and Ullrich Koethe started the
- library. Fernando Cacciola, Jeremy Siek, Beman Dawes, Ullrich Koethe,
- Dave Abrahams suggested numerous improvements during the Formal Review.
- Jeremy Siek was the review manager. Dave Beman Dawes and Ullrich Koethe started the
+ library. Fernando Cacciola, Jeremy Siek, Beman Dawes, Ullrich Koethe,
+ Dave Abrahams suggested numerous improvements during the Formal Review.
+ Jeremy Siek was the review manager. Dave |
+ Boost Test Library: minimal testing+ Introduction Introduction+Boost.Test minimal testing facility provides + the functionality provided before by the original version of Boost.Test. + The same as the Test Execution Monitor + it causes the test program to run in a monitored environment. In addition + it defines several simple test tools that behave similarly to ones defined + in Test Tools. Minimal testing facility + does not require linking with external components, so could be a component + of choice for simple and quick testing needs. Unlike original Boost.Test + version macro BOOST_INCLUDE_MAIN is not used. main function is included + unconditionally. One consequence is that minimal testing could not be + used for multiunit testing. You will need to use other Boost.Test components + for that purpose. +Benefits+ Simple testing framework that provide + the monitored environment and minimal set of testing tools without need + to link with external components. +Example+#include <boost/test/minimal.hpp> + +int add( int i, int j ) { return i+j; } + +int test_main( int, char *[] ) // note the name! +{ + // six 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 "Oops..."; // #5 throws on error + + return add( 2, 2 ) == 4 ? 0 : 1; // #6 returns error code +}+ Approach #1 uses the BOOST_CHECK tool, which displays an error + message 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 Minimal testing facility. +Approach #2 using the BOOST_REQUIRE tool, is similar to #1, + except that after displaying the error, an exception is thrown, to be + caught by the Minimal testing facility. 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 Minimal testing facility + reporting procedure. +Approaches #3 and #4 are similar to #1 and #2 respectively, + except that the error detection is coded separately. This is most useful + when the specific condition being tested is not indicative of the reason + for failure. +Approach #5 throws an exception, which will be caught and reported + by the Minimal testing facility. This approach is suitable for both + production and test code, in libraries or not. 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. +Approach #6 uses a return value to inform the caller of the
+ error. This approach is particularly suitable for integrating existing
+ test code with the test tools library. Although it works fine with the
+ Minimal testing facility libraries, and is very useful for running existing
+ code under them, most C++ experts prefer using exceptions for error
+ reporting. Provided Test Tools+Unlike the Test + Execution Monitor that support complete set of test tools implemented + in a Test Tools component, Minimal testing + facility supply only following four tools: +BOOST_CHECK(
+ predicate ) Their behavior is similar to ones defined in + Test Tools component. Follows the links to see more detailed descriptions. + Old Boost.Test tools names are supported either, but will be deprecated + in a future. +Integration+The only change (other then include boost/test/minimal.hpp) + you need to make to integrate yout test module with Minimal testing + facility is the signature of your main function. It should look like + this: +int test_main( int argc, char* argv[] ) +After that you will automatically start running + your tests in monitored invironment. Also you can start using test tools + provided by minimal testiing facility and get usiform errors reporting. +Test Program+ +Design+
+ The Boost Test Library Design document + describes the relationship between Boost Test Library components. + + |
+
|
+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Boost Test Library: output_test_stream tool Introduction Introduction-The class output_test_stream - is a simple tool for testing output operation with standard std::ostream facilities. - The class output_test_stream comply to std::ostream interface so it can be used - in place of any std::ostream argument. In addition it provide several methods to - validate output content. Also it allows to match/save output content versus/into - specified file. Working mode of the output_test_stream could be defined by framework + The class output_test_stream + is a simple tool for testing output operation with standard std::ostream facilities. + The class output_test_stream comply to std::ostream interface so it can be used + in place of any std::ostream argument. In addition it provide several methods to + validate output content. Also it allows to match/save output content versus/into + specified file. Working mode of the output_test_stream could be defined by framework parameter " Save pattern" Benefits-Simplified mechanism for checking correctness of output + Simplified mechanism for checking correctness of output
operations. Specificationclass output_test_stream { @@ -35,8 +35,8 @@ explicit output_test_stream( char const* pattern_file = NULL, bool match_or_save = true ); - ~output_test_stream(); - + ~output_test_stream(); + bool is_empty( bool flush_stream = true ); bool check_length( std::size_t length, bool flush_stream = true ); bool is_equal( char const* arg, bool flush_stream = true ); @@ -49,63 +49,59 @@ void flush(); };- explicit output_test_stream( + explicit output_test_stream( char const* pattern_file = NULL, bool match_or_save = true ); -The class output_test_stream constructor accept pattern - file name and boolean switch match_or_save that are used by match_pattern + The class output_test_stream constructor accept pattern + file name and boolean switch match_or_save that are used by match_pattern facility. If they are not present you can still use other testing mechanisms. void flush(); -The method output_test_stream::flush() is used to clean + The method output_test_stream::flush() is used to clean the content of the output_test_stream instance. bool is_empty( bool flush_stream = true ); -The method output_test_stream::is_empty(...) is used to - check that the content of the output_test_stream instance is empty. The flush_stream - argument manage automatic call of the method output_test_stream::flush() after + The method output_test_stream::is_empty(...) is used to + check that the content of the output_test_stream instance is empty. The flush_stream + argument manage automatic call of the method output_test_stream::flush() after check is done. -bool check_length( std::size_t length, bool flush_stream + bool check_length( std::size_t length, bool flush_stream = true ); -The method output_test_stream::check_length(...) is used - to check that the length of the content of the output_test_stream instance is equal - to supplied length value. The flush_stream argument manage automatic call of the + The method output_test_stream::check_length(...) is used + to check that the length of the content of the output_test_stream instance is equal + to supplied length value. The flush_stream argument manage automatic call of the method output_test_stream::flush() after check is done. -bool is_equal( char const* arg, bool flush_stream + bool is_equal( char const* arg, bool flush_stream
= true ); The overloaded method output_test_stream::is_equal(...) - is used to check that the content of the output_test_stream instance is equal to - supplied character string. The first version compare with null-terminated string. - The second compare with a reference to std::string object. And finnaly the third - version compare with probably not null-terminated string defined by pointer to - the string begin and the string length. The flush_stream argument manage automatic + The overloaded method output_test_stream::is_equal(...) + is used to check that the content of the output_test_stream instance is equal to + supplied character string. The first version compare with null-terminated string. + The second compare with a reference to std::string object. And finnaly the third + version compare with probably not null-terminated string defined by pointer to + the string begin and the string length. The flush_stream argument manage automatic call of the method output_test_stream::flush() after check is done. -bool match_pattern( + bool match_pattern( bool flush_stream = true ); -The method output_test_stream::match_pattern(...) is used - to match the content of the output_test_stream instance versus the pattern file. - The pattern file name is specified in the class output_test_stream constructor. - If second argument of the class output_test_stream constructor - is false, then every call of the method output_test_stream::match_pattern(...) - will cause the output_test_stream instance content to be stored - at the end of the pattern file. The flush_stream argument manage automatic call + The method output_test_stream::match_pattern(...) is used + to match the content of the output_test_stream instance versus the pattern file. + The pattern file name is specified in the class output_test_stream constructor. + If second argument of the class output_test_stream constructor + is false, then every call of the method output_test_stream::match_pattern(...) + will cause the output_test_stream instance content to be stored + at the end of the pattern file. The flush_stream argument manage automatic call of the method output_test_stream::flush() after check is done. Examlpes and Tests output_test_stream_test.cpp - |
|
+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Boost Test Library: Program Execution Monitor Introduction Introduction-The Boost Test Library's Program Execution Monitor provides - a replacement main() function which calls a user-supplied cpp_main() - function within a try block. The supplied main() then catches and reports exceptions, + The Boost Test Library's Program Execution Monitor provides + a replacement main() function which calls a user-supplied cpp_main() + function within a try block. The supplied main() then catches and reports exceptions, relieving users from messy error detection and reporting duties. -For use with the Program Execution Monitor, the traditional Hello World program + For use with the Program Execution Monitor, the traditional Hello World program becomes: #include <iostream> @@ -37,110 +37,109 @@ return 0; }- It really is that simple - just change the name of your - initial function from main to cpp_main(). Do make sure the argc and arcv parameters - are specified (although you don't have to name them if you don't use them). Now + It really is that simple - just change the name of your + initial function from main to cpp_main(). Do make sure the argc and arcv parameters + are specified (although you don't have to name them if you don't use them). Now you can compile it and link with the Program Execution Monitor library. When the above program executes, the output will be: Hello, world But what if some lower-level function had thrown a runtime_error - with the message "big trouble"? Then the output would look something + But what if some lower-level function had thrown a runtime_error + with the message "big trouble"? Then the output would look something like this: ** exception: std::runtime_error: big trouble And if a lower-level function had bubbled up a return + And if a lower-level function had bubbled up a return code of 5, the output would look something like this: **** error return code 5 Note that the primary messages appear on standard output
- stream, while the final message appears on standard error stream. This increases
- the visibility of error notification if standard output and error streams are directed
- to different devices or files.
- Note that the primary messages appear on standard output
+ stream, while the final message appears on standard error stream. This increases
+ the visibility of error notification if standard output and error streams are directed
+ to different devices or files.
+ BenefitsMore uniform reporting of errors, particularly exceptions. In production programs:-More uniform error reporting is particularly useful for - programs running unattended under control of scripts or batch files. Some operating - systems pop up message boxes if an uncaught exception occurs, and this requires - operator intervention. By converting such exceptions to non-zero program return + More uniform error reporting is particularly useful for + programs running unattended under control of scripts or batch files. Some operating + systems pop up message boxes if an uncaught exception occurs, and this requires + operator intervention. By converting such exceptions to non-zero program return codes, the library makes the program a better citizen. -More uniform reporting of errors isn't a benefit to some - programs, particularly programs always run by hand by a knowledgeable person. So + More uniform reporting of errors isn't a benefit to some + programs, particularly programs always run by hand by a knowledgeable person. So cpp_main() wouldn't be worth using in that environment. In test programs:-More uniform error reporting could be useful in test environments - such as the boost regression tests. But in this case it is preferable to use the - Test Execution Monitor or Unit - Test Framework, cause they allows you to use Test Tools and generate more detailed + More uniform error reporting could be useful in test environments + such as the boost regression tests. But in this case it is preferable to use the + Test Execution Monitor or Unit + Test Framework, cause they allows you to use Test Tools and generate more detailed error information. Specifications of the supplied main()-Uniformly detects and reports the occurrence of several - types of errors, reducing the various errors to a uniform return value which is + Uniformly detects and reports the occurrence of several + types of errors, reducing the various errors to a uniform return value which is returned to the host environment. There are two intended uses:
Requires: -A user-supplied cpp_main() function with same interface + A user-supplied cpp_main() function with same interface as main(). - Effects: + Effects:Call cpp_main( argc, argv ) in a try block. Treat as errors:
Report errors to both cout (with details) and cerr (summary). - Rationale: Detail error reporting goes to cout so that it is properly interlaced - with other output, thus aiding error analysis. Summary goes to cerr in case cout + Report errors to both cout (with details) and cerr (summary). + Rationale: Detail error reporting goes to cout so that it is properly interlaced + with other output, thus aiding error analysis. Summary goes to cerr in case cout is redirected. Returns: -non-zero if any error was detected, zero otherwise. + non-zero if any error was detected, zero otherwise.
The Program Execution Monitor compilation-The Program Execution Monitor is supplied as an offline - library and should be compiled and linked with a test program. Following files, + The Program Execution Monitor is supplied as an offline + library and should be compiled and linked with a test program. Following files, that are located in the Boost Test Library src directory, compose the component: - execution_monitor.cpp execution_monitor.cpp You also have a choice to include all files constituting + the Program Execution Monitor directly into your program. Use <boost/test/included/prg_exec_monitor.hpp> + for this porpose. Example Program-Rationale-The components of a C++ program may report user-detected - errors in several ways, such as via a return value or throwing an exception. System-detected - errors such as dereferencing an invalid pointer are reported in other ways, totally + The components of a C++ program may report user-detected + errors in several ways, such as via a return value or throwing an exception. System-detected + errors such as dereferencing an invalid pointer are reported in other ways, totally operating system and compiler dependent. -Yet many C++ programs, both production and test, must - run in an environment where uniform reporting of errors is necessary. For example, - converting otherwise uncaught exceptions to non-zero program return codes allows - many command line, script, or batch environments to continue processing in a controlled - manner. Even some GUI environments benefit from the unification of errors into + Yet many C++ programs, both production and test, must + run in an environment where uniform reporting of errors is necessary. For example, + converting otherwise uncaught exceptions to non-zero program return codes allows + many command line, script, or batch environments to continue processing in a controlled + manner. Even some GUI environments benefit from the unification of errors into program return codes. Design-The Boost Test Library Design
- document describes the relationship between the Program Execution Monitor and
+ The Boost Test Library Design
+ document describes the relationship between the Program Execution Monitor and
Execution Monitor. |
|
+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Boost Test Library: Unit Test Framework The acceptance test makes the customer satisfied that the The Framework integration Introduction- The Boost Test Library's Unit Test Framework provides
- facilities to simplify writing test cases using Test Tools
- and organizing them into test suites hierarchy. The framework relieves users from
- messy a error detection, reporting duties and parameter processing. It provided
- main() function that initialize the framework, setups parameters based on command
- line arguments and/or environment variables, calls the user-supplied function init_unit_test_suite(argc,
- argv) and than runs the provided test suite. The framework keeps track of all passed/failed
- Test Tools assertions, provides an ability to check
- the testing progress based on the amount of test cases run as part of the total
- amount of test cases and generates the result report in several different formats.
- The Unit Test Framework intended to be used both for a simple testing needs and
- a complex non trivial testing. It is not intended to be used with the production
- code, where the Program Execution Monitor could
- be used. This was one of the design rationale to make the library implemented offline
- vs. an inline implementation to allows us to speed up a compilation at an expense
- of a runtime efficiency. The Unit Test Framework should be preferred over Test
- Execution Monitor while working on creating new test programs. The Boost Test Library's Unit Test Framework provides
+ facilities to simplify writing test cases using Test Tools
+ and organizing them into test suites hierarchy. The framework relieves users from
+ messy a error detection, reporting duties and parameter processing. It provided
+ main() function that initialize the framework, setups parameters based on command
+ line arguments and/or environment variables, calls the user-supplied function init_unit_test_suite(argc,
+ argv) and than runs the provided test suite. The framework keeps track of all passed/failed
+ Test Tools assertions, provides an ability to check
+ the testing progress based on the amount of test cases run as part of the total
+ amount of test cases and generates the result report in several different formats.
+ The Unit Test Framework intended to be used both for a simple testing needs and
+ a complex non trivial testing. It is not intended to be used with the production
+ code, where the Program Execution Monitor could
+ be used. This was one of the design rationale to make the library implemented offline
+ vs. an inline implementation to allows us to speed up a compilation at an expense
+ of a runtime efficiency. The Unit Test Framework should be preferred over Test
+ Execution Monitor while working on creating new test programs. Getting Started- See Getting Started to
+ See Getting Started to
use Unit Test Framework The Unit Test Framework consists of several cooperating
- components. All components are located in the namespace boost::unit_test_framework.
- The Test Case component encapsulate the notion of a simple
- testing unit. The Test Suite component allows to unite
- several related testing units into one bundle that could be considered an a compound
- testing unit. To manage output generated during testing one could use the
- Test Log component. The Test Result component is
+ The Unit Test Framework consists of several cooperating
+ components. All components are located in the namespace boost::unit_test_framework.
+ The Test Case component encapsulate the notion of a simple
+ testing unit. The Test Suite component allows to unite
+ several related testing units into one bundle that could be considered an a compound
+ testing unit. To manage output generated during testing one could use the
+ Test Log component. The Test Result component is
responsible for testing results presentation. The Unit Test Framework provides an ability for the user
- to create the Test Case based on a free function or a user's class method. There
- are four types of test cases: function_test_case,
- class_test_case, parametrized_function_test_case,
- parametrized_class_test_case. All
+ The Unit Test Framework provides an ability for the user
+ to create the Test Case based on a free function or a user's class method. There
+ are four types of test cases: function_test_case,
+ class_test_case, parametrized_function_test_case,
+ parametrized_class_test_case. All
of them implements test case interface defined in the abstract base class test_case. Abstract class test_case define the test case interface.
- Use method test_case:set_timeout(...) to set the
- timeout value for the test case. See method execution_monitor::execute(...)
- for more details about the timeout value. Use method test_case::set_expected_failures(...)
- to set the expected amount of Test Tools failures
- in the test case. In most cases it's more convenient to set these parameters while
- adding this test_case to a test_suite. See the method test_suite::add(...)
- for more details. Use method test_case::run() to
- start the test case processing.
+ Abstract class test_case define the test case interface.
+ Use method test_case:set_timeout(...) to set the
+ timeout value for the test case. See method execution_monitor::execute(...)
+ for more details about the timeout value. Use method test_case::set_expected_failures(...)
+ to set the expected amount of Test Tools failures
+ in the test case. In most cases it's more convenient to set these parameters while
+ adding this test_case to a test_suite. See the method test_suite::add(...)
+ for more details. Use method test_case::run() to
+ start the test case processing.
You will never need to create instances of the class test_case. defined in
- unit_test_suite.hpp
+ defined in
+ unit_test_suite.hpp
Simplest and most widely used form of test cases. Instances
- of the class function_test_case are created by the framework for supplied by the
- user pointer to free function with the following specification: void (*fct)().
- Note void return type. To report a testing results one should use the Test Tools
- instead of returing result code.
+ Simplest and most widely used form of test cases. Instances
+ of the class function_test_case are created by the framework for supplied by the
+ user pointer to free function with the following specification: void (*fct)().
+ Note void return type. To report a testing results one should use the Test Tools
+ instead of returing result code.
To create a test case based on your test function use
+ To create a test case based on your test function use
the following macro: BOOST_TEST_CASE( &free_function ). BOOST_TEST_CASE creates a new instance of the class function_test_case
- and returns a pointer to the base class test_case. In most cases you will use it
+ BOOST_TEST_CASE creates a new instance of the class function_test_case
+ and returns a pointer to the base class test_case. In most cases you will use it
as an argument to the method test_suite::add(...). defined in unit_test_suite.hpp
+ defined in unit_test_suite.hpp
Instances of the class class_test_case are created by
- the framework for the supplied member function and instance of the user's test
- class with the following specification: void (UserTestClass::*fct)(). To allow
- sharing on the same instance, so that one test case could use results of another,
- class_test_case is constructed based on boost::shared_ptr to the user test case
- class instance. Note, though, that we could achive similar effect with use of free
- function like this:
+ Instances of the class class_test_case are created by
+ the framework for the supplied member function and instance of the user's test
+ class with the following specification: void (UserTestClass::*fct)(). To allow
+ sharing on the same instance, so that one test case could use results of another,
+ class_test_case is constructed based on boost::shared_ptr to the user test case
+ class instance. Note, though, that we could achive similar effect with use of free
+ function like this:
To create an instance of the class class_test_case use
+ To create an instance of the class class_test_case use
the following macro: BOOST_CLASS_TEST_CASE( function, shared_test_case_instance
+ BOOST_CLASS_TEST_CASE( function, shared_test_case_instance
). BOOST_CLASS_TEST_CASE creates a new instance of the class
- class_test_case and returns a pointer to the base class test_case. In most cases
+ BOOST_CLASS_TEST_CASE creates a new instance of the class
+ class_test_case and returns a pointer to the base class test_case. In most cases
you will use it as an argument to the method test_suite::add(...). defined in unit_test_suite.hpp
+ defined in unit_test_suite.hpp
Instances of the class parametrized_function_test_case
- are created by the framework for the supplied user's free function with the following
- specification: void (*fct)( ParameterType ).
+ Instances of the class parametrized_function_test_case
+ are created by the framework for the supplied user's free function with the following
+ specification: void (*fct)( ParameterType ).
To create an instance of the class parametrized_function_test_case
+ To create an instance of the class parametrized_function_test_case
use the following macro: BOOST_PARAM_TEST_CASE( free_function, first_parameter,
+ BOOST_PARAM_TEST_CASE( free_function, first_parameter,
last_parameter ). Here first_parameter and last_parameter are begin and
- end iterators for the list of parameters accordingly. BOOST_PARAM_TEST_CASE creates
- a new instance of the class parametrized_function_test_case and returns a pointer
- to the abstract class test_case. In most cases you will use it as an argument to
- the method test_suite::add(...). Be aware that the parametrized_function_test_case
- does not store list of parameters internally. The user should make sure that parameters
- list will not be destroyed until the test case is run. That's why it not recommended
- to create a parameters list as local variable in init_unit_test_suite.
- A simple way to handle a parameters list lifetime is to place it into a user defined
- test suite class.
+ Here first_parameter and last_parameter are begin and
+ end iterators for the list of parameters accordingly. BOOST_PARAM_TEST_CASE creates
+ a new instance of the class parametrized_function_test_case and returns a pointer
+ to the abstract class test_case. In most cases you will use it as an argument to
+ the method test_suite::add(...). Be aware that the parametrized_function_test_case
+ does not store list of parameters internally. The user should make sure that parameters
+ list will not be destroyed until the test case is run. That's why it not recommended
+ to create a parameters list as local variable in init_unit_test_suite.
+ A simple way to handle a parameters list lifetime is to place it into a user defined
+ test suite class.
defined in unit_test_suite.hpp
+ defined in unit_test_suite.hpp
Instances of the class parametrized_class_test_case are
- created by the framework for the supplied method of the user's test class with
- the following specification: void (UserTestClass::*fct)( ParameterType ). The parametrized_class_test_case
- is responsible for the creation and the destroying of the user's test class instance.
+ Instances of the class parametrized_class_test_case are
+ created by the framework for the supplied method of the user's test class with
+ the following specification: void (UserTestClass::*fct)( ParameterType ). The parametrized_class_test_case
+ is responsible for the creation and the destroying of the user's test class instance.
To create an instance of the class parameterized_class_test_case
- use the following macro:
- BOOST_PARAM_TEST_CASE( test_class_method, first_parameter,
- last_parameter ).
- Here first_parameter and last_parameter are begin and
- end iterators for the list of parameters accordingly. BOOST_TEST_CASE creates a
- new instance of the class parametrized_class_test_case and returns a pointer to
- the abstract class test_case. In most cases you will use it as an argument to the
- method test_suite::add(...). Be aware that the parametrized_class_test_case
- does not store list of parameters internally. The user should make sure that parameters
- list will not be destroyed until the test case is run. That's why it not recommended
- to create a parameters list as local variable in init_unit_test_suite.
- For example, you can place parameters list in file scope.
+ To create an instance of the class parameterized_class_test_case
+ use the following macro:
+ BOOST_PARAM_TEST_CASE( test_class_method, first_parameter,
+ last_parameter ).
+ Here first_parameter and last_parameter are begin and
+ end iterators for the list of parameters accordingly. BOOST_TEST_CASE creates a
+ new instance of the class parametrized_class_test_case and returns a pointer to
+ the abstract class test_case. In most cases you will use it as an argument to the
+ method test_suite::add(...). Be aware that the parametrized_class_test_case
+ does not store list of parameters internally. The user should make sure that parameters
+ list will not be destroyed until the test case is run. That's why it not recommended
+ to create a parameters list as local variable in init_unit_test_suite.
+ For example, you can place parameters list in file scope.
defined in unit_test_suite.hpp
+ defined in unit_test_suite.hpp
The Unit Test Framework provides an ability for the user
- to combine created test cases into a test suite and create a hierarchy of test
- suites of any depth. To add a test_case to the test_suite use the method test_suite::add(...).
- The first argument is a pointer to a new test_case, second - expected_failured
- defines the amount of Test Tools assertions that
- are expected to fail in the test case, and third - timeout defines the timeout
- value for the test case. Note that the expected number of failures is calculated
- automatically for the test suites, so you do not need to specify them while adding
- test suites to a hierarchy. See the method execution_monitor::execute(...)
- for more details about the timeout value. Last two arguments are optional and will
+ The Unit Test Framework provides an ability for the user
+ to combine created test cases into a test suite and create a hierarchy of test
+ suites of any depth. To add a test_case to the test_suite use the method test_suite::add(...).
+ The first argument is a pointer to a new test_case, second - expected_failured
+ defines the amount of Test Tools assertions that
+ are expected to fail in the test case, and third - timeout defines the timeout
+ value for the test case. Note that the expected number of failures is calculated
+ automatically for the test suites, so you do not need to specify them while adding
+ test suites to a hierarchy. See the method execution_monitor::execute(...)
+ for more details about the timeout value. Last two arguments are optional and will
not be set if absent. In this case values defined in the test_case are used. To create instances of the class test_suite you can use
+ To create instances of the class test_suite you can use
the following macro: BOOST_TEST_SUITE( test_suite_name ). BOOST_TEST_SUITE creates an instance of the class test_suite
- and returns a pointer to it. test_suite is a test_case, that allows to generate
+ BOOST_TEST_SUITE creates an instance of the class test_suite
+ and returns a pointer to it. test_suite is a test_case, that allows to generate
a multilevel hierarchy. defined in unit_test_result.hpp
+ defined in unit_test_result.hpp
The Unit Test Framework keeps testing results as the instances
- of the class unit_test_result. Class unit_test_result provides three methods for
- the result reporting. Use the method unit_test_result::confirmation_report(...)
- to report the success/failure confirmation massage only. Use the method unit_test_result::short_report(...)
- to report testing results for the current test_case. The report includes an amount
- of passed and failed tests and an amount of passed and failed Test
- Tools assertions. Use the method unit_test_result::detailed_report(...)
- to report testing results for the current test_case and all test cases it consist
- of. In most cases you will not need to use this interface directly. The framework
+ The Unit Test Framework keeps testing results as the instances
+ of the class unit_test_result. Class unit_test_result provides three methods for
+ the result reporting. Use the method unit_test_result::confirmation_report(...)
+ to report the success/failure confirmation massage only. Use the method unit_test_result::short_report(...)
+ to report testing results for the current test_case. The report includes an amount
+ of passed and failed tests and an amount of passed and failed Test
+ Tools assertions. Use the method unit_test_result::detailed_report(...)
+ to report testing results for the current test_case and all test cases it consist
+ of. In most cases you will not need to use this interface directly. The framework
provides a report for overall testing results automatically. To access instance of class unit_test_result holding results
- for the current test case use static method unit_test_result::instance().
+ To access instance of class unit_test_result holding results
+ for the current test case use static method unit_test_result::instance().
defined in unit_test_log.hpp
+ defined in unit_test_log.hpp
To manage the testing output stream the Unit Test Framework
- uses a singleton class unit_test_log. To change the test output stream use method
- unit_test_log::set_log_stream(...). The default stream is std::cout. To set a log
- level use the method unit_test_log::set_log_level_by_name(...). In most cases you
- will not need to use this interface directly. The framework provides a simple way
- to set the log level from out of the test program. For more details and for the
+ To manage the testing output stream the Unit Test Framework
+ uses a singleton class unit_test_log. To change the test output stream use method
+ unit_test_log::set_log_stream(...). The default stream is std::cout. To set a log
+ level use the method unit_test_log::set_log_level_by_name(...). In most cases you
+ will not need to use this interface directly. The framework provides a simple way
+ to set the log level from out of the test program. For more details and for the
list of acceptable values see Framework parameters. To access the only instance of the class unit_test_log
+ To access the only instance of the class unit_test_log
use method unit_test_log::instance(). To monitor a test_case run the Unit Test Framework uses
- a class unit_test_monitor. The unit_test_monitor allows run test_case methods under
- control of a execution_monitor and extends the
- Execution Monitor functionality to translate execution_monitor exceptions into
- designated error codes. For more details about the class unit_test_monitor see
- the Boost Test Library Design. In most cases
- you will not need to utilize unit_test_monitor because the framework already monitor
+ To monitor a test_case run the Unit Test Framework uses
+ a class unit_test_monitor. The unit_test_monitor allows run test_case methods under
+ control of a execution_monitor and extends the
+ Execution Monitor functionality to translate execution_monitor exceptions into
+ designated error codes. For more details about the class unit_test_monitor see
+ the Boost Test Library Design. In most cases
+ you will not need to utilize unit_test_monitor because the framework already monitor
a test case run. As mentioned above Unit Test Framework is responsible
- for supplying main function that initializing testing environment and taking care
- about results reporting. The main function also includes a hook for the function
- that should be supplied by the user. So, to integrate test program with the framework
+ As mentioned above Unit Test Framework is responsible
+ for supplying main function that initializing testing environment and taking care
+ about results reporting. The main function also includes a hook for the function
+ that should be supplied by the user. So, to integrate test program with the framework
you should provide this function with the following specification: boost::unit_test_framework::test_suite* init_unit_test_suite
+ boost::unit_test_framework::test_suite* init_unit_test_suite
( int argc, char* argv[] ) This function should create and initialize top level instance
- of the class test_suite. The NULL pointer returned by the function is treated as
- a non-initialized test_suite. In other case the framework runs provided instance
- of the class test_suite and then destroy it the end of program, so it should be
- allocated dynamically. Command line arguments passed to the function guarantied
+ This function should create and initialize top level instance
+ of the class test_suite. The NULL pointer returned by the function is treated as
+ a non-initialized test_suite. In other case the framework runs provided instance
+ of the class test_suite and then destroy it the end of program, so it should be
+ allocated dynamically. Command line arguments passed to the function guarantied
not to have any framework-specific command line arguments. After test cases run the framework reports the results
- and returns the result code. Here the list of values returned by the testing programs
+ After test cases run the framework reports the results
+ and returns the result code. Here the list of values returned by the testing programs
integrated with the unit test framework: The Unit Test Framework provides two ways to configure
- test program run parameters externally: using command line arguments and setting
- environment variables. The following tables provides a compiled information about
- the framework parameters. Note that default parameter's value (i.e. value of the
- parameter if it is not defined either in the environment or among command-line
+ The Unit Test Framework provides two ways to configure
+ test program run parameters externally: using command line arguments and setting
+ environment variables. The following tables provides a compiled information about
+ the framework parameters. Note that default parameter's value (i.e. value of the
+ parameter if it is not defined either in the environment or among command-line
arguments) for each parameter is bolded. The Unit Test Framework is supplied as an offline library
- and should be compiled and linked with a test program. Following files, that are
+ The Unit Test Framework is supplied as an offline library
+ and should be compiled and linked with a test program. Following files, that are
located in the Boost Test Library src directory, compose the framework: execution_monitor.cpp You also have a choice to include all files
+ constituting the framework directly into your test module. Use <boost/test/included/unit_test_framework.hpp>
+ for this porpose. unit_test_example1.cpp What is the first thing to do when you start working on
- new library/class/program? Exactly - we need the unit test module. Writing of the
- unit test module should be simple and obvious. On the other hand the framework
- should allow us to do a lot of non-trivial things. We want to be able to have a
- lot of small test cases. We want to be able to group them in test suites. At the
- beginning of the development we want to see as much descriptive error message as
- possible, while during regression testing we just want to know is there any errors
- at all. For small test programs a run time should prevail over a compilation time
- - who want to wait a 1 min to start the test that run a 1 sec?. For a long and
+ What is the first thing to do when you start working on
+ new library/class/program? Exactly - we need the unit test module. Writing of the
+ unit test module should be simple and obvious. On the other hand the framework
+ should allow us to do a lot of non-trivial things. We want to be able to have a
+ lot of small test cases. We want to be able to group them in test suites. At the
+ beginning of the development we want to see as much descriptive error message as
+ possible, while during regression testing we just want to know is there any errors
+ at all. For small test programs a run time should prevail over a compilation time
+ - who want to wait a 1 min to start the test that run a 1 sec?. For a long and
complex test we want to be able to see the test progress. The Boost Test Library Design document describes
+ The Boost Test Library Design document describes
the relationship between Boost Test Library components. |