Add snapshots and JUnit result serialization0.2.0

4 files changed, 142 insertions, 0 deletions

diff --git a/src/Progmasoft/Catch3/Assertions.hpp b/src/Progmasoft/Catch3/Assertions.hpp
index 19ac13ef..668c086d 100644
--- a/src/Progmasoft/Catch3/Assertions.hpp
+++ b/src/Progmasoft/Catch3/Assertions.hpp
@@ -6,6 +6,7 @@
 #include <catch2/catch_test_macros.hpp>
 
 #include <Progmasoft/Catch3/Property.hpp>
+#include <Progmasoft/Catch3/Snapshot.hpp>
 
 /// Runs a property and reports its replay seed and minimized counterexample.
 #define CATCH3_CHECK_PROPERTY( ... )                            \
@@ -15,3 +16,12 @@
         INFO( catch3PropertyResult.Describe() );                \
         CHECK( catch3PropertyResult.Succeeded() );              \
     } while ( false )
+
+/// Compares a value with a named snapshot and reports the first difference.
+#define CATCH3_CHECK_SNAPSHOT( name, actual, options )                      \
+    do {                                                                    \
+        const auto catch3SnapshotResult =                                   \
+            ::Progmasoft::Catch3::CompareSnapshot( name, actual, options ); \
+        INFO( catch3SnapshotResult.Message );                               \
+        CHECK( catch3SnapshotResult.Succeeded() );                          \
+    } while ( false )
diff --git a/src/Progmasoft/Catch3/Results.hpp b/src/Progmasoft/Catch3/Results.hpp
new file mode 100644
index 00000000..b0b69b55
--- /dev/null
+++ b/src/Progmasoft/Catch3/Results.hpp
@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Progmasoft.
+// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1
+#pragma once
+
+#include <cstddef>
+#include <string>
+#include <vector>
+
+namespace Progmasoft::Catch3 {
+
+    enum class TestCaseStatus : unsigned char {
+        kPassed,
+        kFailed,
+        kErrored,
+        kSkipped,
+    };
+
+    /// Framework-neutral result for one completed test case.
+    struct TestCaseResult final {
+        std::string Name;
+        std::string ClassName;
+        std::string SourceFile;
+        TestCaseStatus Status = TestCaseStatus::kPassed;
+        double DurationSeconds = 0.0;
+        std::string Message;
+        std::string Details;
+        std::string StandardOutput;
+        std::string StandardError;
+    };
+
+    struct TestSuiteResult final {
+        std::string Name;
+        std::vector<TestCaseResult> TestCases;
+    };
+
+    struct TestRunResult final {
+        std::string Name;
+        std::vector<TestSuiteResult> TestSuites;
+    };
+
+    struct TestRunSummary final {
+        std::size_t Tests = 0;
+        std::size_t Failures = 0;
+        std::size_t Errors = 0;
+        std::size_t Skipped = 0;
+        double DurationSeconds = 0.0;
+
+        [[nodiscard]] std::size_t Passed() const noexcept;
+    };
+
+    /// Validates durations and statuses while aggregating nested test results.
+    [[nodiscard]] TestRunSummary
+    SummarizeTestSuite( const TestSuiteResult& result );
+    [[nodiscard]] TestRunSummary
+    SummarizeTestRun( const TestRunResult& result );
+
+} // namespace Progmasoft::Catch3
diff --git a/src/Progmasoft/Catch3/Snapshot.hpp b/src/Progmasoft/Catch3/Snapshot.hpp
new file mode 100644
index 00000000..09863c1c
--- /dev/null
+++ b/src/Progmasoft/Catch3/Snapshot.hpp
@@ -0,0 +1,55 @@
+// Copyright (c) 2026 Progmasoft.
+// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1
+#pragma once
+
+#include <cstddef>
+#include <filesystem>
+#include <string>
+#include <string_view>
+
+namespace Progmasoft::Catch3 {
+
+    /// Updates are deliberately explicit so normal test runs never rewrite
+    /// files.
+    enum class SnapshotUpdateMode : unsigned char {
+        kNever,
+        kCreateMissing,
+        kAlways,
+    };
+
+    enum class SnapshotStatus : unsigned char {
+        kMatched,
+        kCreated,
+        kUpdated,
+        kMismatched,
+        kInvalidName,
+        kInvalidOptions,
+        kIoError,
+    };
+
+    struct SnapshotOptions final {
+        std::filesystem::path Directory;
+        SnapshotUpdateMode UpdateMode = SnapshotUpdateMode::kNever;
+        bool NormalizeLineEndings = true;
+    };
+
+    /// Structured comparison result; DifferenceLine/Column are one-based.
+    struct SnapshotResult final {
+        SnapshotStatus Status = SnapshotStatus::kInvalidOptions;
+        std::filesystem::path File;
+        std::string Expected;
+        std::string Actual;
+        std::string Message;
+        std::size_t DifferenceLine = 0;
+        std::size_t DifferenceColumn = 0;
+
+        [[nodiscard]] bool Succeeded() const noexcept;
+    };
+
+    /// Compare against `<Directory>/<name>.snap`; names cannot contain paths.
+    [[nodiscard]] SnapshotResult
+    CompareSnapshot( std::string_view name,
+                     std::string_view actual,
+                     const SnapshotOptions& options );
+
+} // namespace Progmasoft::Catch3
diff --git a/src/Progmasoft/Catch3/XmlWriter.hpp b/src/Progmasoft/Catch3/XmlWriter.hpp
new file mode 100644
index 00000000..3216b5ae
--- /dev/null
+++ b/src/Progmasoft/Catch3/XmlWriter.hpp
@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Progmasoft.
+// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1
+#pragma once
+
+#include <iosfwd>
+#include <string>
+
+namespace Progmasoft::Catch3 {
+
+    struct TestRunResult;
+
+    /// Emits deterministic JUnit-style XML without timestamps or global state.
+    class JUnitXmlWriter final {
+    public:
+        static void Write( const TestRunResult& result, std::ostream& output );
+        [[nodiscard]] static std::string
+        ToString( const TestRunResult& result );
+    };
+
+} // namespace Progmasoft::Catch3