boost/test
2
0
Fork 0
mirror of https://github.com/boostorg/test.git synced 2026-02-15 13:32:09 +00:00
Code Issues Projects Releases Wiki Activity

BOOST_TEST doc reorg continued

Browse Source
This commit is contained in:
Raffi Enficiaud
2015-05-29 10:14:16 +02:00
parent 8927ce6176
commit d0909211dc
8 changed files with 66 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/examples/CMakeLists.txt
View File

@@ -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)

23
doc/examples/boost_test_macro_overview.cpp Normal file
View File

@@ -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/test/included/unit_test.hpp>
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));
}
//]

17
doc/examples/boost_test_macro_overview.output Normal file
View File

@@ -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"
//]

52
doc/testing_tools/boost_test_acceptable_statements.qbk
View File

@@ -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]

2
doc/testing_tools/boost_test_collection_comparison.qbk
View File

@@ -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() );

32
doc/testing_tools/boost_test_universal_macro.qbk
View File

@@ -13,35 +13,41 @@ macro. The general form of `BOOST_TEST` is the following:
BOOST_TEST(statement);
BOOST_TEST_<level>(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

6
doc/testing_tools/testing_tools_reference.qbk
View File

@@ -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]