libs/test/doc/test_organization/test_enabling_disabling.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 [section:enabling Enabling or disabling test unit execution]
   9
  10 The __UTF__ provides a way for enabling or disabling a test unit execution. If a test case is disabled, it will not be
  11 run by the test runner. If a test suite is disabled, its status is inherited by the test units under its subtree, unless
  12 otherwise specified.
  13
  14 The run status can be overridden by the command line parameters: by providing the appropriate arguments to the command
  15 line, a disabled test may still be executed. The [link boost_test.runtime_config.test_unit_filtering test unit
  16 filtering] section covers this feature in details.
  17
  18 [warning There is a difference between a disabled test and a skipped test:
  19
  20   * a disabled test has a run status set to disabled, and is completely discarded by the __UTF__.
  21   * a skipped test is a test that has a run status set to enabled, but which execution has been skipped at runtime.
  22 ]
  23
  24 [h3 Unconditional run status]
  25 Decorator __decorator_disabled__ indicates that the test unit's __default_run_status__ is ['false]. This means that that
  26 test cases inside this test unit will not be run by default, unless otherwise specified. Decorator __decorator_enabled__
  27 indicates that the test unit's default run status is ['true]. This means that that test cases inside this test unit will
  28 be run by default, unless otherwise specified.
  29
  30 [bt_example decorator_05..decorators enabled and disabled..run-fail]
  31
  32 Syntactically, it is possible to apply both decorators `enabled` and `disabled` to the same test unit. This is reported
  33 as set-up error when the test program is run.
  34
  35 [h3 Compilation-time run status]
  36
  37 Decorator __decorator_enable_if__ indicates that the test unit's __default_run_status__ is either ['true] or ['false],
  38 depending on the value of `Condition`. This means that that test cases inside this test unit will or will not be run by
  39 default.
  40
  41
  42 [bt_example decorator_06..decorator enable_if..run-fail]
  43
  44 Decorator `enable_if<true>()` is equivalent to decorator `enabled()`. Similarly, `enable_if<false>()` is equivalent to
  45 decorator `disabled()`.
  46
  47 [/-----------------------------------------------------------------]
  48 [h3 Runtime run status]
  49
  50 Decorator __decorator_precondition__ associates a ['predicate] with a test unit. Before the test unit is executed, the
  51 predicate is evaluated with the test unit's ID passed as the argument. If it evaluates to `false`, execution of the test
  52 unit is skipped. Skipping a test suite means skipping the execution of every test unit inside.
  53
  54 [tip The precondition may return an [classref boost::test_tools::assertion_result assertion_result] instead of a boolean.
  55  In that case, the message contained in the `assertion_result` will be printed by the __UTF__.]
  56
  57 [bt_example decorator_08..decorator precondition..run-fail]
  58
  59 In the example above, the user defined a custom predicate `if_either` that evaluates to `true` if at least one of the two
  60 specified tests passed. (It assumes that the tests are registered in the specific order.)
  61
  62 * Test case `test3` has a precondition that at either `test1` or `test2` passed. The precondition is satisfied,
  63   therefore `test3` is run (and fails),
  64 * test case `test4` has a precondition that either `test2` or `test3` passed. Since they both failed, the
  65   precondition is not satisfied, therefore `test4` is skipped.
  66
  67 [note A __decorator_precondition__ that evaluates to `false` does not yield an error and does not fail the attached unit test. However
  68  the __UTF__ returns an error if the test tree is empty (see [link boost_test.tests_organization.test_tree.test_tree_content this section]
  69  for more details). ]
  70
  71 [endsect]