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