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 10The __UTF__ provides a way for enabling or disabling a test unit execution. If a test case is disabled, it will not be 11run by the test runner. If a test suite is disabled, its status is inherited by the test units under its subtree, unless 12otherwise specified. 13 14The run status can be overridden by the command line parameters: by providing the appropriate arguments to the command 15line, a disabled test may still be executed. The [link boost_test.runtime_config.test_unit_filtering test unit 16filtering] 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] 25Decorator __decorator_disabled__ indicates that the test unit's __default_run_status__ is ['false]. This means that that 26test cases inside this test unit will not be run by default, unless otherwise specified. Decorator __decorator_enabled__ 27indicates that the test unit's default run status is ['true]. This means that that test cases inside this test unit will 28be run by default, unless otherwise specified. 29 30[bt_example decorator_05..decorators enabled and disabled..run-fail] 31 32Syntactically, it is possible to apply both decorators `enabled` and `disabled` to the same test unit. This is reported 33as set-up error when the test program is run. 34 35[h3 Compilation-time run status] 36 37Decorator __decorator_enable_if__ indicates that the test unit's __default_run_status__ is either ['true] or ['false], 38depending on the value of `Condition`. This means that that test cases inside this test unit will or will not be run by 39default. 40 41 42[bt_example decorator_06..decorator enable_if..run-fail] 43 44Decorator `enable_if<true>()` is equivalent to decorator `enabled()`. Similarly, `enable_if<false>()` is equivalent to 45decorator `disabled()`. 46 47[/-----------------------------------------------------------------] 48[h3 Runtime run status] 49 50Decorator __decorator_precondition__ associates a ['predicate] with a test unit. Before the test unit is executed, the 51predicate is evaluated with the test unit's ID passed as the argument. If it evaluates to `false`, execution of the test 52unit 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 59In the example above, the user defined a custom predicate `if_either` that evaluates to `true` if at least one of the two 60specified 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] 72