[Vibe] Migrate to Catch2 v3

Vibe-code start using Cursor.AI

Prompts (after initial setup & test instructions):

> I want us to update our Catch2 tests to use the latest version of Catch, version 3.
>
> I want to follow this path:
> Build Catch2 as a proper (static) library, and move to piecewise headers
>
> Please read the upgrade guide and update the project as needed:
> https://github.com/catchorg/Catch2/blob/devel/docs/migrate-v2-to-v3.md
>
> Start with our CMake logic and downloader, then update the C++ test files in test/

Then:
> Great, please self-review your changes.
>
> The latest Catch2 version is 3.11.0 btw

Then:
> Self-review your changes once more, read the change logs on
> https://github.com/catchorg/Catch2/releases  for deprecated
> and new APIs. Modernize as needed.

Author: ax3l

CMakeLists.txt

@@ -525,6 +525,9 @@ if(openPMD_BUILD_TESTING)
     add_library(openPMD::thirdparty::Catch2 INTERFACE IMPORTED)
     target_link_libraries(openPMD::thirdparty::Catch2
             INTERFACE Catch2::Catch2)
+    add_library(openPMD::thirdparty::Catch2WithMain INTERFACE IMPORTED)
+    target_link_libraries(openPMD::thirdparty::Catch2WithMain
+            INTERFACE Catch2::Catch2WithMain)
 endif()
 
 if(openPMD_HAVE_MPI)
@@ -770,14 +773,11 @@ if(openPMD_HAVE_PYTHON)
 endif()
 
 if(openPMD_BUILD_TESTING)
-    # compile Catch2 implementation part separately
-    add_library(CatchRunner ${_openpmd_lib_type}
-        test/CatchRunner.cpp)  # Always MPI_Init with Serial Fallback
-    add_library(CatchMain   ${_openpmd_lib_type}
-        test/CatchMain.cpp)    # Serial only
+    # CatchRunner: custom main with MPI support for parallel tests
+    # In Catch2 v3, we link to Catch2 (not Catch2WithMain) since we provide our own main
+    add_library(CatchRunner ${_openpmd_lib_type} test/CatchRunner.cpp)
     openpmd_cxx_required(CatchRunner)
-    openpmd_cxx_required(CatchMain)
-    set_target_properties(CatchRunner CatchMain PROPERTIES
+    set_target_properties(CatchRunner PROPERTIES
         ARCHIVE_OUTPUT_DIRECTORY ${openPMD_ARCHIVE_OUTPUT_DIRECTORY}
         LIBRARY_OUTPUT_DIRECTORY ${openPMD_LIBRARY_OUTPUT_DIRECTORY}
         RUNTIME_OUTPUT_DIRECTORY ${openPMD_RUNTIME_OUTPUT_DIRECTORY}
@@ -788,7 +788,6 @@ if(openPMD_BUILD_TESTING)
         WINDOWS_EXPORT_ALL_SYMBOLS ON
     )
     set_target_properties(CatchRunner PROPERTIES COMPILE_PDB_NAME CatchRunner)
-    set_target_properties(CatchMain PROPERTIES COMPILE_PDB_NAME CatchMain)
     # note: same as above, but for Multi-Config generators
     if(isMultiConfig)
         foreach(CFG IN LISTS CMAKE_CONFIGURATION_TYPES)
@@ -801,20 +800,10 @@ if(openPMD_BUILD_TESTING)
                 PDB_OUTPUT_DIRECTORY_${CFG_UPPER} ${openPMD_PDB_OUTPUT_DIRECTORY}/${CFG}
                 COMPILE_PDB_OUTPUT_DIRECTORY_${CFG_UPPER} ${openPMD_COMPILE_PDB_OUTPUT_DIRECTORY}/${CFG}
             )
