[/ / Copyright (c) 2003-2014 Gennadiy Rozental / Copyright (c) 2013-2014 Raffi Enficiaud / / Distributed under the Boost Software License, Version 1.0. (See accompanying / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) /] [section:testing_tool_ref Reference] [table [ [Assertions] [Short description] ] [/ ###############################################################################################] [ [__BOOST_TEST__] [General purpose assertion macro.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL__] [Simple validation of a boolean predicate value.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_BITWISE_EQUAL__] [Bitwise equality test of two elements.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_EQUAL__] [Equality test of two elements.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_EQUAL_COLLECTIONS__] [Element-wise equality test of two collections.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_CLOSE__] [Floating point comparison using a percentage of deviation.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_CLOSE_FRACTION__] [Floating point comparison using the fraction of the compared operands.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_EXCEPTION__] [Exception detection and validation check.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_GE__] [Comparison of two values (with convenient reporting).] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_GT__] [Comparison of two values (with convenient reporting).] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_LE__] [Comparison of two values (with convenient reporting).] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_LT__] [Comparison of two values (with convenient reporting).] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_MESSAGE__] [Same as __BOOST_LEVEL__ with a custom message in case of failure.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_NE__] [Comparison of two values (with convenient reporting).] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_NO_THROW__] [Checks an expression does not throw any exception.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_PREDICATE__] [Checks a list of arguments against a predicate functor.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_SMALL__] [Checks a value is small according to a tolerance.] ] [/ ###############################################################################################] [ [__BOOST_LEVEL_THROW__] [Checks an expression throws a specific type of expression.] ] [/ ###############################################################################################] [ [__BOOST_ERROR__] [Logs an error message, fails but does not abort the current test.] ] [/ ###############################################################################################] [ [__BOOST_FAIL__] [Logs an error message, fails and aborts the current test.] ] [/ ###############################################################################################] [ [__BOOST_IS_DEFINED__] [Checks at runtime whether or not the supplied preprocessor symbol is defined.] ] ] [/ ###############################################################################################] [section:assertion_boost_test_super_macro `BOOST_TEST`] `` BOOST_TEST(statement); // Prints a failure message, requires variadic macros BOOST_TEST(statement, "failure message"); // Floating point comparison, requires variadic macros, auto and decltype BOOST_TEST(statement, floating_point_comparison_manipulation); // bitwise comparison, requires variadic macros, auto and decltype BOOST_TEST(statement, boost::test_tools::bitwise); `` The full documentation of this macro is located [link boost_test.users_guide.testing_tools.boost_test_super_macro here]. * `"failure message"` is a C-string printed in case of failure. See [link boost_test.users_guide.testing_tools.boost_test_super_macro.options.option_message this section] for more details. * `floating_point_comparison_manipulation` is one of the floating point comparison manipulators. See [link boost_test.users_guide.testing_tools.boost_test_super_macro.options.floating_point this section] for more details. * [classref boost::test_tools::bitwise] is a manipulator indicating that the comparison should be performed bitwise. See [link boost_test.users_guide.testing_tools.boost_test_super_macro.options.bitwise this section] for more details [h3 Restrictions on the acceptable statements] There are some restrictions on the supported statements. Those are explained [link boost_test.users_guide.testing_tools.boost_test_super_macro.acceptable_statements here]. [endsect] [/ ###############################################################################################] [#ref_BOOST_level][section:assertion_boost_level `BOOST_`] `` BOOST_WARN(predicate); BOOST_CHECK(predicate); BOOST_REQUIRE(predicate); `` These tools are used to validate the predicate value. The only parameter for these tools is a boolean predicate value that gets validated. It could be any expression that could be evaluated and converted to boolean value. The expression gets evaluated only once, so it's safe to pass complex expression for validation. [bt_example example34..BOOST_ usage] See also: * __BOOST_LEVEL_MESSAGE__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_bitwise_eq `BOOST__BITWISE_EQUAL`] `` BOOST_WARN_BITWISE_EQUAL(left, right); BOOST_CHECK_BITWISE_EQUAL(left, right); BOOST_REQUIRE_BITWISE_EQUAL(left, right); `` These tools are used to perform bitwise comparison of two values. The check shows all positions where left and right value's bits mismatch. The first parameter is the left compared value. The second parameter is the right compared value. Parameters are not required to be of the same type, but warning is issued if their type's size does not coincide. [bt_example example33..BOOST__BITWISE_EQUAL usage] See also: * __BOOST_LEVEL_EQUAL__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_eq `BOOST__EQUAL`] `` BOOST_WARN_EQUAL(left, right); BOOST_CHECK_EQUAL(left, right); BOOST_REQUIRE_EQUAL(left, right); `` Check performed by these tools is the same as the one performed by `__BOOST_LEVEL__(left == right)`. The difference is that the mismatched values are reported as well. [note It is bad idea to use these tools to compare floating point values. Use __BOOST_LEVEL_CLOSE__ or __BOOST_LEVEL_CLOSE_FRACTION__ tools instead. ] [bt_example example35..BOOST__EQUAL usage] See also: * __BOOST_LEVEL__ * __BOOST_LEVEL_CLOSE__ * __BOOST_LEVEL_NE__ * __BOOST_LEVEL_EQUAL_COLLECTIONS__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_eq_collections `BOOST__EQUAL_COLLECTIONS`] `` BOOST_WARN_EQUAL_COLLECTIONS(left_begin, left_end, right_begin, right_end); BOOST_CHECK_EQUAL_COLLECTIONS(left_begin, left_end, right_begin, right_end); BOOST_REQUIRE_EQUAL_COLLECTIONS(left_begin, left_end, right_begin, right_end); `` These tools are used to perform an element by element comparison of two collections. They print all mismatched positions, collection elements at these positions and check that the collections have the same size. The first two parameters designate begin and end of the first collection. The two last parameters designate begin and end of the second collection. [bt_example example36..BOOST__EQUAL_COLLECTIONS usage] See also: * __BOOST_LEVEL_EQUAL__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_close `BOOST__CLOSE`] `` BOOST_WARN_CLOSE(left, right, tolerance); BOOST_CHECK_CLOSE(left, right, tolerance); BOOST_REQUIRE_CLOSE(left, right, tolerance); `` These tools are used to check on closeness using strong relationship defined by the predicate ``check_is_close( left, right, tolerance )`` To check for the weak relationship use __BOOST_LEVEL_PREDICATE__ family of tools with explicit `check_is_close` invocation. The first parameter is the ['left] compared value. The second parameter is the ['right] compared value. Last third parameter defines the tolerance for the comparison in [link boost_test.users_guide.testing_tools.testing_floating_points [*percentage units]]. [note It is required for left and right parameters to be of the same floating point type. You will need to explicitly resolve any type mismatch to select which type to use for comparison. ] [note Note that to use these tools you need to include additional header `floating_point_comparison.hpp`. ] [bt_example example42..BOOST__CLOSE usage with small values] [bt_example example43..BOOST__CLOSE usage with big values] See also: * __BOOST_LEVEL_CLOSE_FRACTION__ * __BOOST_LEVEL_SMALL__ * __BOOST_LEVEL_EQUAL__ * __floating_points_testing_tools__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_close_fraction `BOOST__CLOSE_FRACTION`] `` BOOST_WARN_CLOSE_FRACTION(left, right, tolerance); BOOST_CHECK_CLOSE_FRACTION(left, right, tolerance); BOOST_REQUIRE_CLOSE_FRACTION(left, right, tolerance); `` These tools are used to check on closeness using strong relationship defined by the predicate ``check_is_close(left, right, tolerance)`` To check for the weak relationship use __BOOST_LEVEL_PREDICATE__ family of tools with explicit `check_is_close` invocation. The first parameter is the ['left] compared value. The second parameter is the ['right] compared value. Last third parameter defines the tolerance for the comparison as [link boost_test.users_guide.testing_tools.testing_floating_points [*fraction of absolute values being compared]]. [note It is required for left and right parameters to be of the same floating point type. You will need to explicitly resolve any type mismatch to select which type to use for comparison.] [note Note that to use these tools you need to include additional header `floating_point_comparison.hpp`.] [bt_example example44..BOOST__CLOSE_FRACTION usage] See also: * __BOOST_LEVEL_CLOSE__ * __BOOST_LEVEL_SMALL__ * __BOOST_LEVEL_EQUAL__ * __floating_points_testing_tools__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_exception `BOOST__EXCEPTION`] `` BOOST_WARN_EXCEPTION(expression, exception, predicate); BOOST_CHECK_EXCEPTION(expression, exception, predicate); BOOST_REQUIRE_EXCEPTION(expression, exception, predicate); `` These tools are used to perform an exception detection and validation check. Tools execute the supplied expression and validate that it throws an exception of supplied class (or the one derived from it) that complies with the supplied predicate. If the expression throws any other unrelated exception, doesn't throw at all or predicate evaluates to false, check fails. In comparison with __BOOST_LEVEL_THROW__ tools these allow performing more fine-grained checks. For example: make sure that an expected exception has specific error message. [bt_example example37..BOOST__EXCEPTION usage] See also: * __BOOST_LEVEL_THROW__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_ge `BOOST__GE`] `` BOOST_WARN_GE(left, right); BOOST_CHECK_GE(left, right); BOOST_REQUIRE_GE(left, right); `` Check performed by these tools is the same as the one performed by `__BOOST_LEVEL__( left >= right )`. The difference is that the argument values are reported as well. [bt_example example57..BOOST__GE usage] See also: * __BOOST_LEVEL_LE__ * __BOOST_LEVEL_LT__ * __BOOST_LEVEL_GT__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_gt `BOOST__GT`] `` BOOST_WARN_GT(left, right); BOOST_CHECK_GT(left, right); BOOST_REQUIRE_GT(left, right); `` Check performed by these tools is the same as the one performed by __BOOST_LEVEL__`( left > right )`. The difference is that the argument values are reported as well. [bt_example example58..BOOST__GT usage] See also: * __BOOST_LEVEL_LE__ * __BOOST_LEVEL_LT__ * __BOOST_LEVEL_GE__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_le `BOOST__LE`] `` BOOST_WARN_LE(left, right); BOOST_CHECK_LE(left, right); BOOST_REQUIRE_LE(left, right); `` Check performed by these tools is the same as the one performed by `__BOOST_LEVEL__( left <= right )`. The difference is that the argument values are reported as well. [bt_example example55..BOOST__LE usage] See also: * __BOOST_LEVEL_LE__ * __BOOST_LEVEL_GE__ * __BOOST_LEVEL_GT__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_lt `BOOST__LT`] `` BOOST_WARN_LT(left, right); BOOST_CHECK_LT(left, right); BOOST_REQUIRE_LT(left, right); `` Check performed by these tools is the same as the one performed by `__BOOST_LEVEL__( left < right )`. The difference is that the argument values are reported as well. [bt_example example56..BOOST__LT usage] See also: * __BOOST_LEVEL_LE__ * __BOOST_LEVEL_GE__ * __BOOST_LEVEL_GT__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_message `BOOST__MESSAGE`] `` BOOST_WARN_MESSAGE(predicate, message); BOOST_CHECK_MESSAGE(predicate, message); BOOST_REQUIRE_MESSAGE(predicate, message); `` These tools perform exactly the same check as __BOOST_LEVEL__ tools. The only difference is that instead of generating an error/confirm message these use the supplied one. The first parameter is the boolean expression. The second parameter is the message reported in case of check failure. The message argument can be constructed of components of any type supporting the `std::ostream& operator<<(std::ostream&)`. [bt_example example38..BOOST__MESSAGE usage] See also: * __BOOST_LEVEL__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_ne `BOOST__NE`] `` BOOST_WARN_NE(left, right); BOOST_CHECK_NE(left, right); BOOST_REQUIRE_NE(left, right); `` Check performed by these tools is the same as the one performed by `__BOOST___( left != right )`. The difference is that the matched values are reported as well. [bt_example example54..BOOST__NE usage] See also: * __BOOST_LEVEL_EQUAL__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_no_throw `BOOST__NO_THROW`] `` BOOST_WARN_NO_THROW(expression); BOOST_CHECK_NO_THROW(expression); BOOST_REQUIRE_NO_THROW(expression); `` These tools are used to perform a "no throw" check. Tools execute the supplied expression and validate that it does not throw any exceptions. Error would be reported by the framework even if the statement appear directly in test case body and throw any exception. But these tools allow proceeding further with test case in case of failure. If check is successful, tools may produce a confirmation message, in other case they produce an error message in a form ``error in ;exception was thrown by `` The only parameter is an expression to execute. You can use `do {} while(0)` block if you want to execute more than one statement. [bt_example example39..BOOST__NO_THROW usage] See also: * __BOOST_LEVEL_THROW__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_predicate `BOOST__PREDICATE`] `` BOOST_WARN_PREDICATE(predicate, arguments_list); BOOST_CHECK_PREDICATE(predicate, arguments_list); BOOST_REQUIRE_PREDICATE(predicate, arguments_list); `` These are generic tools used to validate an arbitrary supplied predicate functor (there is a compile time limit on predicate arity defined by the configurable macro `BOOST_TEST_MAX_PREDICATE_ARITY`). To validate zero arity predicate use __BOOST___ tools. In other cases prefer theses tools. The advantage of these tools is that they show arguments values in case of predicate failure. The first parameter is the predicate itself. The second parameter is the list of predicate arguments each wrapped in round brackets (`BOOST_PP` sequence format). [bt_example example40..BOOST__PREDICATE usage] [note Note difference in error log from __BOOST___] See also: * __BOOST_LEVEL__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_small `BOOST__SMALL`] `` BOOST_WARN_SMALL(value, tolerance); BOOST_CHECK_SMALL(value, tolerance); BOOST_REQUIRE_SMALL(value, tolerance); `` These tools are used to check that supplied value is small enough. The "smallness" is defined by absolute value of the tolerance supplied as a second argument. Use these tools with caution. To compare to values on closeness it's preferable to use __BOOST_LEVEL_CLOSE__ tools instead. The first parameter is the value to check. The second parameter is the tolerance. [note Note that to use these tools you need to include additional header `floating_point_comparison.hpp`.] [bt_example example41..BOOST__SMALL usage] See also: * __BOOST_LEVEL_CLOSE__ * __BOOST_LEVEL_CLOSE_FRACTION__ * __floating_points_testing_tools__ [endsect] [/ ###############################################################################################] [section:assertion_boost_level_throw `BOOST__THROW`] `` BOOST_WARN_THROW(expression, exception); BOOST_CHECK_THROW(expression, exception); BOOST_REQUIRE_THROW(expression, exception); `` These tools are used to perform an exception detection check. Tools execute the supplied expression and validate that it throws an exception of supplied class (or the one derived from it) or it's child. If the statement throws any other unrelated exception or doesn't throw at all, check fails. If check is successful, the tool produces a confirmation message, in other case it produces an error message in a form `` error in : exception expected `` The first parameter is the expression to execute. Use `do{} while(0)` block if you want to execute more than one statement. The second parameter is an expected exception. [bt_example example45..BOOST__THROW usage] See also: * __BOOST_LEVEL_NO_THROW__ [endsect] [/ ###############################################################################################] [section:assertion_boost_error `BOOST_ERROR`] `` BOOST_ERROR(message); `` __BOOST_ERROR__ tool behave the same way as `__BOOST_CHECK_MESSAGE__(false, message)`. This tool is used for an unconditional error counter increasing and message logging. The tool's only parameter is an error message to log. [bt_example example46..BOOST_ERROR usage] See also: * __BOOST_LEVEL__ [endsect] [/ ###############################################################################################] [section:assertion_boost_fail `BOOST_FAIL`] `` BOOST_FAIL(message); `` `__BOOST_FAIL__(message)` behave the same way as `__BOOST_REQUIRE_MESSAGE__(false, message)`. This tool is used for an unconditional error counter increasing, message logging and the current test case aborting. The tool's only parameter is an error message to log. [bt_example example47..BOOST_FAIL usage] See also: * __BOOST_LEVEL__ * __BOOST_LEVEL_MESSAGE__ [endsect] [/ ###############################################################################################] [section:assertion_boost_is_defined `BOOST_IS_DEFINED`] `` BOOST_IS_DEFINED(symbol); `` Unlike the rest of the tools in the toolbox this tool does not perform the logging itself. Its only purpose is to check at runtime whether or not the supplied preprocessor symbol is defined. Use it in combination with __BOOST___ to perform and log validation. Macros of any arity could be checked. To check the macro definition with non-zero arity specify dummy arguments for it. See below for example. The only tool's parameter is a preprocessor symbol that gets validated. [bt_example example48..BOOST_IS_DEFINED usage] See also: * __BOOST_LEVEL__ [endsect] [endsect] [/ testing_tool_ref]