1[/ 2 / Copyright (c) 2015 Raffi Enficiaud 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:tests_dependencies Managing test dependencies] 9 10In general, it is a good practice to write any test as independent as possible from any other, there are however 11cases where a dependency cannot be avoided and an order for executing the tests is needed. 12 13In the general setup and for any two test cases `TA` and `TB`, `TB` should not take for granted that `TA` has already 14executed, even if `TA` is declared before `TB` in the same translation unit. 15The only ordering-related guarantee that __UTF__ makes by default is that if test cases `TA` and `TB` are declared in the 16same test suite, no test case (call it `TX`) from any other test suite is executed between `TA` and `TB`, even if the 17declaration of `TX` appears between the declarations of `TA` and `TB`. In other words, all tests from a suite are 18executed in one go, even if the test suite namespace is opened multiple times. 19 20Even though the order is not guaranteed, it may accidentally be preserved across the different runs. In order to make 21sure the test cases do not depend on one another, the test module may be called with an additional command-line argument, 22[link boost_test.utf_reference.rt_param_reference.random `random`], to shuffle the tests unit ordering and to be more 23robust against an erroneous implicit ordering. 24 25[h3 Declaring a test case dependency] 26 27If there exist a dependency between test units, and an ordering is required between the execution of those tests, 28it has to be declared explicitly. 29Dependencies in the __UTF__ affect two dimensions of test units, which are: 30 31* the order of execution of these units 32* the execution of a test unit, which is conditioned by the state of its parents 33 34[link boost_test.tests_organization.decorators Decorator] __decorator_depends_on__ associates the decorated test case 35(call it `TB`) with another test case (call it `TA`) specified by name. This affects the processing the test tree in two 36ways: 37 38# first, test case `TA` is ordered to be run before `TB`, irrespective of the order in which they were declared or 39 added to the test tree, 40# second, the execution of `TB` is skipped if `TA` is either disabled or skipped or is executed 41 and marked as failed. 42 43[bt_example decorator_07..decorator depends_on..run-fail] 44 45In the above scenario: 46 47* test case `test3` is run (and fails) because `s1/test1` has been run and succeeded, 48* `test4` is skipped because `test3` has failed, 49* `test5` is skipped because `s1/test2` is disabled. 50 51 52[/-----------------------------------------------------------------] 53 54[endsect] 55