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, it is a good practice to write any test as independent as possible from any other, there are however cases where a dependency cannot be avoided and an order for executing the tests is needed. In the general setup and for any two test cases `TA` and `TB`, `TB` should 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 accidentally be preserved across the different runs. In order to make sure the test cases do not depend on one another, the test module may be called with an additional command-line argument, [link boost_test.utf_reference.rt_param_reference.random `random`], to shuffle the tests unit ordering and to be more robust against an erroneous implicit ordering. [h3 Declaring a test case dependency] If there exist a dependency between test units, and an ordering is required between the execution of those tests, 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]