]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2015 Boost.Test contributors | |
3 | / | |
4 | / Distributed under the Boost Software License, Version 1.0. (See accompanying | |
5 | / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
6 | /] | |
7 | ||
8 | [section:boost_test_universal_macro BOOST_TEST: universal and general purpose assertions] | |
9 | ||
10 | The __UTF__ provides an almost unique interface to a great range of test-case scenarios, through the __BOOST_TEST__ | |
11 | macro. The general form of `BOOST_TEST` is the following: | |
12 | ||
13 | BOOST_TEST(statement); | |
14 | BOOST_TEST_<level>(statement, optional_modifiers) | |
15 | ||
16 | An example of use might be the following: | |
17 | ||
18 | [bt_example boost_test_macro_overview..BOOST_TEST overview..run-fail] | |
19 | ||
20 | The major features of this tool are: | |
21 | ||
22 | * a great flexibility for `statement` which may be almost anything: full expression composed by several operations are supported | |
23 | and handled, | |
24 | * an extended reporting capability in case of failure: not only `BOOST_TEST` reports the location of the failure and a copy of `statement` itself, | |
25 | but also the values of the operands that permits a rapid identification of the issues related to the failed assertion, | |
26 | * the possibility to control better the behavior or the reports of the checks, in particular: | |
27 | ||
28 | * floating point comparison: the tolerance may be provided, either using the `BOOST_TEST` | |
29 | directly with `optional_modifiers`, or with /decorators/ (see [link boost_test.testing_tools.extended_comparison.floating_point here] | |
30 | for more details), | |
31 | * container/collection comparisons: different operations for comparison are provided out of the box for comparing collection of | |
32 | elements (default, per-element, lexicographic), with extended diagnostic on failures (covered in | |
33 | [link boost_test.testing_tools.extended_comparison.collections this] section), | |
34 | * string comparison: C-strings operands are automatically detected and the comparisons are performed as if `std::string` objects | |
35 | were used, | |
36 | * optional failure message, | |
37 | * bitwise comparison, providing extended diagnostic in case of failure | |
38 | ||
39 | [warning To get all the functionalities of `BOOST_TEST` family of assertions, a C++11 capable compiler is required, especially | |
40 | supporting the `auto` and `decltype` keywords and the variadic macros. The documentation focuses on these set of compilers. | |
41 | For compilers not supporting all the features of `BOOST_TEST`, the macro `BOOST_TEST_MACRO_LIMITED_SUPPORT`.] | |
42 | ||
43 | [#boost_test_statement_overloads][h3 Complex statements] | |
44 | `BOOST_TEST` provides an enhanced reporting capability: additional details of the failing operands and operations are provided in the log, | |
45 | as shown on the example below: | |
46 | ||
47 | [bt_example boost_test_macro3..BOOST_TEST enhanced reporting..run-fail] | |
48 | ||
49 | `BOOST_TEST` parses the `statement` and constructs an expression out of it. `statement` may be a complex expressions | |
50 | containing almost any of the overloadable operators in C++: | |
51 | ||
52 | [table | |
53 | [[Class of operation][operators]] | |
54 | [[binary comparisons][`==`, `!=`, `<`, `>`, `<=`, `>=`]] | |
55 | [[arithmetic compositions][`+`, `-`, `*`, `/`, `%`]] | |
56 | [[bitwise compositions][`|`, `&`, `^`, `<<`, `>>`]] | |
57 | [[assignments][`=`, `+=`, `-=`, `*=`, `/=`, `%=`, `<<=`, `>>=`, `&=`, `^=`, `|=`]] | |
58 | ] | |
59 | ||
60 | `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 | |
61 | ||
62 | [h3 Uniform reporting] | |
63 | This tool is provided in three variants corresponding to the corresponding | |
64 | [link boost_test.testing_tools.tools_assertion_severity_level severity levels]. These three levels of assertions are | |
65 | reported into the test log and output, as described in details in the section. The granularity of the | |
66 | report depends on the current [link boost_test.utf_reference.rt_param_reference.log_level log level] and | |
67 | [link boost_test.utf_reference.rt_param_reference.report_level report level]. | |
68 | ||
69 | [#boost_test_statement_limitations][h3 Limitations & workaround] | |
70 | There are a few constructions that are however unsupported, but adding an extra bracket usually solves that: | |
71 | ||
72 | * statements containing ternary conditions: those statement should be surrounded by parenthesis as they cannot be overloaded | |
73 | * statements containing commas: those statements will be intercepted by the preprocessor | |
74 | * compound statements containing any logical composition `||`, `&&`. Those are disabled intentionally and should be surrounded | |
75 | by parenthesis | |
76 | ||
77 | BOOST_TEST((true || false)); | |
78 | ||
79 | The full details are given in [link boost_test.testing_tools.internal_details this section]. | |
80 | ||
81 | [bt_example boost_test_macro_workaround..BOOST_TEST limitation and workaround..run] | |
82 | ||
83 | ||
84 | [endsect] [/ boost_test_universal_macro] |