ceph/src/boost/libs/test/doc/test_organization/managing_tests_dependencies.qbk

   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
  10 In general, you should make sure that test cases are independent on one another. For any two test cases `TA` and `TB`,
  11 `TB` must not take for granted that `TA` has already executed, even if `TA` is declared before `TB` in the same
  12 translation unit.
  13
  14 The only ordering-related guarantee that __UTF__ makes by default is that if test cases `TA` and `TB` are declared in the
  15 same test suite, no test case (call it `TX`) from any other test suite is executed between `TA` and `TB`, even if the
  16 declaration of `TX` appears between the declarations of `TA` and `TB`. In other words, all tests from a suite are
  17 executed in one go, even if the test suite namespace is opened multiple times.
  18
  19 Even though the order is not guaranteed, it may be accidentally preserved across the different runs. In order to make
  20 sure the test cases do not depend on one another, whoever runs the test module may provide a command-line argument
  21 [link boost_test.utf_reference.rt_param_reference.random `random`] to make sure the test units are shuffled within the suites.
  22
  23 [h3 Declaring a test case dependency]
  24
  25 If an ordering dependency is required between the test units within the same suite, it has to be declared explicitly.
  26 Dependencies in the __UTF__ affect two dimensions of test units, which are:
  27
  28 * the order of execution of these units
  29 * the execution of a test unit, which is conditioned by the state of its parents
  30
  31 [link boost_test.tests_organization.decorators Decorator] __decorator_depends_on__ associates the decorated test case
  32 (call it `TB`) with another test case (call it `TA`) specified by name. This affects the processing the test tree in two
  33 ways. First, test case `TA` is ordered to be run before `TB`, irrespective of the order in which they were declared or
  34 added to the test tree. Second, the execution of `TB` is skipped if `TA` is either disabled or skipped or is executed
  35 and marked as failed.
  36
  37
  38 [bt_example decorator_07..decorator depends_on..run-fail]
  39
  40 In the above scenario, test case `test3` is run (and fails) because `s1/test1` has been run and succeeded; `test4` is
  41 skipped because `test3` has failed; `test5` is skipped because `s1/test2` is disabled.
  42
  43
  44 [/-----------------------------------------------------------------]
  45
  46 [endsect]