]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | [h3 Unconditional run status] | |
19 | Decorator __decorator_disabled__ indicates that the test unit's __default_run_status__ is ['false]. This means that that | |
20 | test cases inside this test unit will not be run by default, unless otherwise specified. Decorator __decorator_enabled__ | |
21 | indicates that the test unit's default run status is ['true]. This means that that test cases inside this test unit will | |
22 | be run by default, unless otherwise specified. | |
23 | ||
24 | [bt_example decorator_05..decorators enabled and disabled..run-fail] | |
25 | ||
26 | Syntactically, it is possible to apply both decorators `enabled` and `disabled` to the same test unit. This is reported | |
27 | as set-up error when the test program is run. | |
28 | ||
29 | [h3 Compilation-time run status] | |
30 | ||
31 | Decorator __decorator_enable_if__ indicates that the test unit's __default_run_status__ is either ['true] or ['false], | |
32 | depending on the value of `Condition`. This means that that test cases inside this test unit will or will not be run by | |
33 | default. | |
34 | ||
35 | ||
36 | [bt_example decorator_06..decorator enable_if..run-fail] | |
37 | ||
38 | Decorator `enable_if<true>()` is equivalent to decorator `enabled()`. Similarly, `enable_if<false>()` is equivalent to | |
39 | decorator `disabled()`. | |
40 | ||
41 | [/-----------------------------------------------------------------] | |
42 | [h3 Runtime run status] | |
43 | ||
44 | Decorator __decorator_precondition__ associates a ['predicate] with a test unit. Before the test unit is executed, the | |
45 | predicate is evaluated with the test unit's ID passed as the argument. If it evaluates to `false`, execution of the test | |
46 | unit is skipped. Skipping the test suite means skipping the execution of every test unit inside. | |
47 | ||
48 | [bt_example decorator_08..decorator precondition..run-fail] | |
49 | ||
50 | In the example above, the user defined a custom predicate `if_either` that evaluates to `true` if at least one of the two | |
51 | specified tests passed. (It assumes that the tests are registered in the specific order.) Test case `test3` has a | |
52 | precondition that at either `test1` or `test2` passed. The precondition is satisfied, therefore `test3` is run (and | |
53 | fails). Test case `test4` has a precondition that either `test2` or `test3` passed. Since they both failed, the | |
54 | precondition is not satisfied, therefore `test4` is skipped. | |
55 | ||
56 | [endsect] |