Ryan Prichard | 7aea7e9 | 2022-01-13 17:30:17 -0800 | [diff] [blame] | 1 | FIXTURES_SETUP |
| 2 | -------------- |
| 3 | |
| 4 | .. versionadded:: 3.7 |
| 5 | |
| 6 | Specifies a list of fixtures for which the test is to be treated as a setup |
| 7 | test. These fixture names are distinct from test case names and are not |
| 8 | required to have any similarity to the names of tests associated with them. |
| 9 | |
| 10 | Fixture setup tests are ordinary tests with all of the usual test |
| 11 | functionality. Setting the ``FIXTURES_SETUP`` property for a test has two |
| 12 | primary effects: |
| 13 | |
| 14 | - CTest will ensure the test executes before any other test which lists the |
| 15 | fixture name(s) in its :prop_test:`FIXTURES_REQUIRED` property. |
| 16 | |
| 17 | - If CTest is asked to run only a subset of tests (e.g. using regular |
| 18 | expressions or the ``--rerun-failed`` option) and the setup test is not in |
| 19 | the set of tests to run, it will automatically be added if any tests in the |
| 20 | set require any fixture listed in ``FIXTURES_SETUP``. |
| 21 | |
| 22 | A setup test can have multiple fixtures listed in its ``FIXTURES_SETUP`` |
| 23 | property. It will execute only once for the whole CTest run, not once for each |
| 24 | fixture. A fixture can also have more than one setup test defined. If there are |
| 25 | multiple setup tests for a fixture, projects can control their order with the |
| 26 | usual :prop_test:`DEPENDS` test property if necessary. |
| 27 | |
| 28 | A setup test is allowed to require other fixtures, but not any fixture listed |
| 29 | in its ``FIXTURES_SETUP`` property. For example: |
| 30 | |
| 31 | .. code-block:: cmake |
| 32 | |
| 33 | # Ok: dependent fixture is different to setup |
| 34 | set_tests_properties(setupFoo PROPERTIES |
| 35 | FIXTURES_SETUP Foo |
| 36 | FIXTURES_REQUIRED Bar |
| 37 | ) |
| 38 | |
| 39 | # Error: cannot require same fixture as setup |
| 40 | set_tests_properties(setupFoo PROPERTIES |
| 41 | FIXTURES_SETUP Foo |
| 42 | FIXTURES_REQUIRED Foo |
| 43 | ) |
| 44 | |
| 45 | If any of a fixture's setup tests fail, none of the tests listing that fixture |
| 46 | in its :prop_test:`FIXTURES_REQUIRED` property will be run. Cleanup tests will, |
| 47 | however, still be executed. |
| 48 | |
| 49 | See :prop_test:`FIXTURES_REQUIRED` for a more complete discussion of how to use |
| 50 | test fixtures. |