libs/test/doc/testing_tools/assertions_severity_levels.qbk

   1 [/
   2  / Copyright (c) 2003 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
   9 [section:tools_assertion_severity_level Assertion severity level]
  10
  11 There are three *levels* of assertions and all the testing tools are supplied in these three flavours/levels. These levels
  12 have different meaning on the consistency of the test case:
  13
  14 * `REQUIRE` which implements a *requirements* : this is a strong condition for the operations following the assertion to be valid.
  15   This type of assertions should be used when a pre-condition for running the test is not met or when the test-case cannot continue.
  16   If such as assertion fails, the test case execution stops immediately, and the test-case is flagged as /failed/.
  17 * `CHECK` for standard *checks*: this is the most commonly used assertion level. If the statement evaluates to `false`, the test case is
  18   flagged as failed but its execution continues.
  19 * `WARN` which stands for *warnings*: this is an assertion providing information. The test case execution continues and a warning message is logged.
  20   The warning does not change the success status of a test case. This level of assertion can be used
  21   to validate aspects less important then correctness: performance, portability, usability, etc.
  22
  23 For example:
  24
  25 * [link boost_test.utf_reference.testing_tool_ref.assertion_boost_level_throw `BOOST_REQUIRE_THROW`], __BOOST_TEST_REQUIRE__
  26 * `BOOST_CHECK_THROW`, `BOOST_TEST` [footnote __BOOST_TEST__ is equivalent to `BOOST_TEST_CHECK`]
  27 * `BOOST_WARN_THROW`, `BOOST_TEST_WARN`
  28
  29 These three levels of assertions are filtered by the framework and reported into the test log and output:
  30
  31 # If an assertion designated by the tool passes, confirmation message can be printed in log output
  32   [footnote to manage what messages appear in the test log stream, set the proper [link boost_test.utf_reference.rt_param_reference.log_level `log_level`]].
  33 # If an assertion designated by the tool fails, the following will happen, depending on the assertion level
  34   [footnote in some cases log message can be slightly different to reflect failed tool specifics, see [link boost_test.testing_tools.reports here]]:
  35
  36 [table:assertions_severity_levels Assertions severity levels
  37   [
  38     [Level]
  39     [Test log content]
  40     [Errors counter]
  41     [Test execution]
  42   ]
  43
  44   [
  45     [WARN]
  46     [warning in `<test-case-name>`: condition `<assertion description>` is not satisfied]
  47     [not affected]
  48     [continues]
  49   ]
  50   [
  51     [CHECK]
  52     [error in `<test-case-name>`: test `<assertion description>` failed]
  53     [increased]
  54     [continues]
  55   ]
  56   [
  57     [REQUIRE]
  58     [fatal error in `<test-case-name>`: critical test `<assertion description>` failed]
  59     [increased]
  60     [aborts]
  61   ]
  62 ]
  63
  64 The granularity of the report depends on the current [link boost_test.utf_reference.rt_param_reference.log_level log level] and
  65 [link boost_test.utf_reference.rt_param_reference.report_level report level].
  66
  67 [note in the above table, the ['test execution] is related to the current test case ['only]. Hence ['"aborts"] means
  68  that the current test case is aborted, but other test cases in the test tree are still executed.]
  69
  70 [endsect] [/ assertions severity level]