Help/prop_test/FIXTURES_REQUIRED.rst

   1 FIXTURES_REQUIRED
   2 -----------------
   3
   4 .. versionadded:: 3.7
   5
   6 Specifies a list of fixtures the test requires. Fixture names are case
   7 sensitive and they are not required to have any similarity to test names.
   8
   9 Fixtures are a way to attach setup and cleanup tasks to a set of tests. If a
  10 test requires a given fixture, then all tests marked as setup tasks for that
  11 fixture will be executed first (once for the whole set of tests, not once per
  12 test requiring the fixture). After all tests requiring a particular fixture
  13 have completed, CTest will ensure all tests marked as cleanup tasks for that
  14 fixture are then executed. Tests are marked as setup tasks with the
  15 :prop_test:`FIXTURES_SETUP` property and as cleanup tasks with the
  16 :prop_test:`FIXTURES_CLEANUP` property. If any of a fixture's setup tests fail,
  17 all tests listing that fixture in their ``FIXTURES_REQUIRED`` property will not
  18 be executed. The cleanup tests for the fixture will always be executed, even if
  19 some setup tests fail.
  20
  21 When CTest is asked to execute only a subset of tests (e.g. by the use of
  22 regular expressions or when run with the :option:`--rerun-failed <ctest --rerun-failed>`
  23 command line option), it will automatically add any setup or cleanup tests for
  24 fixtures required by any of the tests that are in the execution set. This
  25 behavior can be overridden with the :option:`-FS <ctest -FS>`,
  26 :option:`-FC <ctest -FC>` and :option:`-FA <ctest -FA>` command line options to
  27 :manual:`ctest(1)` if desired.
  28
  29 Since setup and cleanup tasks are also tests, they can have an ordering
  30 specified by the :prop_test:`DEPENDS` test property just like any other tests.
  31 This can be exploited to implement setup or cleanup using multiple tests for a
  32 single fixture to modularise setup or cleanup logic.
  33
  34 The concept of a fixture is different to that of a resource specified by
  35 :prop_test:`RESOURCE_LOCK`, but they may be used together. A fixture defines a
  36 set of tests which share setup and cleanup requirements, whereas a resource
  37 lock has the effect of ensuring a particular set of tests do not run in
  38 parallel. Some situations may need both, such as setting up a database,
  39 serializing test access to that database and deleting the database again at the
  40 end. For such cases, tests would populate both ``FIXTURES_REQUIRED`` and
  41 :prop_test:`RESOURCE_LOCK` to combine the two behaviors. Names used for
  42 :prop_test:`RESOURCE_LOCK` have no relationship with names of fixtures, so note
  43 that a resource lock does not imply a fixture and vice versa.
  44
  45 Consider the following example which represents a database test scenario
  46 similar to that mentioned above:
  47
  48 .. code-block:: cmake
  49
  50   add_test(NAME testsDone   COMMAND emailResults)
  51   add_test(NAME fooOnly     COMMAND testFoo)
  52   add_test(NAME dbOnly      COMMAND testDb)
  53   add_test(NAME dbWithFoo   COMMAND testDbWithFoo)
  54   add_test(NAME createDB    COMMAND initDB)
  55   add_test(NAME setupUsers  COMMAND userCreation)
  56   add_test(NAME cleanupDB   COMMAND deleteDB)
  57   add_test(NAME cleanupFoo  COMMAND removeFoos)
  58
  59   set_tests_properties(setupUsers PROPERTIES DEPENDS createDB)
  60
  61   set_tests_properties(createDB   PROPERTIES FIXTURES_SETUP    DB)
  62   set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP    DB)
  63   set_tests_properties(cleanupDB  PROPERTIES FIXTURES_CLEANUP  DB)
  64   set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP  Foo)
  65   set_tests_properties(testsDone  PROPERTIES FIXTURES_CLEANUP  "DB;Foo")
  66
  67   set_tests_properties(fooOnly    PROPERTIES FIXTURES_REQUIRED Foo)
  68   set_tests_properties(dbOnly     PROPERTIES FIXTURES_REQUIRED DB)
  69   set_tests_properties(dbWithFoo  PROPERTIES FIXTURES_REQUIRED "DB;Foo")
  70
  71   set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB
  72                        PROPERTIES RESOURCE_LOCK DbAccess)
  73
  74 Key points from this example:
  75
  76 - Two fixtures are defined: ``DB`` and ``Foo``. Tests can require a single
  77   fixture as ``fooOnly`` and ``dbOnly`` do, or they can depend on multiple
  78   fixtures like ``dbWithFoo`` does.
  79
  80 - A ``DEPENDS`` relationship is set up to ensure ``setupUsers`` happens after
  81   ``createDB``, both of which are setup tests for the ``DB`` fixture and will
  82   therefore be executed before the ``dbOnly`` and ``dbWithFoo`` tests
  83   automatically.
  84
  85 - No explicit ``DEPENDS`` relationships were needed to make the setup tests run
  86   before or the cleanup tests run after the regular tests.
  87
  88 - The ``Foo`` fixture has no setup tests defined, only a single cleanup test.
  89
  90 - ``testsDone`` is a cleanup test for both the ``DB`` and ``Foo`` fixtures.
  91   Therefore, it will only execute once regular tests for both fixtures have
  92   finished (i.e. after ``fooOnly``, ``dbOnly`` and ``dbWithFoo``). No
  93   ``DEPENDS`` relationship was specified for ``testsDone``, so it is free to
  94   run before, after or concurrently with other cleanup tests for either
  95   fixture.
  96
  97 - The setup and cleanup tests never list the fixtures they are for in their own
  98   ``FIXTURES_REQUIRED`` property, as that would result in a dependency on
  99   themselves and be considered an error.