Correct tests/CLAUDE.md: testing framework is Catch2 v3, not v2 (#14231)

The testing guide stated OrcaSlicer uses Catch2 v2 and advised the v2
`<catch2/catch.hpp>` include, but the vendored framework is v3.11.0
(tests/catch2/) and every test file includes `<catch2/catch_all.hpp>`.

The wrong version drove several incorrect claims: that SKIP() is
unavailable (it is, v3.3.0+), that the string matcher is "Contains"
rather than "ContainsSubstring", and that thread-safe assertions,
multiple reporters, STATIC_CHECK and built-in sharding do not exist.

Correct all version statements, the example include, and the
former "Version-Specific Limitations" section to reflect v3.11.0.
This commit is contained in:
raistlin7447
2026-06-16 10:00:30 -05:00
committed by GitHub
parent b0c1887f40
commit 454335dba6

View File

@@ -98,9 +98,9 @@ REQUIRE_THAT(calculated_value, WithinULP(expected, 4)); // 4 ULPs apart
## Overview of OrcaSlicer's Testing Framework
OrcaSlicer uses **Catch2 v2** as its primary testing framework. The test suite is organized into several modules that mirror the project's architectural components:
OrcaSlicer uses **Catch2 v3** (currently v3.11.0, vendored in `tests/catch2/`) as its primary testing framework. The test suite is organized into several modules that mirror the project's architectural components:
> **Note**: OrcaSlicer currently uses Catch2 v2 (based on `#include <catch2/catch.hpp>` includes). Some features mentioned in this guide are only available in v3 and marked accordingly.
> **Note**: Test files include the framework via `#include <catch2/catch_all.hpp>` (the v3 single-header convenience include). All v3 features described in this guide are available.
### Test Structure
```
@@ -149,13 +149,13 @@ Stereolithography specific tests:
### File Organization
1. **Naming Convention**: `test_<feature>.cpp` (e.g., `test_geometry.cpp`)
2. **Header Structure**: Include `<catch2/catch.hpp>` first, then relevant headers
2. **Header Structure**: Include `<catch2/catch_all.hpp>` first, then relevant headers
3. **Namespace Usage**: Use `using namespace Slic3r;` for convenience
4. **File Placement**: Add to appropriate test directory and update CMakeLists.txt
### Test Naming and Structure
```cpp
#include <catch2/catch.hpp>
#include <catch2/catch_all.hpp>
#include "libslic3r/Point.hpp"
using namespace Slic3r;
@@ -216,7 +216,7 @@ REQUIRE_THROWS_MATCHES(function_call(), SpecificException,
// String matchers
using Catch::Matchers::StartsWith;
using Catch::Matchers::EndsWith;
using Catch::Matchers::ContainsSubstring; // Note: v2 uses "Contains"
using Catch::Matchers::ContainsSubstring;
using Catch::Matchers::Equals;
using Catch::Matchers::Matches; // Regex matching
@@ -330,7 +330,7 @@ TEST_CASE_METHOD(GeometryFixture, "Point operations", "[Geometry]") {
REQUIRE(origin.distance_to(unit_x) == 1.0);
}
// Persistent fixture - single instance for entire test case (v2.12.0+)
// Persistent fixture - single instance for entire test case (v3.2.0+)
TEST_CASE_PERSISTENT_FIXTURE(GeometryFixture, "Persistent operations", "[Geometry]") {
static int call_count = 0;
++call_count;
@@ -384,8 +384,7 @@ TEST_CASE("Explicit test control", "[Control]") {
WARN("This warns but doesn't fail the test");
if (precondition_not_met) {
// SKIP("Reason"); // v3.3.0+ only, not available in v2
SUCCEED("Test cannot run due to precondition"); // v2 alternative
SKIP("Reason"); // Marks the test as skipped (v3.3.0+, available)
return;
}
@@ -506,7 +505,7 @@ TEST_CASE("Algorithm performance", "[Performance][Algorithm]") {
// Large test data
std::vector<Point> points = generate_large_point_set(10000);
// Time the operation (manual timing for Catch2 v2)
// Time the operation (manual timing example; the BENCHMARK macro is also available)
auto start = std::chrono::high_resolution_clock::now();
auto result = convex_hull(points);
auto end = std::chrono::high_resolution_clock::now();
@@ -746,7 +745,7 @@ REQUIRE_THROWS_AS(risky_function(), SpecificException);
⚠️ **CRITICAL**: Catch2 assertions are **NOT thread-safe** by default!
> **Note**: Catch2 v3.9.0+ has opt-in thread-safe assertions via `CATCH_CONFIG_EXPERIMENTAL_THREAD_SAFE_ASSERTIONS`, but OrcaSlicer uses v2
> **Note**: Catch2 v3.9.0+ has opt-in thread-safe assertions via `CATCH_CONFIG_EXPERIMENTAL_THREAD_SAFE_ASSERTIONS`. OrcaSlicer is on v3.11.0 but does not enable this flag, so assertions remain non-thread-safe by default.
**Incorrect**: Will cause undefined behavior or crashes
```cpp
@@ -812,7 +811,7 @@ TEST_CASE("Resource management", "[Memory]") {
### Runtime Performance
```cpp
TEST_CASE("Performance-sensitive test", "[Performance]") {
// Manual timing for Catch2 v2 (v3 has built-in benchmarking)
// Manual timing example (Catch2's built-in BENCHMARK macro is also available)
auto start = std::chrono::high_resolution_clock::now();
auto result = expensive_operation();
@@ -921,21 +920,20 @@ std::foo_function(); // Always call qualified
// NOT: #include <foo.h> and foo_function();
```
### Catch2 Version-Specific Limitations
### Catch2 v3 Features Available
```cpp
// OrcaSlicer uses Catch2 v2 - these features are NOT available:
// SKIP() macro - Available in v3.3.0+
// Thread-safe assertions - Available in v3.9.0+
// BENCHMARK improvements - Many in v3.x
// testCasePartial events - Available in v3.0.1+
// Multiple reporters - Available in v3.0.1+
// STATIC_CHECK macro - Available in v3.0.1+
// OrcaSlicer is on Catch2 v3.11.0 - all of these ARE available:
// SKIP() macro - v3.3.0+
// Opt-in thread-safe assertions - v3.9.0+ (NOT enabled here; see Thread Safety)
// Built-in BENCHMARK / BENCHMARK_ADVANCED - v3.x
// testCasePartial events - v3.0.1+
// Multiple reporters simultaneously - v3.0.1+
// STATIC_CHECK macro - v3.0.1+
// Built-in test sharding (--shard-*) - v3.x
// v2 Limitations to remember:
// - Sections can be re-run if last section fails
// - String matcher is "Contains" not "ContainsSubstring"
// - Limited benchmarking support compared to v3
// - No test sharding built-in
// v3 notes to remember:
// - String matcher is "ContainsSubstring" (v2's "Contains" no longer exists)
// - Sections can still be re-run if a later section fails (unchanged from v2)
```
### Test Organization Best Practices