FIXTURES_REQUIRED

Specifies a list of fixtures the test requires. Fixture names are case sensitive.

Fixtures are a way to attach setup and cleanup tasks to a set of tests. If a test requires a given fixture, then all tests marked as setup tasks for that fixture will be executed first (once for the whole set of tests, not once per test requiring the fixture). After all tests requiring a particular fixture have completed, CTest will ensure all tests marked as cleanup tasks for that fixture are then executed. Tests are marked as setup tasks with the FIXTURES_SETUP property and as cleanup tasks with the FIXTURES_CLEANUP property. If any of a fixture’s setup tests fail, all tests listing that fixture in their FIXTURES_REQUIRED property will not be executed. The cleanup tests for the fixture will always be executed, even if some setup tests fail.

When CTest is asked to execute only a subset of tests (e.g. by the use of regular expressions or when run with the --rerun-failed command line option), it will automatically add any setup or cleanup tests for fixtures required by any of the tests that are in the execution set.

Since setup and cleanup tasks are also tests, they can have an ordering specified by the DEPENDS test property just like any other tests. This can be exploited to implement setup or cleanup using multiple tests for a single fixture to modularise setup or cleanup logic.

The concept of a fixture is different to that of a resource specified by RESOURCE_LOCK, but they may be used together. A fixture defines a set of tests which share setup and cleanup requirements, whereas a resource lock has the effect of ensuring a particular set of tests do not run in parallel. Some situations may need both, such as setting up a database, serialising test access to that database and deleting the database again at the end. For such cases, tests would populate both FIXTURES_REQUIRED and RESOURCE_LOCK to combine the two behaviours. Names used for RESOURCE_LOCK have no relationship with names of fixtures, so note that a resource lock does not imply a fixture and vice versa.

Consider the following example which represents a database test scenario similar to that mentioned above:

add_test(NAME testsDone   COMMAND emailResults)
add_test(NAME fooOnly     COMMAND testFoo)
add_test(NAME dbOnly      COMMAND testDb)
add_test(NAME dbWithFoo   COMMAND testDbWithFoo)
add_test(NAME createDB    COMMAND initDB)
add_test(NAME setupUsers  COMMAND userCreation)
add_test(NAME cleanupDB   COMMAND deleteDB)
add_test(NAME cleanupFoo  COMMAND removeFoos)

set_tests_properties(setupUsers PROPERTIES DEPENDS createDB)

set_tests_properties(createDB   PROPERTIES FIXTURES_SETUP    DB)
set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP    DB)
set_tests_properties(cleanupDB  PROPERTIES FIXTURES_CLEANUP  DB)
set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP  Foo)
set_tests_properties(testsDone  PROPERTIES FIXTURES_CLEANUP  "DB;Foo")

set_tests_properties(fooOnly    PROPERTIES FIXTURES_REQUIRED Foo)
set_tests_properties(dbOnly     PROPERTIES FIXTURES_REQUIRED DB)
set_tests_properties(dbWithFoo  PROPERTIES FIXTURES_REQUIRED "DB;Foo")

set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB
                     PROPERTIES RESOURCE_LOCK DbAccess)

Key points from this example:

  • Two fixtures are defined: DB and Foo. Tests can require a single fixture as fooOnly and dbOnly do, or they can depend on multiple fixtures like dbWithFoo does.

  • A DEPENDS relationship is set up to ensure setupUsers happens after createDB, both of which are setup tests for the DB fixture and will therefore be executed before the dbOnly and dbWithFoo tests automatically.

  • No explicit DEPENDS relationships were needed to make the setup tests run before or the cleanup tests run after the regular tests.

  • The Foo fixture has no setup tests defined, only a single cleanup test.

  • testsDone is a cleanup test for both the DB and Foo fixtures. Therefore, it will only execute once regular tests for both fixtures have finished (i.e. after fooOnly, dbOnly and dbWithFoo). No DEPENDS relationship was specified for testsDone, so it is free to run before, after or concurrently with other cleanup tests for either fixture.

  • The setup and cleanup tests never list the fixtures they are for in their own FIXTURES_REQUIRED property, as that would result in a dependency on themselves and be considered an error.