Update CONTRIBUTING.md with platform-specific test instructions

opensim-org · Dec 20, 2023 · d79ffe6 · d79ffe6
1 parent 32afdc2
commit d79ffe6
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 13 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -83,21 +83,57 @@ that are already in `OpenSim/Tests/shared`; you could inadvertently weaken tests
 that rely on some obscure aspect of the files.
 
 
+Platform-specific tests
+-----------------------
+The Catch2 testing framework can be used to write platform-specific tests. For
+example, if you want to write a test that only runs on Windows, you can use the
+`TEST_CASE()` or `TEMPLATE_TEST_CASE` macros with the tag `"[win]"`:
+
+```cpp
+TEST_CASE("MyTest", "[win]") {
+    // ...
+}
+```
+
+```cpp
+TEMPLATE_TEST_CASE("MyTest", "[win]", TestType) {
+    // ...
+}
+```
+
+Specifying the tag `"[win]"` means that this test will be _excluded_ on Mac and
+Linux. The tags `"[mac]"` and `"[linux]"` can be used similarly for tests specific 
+to Mac or Linux. If you want to run a test on two platforms but not the third,
+use combined tags (e.g., `"[win/linux]"`, `"[mac/win]"`, or `"[unix]"`). Do not
+concatenate tags; for example, `"[win][linux]"`) will not run on Linux or Windows
+since Windows excludes Linux-only tests and vice-versa. Specifying no tag means 
+that the test will run on all platforms. The table below summarizes the tags that 
+can be used to specify platform-specific tests.
+
+| Platform(s)       | Tag(s)                                       |
+|-------------------|----------------------------------------------|
+| Windows           | `"[win]"`                                    |
+| Mac               | `"[mac]"`                                    |
+| Linux             | `"[linux]"`                                  |
+| Mac and Linux     | `"[unix]"`, `"[mac/linux]"`, `"[linux/mac]"` |
+| Windows and Mac   | `"[win/mac]"`, `"[mac/win]"`                 |
+| Windows and Linux | `"[win/linux]"`, `"[linux/win]"`             |
+| All platforms     | (no tag)                                     |
+
+
 Running Moco tests
 ------------------
 In general, Moco's tests depend on the CasADi and Tropter libraries, whose use
 is determined by the `OPENSIM_WITH_CASADI` and `OPENSIM_WITH_TROPTER` CMake
 variables. The CTests are designed to succeed regardless of the value of these
 CMake variables: if `OPENSIM_WITH_CASADI` is off, Moco's C++ tests are run with
-arguments `"exclude:*MocoCasADiSolver*" "exclude:[casadi]"`,
-which excludes Catch2 templatized tests using MocoCasADiSolver and other tests
-that are tagged as relying on CasADi (likewise for Tropter).
-If the test executables are run without CTest (e.g., debugging a project in
-Visual Studio), the tests will fail if either `OPENSIM_WITH_CASADI` or
-`OPENSIM_WITH_TROPTER` is false; for the tests to pass, provide the argument(s)
-`"exclude:*MocoCasADiSolver*" "exclude:[casadi]"` and/or
-`"exclude:*MocoTropterSolver*" "exclude:[tropter]"` (depending on which
-libraries are available).
+arguments `"~*MocoCasADiSolver*" "~[casadi]"`, which excludes Catch2 templatized 
+tests using MocoCasADiSolver and other tests that are tagged as relying on CasADi 
+(likewise for Tropter). If the test executables are run without CTest (e.g., 
+debugging a project in Visual Studio), the tests will fail if either 
+`OPENSIM_WITH_CASADI` orv`OPENSIM_WITH_TROPTER` is false; for the tests to pass, 
+provide the argument(s) `"~*MocoCasADiSolver*" "~[casadi]"` and/or
+`"~*MocoTropterSolver*" "~[tropter]"` (depending on which libraries are available).
 
 
 Checking for Memory Leaks with LibASAN

diff --git a/cmake/OpenSimMacros.cmake b/cmake/OpenSimMacros.cmake
@@ -369,19 +369,18 @@ function(OpenSimAddTests)
             target_link_libraries(${TEST_NAME} ${OSIMADDTESTS_LINKLIBS})
             set(test_args "")
             if(APPLE)
-                list(APPEND test_args "~[win]~[linux]~[win/linux]")
+                list(APPEND test_args "~[win]~[linux]~[win/linux]~[linux/win]")
             endif()
             if(LINUX)
-                list(APPEND test_args "~[win]~[mac]~[win/mac]")
+                list(APPEND test_args "~[win]~[mac]~[win/mac]~[mac/win]")
             endif()
             if(WIN32)
-                list(APPEND test_args "~[mac]~[linux]~[unix]")
+                list(APPEND test_args "~[mac]~[linux]~[mac/linux]~[linux/mac]~[unix]")
             endif()
             add_test(NAME ${TEST_NAME} COMMAND ${TEST_NAME} ${test_args})
             set_target_properties(${TEST_NAME} PROPERTIES
                 FOLDER "Tests"
             )
-
         endforeach()
 
         # Copy data files to build directory.::