Help: Clarify test fixture naming and use

* Make it clearer that fixture names are distinct from test case names.
* Mention -FS, -FC and -FA ctest command line options for overriding
  fixture behavior.

Fixes: #17141

3 files changed, 9 insertions, 5 deletions

diff --git a/Help/prop_test/FIXTURES_CLEANUP.rst b/Help/prop_test/FIXTURES_CLEANUP.rst
index f0a4be0..3075b4d 100644
--- a/Help/prop_test/FIXTURES_CLEANUP.rst
+++ b/Help/prop_test/FIXTURES_CLEANUP.rst
@@ -2,7 +2,8 @@ FIXTURES_CLEANUP
 ----------------
 
 Specifies a list of fixtures for which the test is to be treated as a cleanup
-test.
+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.
 
 Fixture cleanup tests are ordinary tests with all of the usual test
 functionality. Setting the ``FIXTURES_CLEANUP`` property for a test has two
diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst
index e37dfb5..e3f60c4 100644
--- a/Help/prop_test/FIXTURES_REQUIRED.rst
+++ b/Help/prop_test/FIXTURES_REQUIRED.rst
@@ -2,7 +2,7 @@ FIXTURES_REQUIRED
 -----------------
 
 Specifies a list of fixtures the test requires. Fixture names are case
-sensitive.
+sensitive and they are not required to have any similarity to test names.
 
 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
@@ -19,7 +19,9 @@ 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.
+required by any of the tests that are in the execution set. This behavior can
+be overridden with the ``-FS``, ``-FC`` and ``-FA`` command line options to
+:manual:`ctest(1)` if desired.
 
 Since setup and cleanup tasks are also tests, they can have an ordering
 specified by the :prop_test:`DEPENDS` test property just like any other tests.
diff --git a/Help/prop_test/FIXTURES_SETUP.rst b/Help/prop_test/FIXTURES_SETUP.rst
index a220215..fdb21cc 100644
--- a/Help/prop_test/FIXTURES_SETUP.rst
+++ b/Help/prop_test/FIXTURES_SETUP.rst
@@ -2,14 +2,15 @@ FIXTURES_SETUP
 --------------
 
 Specifies a list of fixtures for which the test is to be treated as a setup
-test.
+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.
 
 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
-  fixture(s) in its :prop_test:`FIXTURES_REQUIRED` property.
+  fixture name(s) in its :prop_test:`FIXTURES_REQUIRED` property.
 
 - 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