Help: Clarify CTEST_NO_TESTS_ACTION support and interaction

Help/command/ctest_test.rst

@@ -212,6 +212,13 @@ The options are:
   See also the :variable:`CTEST_TEST_PRESET` and
   :variable:`CTEST_PRESET` variables.
 
+  In general, only preset fields which have equivalent options to
+  ``ctest_test`` are supported. An exception is the
+  :preset:`testPresets.environment`, which can hold a value for the
+  :envvar:`CTEST_NO_TESTS_ACTION` environment variable and will be respected,
+  despite ``ctest_test`` not having an equivalent option to the
+  :preset:`testPresets.execution.noTestsAction` presets field.
+
 ``PRESETS_FILE <file>``
   .. versionadded:: 4.4
 

Help/envvar/CTEST_NO_TESTS_ACTION.rst

@@ -12,3 +12,18 @@ cases when there are no tests to run. Possible values are: ``error``,
 The :option:`--no-tests=\<action\> <ctest --no-tests>` option to
 :manual:`ctest <ctest(1)>` overrides this environment variable if both
 are given.
+
+When :option:`ctest --preset` is used, this environment variable, if set,
+takes precedence over the :preset:`testPresets.execution.noTestsAction`
+field of the selected test preset. This includes the case where the
+variable is instead set via the preset's own
+:preset:`testPresets.environment` field, which is equivalent to setting it
+in the calling process's environment. An explicit
+:option:`--no-tests=\<action\> <ctest --no-tests>` on the command line
+takes precedence over all of the above.
+
+This environment variable, including when set via a test preset's
+``environment`` field, is also respected when that same preset is used by
+a :command:`ctest_test` command in a :ref:`CTest Script`. However, in that
+case, the preset's ``noTestsAction`` field itself has no effect, because
+:command:`ctest_test` has no equivalent argument to apply it through.

Help/manual/ctest.1.rst

@@ -556,7 +556,9 @@ The options for running tests are:
  .. versionadded:: 3.26
 
  This option can also be set by setting the :envvar:`CTEST_NO_TESTS_ACTION`
- environment variable.
+ environment variable. See the documentation of that variable for how it
+ interacts with a test preset's :preset:`testPresets.execution.noTestsAction`
+ field.
 
 .. option:: --collect-instrumentation <build>
 

Help/manual/presets/execution-properties.rst

@@ -106,6 +106,13 @@
     Equivalent to passing :ctest-option:`--no-tests=ignore`
     on the command line.
 
+  If set, this field is overridden by the
+  :envvar:`CTEST_NO_TESTS_ACTION` environment variable,
+  including when that variable is instead set via this test
+  preset's own :preset:`testPresets.environment` field.
+  See :envvar:`CTEST_NO_TESTS_ACTION` for the full precedence
+  order.
+
 .. _`CMakePresets.testPresets.execution.testPassthroughArguments`:
 
 ``testPassthroughArguments``

Help/manual/presets/schema.yaml

@@ -1766,6 +1766,13 @@ properties:
                 ``ignore``
                   Equivalent to passing :ctest-option:`--no-tests=ignore`
                   on the command line.
+
+                If set, this field is overridden by the
+                :envvar:`CTEST_NO_TESTS_ACTION` environment variable,
+                including when that variable is instead set via this test
+                preset's own :preset:`testPresets.environment` field.
+                See :envvar:`CTEST_NO_TESTS_ACTION` for the full precedence
+                order.
             testPassthroughArguments:
               since: 12
               type: array