bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / libs / test / doc / test_organization / managing_tests_dependencies.qbk

[/
 / Copyright (c) 2015 Raffi Enficiaud
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:tests_dependencies Managing test dependencies]

In general, you should make sure that test cases are independent on one another. For any two test cases `TA` and `TB`,
`TB` must not take for granted that `TA` has already executed, even if `TA` is declared before `TB` in the same
translation unit.

The only ordering-related guarantee that __UTF__ makes by default is that if test cases `TA` and `TB` are declared in the
same test suite, no test case (call it `TX`) from any other test suite is executed between `TA` and `TB`, even if the
declaration of `TX` appears between the declarations of `TA` and `TB`. In other words, all tests from a suite are
executed in one go, even if the test suite namespace is opened multiple times.

Even though the order is not guaranteed, it may be accidentally preserved across the different runs. In order to make
sure the test cases do not depend on one another, whoever runs the test module may provide a command-line argument
[link boost_test.utf_reference.rt_param_reference.random `random`] to make sure the test units are shuffled within the suites.

[h3 Declaring a test case dependency]

If an ordering dependency is required between the test units within the same suite, it has to be declared explicitly.
Dependencies in the __UTF__ affect two dimensions of test units, which are:

* the order of execution of these units
* the execution of a test unit, which is conditioned by the state of its parents

[link boost_test.tests_organization.decorators Decorator] __decorator_depends_on__ associates the decorated test case
(call it `TB`) with another test case (call it `TA`) specified by name. This affects the processing the test tree in two
ways. First, test case `TA` is ordered to be run before `TB`, irrespective of the order in which they were declared or
added to the test tree. Second, the execution of `TB` is skipped if `TA` is either disabled or skipped or is executed
and marked as failed.


[bt_example decorator_07..decorator depends_on..run-fail]

In the above scenario, test case `test3` is run (and fails) because `s1/test1` has been run and succeeded; `test4` is 
skipped because `test3` has failed; `test5` is skipped because `s1/test2` is disabled.


[/-----------------------------------------------------------------]

[endsect]