-            set_target_properties(CatchMain PROPERTIES
-                COMPILE_PDB_NAME_${CFG_UPPER} CatchMain
-                ARCHIVE_OUTPUT_DIRECTORY_${CFG_UPPER} ${openPMD_ARCHIVE_OUTPUT_DIRECTORY}/${CFG}
-                LIBRARY_OUTPUT_DIRECTORY_${CFG_UPPER} ${openPMD_LIBRARY_OUTPUT_DIRECTORY}/${CFG}
-                RUNTIME_OUTPUT_DIRECTORY_${CFG_UPPER} ${openPMD_RUNTIME_OUTPUT_DIRECTORY}/${CFG}
-                PDB_OUTPUT_DIRECTORY_${CFG_UPPER} ${openPMD_PDB_OUTPUT_DIRECTORY}/${CFG}
-                COMPILE_PDB_OUTPUT_DIRECTORY_${CFG_UPPER} ${openPMD_COMPILE_PDB_OUTPUT_DIRECTORY}/${CFG}
-            )
         endforeach()
     endif()
     target_compile_options(CatchRunner PUBLIC ${_msvc_options})
-    target_compile_options(CatchMain   PUBLIC ${_msvc_options})
     target_link_libraries(CatchRunner PUBLIC openPMD::thirdparty::Catch2)
-    target_link_libraries(CatchMain   PUBLIC openPMD::thirdparty::Catch2)
     if(openPMD_HAVE_MPI)
         target_link_libraries(CatchRunner PUBLIC ${openPMD_MPI_TARGETS})
         target_compile_definitions(CatchRunner PUBLIC openPMD_HAVE_MPI=1)
@@ -875,9 +864,11 @@ if(openPMD_BUILD_TESTING)
         endif()
         target_link_libraries(${testname}Tests PRIVATE openPMD)
         if(${testname} MATCHES "Parallel.+$")
+            # Parallel tests use CatchRunner (custom main with MPI)
             target_link_libraries(${testname}Tests PRIVATE CatchRunner)
         else()
-            target_link_libraries(${testname}Tests PRIVATE CatchMain)
+            # Serial tests use Catch2WithMain (provides default main)
+            target_link_libraries(${testname}Tests PRIVATE openPMD::thirdparty::Catch2WithMain)
         endif()
 
         if(${testname} STREQUAL JSON)

cmake/dependencies/catch.cmake

@@ -45,7 +45,7 @@ function(find_catch2)
         mark_as_advanced(FETCHCONTENT_UPDATES_DISCONNECTED)
         #mark_as_advanced(FETCHCONTENT_UPDATES_DISCONNECTED_FETCHEDCatch2)
     elseif(NOT openPMD_USE_INTERNAL_CATCH)
-        find_package(Catch2 2.13.10 CONFIG REQUIRED)
+        find_package(Catch2 3.0.0 CONFIG REQUIRED)
         message(STATUS "Catch2: Found version '${Catch2_VERSION}'")
     endif()
 endfunction()
@@ -56,18 +56,18 @@ set(openPMD_catch_src ""
     "Local path to Catch2 source directory (preferred if set)")
 
 # tarball fetcher
