Merge topic 'doc-testprop-DEPENDS-REQUIRED_FILES' into release-3.18

6b75175219 Help: Add example for REQUIRED_FILES test property
61139c91d2 Help: Add example for DEPENDS test property

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4853

2 files changed, 44 insertions, 1 deletions

diff --git a/Help/prop_test/DEPENDS.rst b/Help/prop_test/DEPENDS.rst
index 89c7553..5aa36b4 100644
--- a/Help/prop_test/DEPENDS.rst
+++ b/Help/prop_test/DEPENDS.rst
@@ -8,3 +8,15 @@ results of those tests are not considered, the dependency relationship is
 purely for order of execution (i.e. it is really just a *run after*
 relationship). Consider using test fixtures with setup tests if a dependency
 with successful completion is required (see :prop_test:`FIXTURES_REQUIRED`).
+
+Examples
+~~~~~~~~
+
+.. code-block:: cmake
+
+  add_test(NAME baseTest1 ...)
+  add_test(NAME baseTest2 ...)
+  add_test(NAME dependsTest12 ...)
+
+  set_tests_properties(dependsTest12 PROPERTIES DEPENDS "baseTest1;baseTest2")
+  # dependsTest12 runs after baseTest1 and baseTest2, even if they fail
diff --git a/Help/prop_test/REQUIRED_FILES.rst b/Help/prop_test/REQUIRED_FILES.rst
index fac357c..baf209c 100644
--- a/Help/prop_test/REQUIRED_FILES.rst
+++ b/Help/prop_test/REQUIRED_FILES.rst
@@ -1,7 +1,38 @@
 REQUIRED_FILES
 --------------
 
-List of files required to run the test.
+List of files required to run the test.  The filenames are relative to the
+test :prop_test:`WORKING_DIRECTORY` unless an absolute path is specified.
 
 If set to a list of files, the test will not be run unless all of the
 files exist.
+
+Examples
+~~~~~~~~
+
+Suppose that ``test.txt`` is created by test ``baseTest`` and ``none.txt``
+does not exist:
+
+.. code-block:: cmake
+
+  add_test(NAME baseTest ...)   # Assumed to create test.txt
+  add_test(NAME fileTest ...)
+
+  # The following ensures that if baseTest is successful, test.txt will
+  # have been created before fileTest is run
+  set_tests_properties(fileTest PROPERTIES
+    DEPENDS baseTest
+    REQUIRED_FILES test.txt
+  )
+
+  add_test(NAME notRunTest ...)
+
+  # The following makes notRunTest depend on two files. Nothing creates
+  # the none.txt file, so notRunTest will fail with status "Not Run".
+  set_tests_properties(notRunTest PROPERTIES
+    REQUIRED_FILES "test.txt;none.txt"
+  )
+
+The above example demonstrates how ``REQUIRED_FILES`` works, but it is not the
+most robust way to implement test ordering with failure detection.  For that,
+test fixtures are a better alternative (see :prop_test:`FIXTURES_REQUIRED`).