diff --git a/doc/examples/CMakeLists.txt b/doc/examples/CMakeLists.txt index a16d9982..34fa51c2 100644 --- a/doc/examples/CMakeLists.txt +++ b/doc/examples/CMakeLists.txt @@ -22,6 +22,7 @@ set(EXAMPLES_SRC # source files needing variadic macros set(EXAMPLES_VARIADIC_MACROS_SRC + boost_test_macro_overview.cpp boost_test_macro1.cpp boost_test_macro2.cpp boost_test_macro3.cpp @@ -33,8 +34,6 @@ set(EXAMPLES_VARIADIC_MACROS_SRC boost_test_sequence_per_element.cpp boost_test_container_lex.cpp boost_test_macro_container_c_array.cpp - - test_float_04.cpp ) if(CMAKE_CXX_COMPILER_ID STREQUAL Clang) diff --git a/doc/examples/boost_test_macro_overview.cpp b/doc/examples/boost_test_macro_overview.cpp new file mode 100644 index 00000000..bf8f9457 --- /dev/null +++ b/doc/examples/boost_test_macro_overview.cpp @@ -0,0 +1,23 @@ +// (C) Copyright Raffi Enficiaud 2014. +// 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) + +// See http://www.boost.org/libs/test for the library home page. + +//[example_code +#define BOOST_TEST_MODULE boost_test_macro_overview +#include + +BOOST_AUTO_TEST_CASE( test_macro_overview ) +{ + namespace tt = boost::test_tools; + int a = 1; + int b = 2; + BOOST_TEST(a != b - 1); + BOOST_TEST(a + 1 < b); + BOOST_TEST(b -1 > a, a << " < " << b - 1 << " does not hold"); + BOOST_TEST(a == b, tt::bitwise()); + BOOST_TEST(a + 0.1 == b - 0.8, tt::tolerance(0.01)); +} +//] diff --git a/doc/examples/boost_test_macro_overview.output b/doc/examples/boost_test_macro_overview.output new file mode 100644 index 00000000..96803a7e --- /dev/null +++ b/doc/examples/boost_test_macro_overview.output @@ -0,0 +1,17 @@ +//[example_output +> ./boost_test_macro_overview --log_level=all +Running 1 test case... +Entering test module "boost_test_macro_overview" +test.cpp:12: Entering test case "test_macro_overview" +test.cpp:17: error: in "test_macro_overview": check a != b - 1 has failed [1 == 1] +test.cpp:18: error: in "test_macro_overview": check a + 1 < b has failed [1 + 1 >= 2] +test.cpp:19: error: in "test_macro_overview": 1 < 1 does not hold +test.cpp:20: error: in "test_macro_overview": check a == b has failed [1 != 2]. Bitwise comparison failed +Mismatch at position 0 +Mismatch at position 1 +test.cpp:21: error: in "test_macro_overview": check a + 0.1 == b - 0.8 has failed [1 + 0.10000000000000001 != 1.2]. Relative difference exceeds tolerance [0.0909091 > 0.01] +test.cpp:12: Leaving test case "test_macro_overview"; testing time: 380us +Leaving test module "boost_test_macro_overview"; testing time: 459us + +*** 5 failures are detected in the test module "boost_test_macro_overview" +//] diff --git a/doc/testing_tools/boost_test_acceptable_statements.qbk b/doc/testing_tools/boost_test_acceptable_statements.qbk deleted file mode 100644 index b1a7701b..00000000 --- a/doc/testing_tools/boost_test_acceptable_statements.qbk +++ /dev/null @@ -1,52 +0,0 @@ -[/ - / Copyright (c) 2015 Boost.Test team - / - / 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:acceptable_statements Acceptable statements] - - - -* `statement` above may be almost anything: in particular it might contain a full expression composed by several operations, -* `statement` is cast to a `bool`, as if it would appear as argument to an `if` statement: this is the result of the assertion, -* `optional_modifiers` may be: - * a [link boost_test.testing_tools.reports custom message] printed in case of failure - * additional control over how comparisons are performed (floating point, collections, type of report) - -`BOOST_TEST` assertion uses operator overloading in order to provide an enhanced reporting capability, as -shown on the example below: - -[bt_example boost_test_macro3..BOOST_TEST enhanced reporting] - -As it can be seen, additional details are provided in log. This is possible for almost all overloadable operators in C++: - -[table - [[Class of operation][operators]] - [[binary comparisons][`==`, `!=`, `<`, `>`, `<=`, `>=`]] - [[arithmetic compositions][`+`, `-`, `*`, `/`, `%`]] - [[bitwise compositions][`|`, `&`, `^`, `<<`, `>>`]] - [[assignments][`=`, `+=`, `-=`, `*=`, `/=`, `%=`, `<<=`, `>>=`, `&=`, `^=`, `|=`]] -] - - -There are a few constructions that are however unsupported, but adding an extra bracket usually solves that: - -* statements containing ternary conditions: those statement should be surrounded by parenthesis as they cannot be overloaded -* statements containing commas: those statements will be intercepted by the preprocessor -* compound statements containing any logical composition `||`, `&&`. Those are disabled intentionally and should be surrounded - by parenthesis - - BOOST_TEST((true || false)); - - The full details are given in [link boost_test.testing_tools.internal_details this section]. - -[bt_example boost_test_macro1..BOOST_TEST acceptable expressions] - - - - - -[endsect] diff --git a/doc/testing_tools/boost_test_collection_comparison.qbk b/doc/testing_tools/boost_test_collection_comparison.qbk index 8bfa3721..97755d2f 100644 --- a/doc/testing_tools/boost_test_collection_comparison.qbk +++ b/doc/testing_tools/boost_test_collection_comparison.qbk @@ -46,7 +46,7 @@ the /sequences/ of elements generated by the containers, for which the __UTF__ p In more details, let `c_a = (a_1,... a_n)` and `c_b = (b_1,... b_n)` be two sequences of same length, but not necessarily of same type. Those sequences correspond to the content of the respective containers, in the order given by their iterator. Let -`op` be one of the [link boost_test.testing_tools.acceptable_statements binary comparison operators]. +`op` be one of the [link boost_test_statement_overloads binary comparison operators]. `` BOOST_TEST(c_a op c_b, boost::test_tools::per_element() ); diff --git a/doc/testing_tools/boost_test_universal_macro.qbk b/doc/testing_tools/boost_test_universal_macro.qbk index 49b98ee0..facbe91c 100644 --- a/doc/testing_tools/boost_test_universal_macro.qbk +++ b/doc/testing_tools/boost_test_universal_macro.qbk @@ -13,35 +13,41 @@ macro. The general form of `BOOST_TEST` is the following: BOOST_TEST(statement); BOOST_TEST_(statement, optional_modifiers) +An example of use might be the following: + +[bt_example boost_test_macro_overview..BOOST_TEST overview] + The major features of this tool are: * a great flexibility for `statement` which may be almost anything: full expression composed by several operations are supported and handled, -* an extended reporting capability in case of failure: not only `BOOST_TEST` reports the location of the failure and the `statement`, +* an extended reporting capability in case of failure: not only `BOOST_TEST` reports the location of the failure and a copy of `statement` itself, but also the values of the operands that permits a rapid identification of the issues related to the failed assertion, * the possibility to control better the behaviour or the reports of the checks, in particular: - * floating point comparison: the tolerance may be provided, either using - `optional_modifiers` directly or /decorators/ (see [link boost_test.testing_tools.extended_comparison.floating_point here] + * floating point comparison: the tolerance may be provided, either using the `BOOST_TEST` + directly with `optional_modifiers`, or with /decorators/ (see [link boost_test.testing_tools.extended_comparison.floating_point here] for more details), - * container/collection comparisons: different operations for comparison are provided out of the box, + * container/collection comparisons: different operations for comparison are provided out of the box for comparing collection of + elements (default, per-element, lexicographic), with extended diagnostic on failures (covered in + [link boost_test.testing_tools.extended_comparison.collections this] section), * string comparison: C-strings operands are automatically detected and the comparisons are performed as if `std::string` objects were used, * optional failure message, - * bitwise comparison + * bitwise comparison, providing extended diagnostic in case of failure [warning To get all the functionalities of `BOOST_TEST` family of assertions, a C++11 capable compiler is required, especially supporting the `auto` and `decltype` keywords and the variadic macros. The documentation focuses on these set of compilers. A limited support is provided for C++03 compilers.] - -[h3 Examples] -`BOOST_TEST` assertion uses operator overloading in order to provide an enhanced reporting capability, as -shown on the example below: +[#boost_test_statement_overloads][h3 Complex statements] +`BOOST_TEST` provides an enhanced reporting capability: additional details of the failing operands and operations are provided in the log, +as shown on the example below: [bt_example boost_test_macro3..BOOST_TEST enhanced reporting] -As it can be seen, additional details are provided in log. This is possible for almost all overloadable operators in C++: +`BOOST_TEST` parses the `statement` and constructs an expression out of it. `statement` may be a complex expressions +containing almost any of the overloadable operators in C++: [table [[Class of operation][operators]] @@ -49,7 +55,9 @@ As it can be seen, additional details are provided in log. This is possible for [[arithmetic compositions][`+`, `-`, `*`, `/`, `%`]] [[bitwise compositions][`|`, `&`, `^`, `<<`, `>>`]] [[assignments][`=`, `+=`, `-=`, `*=`, `/=`, `%=`, `<<=`, `>>=`, `&=`, `^=`, `|=`]] -] +] + +`statement` is evaluated and cast to `bool`, as if it would appear as argument to an `if` statement: this is the result of the assertion [h3 Uniform reporting] This tool is provided in three variants corresponding to the corresponding @@ -58,7 +66,7 @@ reported into the test log and output, as described in details in the section. T report depends on the current [link boost_test.utf_reference.rt_param_reference.log_level log level] and [link boost_test.utf_reference.rt_param_reference.report_level report level]. -[h3 Limitations] +[#boost_test_statement_limitations][h3 Limitations & workaround] There are a few constructions that are however unsupported, but adding an extra bracket usually solves that: * statements containing ternary conditions: those statement should be surrounded by parenthesis as they cannot be overloaded diff --git a/doc/testing_tools/testing_tools_reference.qbk b/doc/testing_tools/testing_tools_reference.qbk index dcb1b56e..1431749c 100644 --- a/doc/testing_tools/testing_tools_reference.qbk +++ b/doc/testing_tools/testing_tools_reference.qbk @@ -59,9 +59,9 @@ The macro is available in three variants, corresponding to different [link boost * [classref boost::test_tools::lexicographic] is a manipulator indicating that the comparison should be performed with the lexicographic order. See [link boost_test_coll_default_lex this section] for more details -[h3 Restrictions on the acceptable statements] -There are some restrictions on the supported statements. Those are explained in details in -[link boost_test.testing_tools.acceptable_statements this] section. +[h3 Limitations and workaround] +There are some restrictions on the statements that are supported by this tool. Those are explained in details in +[link boost_test_statement_limitations this] section. [endsect] diff --git a/test/Jamfile.v2 b/test/Jamfile.v2 index 008f605f..92d05330 100644 --- a/test/Jamfile.v2 +++ b/test/Jamfile.v2 @@ -168,6 +168,7 @@ test-suite "unit_test_framework_test" [ test-btl-doc-example-as-test run-fail : dataset_example68 ] # examples in BOOST_TEST + [ test-btl-doc-example-as-test run-fail : boost_test_macro_overview ] [ test-btl-doc-example-as-test run : boost_test_macro1 ] [ test-btl-doc-example-as-test run-fail : boost_test_macro2 ] [ test-btl-doc-example-as-test run-fail : boost_test_macro3 ]