-set(openPMD_catch_tar "https://github.com/catchorg/Catch2/archive/refs/tags/v2.13.10.tar.gz"
+set(openPMD_catch_tar "https://github.com/catchorg/Catch2/archive/refs/tags/v3.11.0.tar.gz"
     CACHE STRING
     "Remote tarball link to pull and build Catch2 from if(openPMD_USE_INTERNAL_CATCH)")
-set(openPMD_catch_tar_hash "SHA256=d54a712b7b1d7708bc7a819a8e6e47b2fde9536f487b89ccbca295072a7d9943"
+set(openPMD_catch_tar_hash "SHA256=82fa1cb59dc28bab220935923f7469b997b259eb192fb9355db62da03c2a3137"
     CACHE STRING
     "Hash checksum of the tarball of Catch2 if(openPMD_USE_INTERNAL_CATCH)")
 
 # Git fetcher
 set(openPMD_catch_repo "https://github.com/catchorg/Catch2.git"
     CACHE STRING
     "Repository URI to pull and build Catch2 from if(openPMD_USE_INTERNAL_CATCH)")
-set(openPMD_catch_branch "v2.13.10"
+set(openPMD_catch_branch "v3.11.0"
     CACHE STRING
     "Repository branch for openPMD_catch_repo if(openPMD_USE_INTERNAL_CATCH)")
 

test/AuxiliaryTest.cpp

@@ -37,7 +37,7 @@
 #include "openPMD/backend/Writable.hpp"
 #include "openPMD/config.hpp"
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 
 #include <array>
 #include <exception>

test/CatchMain.cpp

@@ -18,8 +18,7 @@
  * and the GNU Lesser General Public License along with openPMD-api.
  * If not, see <http://www.gnu.org/licenses/>.
  */
-#define CATCH_CONFIG_RUNNER
-#include <catch2/catch.hpp>
+#include <catch2/catch_session.hpp>
 
 #if openPMD_HAVE_MPI
 #include <mpi.h>
@@ -29,13 +28,10 @@ int main(int argc, char *argv[])
     MPI_Init(&argc, &argv);
 
     Catch::Session session;
-    int result = 0;
+    int result = session.applyCommandLine(argc, argv);
+    if (result == 0)
     {
-        // Indicates a command line parsing
-        result = session.applyCommandLine(argc, argv);
-        // RT tests
-        if (result == 0)
-            result = session.run();
+        result = session.run();
     }
     MPI_Finalize();
     return result;
@@ -44,13 +40,10 @@ int main(int argc, char *argv[])
 int main(int argc, char *argv[])
 {
     Catch::Session session;
-    int result = 0;
+    int result = session.applyCommandLine(argc, argv);
+    if (result == 0)
     {
-        // Indicates a command line parsing
-        result = session.applyCommandLine(argc, argv);
-        // RT tests
-        if (result == 0)
-            result = session.run();
+        result = session.run();
     }
     return result;
 }

test/CatchRunner.cpp

@@ -34,7 +34,8 @@
 #include "openPMD/auxiliary/Memory_internal.hpp"
 #include "openPMD/auxiliary/UniquePtr.hpp"
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
+#include <catch2/matchers/catch_matchers_string.hpp>
 
 #include <algorithm>
 #include <array>
@@ -1100,7 +1101,7 @@ TEST_CASE("wrapper_test", "[core]")
     // it once? value = 43.; mrc2.makeConstant(value);
     REQUIRE_THROWS_WITH(
         mrc2.makeConstant(value),
-        Catch::Equals(
+        Catch::Matchers::Equals(
             "A recordComponent can not (yet) be made constant after "
             "it has been written."));
     std::array<double, 1> moreData = {{112233.}};
@@ -1121,7 +1122,7 @@ TEST_CASE("wrapper_test", "[core]")
     int wrongData = 42;
     REQUIRE_THROWS_WITH(
         o.iterations[5].meshes["E"]["y"].storeChunkRaw(&wrongData, {0}, {1}),
-        Catch::Equals(
+        Catch::Matchers::Equals(
             "Datatypes of chunk data (INT) and record component "
             "(DOUBLE) do not match."));
     std::shared_ptr<double> storeData = std::make_shared<double>(44);
@@ -1192,7 +1193,7 @@ TEST_CASE("wrapper_test", "[core]")
             .particles["electrons"]
             .particlePatches["numParticles"][RecordComponent::SCALAR]
             .store(idx + 1, 42.),
-        Catch::Equals(
+        Catch::Matchers::Equals(
             "Datatypes of patch data (DOUBLE) and dataset (" + u64str.str() +
             ") do not match."));
     o.iterations[6]
@@ -1285,7 +1286,7 @@ TEST_CASE("empty_record_test", "[core]")
         "No assumption about contained RecordComponents will be made");
     REQUIRE_THROWS_WITH(
         o.flush(),
-        Catch::Equals(
+        Catch::Matchers::Equals(
             "A Record can not be written without any contained "
             "RecordComponents: E"));
     o.iterations[1].meshes["E"][RecordComponent::SCALAR].resetDataset(
@@ -1302,28 +1303,29 @@ TEST_CASE("zero_extent_component", "[core]")
     auto E_x = o.iterations[1].meshes["E"]["x"];
     E_x.setComment("Datasets must contain dimensions.");
     // REQUIRE_THROWS_WITH(E_x.resetDataset(Dataset(Datatype::LONG, {})),
-    //                    Catch::Equals("Dataset extent must be at least 1D."));
+    //                    Catch::Matchers::Equals("Dataset extent must be at
+    //                    least 1D."));
     REQUIRE_THROWS_WITH(
         E_x.makeEmpty<int>(0),
-        Catch::Equals("Dataset extent must be at least 1D."));
+        Catch::Matchers::Equals("Dataset extent must be at least 1D."));
     E_x.resetDataset(Dataset(Datatype::DOUBLE, {1}));
 }
 
 TEST_CASE("no_file_ending", "[core]")
 {
     REQUIRE_THROWS_WITH(
         Series("./new_openpmd_output", Access::CREATE),
-        Catch::Equals(
+        Catch::Matchers::Equals(
             "Unknown file format! Did you specify a file ending? "
             "Specified file name was './new_openpmd_output'."));
     REQUIRE_THROWS_WITH(
         Series("./new_openpmd_output_%T", Access::CREATE),
-        Catch::Equals(
+        Catch::Matchers::Equals(
             "Unknown file format! Did you specify a file ending? "
             "Specified file name was './new_openpmd_output_%T'."));
     REQUIRE_THROWS_WITH(
         Series("./new_openpmd_output_%05T", Access::CREATE),
-        Catch::Equals(
+        Catch::Matchers::Equals(
             "Unknown file format! Did you specify a file ending? "
             "Specified file name was './new_openpmd_output_%05T'."));
     {
@@ -1625,7 +1627,7 @@ TEST_CASE("load_chunk_wrong_datatype", "[core]")
             read.iterations[0]
                 .meshes["rho"][RecordComponent::SCALAR]
                 .loadChunk<double>({0}, {10}),
-            Catch::Equals(err_msg));
+            Catch::Matchers::Equals(err_msg));
     }
 }
 
@@ -1694,7 +1696,7 @@ TEST_CASE("DoConvert_single_value_to_vector", "[core]")
         REQUIRE(attr.get<std::array<int, 7>>() == arrayint);
         REQUIRE_THROWS_WITH(
             (attr.get<std::array<int, 8>>()),
-            Catch::Equals(
+            Catch::Matchers::Equals(
                 "getCast: no vector to array conversion possible "
                 "(wrong requested array size)."));
 #endif

test/CoreTest.cpp

@@ -20,7 +20,7 @@
  */
 #include "CoreTests.hpp"
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 
 namespace automatic_variable_encoding
 {

test/Files_Core/automatic_variable_encoding.cpp

@@ -22,7 +22,7 @@
 
 #include "openPMD/IO/ADIOS/macros.hpp"
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 #include <mpi.h>
 
 namespace iterate_nonstreaming_series

test/Files_ParallelIO/iterate_nonstreaming_series.cpp

@@ -25,7 +25,7 @@
 
 #include <numeric>
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 #include <optional>
 
 #if openPMD_HAVE_ADIOS2 && openPMD_HAVE_MPI

test/Files_ParallelIO/read_variablebased_randomaccess.cpp

@@ -24,7 +24,7 @@
 #include "openPMD/Series.hpp"
 #include "openPMD/auxiliary/Filesystem.hpp"
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 
 namespace close_and_reopen_test
 {