ceph/src/boost/libs/test/doc/testing_tools/boost_test_universal_macro.qbk

   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]