CTest: Clarify that resource requirements can be split

Add a note to the documentation to clarify this, and add test cases
to ensure it.

Fixes: #19987

10 files changed, 41 insertions, 2 deletions

diff --git a/Help/prop_test/RESOURCE_GROUPS.rst b/Help/prop_test/RESOURCE_GROUPS.rst
index 436451cc9b..63c56ce559 100644
--- a/Help/prop_test/RESOURCE_GROUPS.rst
+++ b/Help/prop_test/RESOURCE_GROUPS.rst
@@ -38,6 +38,22 @@ This single group requires 4 slots from a single GPU and 2 slots from a
 single cryptography chip. In total, 3 resource groups are specified for this
 test, each with its own unique requirements.
 
+Note that the number of slots following the resource type specifies slots from
+a *single* instance of the resource. If the resource group can tolerate
+receiving slots from different instances of the same resource, it can indicate
+this by splitting the specification into multiple requirements of one slot. For
+example:
+
+.. code-block:: cmake
+
+  add_test(NAME MyTest COMMAND MyExe)
+  set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
+    "gpus:1,gpus:1,gpus:1,gpus:1")
+
+In this case, the single resource group indicates that it needs four GPU slots,
+all of which may come from separate GPUs (though they don't have to; CTest may
+still assign slots from the same GPU.)
+
 When CTest sets the :ref:`environment variables
 <ctest-resource-environment-variables>` for a test, it assigns a group number
 based on the group description, starting at 0 on the left and the number of
diff --git a/Tests/CMakeLib/testCTestResourceGroups.cxx b/Tests/CMakeLib/testCTestResourceGroups.cxx
index 5fd7d4ad86..c3532a68d7 100644
--- a/Tests/CMakeLib/testCTestResourceGroups.cxx
+++ b/Tests/CMakeLib/testCTestResourceGroups.cxx
@@ -74,6 +74,9 @@ static const std::vector<ExpectedParseResult> expectedResults{
   { "1,threads:1,", true, {
     { { "threads", 1, 1 } },
   } },
+  { "threads:1,threads:1", true, {
+    { { "threads", 1, 1 }, { "threads", 1, 1 } },
+  } },
   { "threads:1;;threads:2", true, {
     { { "threads", 1, 1 } },
     { { "threads", 2, 1 } },
diff --git a/Tests/RunCMake/CTestResourceAllocation/RunCMakeTest.cmake b/Tests/RunCMake/CTestResourceAllocation/RunCMakeTest.cmake
index d52a63e425..8584786479 100644
--- a/Tests/RunCMake/CTestResourceAllocation/RunCMakeTest.cmake
+++ b/Tests/RunCMake/CTestResourceAllocation/RunCMakeTest.cmake
@@ -160,6 +160,8 @@ run_ctest_resource(checkfree1 2 0)
 run_ctest_resource(checkfree2 1 0)
 run_ctest_resource(notenough1 1 0)
 run_ctest_resource(notenough2 1 0)
+run_ctest_resource(notenough3 1 0)
+run_ctest_resource(combine 1 0)
 run_ctest_resource(ensure_parallel 2 0)
 
 set(ENV{CTEST_RESOURCE_GROUP_COUNT} 2)
diff --git a/Tests/RunCMake/CTestResourceAllocation/combine.cmake b/Tests/RunCMake/CTestResourceAllocation/combine.cmake
new file mode 100644
index 0000000000..ed5b25109b
--- /dev/null
+++ b/Tests/RunCMake/CTestResourceAllocation/combine.cmake
@@ -0,0 +1,5 @@
+setup_resource_tests()
+
+add_resource_test(Test1 0 "widgets:8,widgets:4")
+
+cleanup_resource_tests()
diff --git a/Tests/RunCMake/CTestResourceAllocation/notenough1.cmake b/Tests/RunCMake/CTestResourceAllocation/notenough1.cmake
index 2908812d36..f820c378cc 100644
--- a/Tests/RunCMake/CTestResourceAllocation/notenough1.cmake
+++ b/Tests/RunCMake/CTestResourceAllocation/notenough1.cmake
@@ -1,5 +1,5 @@
 setup_resource_tests()
 
-add_resource_test(Test1 1 "fluxcapacitors:200")
+add_resource_test(Test1 0 "fluxcapacitors:200")
 
 cleanup_resource_tests()
diff --git a/Tests/RunCMake/CTestResourceAllocation/notenough2.cmake b/Tests/RunCMake/CTestResourceAllocation/notenough2.cmake
index d7600c8963..5b81776364 100644
--- a/Tests/RunCMake/CTestResourceAllocation/notenough2.cmake
+++ b/Tests/RunCMake/CTestResourceAllocation/notenough2.cmake
@@ -1,5 +1,5 @@
 setup_resource_tests()
 
-add_resource_test(Test1 1 "terminators:2")
+add_resource_test(Test1 0 "terminators:2")
 
 cleanup_resource_tests()
diff --git a/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-check.cmake b/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-check.cmake
new file mode 100644
index 0000000000..321e9a2f87
--- /dev/null
+++ b/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-check.cmake
@@ -0,0 +1,3 @@
+if(EXISTS "${RunCMake_TEST_BINARY_DIR}/ctresalloc.log")
+  set(RunCMake_TEST_FAILED "ctresalloc.log should not exist")
+endif()
diff --git a/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-result.txt b/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-result.txt
new file mode 100644
index 0000000000..b57e2deb77
--- /dev/null
+++ b/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-result.txt
@@ -0,0 +1 @@
+(-1|255)
diff --git a/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-stderr.txt b/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-stderr.txt
new file mode 100644
index 0000000000..82dfdefcfe
--- /dev/null
+++ b/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res-stderr.txt
@@ -0,0 +1,4 @@
+^Insufficient resources
+CMake Error at [^
+]*/Tests/RunCMake/CTestResourceAllocation/notenough3-ctest-s-res/test\.cmake:[0-9]+ \(message\):
+  Tests did not pass$
diff --git a/Tests/RunCMake/CTestResourceAllocation/notenough3.cmake b/Tests/RunCMake/CTestResourceAllocation/notenough3.cmake
new file mode 100644
index 0000000000..ddf3a9cd52
--- /dev/null
+++ b/Tests/RunCMake/CTestResourceAllocation/notenough3.cmake
@@ -0,0 +1,5 @@
+setup_resource_tests()
+
+add_resource_test(Test1 0 "widgets:12")
+
+cleanup_resource_tests()