FIXTURES_SETUP.rst 1.89 KB
Newer Older
1 2 3 4
FIXTURES_SETUP
--------------

Specifies a list of fixtures for which the test is to be treated as a setup
5 6
test. These fixture names are distinct from test case names and are not
required to have any similarity to the names of tests associated with them.
7 8 9 10 11 12

Fixture setup tests are ordinary tests with all of the usual test
functionality. Setting the ``FIXTURES_SETUP`` property for a test has two
primary effects:

- CTest will ensure the test executes before any other test which lists the
13
  fixture name(s) in its :prop_test:`FIXTURES_REQUIRED` property.
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48

- If CTest is asked to run only a subset of tests (e.g. using regular
  expressions or the ``--rerun-failed`` option) and the setup test is not in
  the set of tests to run, it will automatically be added if any tests in the
  set require any fixture listed in ``FIXTURES_SETUP``.

A setup test can have multiple fixtures listed in its ``FIXTURES_SETUP``
property. It will execute only once for the whole CTest run, not once for each
fixture. A fixture can also have more than one setup test defined. If there are
multiple setup tests for a fixture, projects can control their order with the
usual :prop_test:`DEPENDS` test property if necessary.

A setup test is allowed to require other fixtures, but not any fixture listed
in its ``FIXTURES_SETUP`` property. For example:

.. code-block:: cmake

  # Ok: dependent fixture is different to setup
  set_tests_properties(setupFoo PROPERTIES
    FIXTURES_SETUP    Foo
    FIXTURES_REQUIRED Bar
  )

  # Error: cannot require same fixture as setup
  set_tests_properties(setupFoo PROPERTIES
    FIXTURES_SETUP    Foo
    FIXTURES_REQUIRED Foo
  )

If any of a fixture's setup tests fail, none of the tests listing that fixture
in its :prop_test:`FIXTURES_REQUIRED` property will be run. Cleanup tests will,
however, still be executed.

See :prop_test:`FIXTURES_REQUIRED` for a more complete discussion of how to use
test fixtures.