catch3
Progmasoft Catch3: an independently maintained C++17 test framework with a parallel runner, property checks, snapshots and structured results.
Clonegit clone https://git.progmasoft.com/catch3
Add Progmasoft Catch3 property testing and build support
- Commit
9ad804cedf4cc4a85ef89fe097f97a3b44654360- Author
- Leitwolf11 ·
- Parents
02f8b5593a15
Changes
.bazelversion | 1 + .github/workflows/alternative-build-systems.yml | 64 ++++ .github/workflows/linux-bazel-builds.yml | 28 -- .github/workflows/linux-meson-builds.yml | 48 --- .github/workflows/linux-other-builds.yml | 129 -------- .github/workflows/linux-simple-builds.yml | 109 ------- .github/workflows/meson-builds.yml | 42 +++ .github/workflows/package-manager-builds.yaml | 3 +- .github/workflows/validate-header-guards.yml | 2 +- .gitignore | 2 + BUILD.bazel | 4 +- LICENSES/AdditionRef-Progmasoft-Exception-1.1.txt | 80 +++++ LICENSES/MPL-2.0.txt | 373 ++++++++++++++++++++++ LICENSES/README.md | 15 + MODULE.bazel | 5 +- README.md | 45 ++- buildsupport/catch2_config.lua | 57 ++++ docs/progmasoft-catch3.md | 131 ++++++++ docs/why-catch3.md | 67 ++++ meson.build | 4 +- premake5.lua | 68 ++++ src/CMakeLists.txt | 43 +++ src/Progmasoft/BUILD.bazel | 20 ++ src/Progmasoft/Catch3.hpp | 13 + src/Progmasoft/Catch3/Assertions.hpp | 17 + src/Progmasoft/Catch3/Generator.hpp | 61 ++++ src/Progmasoft/Catch3/Generators/Boolean.hpp | 18 ++ src/Progmasoft/Catch3/Generators/Integer.hpp | 82 +++++ src/Progmasoft/Catch3/Property.hpp | 244 ++++++++++++++ src/Progmasoft/Catch3/Random.hpp | 113 +++++++ src/Progmasoft/ProgmasoftCatch3Config.cmake.in | 7 + src/Progmasoft/meson.build | 18 ++ tests/CMakeLists.txt | 7 + tests/Progmasoft/BUILD.bazel | 19 ++ tests/Progmasoft/Property.tests.cpp | 233 ++++++++++++++ tests/meson.build | 12 + xmake.lua | 49 +++ 37 files changed, 1885 insertions(+), 348 deletions(-) diff --git a/.bazelversion b/.bazelversion new file mode 100644 index 00000000..deeb3d66 --- /dev/null +++ b/.bazelversion @@ -0,0 +1 @@ +9.2.0 diff --git a/.github/workflows/alternative-build-systems.yml b/.github/workflows/alternative-build-systems.yml new file mode 100644 index 00000000..7f2cf531 --- /dev/null +++ b/.github/workflows/alternative-build-systems.yml @@ -0,0 +1,64 @@ +name: Alternative Build Systems + +on: [push, pull_request] + +jobs: + xmake: + name: Xmake on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [windows-2025, macos-15] + + steps: + - uses: actions/checkout@v6 + + - uses: xmake-io/github-action-setup-xmake@v1 + with: + xmake-version: '3.1.1' + + - name: Configure Clang build + run: xmake f --toolchain=clang -m debug -y + + - name: Build + run: xmake -j 4 + + - name: Run property tests + run: xmake run ProgmasoftPropertyTests + + premake: + name: Premake on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [windows-2022, macos-15] + + steps: + - uses: actions/checkout@v6 + + - uses: abel0b/setup-premake@v2.4 + with: + version: '5.0.0-beta7' + + - name: Generate and build Visual Studio projects + if: runner.os == 'Windows' + shell: pwsh + run: | + premake5 vs2022 + msbuild build/premake/Catch3.sln /m /p:Configuration=Debug /p:Platform=x64 /nologo + + - name: Run property tests on Windows + if: runner.os == 'Windows' + run: build/premake/bin/Debug/ProgmasoftPropertyTests.exe + + - name: Generate and build Clang Makefiles + if: runner.os == 'macOS' + run: | + premake5 gmake + make -C build/premake config=debug -j 4 + + - name: Run property tests on macOS + if: runner.os == 'macOS' + run: build/premake/bin/Debug/ProgmasoftPropertyTests diff --git a/.github/workflows/linux-bazel-builds.yml b/.github/workflows/linux-bazel-builds.yml deleted file mode 100644 index 20060405..00000000 --- a/.github/workflows/linux-bazel-builds.yml +++ /dev/null @@ -1,28 +0,0 @@ -name: Linux Builds (Bazel) - -on: [push, pull_request] - -env: - CTEST_OUTPUT_ON_FAILURE: 1 - CTEST_NO_TESTS_ACTION: error - -jobs: - build_and_test_ubuntu: - name: Linux Ubuntu 22.04 Bazel build <GCC 11.2.0> - runs-on: ubuntu-22.04 - strategy: - fail-fast: false - matrix: - compilation_mode: [fastbuild, dbg, opt] - - steps: - - uses: actions/checkout@v6 - - - name: Mount Bazel cache - uses: actions/cache@v5 - with: - path: "/home/runner/.cache/bazel" - key: bazel-ubuntu22-gcc11 - - - name: Build - run: bazelisk build --compilation_mode=${{matrix.compilation_mode}} //... diff --git a/.github/workflows/linux-meson-builds.yml b/.github/workflows/linux-meson-builds.yml deleted file mode 100644 index 5240c7cb..00000000 --- a/.github/workflows/linux-meson-builds.yml +++ /dev/null @@ -1,48 +0,0 @@ -name: Linux Builds (Meson) - -on: [push, pull_request] - -env: - CTEST_OUTPUT_ON_FAILURE: 1 - CTEST_NO_TESTS_ACTION: error - -jobs: - build: - name: meson ${{matrix.cxx}}, C++${{matrix.std}}, ${{matrix.build_type}} - runs-on: ubuntu-22.04 - strategy: - fail-fast: false - matrix: - cxx: - - g++-11 - - clang++-11 - build_type: [debug, release] - std: [14, 17] - include: - - cxx: clang++-11 - other_pkgs: clang-11 - - steps: - - uses: actions/checkout@v6 - - - name: Prepare environment - run: | - sudo apt-get update - sudo apt-get install -y meson ninja-build ${{matrix.other_pkgs}} - - - name: Configure - env: - CXX: ${{matrix.cxx}} - CXXFLAGS: -std=c++${{matrix.std}} ${{matrix.cxxflags}} - # Note: $GITHUB_WORKSPACE is distinct from ${{runner.workspace}}. - # This is important - run: | - meson -Dbuildtype=${{matrix.build_type}} ${{runner.workspace}}/meson-build - - - name: Build - working-directory: ${{runner.workspace}}/meson-build - run: ninja - - - name: Test - working-directory: ${{runner.workspace}}/meson-build - run: meson test --verbose diff --git a/.github/workflows/linux-other-builds.yml b/.github/workflows/linux-other-builds.yml deleted file mode 100644 index 188a1891..00000000 --- a/.github/workflows/linux-other-builds.yml +++ /dev/null @@ -1,129 +0,0 @@ -# The builds in this file are more complex (e.g. they need custom CMake -# configuration) and thus are unsuitable to the simple build matrix -# approach used in simple-builds -name: Linux Builds (Complex) - -on: [push, pull_request] - -env: - CTEST_OUTPUT_ON_FAILURE: 1 - CTEST_NO_TESTS_ACTION: error - -jobs: - build: - name: ${{matrix.build_description}}, ${{matrix.cxx}}, C++${{matrix.std}} ${{matrix.build_type}} - runs-on: ubuntu-22.04 - strategy: - fail-fast: false - matrix: - # We add builds one by one in this case, because there are no - # dimensions that are shared across the builds - include: - - # Single surrogate header build - - cxx: clang++-14 - build_description: Surrogates build - build_type: Debug - std: 14 - other_pkgs: clang-14 - cmake_configurations: -DCATCH_BUILD_SURROGATES=ON - - # Extras and examples with gcc-11 - - cxx: g++-11 - build_description: Extras + Examples - build_type: Debug - std: 14 - other_pkgs: g++-11 - cmake_configurations: -DCATCH_BUILD_EXTRA_TESTS=ON -DCATCH_BUILD_EXAMPLES=ON -DCATCH_ENABLE_CMAKE_HELPER_TESTS=ON - - cxx: g++-11 - build_description: Extras + Examples - build_type: Release - std: 14 - other_pkgs: g++-11 - cmake_configurations: -DCATCH_BUILD_EXTRA_TESTS=ON -DCATCH_BUILD_EXAMPLES=ON -DCATCH_ENABLE_CMAKE_HELPER_TESTS=ON - - # Extras and examples with Clang-14 - - cxx: clang++-14 - build_description: Extras + Examples - build_type: Debug - std: 17 - other_pkgs: clang-14 - cmake_configurations: -DCATCH_BUILD_EXTRA_TESTS=ON -DCATCH_BUILD_EXAMPLES=ON -DCATCH_ENABLE_CMAKE_HELPER_TESTS=ON - - cxx: clang++-14 - build_description: Extras + Examples - build_type: Release - std: 17 - other_pkgs: clang-14 - cmake_configurations: -DCATCH_BUILD_EXTRA_TESTS=ON -DCATCH_BUILD_EXAMPLES=ON -DCATCH_ENABLE_CMAKE_HELPER_TESTS=ON - - # Configure tests with Clang-14 - - cxx: clang++-14 - build_description: CMake configuration tests - build_type: Debug - std: 14 - other_pkgs: clang-14 - cmake_configurations: -DCATCH_ENABLE_CONFIGURE_TESTS=ON - - # Valgrind test Clang-14 - # - cxx: clang++-14 - # build_description: Valgrind tests - # build_type: Debug - # std: 14 - # other_pkgs: clang-14 valgrind - # cmake_configurations: -DMEMORYCHECK_COMMAND=`which valgrind` -DMEMORYCHECK_COMMAND_OPTIONS="-q --track-origins=yes --leak-check=full --num-callers=50 --show-leak-kinds=definite --error-exitcode=1" - # other_ctest_args: -T memcheck -LE uses-python - - - steps: - - uses: actions/checkout@v6 - - - name: Prepare environment - run: | - sudo apt-get update - sudo apt-get install -y ninja-build ${{matrix.other_pkgs}} - - - name: Configure build - run: | - cmake --preset basic-tests -GNinja \ - -DCMAKE_BUILD_TYPE=${{matrix.build_type}} \ - -DCMAKE_CXX_COMPILER=${{matrix.cxx}} \ - -DCMAKE_CXX_STANDARD=${{matrix.std}} \ - ${{matrix.cmake_configurations}} - - - name: Build - run: cmake --build build - - - name: Test - run: ctest --test-dir build -j - - clang-tidy: - name: clang-tidy - runs-on: ubuntu-22.04 - steps: - - uses: actions/checkout@v6 - - - name: Prepare environment - run: | - sudo apt-get update - sudo apt-get install -y ninja-build clang-15 clang-tidy-15 - - - name: Configure - run: | - clangtidy="clang-tidy-15;-use-color" - # Use a dummy compiler/linker/ar/ranlib to effectively disable the - # compilation and only run clang-tidy. - cmake --preset basic-tests -GNinja \ - -DCMAKE_AR=/usr/bin/true \ - -DCMAKE_BUILD_TYPE=Debug \ - -DCMAKE_CXX_CLANG_TIDY="$clangtidy" \ - -DCMAKE_CXX_COMPILER_AR=/usr/bin/true \ - -DCMAKE_CXX_COMPILER_LAUNCHER=/usr/bin/true \ - -DCMAKE_CXX_COMPILER=clang++-15 \ - -DCMAKE_CXX_LINK_EXECUTABLE=/usr/bin/true \ - -DCMAKE_CXX_STANDARD=17 \ - -DCMAKE_RANLIB=/usr/bin/true \ - -DCATCH_BUILD_EXAMPLES=ON \ - -DCATCH_ENABLE_CMAKE_HELPER_TESTS=ON - - - name: Run clang-tidy - run: cmake --build build diff --git a/.github/workflows/linux-simple-builds.yml b/.github/workflows/linux-simple-builds.yml deleted file mode 100644 index 17962cb8..00000000 --- a/.github/workflows/linux-simple-builds.yml +++ /dev/null @@ -1,109 +0,0 @@ -name: Linux Builds (Basic) - -on: [push, pull_request] - -env: - CTEST_OUTPUT_ON_FAILURE: 1 - CTEST_NO_TESTS_ACTION: error - -jobs: - build: - name: ${{matrix.cxx}}, C++${{matrix.std}}, ${{matrix.build_type}} - runs-on: ubuntu-22.04 - strategy: - fail-fast: false - matrix: - cxx: - - g++-9 - - g++-10 - - g++-11 - - g++-12 - - clang++-6.0 - - clang++-7 - - clang++-8 - - clang++-9 - - clang++-10 - - clang++-11 - - clang++-12 - - clang++-13 - - clang++-14 - build_type: [Debug, Release] - std: [14] - include: - - cxx: g++-9 - other_pkgs: g++-9 - - cxx: g++-10 - other_pkgs: g++-10 - - cxx: g++-11 - other_pkgs: g++-11 - - cxx: g++-12 - other_pkgs: g++-12 - - cxx: clang++-6.0 - other_pkgs: clang-6.0 - - cxx: clang++-7 - other_pkgs: clang-7 - - cxx: clang++-8 - other_pkgs: clang-8 - - cxx: clang++-9 - other_pkgs: clang-9 - - cxx: clang++-10 - other_pkgs: clang-10 - - cxx: clang++-11 - other_pkgs: clang-11 - - cxx: clang++-12 - other_pkgs: clang-12 - - cxx: clang++-13 - other_pkgs: clang-13 - - cxx: clang++-14 - other_pkgs: clang-14 - # Clang 14 + C++17 - - cxx: clang++-14 - build_type: Debug - std: 17 - other_pkgs: clang-14 - - cxx: clang++-14 - build_type: Release - std: 17 - other_pkgs: clang-14 - - cxx: clang++-14 - build_type: Debug - std: 20 - other_pkgs: clang-14 - - cxx: clang++-14 - build_type: Release - std: 20 - other_pkgs: clang-14 - - cxx: g++-11 - build_type: Debug - std: 20 - other_pkgs: g++-11 - - cxx: g++-11 - build_type: Release - std: 20 - other_pkgs: g++-11 - - steps: - - uses: actions/checkout@v6 - - - name: Add repositories for older compilers - run: | - sudo apt-add-repository 'deb http://azure.archive.ubuntu.com/ubuntu/ focal main' - sudo apt-add-repository 'deb http://azure.archive.ubuntu.com/ubuntu/ focal universe' - - - name: Prepare environment - run: | - sudo apt-get update - sudo apt-get install -y ninja-build ${{matrix.other_pkgs}} - - - name: Configure - run: | - cmake --preset basic-tests -GNinja \ - -DCMAKE_BUILD_TYPE=${{matrix.build_type}} \ - -DCMAKE_CXX_COMPILER=${{matrix.cxx}} \ - -DCMAKE_CXX_STANDARD=${{matrix.std}} - - - name: Build - run: cmake --build build - - - name: Test - run: ctest --test-dir build -j diff --git a/.github/workflows/meson-builds.yml b/.github/workflows/meson-builds.yml new file mode 100644 index 00000000..e7ff79af --- /dev/null +++ b/.github/workflows/meson-builds.yml @@ -0,0 +1,42 @@ +name: Meson Builds + +on: [push, pull_request] + +jobs: + build: + name: Meson on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [windows-2025, macos-15] + + steps: + - uses: actions/checkout@v6 + + - uses: actions/setup-python@v6 + with: + python-version: '3.14' + + - name: Install Meson and Ninja + run: python -m pip install meson ninja + + - name: Configure with Clang-CL on Windows + if: runner.os == 'Windows' + env: + CC: clang-cl + CXX: clang-cl + run: meson setup build/meson --vsenv -Dtests=true -Dinstall=false + + - name: Configure with Apple Clang on macOS + if: runner.os == 'macOS' + env: + CC: clang + CXX: clang++ + run: meson setup build/meson -Dtests=true -Dinstall=false + + - name: Build + run: meson compile -C build/meson + + - name: Test + run: meson test -C build/meson --print-errorlogs diff --git a/.github/workflows/package-manager-builds.yaml b/.github/workflows/package-manager-builds.yaml index 5754205d..8874b10a 100644 --- a/.github/workflows/package-manager-builds.yaml +++ b/.github/workflows/package-manager-builds.yaml @@ -5,9 +5,10 @@ on: [push, pull_request] jobs: conan_builds: name: Conan ${{matrix.conan_version}} - runs-on: ubuntu-22.04 + runs-on: ${{matrix.os}} strategy: matrix: + os: [macos-15, windows-2025] conan_version: - '1.63' - '2.1' diff --git a/.github/workflows/validate-header-guards.yml b/.github/workflows/validate-header-guards.yml index e6a1a190..bb82bd84 100644 --- a/.github/workflows/validate-header-guards.yml +++ b/.github/workflows/validate-header-guards.yml @@ -5,7 +5,7 @@ on: [push, pull_request] jobs: build: # Set the type of machine to run on - runs-on: ubuntu-22.04 + runs-on: macos-15 steps: - name: Checkout source code diff --git a/.gitignore b/.gitignore index dbf9f40a..cde67c29 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,8 @@ build-fuzzers debug-build .vscode msvc-sln* +.xmake/ +/build/ # Currently we use Doxygen for dep graphs and the full docs are only slowly # being filled in, so we definitely do not want git to deal with the docs. docs/doxygen diff --git a/BUILD.bazel b/BUILD.bazel index a318d190..4d4bfac9 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -7,13 +7,13 @@ package( ) exports_files([ - "LICENSE.MIT", + "LICENSE.txt", ]) license( name = "license", license_kinds = ["@rules_license//licenses/spdx:BSL-1.0"], - license_text = "LICENSE.MIT", + license_text = "LICENSE.txt", ) expand_template( diff --git a/LICENSES/AdditionRef-Progmasoft-Exception-1.1.txt b/LICENSES/AdditionRef-Progmasoft-Exception-1.1.txt new file mode 100644 index 00000000..b9dab6e0 --- /dev/null +++ b/LICENSES/AdditionRef-Progmasoft-Exception-1.1.txt @@ -0,0 +1,80 @@ +Progmasoft Linking Exception, Version 1.1 + +This Exception is an additional permission to the Mozilla Public License, version 2.0 ("MPL-2.0"). It is intended to preserve MPL-2.0's file-level obligations for Covered Software while removing doubt about combining that software with independent code. Capitalized terms not defined here have the meanings given in MPL-2.0. + +1. Definitions + +"Independent Component" means software contained in one or more Source Code Form files that neither contain Covered Software nor are Modifications of Covered Software. A component does not cease to be independent merely because compilation, static or dynamic linking, loading, packaging, or deployment places its Executable Form in the same file, process, address space, archive, image, or distribution as Covered Software. + +"Combined Work" means a Larger Work that combines Covered Software with one or more Independent Components by any technical means, including static or dynamic linking, loading, embedding, plugins, extensions, language bindings, an API, ABI, FFI boundary, command-line interface, protocol, inter-process communication mechanism, or file format. + +"Output" means material produced by executing Covered Software, including generated source, object code, executable code, intermediate representations, documentation, reports, diagnostics, formatted text, and analysis results. + +2. Additional Permission for Combined Works + +Subject to compliance with MPL-2.0 for the Covered Software, each recipient has a worldwide, royalty-free, non-exclusive, irrevocable additional copyright permission to create, reproduce, use, modify, display, perform, make available, and distribute a Combined Work under terms of the recipient's choice, including proprietary or closed-source terms. + +Those chosen terms may govern Independent Components and other portions of the Combined Work, but must not restrict or alter any recipient's rights in the Covered Software under MPL-2.0 and this Exception. No distributor is required to relicense an Independent Component merely because it forms part of a Combined Work. + +3. Boundary of Covered Software + +Linking, loading, calling, communicating with, packaging, installing, or distributing an Independent Component with Covered Software does not, by itself: + +(a) make the Independent Component Covered Software or a Modification; +(b) subject the Independent Component's Source Code Form to MPL-2.0; or +(c) expand MPL-2.0 beyond files that are Covered Software or Modifications under MPL-2.0. + +If Source Code Form from Covered Software is copied into another file, or a new Source Code Form file contains Covered Software, MPL-2.0 determines whether that file is a Modification. Labels, file extensions, build boundaries, code generation, or later separation of files do not avoid that determination. + +4. Outputs + +An Output does not become Covered Software merely because Covered Software produced, transformed, linked, or processed it. The copyright license chosen for input material does not change merely because Covered Software processes that material. + +If an Output contains copyrightable Source Code Form or other copyrightable material copied or derived from Covered Software, this Exception does not remove MPL-2.0 obligations from that incorporated material. Facts, ideas, interfaces, names, signatures, diagnostics, and other material not protected by copyright are not converted into Covered Software by this Exception. + +5. Preservation of MPL-2.0 Obligations + +This Exception does not remove, replace, waive, or narrow any MPL-2.0 obligation applicable to Covered Software. In particular: + +(a) Covered Software in Source Code Form and every Modification remain subject to MPL-2.0; +(b) distribution in Executable Form remains subject to MPL-2.0 Section 3.2, including the obligation to inform recipients how to obtain the corresponding Source Code Form when that section applies; +(c) notices protected by MPL-2.0 Section 3.4 must be retained; and +(d) this Exception grants no permission to withhold Source Code Form that MPL-2.0 requires to be made available. + +Distribution of a Combined Work under terms of choice is permission for the Combined Work as a whole and its Independent Components. It is not permission to relicense a Covered Software file. + +6. Packaging and Deployment + +Placing Covered Software and an Independent Component in the same archive, package, installer, application bundle, container image, firmware image, distribution medium, hosted deployment, or process does not change their respective copyright licenses. Network interaction or operation as separate processes is not required for independence. + +7. Direct Grant to Recipients + +The additional permission in this Exception is granted directly by the copyright holders applying it to every recipient of the applicable Covered Software. A distributor need not sublicense this Exception. Distribution through one or more intermediaries does not reduce the permission, and termination of an upstream distributor's rights does not terminate rights already received by a compliant downstream recipient. + +8. Termination and Reinstatement + +This Exception has no separate patent-litigation, field-of-use, combination, or compatibility termination condition. A recipient may exercise it only while entitled to exercise the corresponding MPL-2.0 copyright rights. If those rights terminate under MPL-2.0 Section 5.1, exercise of this Exception for the affected Covered Software is suspended to the same extent and is reinstated when, and to the extent that, the MPL-2.0 rights are reinstated. + +A recipient may elect to use Covered Software under MPL-2.0 without relying on this Exception. + +9. Other Rights + +This Exception grants copyright permission only. It grants no trademark, trade dress, service mark, publicity, confidential-information, or patent rights. Patent rights, if any, arise only under MPL-2.0 or a separately applicable patent grant. Nothing in this Exception limits rights arising independently under exhaustion, fair use, fair dealing, implied license, estoppel, or other applicable law. + +10. Relationship to MPL-2.0 + +MPL-2.0 and this Exception are read together. If this Exception and MPL-2.0 cannot both be given effect with respect to the creation or distribution of a Combined Work, this Exception controls only to the minimum extent necessary to provide the additional permission stated in Sections 2 through 6. MPL-2.0 controls in every other respect. + +Nothing here changes whether Covered Software is "Incompatible With Secondary Licenses" or changes the operation of MPL-2.0 Section 3.3 for a work governed by a Secondary License. + +11. Applicability and Version + +This Exception applies only to a file that expressly identifies it with this exact SPDX license expression: + +MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 + +Reference to Version 1.1 does not incorporate any later version. A copy of this text supplied in a repository or distribution identifies the permission; the per-file expression determines which files receive it. + +12. Severability + +If any provision of this Exception is held unenforceable, it shall be reformed only to the minimum extent necessary to make it enforceable. If reformation is unavailable, that provision is severed and the remaining provisions continue to the maximum extent permitted by law. diff --git a/LICENSES/MPL-2.0.txt b/LICENSES/MPL-2.0.txt new file mode 100644 index 00000000..d0a1fa14 --- /dev/null +++ b/LICENSES/MPL-2.0.txt @@ -0,0 +1,373 @@ +Mozilla Public License Version 2.0 +================================== + +1. Definitions +-------------- + +1.1. "Contributor" + means each individual or legal entity that creates, contributes to + the creation of, or owns Covered Software. + +1.2. "Contributor Version" + means the combination of the Contributions of others (if any) used + by a Contributor and that particular Contributor's Contribution. + +1.3. "Contribution" + means Covered Software of a particular Contributor. + +1.4. "Covered Software" + means Source Code Form to which the initial Contributor has attached + the notice in Exhibit A, the Executable Form of such Source Code + Form, and Modifications of such Source Code Form, in each case + including portions thereof. + +1.5. "Incompatible With Secondary Licenses" + means + + (a) that the initial Contributor has attached the notice described + in Exhibit B to the Covered Software; or + + (b) that the Covered Software was made available under the terms of + version 1.1 or earlier of the License, but not also under the + terms of a Secondary License. + +1.6. "Executable Form" + means any form of the work other than Source Code Form. + +1.7. "Larger Work" + means a work that combines Covered Software with other material, in + a separate file or files, that is not Covered Software. + +1.8. "License" + means this document. + +1.9. "Licensable" + means having the right to grant, to the maximum extent possible, + whether at the time of the initial grant or subsequently, any and + all of the rights conveyed by this License. + +1.10. "Modifications" + means any of the following: + + (a) any file in Source Code Form that results from an addition to, + deletion from, or modification of the contents of Covered + Software; or + + (b) any new file in Source Code Form that contains any Covered + Software. + +1.11. "Patent Claims" of a Contributor + means any patent claim(s), including without limitation, method, + process, and apparatus claims, in any patent Licensable by such + Contributor that would be infringed, but for the grant of the + License, by the making, using, selling, offering for sale, having + made, import, or transfer of either its Contributions or its + Contributor Version. + +1.12. "Secondary License" + means either the GNU General Public License, Version 2.0, the GNU + Lesser General Public License, Version 2.1, the GNU Affero General + Public License, Version 3.0, or any later versions of those + licenses. + +1.13. "Source Code Form" + means the form of the work preferred for making modifications. + +1.14. "You" (or "Your") + means an individual or a legal entity exercising rights under this + License. For legal entities, "You" includes any entity that + controls, is controlled by, or is under common control with You. For + purposes of this definition, "control" means (a) the power, direct + or indirect, to cause the direction or management of such entity, + whether by contract or otherwise, or (b) ownership of more than + fifty percent (50%) of the outstanding shares or beneficial + ownership of such entity. + +2. License Grants and Conditions +-------------------------------- + +2.1. Grants + +Each Contributor hereby grants You a world-wide, royalty-free, +non-exclusive license: + +(a) under intellectual property rights (other than patent or trademark) + Licensable by such Contributor to use, reproduce, make available, + modify, display, perform, distribute, and otherwise exploit its + Contributions, either on an unmodified basis, with Modifications, or + as part of a Larger Work; and + +(b) under Patent Claims of such Contributor to make, use, sell, offer + for sale, have made, import, and otherwise transfer either its + Contributions or its Contributor Version. + +2.2. Effective Date + +The licenses granted in Section 2.1 with respect to any Contribution +become effective for each Contribution on the date the Contributor first +distributes such Contribution. + +2.3. Limitations on Grant Scope + +The licenses granted in this Section 2 are the only rights granted under +this License. No additional rights or licenses will be implied from the +distribution or licensing of Covered Software under this License. +Notwithstanding Section 2.1(b) above, no patent license is granted by a +Contributor: + +(a) for any code that a Contributor has removed from Covered Software; + or + +(b) for infringements caused by: (i) Your and any other third party's + modifications of Covered Software, or (ii) the combination of its + Contributions with other software (except as part of its Contributor + Version); or + +(c) under Patent Claims infringed by Covered Software in the absence of + its Contributions. + +This License does not grant any rights in the trademarks, service marks, +or logos of any Contributor (except as may be necessary to comply with +the notice requirements in Section 3.4). + +2.4. Subsequent Licenses + +No Contributor makes additional grants as a result of Your choice to +distribute the Covered Software under a subsequent version of this +License (see Section 10.2) or under the terms of a Secondary License (if +permitted under the terms of Section 3.3). + +2.5. Representation + +Each Contributor represents that the Contributor believes its +Contributions are its original creation(s) or it has sufficient rights +to grant the rights to its Contributions conveyed by this License. + +2.6. Fair Use + +This License is not intended to limit any rights You have under +applicable copyright doctrines of fair use, fair dealing, or other +equivalents. + +2.7. Conditions + +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted +in Section 2.1. + +3. Responsibilities +------------------- + +3.1. Distribution of Source Form + +All distribution of Covered Software in Source Code Form, including any +Modifications that You create or to which You contribute, must be under +the terms of this License. You must inform recipients that the Source +Code Form of the Covered Software is governed by the terms of this +License, and how they can obtain a copy of this License. You may not +attempt to alter or restrict the recipients' rights in the Source Code +Form. + +3.2. Distribution of Executable Form + +If You distribute Covered Software in Executable Form then: + +(a) such Covered Software must also be made available in Source Code + Form, as described in Section 3.1, and You must inform recipients of + the Executable Form how they can obtain a copy of such Source Code + Form by reasonable means in a timely manner, at a charge no more + than the cost of distribution to the recipient; and + +(b) You may distribute such Executable Form under the terms of this + License, or sublicense it under different terms, provided that the + license for the Executable Form does not attempt to limit or alter + the recipients' rights in the Source Code Form under this License. + +3.3. Distribution of a Larger Work + +You may create and distribute a Larger Work under terms of Your choice, +provided that You also comply with the requirements of this License for +the Covered Software. If the Larger Work is a combination of Covered +Software with a work governed by one or more Secondary Licenses, and the +Covered Software is not Incompatible With Secondary Licenses, this +License permits You to additionally distribute such Covered Software +under the terms of such Secondary License(s), so that the recipient of +the Larger Work may, at their option, further distribute the Covered +Software under the terms of either this License or such Secondary +License(s). + +3.4. Notices + +You may not remove or alter the substance of any license notices +(including copyright notices, patent notices, disclaimers of warranty, +or limitations of liability) contained within the Source Code Form of +the Covered Software, except that You may alter any license notices to +the extent required to remedy known factual inaccuracies. + +3.5. Application of Additional Terms + +You may choose to offer, and to charge a fee for, warranty, support, +indemnity or liability obligations to one or more recipients of Covered +Software. However, You may do so only on Your own behalf, and not on +behalf of any Contributor. You must make it absolutely clear that any +such warranty, support, indemnity, or liability obligation is offered by +You alone, and You hereby agree to indemnify every Contributor for any +liability incurred by such Contributor as a result of warranty, support, +indemnity or liability terms You offer. You may include additional +disclaimers of warranty and limitations of liability specific to any +jurisdiction. + +4. Inability to Comply Due to Statute or Regulation +--------------------------------------------------- + +If it is impossible for You to comply with any of the terms of this +License with respect to some or all of the Covered Software due to +statute, judicial order, or regulation then You must: (a) comply with +the terms of this License to the maximum extent possible; and (b) +describe the limitations and the code they affect. Such description must +be placed in a text file included with all distributions of the Covered +Software under this License. Except to the extent prohibited by statute +or regulation, such description must be sufficiently detailed for a +recipient of ordinary skill to be able to understand it. + +5. Termination +-------------- + +5.1. The rights granted under this License will terminate automatically +if You fail to comply with any of its terms. However, if You become +compliant, then the rights granted under this License from a particular +Contributor are reinstated (a) provisionally, unless and until such +Contributor explicitly and finally terminates Your grants, and (b) on an +ongoing basis, if such Contributor fails to notify You of the +non-compliance by some reasonable means prior to 60 days after You have +come back into compliance. Moreover, Your grants from a particular +Contributor are reinstated on an ongoing basis if such Contributor +notifies You of the non-compliance by some reasonable means, this is the +first time You have received notice of non-compliance with this License +from such Contributor, and You become compliant prior to 30 days after +Your receipt of the notice. + +5.2. If You initiate litigation against any entity by asserting a patent +infringement claim (excluding declaratory judgment actions, +counter-claims, and cross-claims) alleging that a Contributor Version +directly or indirectly infringes any patent, then the rights granted to +You by any and all Contributors for the Covered Software under Section +2.1 of this License shall terminate. + +5.3. In the event of termination under Sections 5.1 or 5.2 above, all +end user license agreements (excluding distributors and resellers) which +have been validly granted by You or Your distributors under this License +prior to termination shall survive termination. + +************************************************************************ +* * +* 6. Disclaimer of Warranty * +* ------------------------- * +* * +* Covered Software is provided under this License on an "as is" * +* basis, without warranty of any kind, either expressed, implied, or * +* statutory, including, without limitation, warranties that the * +* Covered Software is free of defects, merchantable, fit for a * +* particular purpose or non-infringing. The entire risk as to the * +* quality and performance of the Covered Software is with You. * +* Should any Covered Software prove defective in any respect, You * +* (not any Contributor) assume the cost of any necessary servicing, * +* repair, or correction. This disclaimer of warranty constitutes an * +* essential part of this License. No use of any Covered Software is * +* authorized under this License except under this disclaimer. * +* * +************************************************************************ + +************************************************************************ +* * +* 7. Limitation of Liability * +* -------------------------- * +* * +* Under no circumstances and under no legal theory, whether tort * +* (including negligence), contract, or otherwise, shall any * +* Contributor, or anyone who distributes Covered Software as * +* permitted above, be liable to You for any direct, indirect, * +* special, incidental, or consequential damages of any character * +* including, without limitation, damages for lost profits, loss of * +* goodwill, work stoppage, computer failure or malfunction, or any * +* and all other commercial damages or losses, even if such party * +* shall have been informed of the possibility of such damages. This * +* limitation of liability shall not apply to liability for death or * +* personal injury resulting from such party's negligence to the * +* extent applicable law prohibits such limitation. Some * +* jurisdictions do not allow the exclusion or limitation of * +* incidental or consequential damages, so this exclusion and * +* limitation may not apply to You. * +* * +************************************************************************ + +8. Litigation +------------- + +Any litigation relating to this License may be brought only in the +courts of a jurisdiction where the defendant maintains its principal +place of business and such litigation shall be governed by laws of that +jurisdiction, without reference to its conflict-of-law provisions. +Nothing in this Section shall prevent a party's ability to bring +cross-claims or counter-claims. + +9. Miscellaneous +---------------- + +This License represents the complete agreement concerning the subject +matter hereof. If any provision of this License is held to be +unenforceable, such provision shall be reformed only to the extent +necessary to make it enforceable. Any law or regulation which provides +that the language of a contract shall be construed against the drafter +shall not be used to construe this License against a Contributor. + +10. Versions of the License +--------------------------- + +10.1. New Versions + +Mozilla Foundation is the license steward. Except as provided in Section +10.3, no one other than the license steward has the right to modify or +publish new versions of this License. Each version will be given a +distinguishing version number. + +10.2. Effect of New Versions + +You may distribute the Covered Software under the terms of the version +of the License under which You originally received the Covered Software, +or under the terms of any subsequent version published by the license +steward. + +10.3. Modified Versions + +If you create software not governed by this License, and you want to +create a new license for such software, you may create and use a +modified version of this License if you rename the license and remove +any references to the name of the license steward (except to note that +such modified license differs from this License). + +10.4. Distributing Source Code Form that is Incompatible With Secondary +Licenses + +If You choose to distribute Source Code Form that is Incompatible With +Secondary Licenses under the terms of this version of the License, the +notice described in Exhibit B of this License must be attached. + +Exhibit A - Source Code Form License Notice +------------------------------------------- + + This Source Code Form is subject to the terms of the Mozilla Public + License, v. 2.0. If a copy of the MPL was not distributed with this + file, You can obtain one at https://mozilla.org/MPL/2.0/. + +If it is not possible or desirable to put the notice in a particular +file, then You may include the notice in a location (such as a LICENSE +file in a relevant directory) where a recipient would be likely to look +for such a notice. + +You may add additional accurate notices of copyright ownership. + +Exhibit B - "Incompatible With Secondary Licenses" Notice +--------------------------------------------------------- + + This Source Code Form is "Incompatible With Secondary Licenses", as + defined by the Mozilla Public License, v. 2.0. diff --git a/LICENSES/README.md b/LICENSES/README.md new file mode 100644 index 00000000..8beb7655 --- /dev/null +++ b/LICENSES/README.md @@ -0,0 +1,15 @@ +# License map + +This repository contains two independently licensed source areas: + +- Catch2-originated files retain their upstream Boost Software License 1.0 + notices and the root `LICENSE.txt`. +- Progmasoft-authored files identify their terms in each file with + `SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1`. + The canonical MPL-2.0 text and Progmasoft linking exception are in this + directory. + +New Progmasoft files are kept separate from upstream files so the two license +boundaries remain visible. A patch intended for Catch2 upstream must follow the +upstream contribution instructions and must not be copied from a differently +licensed Progmasoft file without resolving that licensing boundary first. diff --git a/MODULE.bazel b/MODULE.bazel index ad4c2c4e..8bff2332 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -1,5 +1,6 @@ -module(name = "catch2") +module(name = "catch3", version = "0.1.0") bazel_dep(name = "bazel_skylib", version = "1.9.0") -bazel_dep(name = "rules_cc", version = "0.2.16") +bazel_dep(name = "rules_cc", version = "0.2.17") bazel_dep(name = "rules_license", version = "1.0.0") +bazel_dep(name = "platforms", version = "1.0.0") diff --git a/README.md b/README.md index 03dc7d7c..0af5cec5 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,12 @@ <a id="top"></a>  -[](https://github.com/catchorg/catch2/releases) -[](https://github.com/catchorg/Catch2/actions/workflows/linux-simple-builds.yml) -[](https://github.com/catchorg/Catch2/actions/workflows/linux-other-builds.yml) -[](https://github.com/catchorg/Catch2/actions/workflows/mac-builds.yml) -[](https://ci.appveyor.com/project/catchorg/catch2) -[](https://codecov.io/gh/catchorg/Catch2) -[](https://godbolt.org/z/EdoY15q9G) -[](https://discord.gg/4CWS9zD) +> **Progmasoft Catch3 is an independently maintained Catch2-derived project.** +> It currently keeps Catch2 3.16.0's test runner and compatibility API as its +> engine, and adds a separate C++20 property-testing layer. Catch2-originated +> files retain their upstream license; new Progmasoft APIs use the terms stated +> in each file. Catch3 is not an official Catch2 release or endorsed by Catch2's +> maintainers. [Why Catch3 exists and how it differs](docs/why-catch3.md). ## What is Catch2? @@ -69,23 +67,14 @@ _Note that benchmarks are not run by default, so you need to run it explicitly with the `[!benchmark]` tag._ -## Catch2 v3 has been released! +## Project status -You are on the `devel` branch, where the v3 version is being developed. -v3 brings a bunch of significant changes, the big one being that Catch2 -is no longer a single-header library. Catch2 now behaves as a normal -library, with multiple headers and separately compiled implementation. - -The documentation is slowly being updated to take these changes into -account, but this work is currently still ongoing. - -For migrating from the v2 releases to v3, you should look at [our -documentation](docs/migrate-v2-to-v3.md#top). It provides a simple -guidelines on getting started, and collects most common migration -problems. - -For the previous major version of Catch2 [look into the `v2.x` branch -here on GitHub](https://github.com/catchorg/Catch2/tree/v2.x). +This repository is based on Catch2's v3 development line and currently identifies +its compatibility engine as version 3.16.0. It is an early-stage fork: existing +Catch2 functionality remains the foundation, while Progmasoft additions are +being introduced in their own namespace and include tree. See the +[compatibility and difference notes](docs/why-catch3.md) before treating this as +a drop-in replacement in production. ## How to use it @@ -97,7 +86,9 @@ This documentation comprises these three parts: ## More -* Issues and bugs can be raised on the [Issue tracker on GitHub](https://github.com/catchorg/Catch2/issues) -* For discussion or questions please use [our Discord](https://discord.gg/4CWS9zD) -* See who else is using Catch2 in [Open Source Software](docs/opensource-users.md#top) +* Catch3 differences and current limitations: [docs/why-catch3.md](docs/why-catch3.md) +* Progmasoft property-testing API and integration: [docs/progmasoft-catch3.md](docs/progmasoft-catch3.md) +* Catch2 upstream history and migration reference: [Catch2's repository](https://github.com/catchorg/Catch2) +* Issues and bugs for this fork can be raised on the [Progmasoft/Catch3 issue tracker](https://github.com/Progmasoft/catch3/issues) +* Catch2's upstream documentation on [open-source users](docs/opensource-users.md#top) or [commercially](docs/commercial-users.md#top). diff --git a/buildsupport/catch2_config.lua b/buildsupport/catch2_config.lua new file mode 100644 index 00000000..5067d247 --- /dev/null +++ b/buildsupport/catch2_config.lua @@ -0,0 +1,57 @@ +-- Copyright (c) 2026 Progmasoft. +-- SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 + +-- Materialize Catch2's checked-in CMake template for non-CMake build tools. +-- Keeping the template as the source of truth avoids maintaining a second +-- copy of upstream configuration declarations under a different license. +local M = {} + +local function read_file(file_path) + local file = assert(io.open(file_path, "rb"), "cannot read " .. file_path) + local contents = file:read("*a") + file:close() + return contents +end + +local function write_file(file_path, contents) + local file = assert(io.open(file_path, "wb"), "cannot write " .. file_path) + file:write(contents) + file:close() +end + +--- Generates the default Catch2 user configuration header under output_root. +--- The generated path is output_root/catch2/catch_user_config.hpp. +function M.generate(output_root, repository_root) + local template_path = repository_root .. "/src/catch2/catch_user_config.hpp.in" + local template = read_file(template_path) + + -- Neither Xmake nor Premake interprets CMake's #cmakedefine directives. + -- All feature toggles stay at Catch2's defaults; the two value settings + -- match Catch2's own CMake defaults and the root Bazel configuration. + local configured = template:gsub( + "#cmakedefine%s+([%w_]+)%s*([^\r\n]*)", + function(name) + if name == "CATCH_CONFIG_DEFAULT_REPORTER" then + return '#define CATCH_CONFIG_DEFAULT_REPORTER "console"' + elseif name == "CATCH_CONFIG_CONSOLE_WIDTH" then + return "#define CATCH_CONFIG_CONSOLE_WIDTH 80" + end + return "/* #undef " .. name .. " */" + end + ) + + configured = configured:gsub('"@CATCH_CONFIG_DEFAULT_REPORTER@"', '"console"') + configured = configured:gsub("@CATCH_CONFIG_CONSOLE_WIDTH@", "80") + configured = configured:gsub("@CATCH_CONFIG_FALLBACK_STRINGIFIER@", "") + + local output_dir = output_root .. "/catch2" + os.mkdir(output_dir) + write_file(output_dir .. "/catch_user_config.hpp", configured) +end + +-- Xmake imports call the module's main entry point; Premake can use generate. +function main(output_root, repository_root) + return M.generate(output_root, repository_root) +end + +return M diff --git a/docs/progmasoft-catch3.md b/docs/progmasoft-catch3.md new file mode 100644 index 00000000..96989479 --- /dev/null +++ b/docs/progmasoft-catch3.md @@ -0,0 +1,131 @@ +# Progmasoft Catch3 additions + +Progmasoft Catch3 is a compatibility-preserving extension of Catch2, not a +replacement runner. The upstream `Catch2` API, command-line behavior, include +paths, and BSL-1.0 files remain the compatibility foundation. Progmasoft-owned +headers use the `Progmasoft/Catch3` include tree and `Progmasoft::Catch3` +namespace. + +## Property testing + +`<Progmasoft/Catch3.hpp>` is the umbrella header. It brings in Catch2's +`catch_all.hpp` as well as the Progmasoft extensions, so it is convenient but +increases compile time. Include individual headers when a translation unit only +needs a narrow part of the API. + +```cpp +#include <Progmasoft/Catch3.hpp> + +TEST_CASE("integer values stay in their requested domain", "[property]") { + CATCH3_CHECK_PROPERTY( + Progmasoft::Catch3::Integer<int>(1, 100), + [](int value) { return value > 0; }, + Progmasoft::Catch3::PropertyOptions{ + .Trials = 250, + .Seed = 0xC0FFEE, + .MaxShrinkSteps = 200}); +} +``` + +The current property API is split into these headers: + +- `<Progmasoft/Catch3/Random.hpp>`: portable SplitMix64 sequence, unbiased + bounded sampling, inclusive integer ranges, and per-trial seed derivation. +- `<Progmasoft/Catch3/Generator.hpp>`: user-defined generation/shrinking pair. +- `<Progmasoft/Catch3/Generators/Integer.hpp>` and `Boolean.hpp`: built-in + strategies with deterministic shrink candidates. +- `<Progmasoft/Catch3/Property.hpp>`: trial execution and structured results. +- `<Progmasoft/Catch3/Assertions.hpp>`: `CATCH3_CHECK_PROPERTY`, which reports + the failing trial, replay seed, reason, and minimized counterexample through + Catch2's normal assertion/reporting path. + +`PropertyOptions::Seed` is a stable root seed. Each trial receives a seed derived +from the root and its zero-based trial index, so the reported replay seed can be +used to reproduce that trial independently. The default generator is also stable +across standard-library implementations; it does not rely on the implementation- +defined output sequence of `std::uniform_int_distribution`. + +Shrinking is deterministic and greedy: candidates are tested in the order +provided by the generator, and the first still-failing candidate is selected. +`MaxShrinkSteps` bounds predicate evaluations during minimization. The result is +therefore a useful locally minimized counterexample, not a claim of a globally +minimal value. A false predicate or an exception from the predicate fails the +property. Exceptions from generation or shrinking are reported as execution +errors, distinct from an ordinary failing property. + +The API currently accepts one generated value per property. Tuple strategies, +state-machine commands, parallel trials, and adaptive shrinking are deliberately +not implied by this first module; they need their own deterministic contracts and +tests before being added. + +## Build and integration + +The CMake build exposes `Progmasoft::Catch3`, a C++20 interface target linked to +`Catch2::Catch2`. The existing Catch2 target retains its C++14 baseline. After +installation, consumers can use: + +```cmake +find_package(Catch2 3.16 CONFIG REQUIRED) +find_package(ProgmasoftCatch3 3.16 CONFIG REQUIRED) +target_link_libraries(MyTests PRIVATE Progmasoft::Catch3 Catch2::Catch2WithMain) +``` + +The Bazel target is `//src/Progmasoft:catch3`; its tests are +`//tests/Progmasoft:property_tests`. The compatibility project continues to +build with Catch2's upstream build and test structure. Bazel is the primary +build path; CMake, Meson, Xmake, and Premake are also maintained as alternate +ways to build the same engine and property tests. Their root files are +`CMakeLists.txt`, `meson.build`, `xmake.lua`, and `premake5.lua`. Xmake and +Premake materialize Catch2's default generated configuration header from the +checked-in upstream template. Meson 1.1.0 or newer is required for the Clang-CL +C++20 test target. + +For project history, compatibility intent, license split, and current feature +limits, read [Why Progmasoft Catch3?](why-catch3.md). + +## Build quick start + +Bazel is the primary build path: + +```sh +bazel test //tests/Progmasoft:property_tests +``` + +The alternate project builds exercise the same property suite: + +```sh +# CMake +cmake -S . -B build/cmake -DCATCH_DEVELOPMENT_BUILD=ON -DCATCH_BUILD_TESTING=ON +cmake --build build/cmake --target ProgmasoftSelfTest +ctest --test-dir build/cmake -R Progmasoft --output-on-failure + +# Xmake +xmake build ProgmasoftPropertyTests +xmake run ProgmasoftPropertyTests + +# Meson (Windows PowerShell; requires the Visual C++ SDK/CRT) +$env:CC = 'clang-cl'; $env:CXX = 'clang-cl' +meson setup build/meson --vsenv -Dtests=true -Dinstall=false +meson compile -C build/meson +meson test -C build/meson --print-errorlogs + +# Premake (choose an action supported by the host) +premake5 vs2022 +``` + +Premake generates projects rather than compiling directly; build the generated +solution with the corresponding host toolchain. On macOS, use +`premake5 gmake`, then build the generated makefiles with `make`. Meson users on +macOS can select Apple Clang with `CC=clang CXX=clang++` before configuration. + +## Compatibility and licensing boundary + +Do not rename or rewrite Catch2 headers, `Catch` symbols, macros, runner options, +or upstream coding style as part of this extension. New functionality belongs +in separately licensed Progmasoft headers and uses Progmasoft's PascalCase C++ +types/functions and project naming conventions. Catch2-originated source files +remain under BSL-1.0; Progmasoft-authored source files carry the MPL-2.0 plus +Progmasoft linking-exception SPDX expression shown in their headers. The two +areas are not relicensed as a whole. Any proposed upstream PR must be prepared +under Catch2's contribution rules as a separate contribution, rather than +reusing a source file whose license header says otherwise. diff --git a/docs/why-catch3.md b/docs/why-catch3.md new file mode 100644 index 00000000..0b62402f --- /dev/null +++ b/docs/why-catch3.md @@ -0,0 +1,67 @@ +# Why Progmasoft Catch3? + +Progmasoft Catch3 is an independently maintained continuation built on the +Catch2 v3 codebase. It exists to preserve Catch2's practical testing model while +giving Progmasoft room to add capabilities and APIs under a clear ownership, +namespace, build-target, and licensing boundary. + +The name does **not** mean that this is an official Catch2 v3 release, a new +upstream version, or a project endorsed by Catch2's maintainers. The current +compatibility engine is based on Catch2's 3.16.0 development line. The project +is still early-stage and does not yet replace or independently reimplement the +Catch2 runner. + +## What is different today? + +| Area | Catch2 compatibility engine | Progmasoft Catch3 additions | +| --- | --- | --- | +| Test execution | Catch2's existing runner, reporters, command-line interface, and test registration | `CATCH3_CHECK_PROPERTY` reports property outcomes through Catch2's assertion path | +| Public include path | Existing `catch2/...` headers | `Progmasoft/Catch3.hpp` and focused `Progmasoft/Catch3/...` headers | +| C++ baseline | Existing Catch2 target remains at C++14 | The added property API requires C++20 | +| Randomness | Catch2's existing behavior is unchanged | A specified SplitMix64 sequence provides deterministic trial seeds and unbiased bounded integer sampling | +| Generated values | No change to existing Catch2 generators | Initial integer/boolean strategies, custom generator callbacks, and bounded greedy shrinking | +| Build identity | Existing `Catch2` target and APIs remain available | Separate `Progmasoft::Catch3` CMake target and `//src/Progmasoft:catch3` Bazel target | +| Source terms | Catch2-originated source retains its upstream BSL-1.0 terms | Progmasoft-authored additions state their own SPDX license in each file | + +The current property runner handles one generated value per property. Shrinking +is deterministic and bounded, but greedy rather than globally minimal. There is +not yet built-in support for state-machine properties, generated tuples, +discard/classification policies, parallel execution, or a standalone Catch3 +runner. Those features are not implied by the initial API. + +## Compatibility policy + +Catch2's `Catch` namespace, established headers, macros, command-line behavior, +reporters, and coding style remain the compatibility surface. Progmasoft +features should be added under `Progmasoft::Catch3` and must not require users +to rename existing Catch2 tests. The first compatibility goal is source-level +continuity with the included Catch2 3.16.0 base; this is not a promise that every +future Catch2 upstream change will be adopted unchanged or that all downstream +projects have already been validated. + +The split also applies to implementation and packaging: Catch2 remains the +engine dependency, while Progmasoft's header-only API is a separate target. +Keep tests for the two areas independently identifiable so additions do not +silently alter the upstream compatibility baseline. + +## Why a fork instead of a patch series? + +The initial additions need their own design and release cycle. Keeping them in a +separate namespace and file tree lets the project prototype those APIs without +presenting them as upstream Catch2 behavior. If a change is later proposed to +Catch2 upstream, prepare it as a separate contribution under Catch2's current +contribution and licensing requirements; do not assume Progmasoft-licensed +files can be submitted unchanged. + +## Build-system support + +Bazel is the primary build and validation path. CMake, Meson, Xmake, and Premake +are supported alternate project-generation/build paths over the same local sources. +The CMake project preserves the upstream `Catch2` targets and adds +`Progmasoft::Catch3`; the other build descriptions compile the same Catch2 +engine and the Progmasoft property-test executable. See the repository build +instructions and each build file for tool-specific commands. + +Registry publication is a separate release step. It requires a versioned +immutable source archive and successful validation and maintainer review for +the `catch3` module name; a submission is not a guarantee of acceptance. diff --git a/meson.build b/meson.build index fe255fd0..467ebb61 100644 --- a/meson.build +++ b/meson.build @@ -10,10 +10,12 @@ project( 'cpp', version: '3.16.0', # CML version placeholder, don't delete license: 'BSL-1.0', - meson_version: '>=0.54.1', + # Meson 1.1 added clang-cl support for the C++20 mode used by Progmasoft tests. + meson_version: '>=1.1.0', ) subdir('src/catch2') +subdir('src/Progmasoft') if get_option('tests') subdir('tests') endif diff --git a/premake5.lua b/premake5.lua new file mode 100644 index 00000000..a03b8734 --- /dev/null +++ b/premake5.lua @@ -0,0 +1,68 @@ +-- Copyright (c) 2026 Progmasoft. +-- SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 + +local repository_root = path.getabsolute(".") +local generated_include = path.join(repository_root, "build", "premake", "generated") +local configure_catch2 = dofile(path.join(repository_root, "buildsupport", "catch2_config.lua")) +configure_catch2.generate(generated_include, repository_root) + +workspace "Catch3" + location "build/premake" + configurations { "Debug", "Release" } + startproject "ProgmasoftPropertyTests" + + filter "system:windows" + architecture "x86_64" + filter {} + + filter "system:macosx" + toolset "clang" + filter {} + + filter "configurations:Debug" + symbols "On" + runtime "Debug" + filter "configurations:Release" + optimize "Speed" + runtime "Release" + filter {} + +project "Catch2" + kind "StaticLib" + language "C++" + cppdialect "C++14" + targetdir "build/premake/bin/%{cfg.buildcfg}" + objdir "build/premake/obj/Catch2/%{cfg.buildcfg}" + files { + "src/catch2/**.cpp", + "src/catch2/**.hpp", + path.join(generated_include, "catch2", "catch_user_config.hpp"), + } + removefiles { "src/catch2/internal/catch_main.cpp" } + includedirs { "src", generated_include } + +project "Catch2WithMain" + kind "StaticLib" + language "C++" + cppdialect "C++14" + -- Visual Studio injects UNICODE for Windows projects, which would select + -- Catch2's wmain entry point instead of the normal console main. + defines { "DO_NOT_USE_WMAIN" } + targetdir "build/premake/bin/%{cfg.buildcfg}" + objdir "build/premake/obj/Catch2WithMain/%{cfg.buildcfg}" + files { "src/catch2/internal/catch_main.cpp" } + includedirs { "src", generated_include } + links { "Catch2" } + +project "ProgmasoftPropertyTests" + kind "ConsoleApp" + language "C++" + cppdialect "C++20" + targetdir "build/premake/bin/%{cfg.buildcfg}" + objdir "build/premake/obj/ProgmasoftPropertyTests/%{cfg.buildcfg}" + files { + "tests/Progmasoft/Property.tests.cpp", + "src/Progmasoft/**.hpp", + } + includedirs { "src", generated_include } + links { "Catch2WithMain", "Catch2" } diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 886605f1..cb8c339d 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -360,6 +360,19 @@ if(CATCH_ENABLE_REPRODUCIBLE_BUILD) endif() add_library(Catch2::Catch2 ALIAS Catch2) +# Progmasoft's C++20 additions are a separate target so the Catch2 +# compatibility engine can keep its existing, broader C++14 baseline. +add_library(ProgmasoftCatch3 INTERFACE) +add_library(Progmasoft::Catch3 ALIAS ProgmasoftCatch3) +set_target_properties(ProgmasoftCatch3 PROPERTIES EXPORT_NAME Catch3) +target_link_libraries(ProgmasoftCatch3 INTERFACE Catch2::Catch2) +target_include_directories(ProgmasoftCatch3 + INTERFACE + $<BUILD_INTERFACE:${CATCH_DIR}/src> + $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}> +) +target_compile_features(ProgmasoftCatch3 INTERFACE cxx_std_20) + if(ANDROID) target_link_libraries(Catch2 PRIVATE log) endif() @@ -436,6 +449,36 @@ if(NOT_SUBPROJECT) FILES_MATCHING PATTERN "*.hpp" ) + + # Keep the independently licensed Progmasoft headers beside Catch2's public + # headers while preserving a separate CMake target and package namespace. + install( + DIRECTORY "${CATCH_DIR}/src/Progmasoft" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}" + FILES_MATCHING PATTERN "*.hpp" + ) + install(TARGETS ProgmasoftCatch3 EXPORT ProgmasoftCatch3Targets) + install( + EXPORT ProgmasoftCatch3Targets + NAMESPACE Progmasoft:: + DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/ProgmasoftCatch3" + ) + configure_package_config_file( + "${CATCH_DIR}/src/Progmasoft/ProgmasoftCatch3Config.cmake.in" + "${PROJECT_BINARY_DIR}/ProgmasoftCatch3Config.cmake" + INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/ProgmasoftCatch3" + ) + write_basic_package_version_file( + "${PROJECT_BINARY_DIR}/ProgmasoftCatch3ConfigVersion.cmake" + VERSION "${PROJECT_VERSION}" + COMPATIBILITY SameMajorVersion + ) + install( + FILES + "${PROJECT_BINARY_DIR}/ProgmasoftCatch3Config.cmake" + "${PROJECT_BINARY_DIR}/ProgmasoftCatch3ConfigVersion.cmake" + DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/ProgmasoftCatch3" + ) endif() # Some tests require a full recompilation of Catch2 lib with different diff --git a/src/Progmasoft/BUILD.bazel b/src/Progmasoft/BUILD.bazel new file mode 100644 index 00000000..9927aafa --- /dev/null +++ b/src/Progmasoft/BUILD.bazel @@ -0,0 +1,20 @@ +# Copyright (c) 2026 Progmasoft. +# SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +load("@rules_cc//cc:defs.bzl", "cc_library") + +package(default_visibility = ["//visibility:public"]) + +cc_library( + name = "catch3", + hdrs = [ + "Catch3.hpp", + "Catch3/Assertions.hpp", + "Catch3/Generator.hpp", + "Catch3/Generators/Boolean.hpp", + "Catch3/Generators/Integer.hpp", + "Catch3/Property.hpp", + "Catch3/Random.hpp", + ], + strip_include_prefix = "/src", + deps = ["//:catch2"], +) diff --git a/src/Progmasoft/Catch3.hpp b/src/Progmasoft/Catch3.hpp new file mode 100644 index 00000000..1ae73e53 --- /dev/null +++ b/src/Progmasoft/Catch3.hpp @@ -0,0 +1,13 @@ +// Copyright (c) 2026 Progmasoft. +// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +#pragma once + +// Convenience include: prefer narrow headers when compile time matters. +#include <catch2/catch_all.hpp> + +#include <Progmasoft/Catch3/Assertions.hpp> +#include <Progmasoft/Catch3/Generator.hpp> +#include <Progmasoft/Catch3/Generators/Boolean.hpp> +#include <Progmasoft/Catch3/Generators/Integer.hpp> +#include <Progmasoft/Catch3/Property.hpp> +#include <Progmasoft/Catch3/Random.hpp> diff --git a/src/Progmasoft/Catch3/Assertions.hpp b/src/Progmasoft/Catch3/Assertions.hpp new file mode 100644 index 00000000..19ac13ef --- /dev/null +++ b/src/Progmasoft/Catch3/Assertions.hpp @@ -0,0 +1,17 @@ +// Copyright (c) 2026 Progmasoft. +// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +#pragma once + +#include <catch2/catch_message.hpp> +#include <catch2/catch_test_macros.hpp> + +#include <Progmasoft/Catch3/Property.hpp> + +/// Runs a property and reports its replay seed and minimized counterexample. +#define CATCH3_CHECK_PROPERTY( ... ) \ + do { \ + const auto catch3PropertyResult = \ + ::Progmasoft::Catch3::CheckProperty( __VA_ARGS__ ); \ + INFO( catch3PropertyResult.Describe() ); \ + CHECK( catch3PropertyResult.Succeeded() ); \ + } while ( false ) diff --git a/src/Progmasoft/Catch3/Generator.hpp b/src/Progmasoft/Catch3/Generator.hpp new file mode 100644 index 00000000..0e48aaa3 --- /dev/null +++ b/src/Progmasoft/Catch3/Generator.hpp @@ -0,0 +1,61 @@ +// Copyright (c) 2026 Progmasoft. +// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +#pragma once + +#include <Progmasoft/Catch3/Random.hpp> + +#include <functional> +#include <stdexcept> +#include <utility> +#include <vector> + +namespace Progmasoft::Catch3 { + + /// A value source paired with an ordered sequence of simpler candidates. + /// + /// The property runner owns the shrinking policy; generators only describe + /// which candidates are valid and which order is most useful for + /// minimization. + template <typename ValueType> + class Generator final { + public: + using GenerationFunction = std::function<ValueType( Random& )>; + using ShrinkingFunction = + std::function<std::vector<ValueType>( const ValueType& )>; + + Generator( GenerationFunction generate, ShrinkingFunction shrink ): + generate_( std::move( generate ) ), shrink_( std::move( shrink ) ) { + if ( !generate_ || !shrink_ ) { + throw std::invalid_argument( + "a generator requires both callbacks" ); + } + } + + [[nodiscard]] ValueType Generate( Random& random ) const { + return generate_( random ); + } + + [[nodiscard]] std::vector<ValueType> + Shrink( const ValueType& value ) const { + return shrink_( value ); + } + + private: + GenerationFunction generate_; + ShrinkingFunction shrink_; + }; + + /// Adapts user callables into a reusable generator. + template <typename ValueType, + typename GenerateFunction, + typename ShrinkFunction> + [[nodiscard]] Generator<ValueType> + MakeGenerator( GenerateFunction&& generate, ShrinkFunction&& shrink ) { + return Generator<ValueType>( + typename Generator<ValueType>::GenerationFunction( + std::forward<GenerateFunction>( generate ) ), + typename Generator<ValueType>::ShrinkingFunction( + std::forward<ShrinkFunction>( shrink ) ) ); + } + +} // namespace Progmasoft::Catch3 diff --git a/src/Progmasoft/Catch3/Generators/Boolean.hpp b/src/Progmasoft/Catch3/Generators/Boolean.hpp new file mode 100644 index 00000000..3f881927 --- /dev/null +++ b/src/Progmasoft/Catch3/Generators/Boolean.hpp @@ -0,0 +1,18 @@ +// Copyright (c) 2026 Progmasoft. +// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +#pragma once + +#include <Progmasoft/Catch3/Generator.hpp> + +namespace Progmasoft::Catch3 { + + /// Generates booleans and shrinks true to the simplest value, false. + [[nodiscard]] inline Generator<bool> Boolean() { + return MakeGenerator<bool>( + []( Random& random ) { return ( random.Next() & 1U ) != 0; }, + []( const bool& value ) { + return value ? std::vector<bool>{ false } : std::vector<bool>{}; + } ); + } + +} // namespace Progmasoft::Catch3 diff --git a/src/Progmasoft/Catch3/Generators/Integer.hpp b/src/Progmasoft/Catch3/Generators/Integer.hpp new file mode 100644 index 00000000..2a50525e --- /dev/null +++ b/src/Progmasoft/Catch3/Generators/Integer.hpp @@ -0,0 +1,82 @@ +// Copyright (c) 2026 Progmasoft. +// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +#pragma once + +#include <Progmasoft/Catch3/Generator.hpp> + +#include <algorithm> +#include <concepts> +#include <limits> +#include <type_traits> + +namespace Progmasoft::Catch3 { + namespace Detail { + + template <std::integral IntegerType> + requires( !std::same_as<IntegerType, bool> ) + [[nodiscard]] std::vector<IntegerType> ShrinkInteger( + IntegerType value, IntegerType minimum, IntegerType maximum ) { + std::vector<IntegerType> candidates; + const auto addCandidate = [&]( IntegerType candidate ) { + if ( candidate < minimum || candidate > maximum || + candidate == value || + std::ranges::find( candidates, candidate ) != + candidates.end() ) { + return; + } + candidates.push_back( candidate ); + }; + + if ( value == 0 ) { return candidates; } + + // First try the conventional simplest value, then halve toward it. + // The adjacent value at the end lets the runner find boundary + // counterexamples (for example, the first failing integer in a + // threshold property). + if ( minimum <= 0 && maximum >= 0 ) { addCandidate( 0 ); } + + IntegerType smaller = value; + while ( smaller != 0 ) { + smaller = static_cast<IntegerType>( smaller / 2 ); + if ( smaller == 0 ) { break; } + addCandidate( smaller ); + } + + if ( value > 0 ) { + if ( value > minimum ) { + addCandidate( static_cast<IntegerType>( value - 1 ) ); + } + if ( minimum > 0 ) { addCandidate( minimum ); } + } else { + if ( value < maximum ) { + addCandidate( static_cast<IntegerType>( value + 1 ) ); + } + if ( maximum < 0 ) { addCandidate( maximum ); } + } + return candidates; + } + + } // namespace Detail + + /// Generates integers over the inclusive range and shrinks toward simple + /// values. + template <std::integral IntegerType> + requires( !std::same_as<IntegerType, bool> ) + [[nodiscard]] Generator<IntegerType> Integer( + IntegerType minimum = std::numeric_limits<IntegerType>::lowest(), + IntegerType maximum = std::numeric_limits<IntegerType>::max() ) { + if ( minimum > maximum ) { + throw std::invalid_argument( + "Integer requires minimum <= maximum" ); + } + + return MakeGenerator<IntegerType>( + [minimum, maximum]( Random& random ) { + return random.Between( minimum, maximum ); + }, + [minimum, maximum]( const IntegerType& value ) { + return Detail::ShrinkInteger( value, minimum, maximum ); + } ); + } + +} // namespace Progmasoft::Catch3 diff --git a/src/Progmasoft/Catch3/Property.hpp b/src/Progmasoft/Catch3/Property.hpp new file mode 100644 index 00000000..57e74408 --- /dev/null +++ b/src/Progmasoft/Catch3/Property.hpp @@ -0,0 +1,244 @@ +// Copyright (c) 2026 Progmasoft. +// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +#pragma once + +#include <catch2/catch_tostring.hpp> + +#include <Progmasoft/Catch3/Generator.hpp> + +#include <concepts> +#include <cstddef> +#include <cstdint> +#include <exception> +#include <functional> +#include <optional> +#include <sstream> +#include <string> +#include <type_traits> +#include <utility> + +namespace Progmasoft::Catch3 { + + /// Controls a property run without changing the compatibility runner's CLI. + struct PropertyOptions final { + std::size_t Trials = 100; + std::uint64_t Seed = 0xC47C4A53ULL; + std::size_t MaxShrinkSteps = 1000; + }; + + enum class PropertyStatus : std::uint8_t { + kPassed, + kFailed, + kErrored, + kInvalidConfiguration, + }; + + struct PropertyFailure final { + std::uint64_t RootSeed = 0; + std::uint64_t TrialSeed = 0; + std::size_t Trial = 0; + std::size_t ShrinkSteps = 0; + std::string Counterexample; + std::string Reason; + }; + + /// Stable, machine-readable outcome with a deterministic human-readable + /// report. + struct PropertyResult final { + PropertyStatus Status = PropertyStatus::kPassed; + std::size_t TrialsRun = 0; + std::optional<PropertyFailure> Failure; + std::string Error; + + [[nodiscard]] bool Succeeded() const noexcept { + return Status == PropertyStatus::kPassed; + } + + [[nodiscard]] std::string Describe() const { + std::ostringstream output; + switch ( Status ) { + case PropertyStatus::kPassed: + output << "property passed: " << TrialsRun << " trials"; + return output.str(); + case PropertyStatus::kInvalidConfiguration: + output << "invalid property configuration: " << Error; + return output.str(); + case PropertyStatus::kErrored: + output << "property execution errored after " << TrialsRun + << " trials: " << Error; + break; + case PropertyStatus::kFailed: + output << "property failed after " << TrialsRun << " trials"; + break; + } + + if ( Failure.has_value() ) { + output << "; failing trial " << Failure->Trial << ", root seed " + << Failure->RootSeed << ", replay seed " + << Failure->TrialSeed << ", shrink checks " + << Failure->ShrinkSteps + << "\ncounterexample: " << Failure->Counterexample + << "\nreason: " << Failure->Reason; + } + return output.str(); + } + }; + + namespace Detail { + + template <typename ValueType> + [[nodiscard]] std::string + StringifyPropertyValue( const ValueType& value ) { + return Catch::StringMaker<std::remove_cvref_t<ValueType>>::convert( + value ); + } + + template <typename Predicate, typename ValueType> + [[nodiscard]] std::optional<std::string> + EvaluateProperty( Predicate& predicate, const ValueType& value ) { + try { + if ( static_cast<bool>( std::invoke( predicate, value ) ) ) { + return std::nullopt; + } + return "predicate returned false"; + } catch ( const std::exception& exception ) { + return std::string( "predicate threw std::exception: " ) + + exception.what(); + } catch ( ... ) { + return "predicate threw a non-standard exception"; + } + } + + template <typename ValueType> + [[nodiscard]] std::string + DescribeValue( const ValueType& value ) noexcept { + try { + return StringifyPropertyValue( value ); + } catch ( const std::exception& exception ) { + return std::string( "<stringification failed: " ) + + exception.what() + ">"; + } catch ( ... ) { + return "<stringification failed with a non-standard exception>"; + } + } + + } // namespace Detail + + /// Runs independently seeded trials and greedily accepts failing shrink + /// candidates. + template <typename ValueType, typename Predicate> + requires std::invocable<Predicate&, const ValueType&>&& + std::convertible_to<std::invoke_result_t<Predicate&, const ValueType&>, + bool> [[nodiscard]] PropertyResult + CheckProperty( const Generator<ValueType>& generator, + Predicate predicate, + PropertyOptions options = {} ) { + if ( options.Trials == 0 ) { + return { PropertyStatus::kInvalidConfiguration, + 0, + std::nullopt, + "Trials must be greater than zero" }; + } + + PropertyResult result; + for ( std::size_t trial = 0; trial < options.Trials; ++trial ) { + result.TrialsRun = trial + 1; + const std::uint64_t trialSeed = + Random::DeriveSeed( options.Seed, trial ); + Random random( trialSeed ); + std::optional<ValueType> sample; + + try { + sample.emplace( generator.Generate( random ) ); + } catch ( const std::exception& exception ) { + result.Status = PropertyStatus::kErrored; + result.Error = + std::string( "generator threw std::exception: " ) + + exception.what(); + result.Failure = PropertyFailure{ options.Seed, + trialSeed, + trial + 1, + 0, + "<not generated>", + result.Error }; + return result; + } catch ( ... ) { + result.Status = PropertyStatus::kErrored; + result.Error = "generator threw a non-standard exception"; + result.Failure = PropertyFailure{ options.Seed, + trialSeed, + trial + 1, + 0, + "<not generated>", + result.Error }; + return result; + } + + auto reason = Detail::EvaluateProperty( predicate, *sample ); + if ( !reason.has_value() ) { continue; } + + std::size_t shrinkChecks = 0; + try { + bool improved = true; + while ( improved && shrinkChecks < options.MaxShrinkSteps ) { + improved = false; + const std::vector<ValueType> candidates = + generator.Shrink( *sample ); + for ( std::size_t candidateIndex = 0; + candidateIndex < candidates.size(); + ++candidateIndex ) { + if ( shrinkChecks >= options.MaxShrinkSteps ) { break; } + ++shrinkChecks; + const ValueType candidate = static_cast<ValueType>( + candidates[candidateIndex] ); + auto candidateReason = + Detail::EvaluateProperty( predicate, candidate ); + if ( candidateReason.has_value() ) { + sample.emplace( candidate ); + reason = std::move( candidateReason ); + improved = true; + break; + } + } + } + } catch ( const std::exception& exception ) { + result.Status = PropertyStatus::kErrored; + result.Error = + std::string( "shrinker threw std::exception: " ) + + exception.what(); + result.Failure = + PropertyFailure{ options.Seed, + trialSeed, + trial + 1, + shrinkChecks, + Detail::DescribeValue( *sample ), + *reason }; + return result; + } catch ( ... ) { + result.Status = PropertyStatus::kErrored; + result.Error = "shrinker threw a non-standard exception"; + result.Failure = + PropertyFailure{ options.Seed, + trialSeed, + trial + 1, + shrinkChecks, + Detail::DescribeValue( *sample ), + *reason }; + return result; + } + + result.Status = PropertyStatus::kFailed; + result.Failure = PropertyFailure{ options.Seed, + trialSeed, + trial + 1, + shrinkChecks, + Detail::DescribeValue( *sample ), + *reason }; + return result; + } + + result.Status = PropertyStatus::kPassed; + return result; + } + +} // namespace Progmasoft::Catch3 diff --git a/src/Progmasoft/Catch3/Random.hpp b/src/Progmasoft/Catch3/Random.hpp new file mode 100644 index 00000000..0a95cb84 --- /dev/null +++ b/src/Progmasoft/Catch3/Random.hpp @@ -0,0 +1,113 @@ +// Copyright (c) 2026 Progmasoft. +// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +#pragma once + +#include <bit> +#include <concepts> +#include <cstdint> +#include <limits> +#include <stdexcept> +#include <type_traits> + +namespace Progmasoft::Catch3 { + + /// Small, deterministic random source for repeatable property-test cases. + /// + /// The SplitMix64 sequence is specified here instead of delegating to a + /// standard-library engine, whose output sequence is not portable between + /// library implementations. A Random object is intentionally not + /// thread-safe; property trials receive independent instances derived from + /// the root seed. + class Random final { + public: + explicit constexpr Random( std::uint64_t seed ) noexcept: + state_( seed ) {} + + /// Returns the next value in the stable SplitMix64 sequence. + [[nodiscard]] constexpr std::uint64_t Next() noexcept { + state_ += kGamma; + std::uint64_t value = state_; + value = ( value ^ ( value >> 30U ) ) * kMultiplierOne; + value = ( value ^ ( value >> 27U ) ) * kMultiplierTwo; + return value ^ ( value >> 31U ); + } + + /// Returns a value in [0, bound); bound == 0 requests the full uint64 + /// range. + [[nodiscard]] constexpr std::uint64_t + Below( std::uint64_t bound ) noexcept { + if ( bound == 0 ) { return Next(); } + + // Rejection sampling avoids the modulo bias of a single `% bound`. + const std::uint64_t threshold = + ( std::uint64_t{ 0 } - bound ) % bound; + while ( true ) { + const std::uint64_t value = Next(); + if ( value >= threshold ) { return value % bound; } + } + } + + /// Returns an inclusive integral value without overflowing at type + /// limits. + template <std::integral IntegerType> + requires( !std::same_as<IntegerType, bool> ) [[nodiscard]] IntegerType + Between( IntegerType minimum, IntegerType maximum ) { + if ( minimum > maximum ) { + throw std::invalid_argument( + "Random::Between requires minimum <= maximum" ); + } + + using UnsignedType = std::make_unsigned_t<IntegerType>; + static_assert( std::numeric_limits<UnsignedType>::digits <= 64 ); + + constexpr unsigned kBitCount = static_cast<unsigned>( + std::numeric_limits<UnsignedType>::digits ); + constexpr UnsignedType kSignBit = UnsignedType{ 1 } + << ( kBitCount - 1U ); + + const auto encode = + []( IntegerType value ) constexpr -> UnsignedType { + if constexpr ( std::is_signed_v<IntegerType> ) { + return std::bit_cast<UnsignedType>( value ) ^ kSignBit; + } else { + return value; + } + }; + const auto decode = + []( UnsignedType value ) constexpr -> IntegerType { + if constexpr ( std::is_signed_v<IntegerType> ) { + return std::bit_cast<IntegerType>( value ^ kSignBit ); + } else { + return value; + } + }; + + const UnsignedType lower = encode( minimum ); + const UnsignedType upper = encode( maximum ); + // Unsigned wrap to zero represents the complete value domain. + const UnsignedType width = + static_cast<UnsignedType>( upper - lower + UnsignedType{ 1 } ); + const UnsignedType offset = + width == 0 ? static_cast<UnsignedType>( Next() ) + : static_cast<UnsignedType>( + Below( static_cast<std::uint64_t>( width ) ) ); + return decode( static_cast<UnsignedType>( lower + offset ) ); + } + + /// Derives an independent, reproducible seed for one trial. + [[nodiscard]] static constexpr std::uint64_t + DeriveSeed( std::uint64_t rootSeed, + std::uint64_t trialIndex ) noexcept { + Random trialRandom( rootSeed + kGamma * ( trialIndex + 1U ) ); + return trialRandom.Next(); + } + + private: + static constexpr std::uint64_t kGamma = 0x9E3779B97F4A7C15ULL; + static constexpr std::uint64_t kMultiplierOne = 0xBF58476D1CE4E5B9ULL; + static constexpr std::uint64_t kMultiplierTwo = 0x94D049BB133111EBULL; + + std::uint64_t state_; + }; + +} // namespace Progmasoft::Catch3 diff --git a/src/Progmasoft/ProgmasoftCatch3Config.cmake.in b/src/Progmasoft/ProgmasoftCatch3Config.cmake.in new file mode 100644 index 00000000..a4b3ff31 --- /dev/null +++ b/src/Progmasoft/ProgmasoftCatch3Config.cmake.in @@ -0,0 +1,7 @@ +# Copyright (c) 2026 Progmasoft. +# SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +@PACKAGE_INIT@ + +include(CMakeFindDependencyMacro) +find_dependency(Catch2 @PROJECT_VERSION@ CONFIG REQUIRED) +include("${CMAKE_CURRENT_LIST_DIR}/ProgmasoftCatch3Targets.cmake") diff --git a/src/Progmasoft/meson.build b/src/Progmasoft/meson.build new file mode 100644 index 00000000..109edaa4 --- /dev/null +++ b/src/Progmasoft/meson.build @@ -0,0 +1,18 @@ +# Copyright (c) 2026 Progmasoft. +# SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 + +# Expose the header-only C++20 layer without raising Catch2's C++14 baseline. +progmasoft_catch3_dep = declare_dependency( + dependencies: catch2_dep, + include_directories: include_directories('..'), +) + +if get_option('install') + install_headers('Catch3.hpp', subdir: 'Progmasoft') + install_headers('Catch3/Assertions.hpp', subdir: 'Progmasoft/Catch3') + install_headers('Catch3/Generator.hpp', subdir: 'Progmasoft/Catch3') + install_headers('Catch3/Property.hpp', subdir: 'Progmasoft/Catch3') + install_headers('Catch3/Random.hpp', subdir: 'Progmasoft/Catch3') + install_headers('Catch3/Generators/Boolean.hpp', subdir: 'Progmasoft/Catch3/Generators') + install_headers('Catch3/Generators/Integer.hpp', subdir: 'Progmasoft/Catch3/Generators') +endif diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 33daefb8..d307ecd8 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -154,6 +154,13 @@ include(CTest) add_executable(SelfTest ${TEST_SOURCES} ${TEST_HEADERS}) target_include_directories(SelfTest PRIVATE ${SELF_TEST_DIR}) target_link_libraries(SelfTest PRIVATE Catch2WithMain) + +# Exercise the C++20 Progmasoft layer independently so the upstream Catch2 +# SelfTest continues to compile at its supported baseline language level. +add_executable(ProgmasoftSelfTest Progmasoft/Property.tests.cpp) +target_link_libraries(ProgmasoftSelfTest PRIVATE Progmasoft::Catch3 Catch2WithMain) +target_compile_features(ProgmasoftSelfTest PRIVATE cxx_std_20) +add_test(NAME Progmasoft::PropertyTests COMMAND $<TARGET_FILE:ProgmasoftSelfTest>) if(BUILD_SHARED_LIBS AND WIN32) add_custom_command(TARGET SelfTest PRE_LINK COMMAND ${CMAKE_COMMAND} -E copy_if_different $<TARGET_FILE:Catch2> diff --git a/tests/Progmasoft/BUILD.bazel b/tests/Progmasoft/BUILD.bazel new file mode 100644 index 00000000..c0cb14ac --- /dev/null +++ b/tests/Progmasoft/BUILD.bazel @@ -0,0 +1,19 @@ +# Copyright (c) 2026 Progmasoft. +# SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +load("@rules_cc//cc:defs.bzl", "cc_test") + +package(default_visibility = ["//visibility:public"]) + +cc_test( + name = "property_tests", + srcs = ["Property.tests.cpp"], + copts = select({ + "@platforms//os:windows": ["/std:c++20"], + "//conditions:default": ["-std=c++20"], + }), + deps = [ + "//:catch2", + "//:catch2_main", + "//src/Progmasoft:catch3", + ], +) diff --git a/tests/Progmasoft/Property.tests.cpp b/tests/Progmasoft/Property.tests.cpp new file mode 100644 index 00000000..5cec3979 --- /dev/null +++ b/tests/Progmasoft/Property.tests.cpp @@ -0,0 +1,233 @@ +// Copyright (c) 2026 Progmasoft. +// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 +#include <Progmasoft/Catch3.hpp> + +#include <algorithm> +#include <cstdint> +#include <limits> +#include <stdexcept> +#include <string> +#include <vector> + +TEST_CASE( "Progmasoft random sequences are stable and bounded", + "[progmasoft][random]" ) { + using Progmasoft::Catch3::Random; + + Random random( 0 ); + CHECK( random.Next() == 0xE220A8397B1DCDAFULL ); + CHECK( random.Next() == 0x6E789E6AA1B965F4ULL ); + + Random bounded( 0xA55A ); + for ( int index = 0; index < 1000; ++index ) { + CHECK( bounded.Below( 17 ) < 17 ); + CHECK( bounded.Between<std::int32_t>( -31, 47 ) >= -31 ); + CHECK( bounded.Between<std::int32_t>( -31, 47 ) <= 47 ); + } + + CHECK_THROWS_AS( bounded.Between<std::int32_t>( 2, 1 ), + std::invalid_argument ); +} + +TEST_CASE( "Progmasoft random supports full-width signed intervals", + "[progmasoft][random]" ) { + using Progmasoft::Catch3::Random; + + Random random( 0x12345678 ); + for ( int index = 0; index < 100; ++index ) { + const std::int64_t value = + random.Between( std::numeric_limits<std::int64_t>::lowest(), + std::numeric_limits<std::int64_t>::max() ); + CHECK( value <= std::numeric_limits<std::int64_t>::max() ); + CHECK( value >= std::numeric_limits<std::int64_t>::lowest() ); + } + + const std::uint64_t first = Random::DeriveSeed( 99, 0 ); + CHECK( first == Random::DeriveSeed( 99, 0 ) ); + CHECK( first != Random::DeriveSeed( 99, 1 ) ); +} + +TEST_CASE( "Integer generators preserve bounds and useful shrink order", + "[progmasoft][generator]" ) { + using Progmasoft::Catch3::Integer; + using Progmasoft::Catch3::Random; + + const auto generator = Integer<int>( -100, 100 ); + Random random( 0xBADC0DE ); + for ( int index = 0; index < 100; ++index ) { + const int value = generator.Generate( random ); + CHECK( value >= -100 ); + CHECK( value <= 100 ); + } + + const std::vector<int> positiveShrinks = + Integer<int>( -100, 100 ).Shrink( 6 ); + REQUIRE( !positiveShrinks.empty() ); + CHECK( positiveShrinks.front() == 0 ); + CHECK( std::ranges::find( positiveShrinks, 5 ) != positiveShrinks.end() ); + + const std::vector<int> negativeShrinks = generator.Shrink( -6 ); + CHECK( negativeShrinks.front() == 0 ); + CHECK( std::ranges::find( negativeShrinks, -5 ) != negativeShrinks.end() ); + + CHECK_THROWS_AS( Integer<int>( 5, -5 ), std::invalid_argument ); +} + +TEST_CASE( "Boolean generator shrinks true to false", + "[progmasoft][generator]" ) { + using Progmasoft::Catch3::Boolean; + using Progmasoft::Catch3::Random; + + const auto generator = Boolean(); + Random random( 0xB001 ); + CHECK( generator.Shrink( true ) == std::vector<bool>{ false } ); + CHECK( generator.Shrink( false ).empty() ); + for ( int index = 0; index < 100; ++index ) { + (void)generator.Generate( random ); + } +} + +TEST_CASE( "Properties count trials and reproduce their seed", + "[progmasoft][property]" ) { + using Progmasoft::Catch3::CheckProperty; + using Progmasoft::Catch3::Integer; + using Progmasoft::Catch3::PropertyOptions; + + int checks = 0; + const PropertyOptions options{ + .Trials = 64, .Seed = 0xC0FFEE, .MaxShrinkSteps = 100 }; + const auto property = [&]( int value ) { + ++checks; + return value >= -100 && value <= 100; + }; + + const auto first = + CheckProperty( Integer<int>( -100, 100 ), property, options ); + const auto second = + CheckProperty( Integer<int>( -100, 100 ), property, options ); + + CHECK( first.Succeeded() ); + CHECK( first.TrialsRun == options.Trials ); + CHECK( checks == static_cast<int>( options.Trials * 2 ) ); + CHECK( first.Describe() == second.Describe() ); +} + +TEST_CASE( "Property failures shrink to and report a replayable counterexample", + "[progmasoft][property]" ) { + using Progmasoft::Catch3::CheckProperty; + using Progmasoft::Catch3::MakeGenerator; + using Progmasoft::Catch3::PropertyOptions; + + const auto generator = + MakeGenerator<int>( []( Progmasoft::Catch3::Random& ) { return -100; }, + []( const int& value ) { + if ( value == -100 ) { + return std::vector<int>{ -50, -1, 0 }; + } + if ( value == -50 ) { + return std::vector<int>{ -10, -1 }; + } + if ( value == -10 ) { + return std::vector<int>{ -3, -1 }; + } + if ( value == -3 ) { + return std::vector<int>{ -1, 0 }; + } + return std::vector<int>{ 0 }; + } ); + + const auto result = CheckProperty( + generator, + []( int value ) { return value >= 0; }, + PropertyOptions{ .Trials = 4, .Seed = 0xFACE, .MaxShrinkSteps = 20 } ); + + CHECK_FALSE( result.Succeeded() ); + CHECK( result.Status == Progmasoft::Catch3::PropertyStatus::kFailed ); + REQUIRE( result.Failure.has_value() ); + CHECK( result.Failure->Counterexample == "-1" ); + CHECK( result.Failure->RootSeed == 0xFACE ); + CHECK( result.Failure->TrialSeed == + Progmasoft::Catch3::Random::DeriveSeed( 0xFACE, 0 ) ); + CHECK( result.Failure->ShrinkSteps > 0 ); + CHECK( result.Describe().find( "counterexample: -1" ) != + std::string::npos ); + CHECK( result.Describe().find( "replay seed" ) != std::string::npos ); +} + +TEST_CASE( "Property shrink work is bounded", "[progmasoft][property]" ) { + using Progmasoft::Catch3::CheckProperty; + using Progmasoft::Catch3::MakeGenerator; + using Progmasoft::Catch3::PropertyOptions; + + const auto generator = + MakeGenerator<int>( []( Progmasoft::Catch3::Random& ) { return 100; }, + []( const int& value ) { + return value > 1 ? std::vector<int>{ value - 1 } + : std::vector<int>{}; + } ); + const auto result = CheckProperty( + generator, + []( int ) { return false; }, + PropertyOptions{ .Trials = 1, .Seed = 4, .MaxShrinkSteps = 3 } ); + + REQUIRE( result.Failure.has_value() ); + CHECK( result.Failure->ShrinkSteps == 3 ); + CHECK( result.Failure->Counterexample == "97" ); +} + +TEST_CASE( + "Property errors distinguish invalid configuration and generator failures", + "[progmasoft][property]" ) { + using Progmasoft::Catch3::CheckProperty; + using Progmasoft::Catch3::Generator; + using Progmasoft::Catch3::PropertyOptions; + using Progmasoft::Catch3::PropertyStatus; + + const Generator<int> throwingGenerator( + []( Progmasoft::Catch3::Random& ) -> int { + throw std::runtime_error( "sample unavailable" ); + }, + []( const int& ) { return std::vector<int>{}; } ); + const auto generatorError = + CheckProperty( throwingGenerator, []( int ) { return true; } ); + CHECK( generatorError.Status == PropertyStatus::kErrored ); + CHECK( generatorError.Describe().find( "sample unavailable" ) != + std::string::npos ); + + const Generator<int> constantGenerator( + []( Progmasoft::Catch3::Random& ) { return 1; }, + []( const int& ) { return std::vector<int>{}; } ); + const auto invalidOptions = CheckProperty( + constantGenerator, + []( int ) { return true; }, + PropertyOptions{ .Trials = 0, .Seed = 1, .MaxShrinkSteps = 1 } ); + CHECK( invalidOptions.Status == PropertyStatus::kInvalidConfiguration ); +} + +TEST_CASE( "Predicate exceptions are ordinary reproducible property failures", + "[progmasoft][property]" ) { + using Progmasoft::Catch3::CheckProperty; + using Progmasoft::Catch3::Generator; + using Progmasoft::Catch3::PropertyStatus; + + const Generator<int> generator( + []( Progmasoft::Catch3::Random& ) { return 7; }, + []( const int& ) { return std::vector<int>{}; } ); + const auto result = CheckProperty( generator, []( int ) -> bool { + throw std::runtime_error( "predicate failed" ); + } ); + + CHECK( result.Status == PropertyStatus::kFailed ); + REQUIRE( result.Failure.has_value() ); + CHECK( result.Failure->Reason.find( "predicate failed" ) != + std::string::npos ); + CHECK( result.Failure->Counterexample == "7" ); +} + +TEST_CASE( "Catch3 property assertions report successful runs", + "[progmasoft][property]" ) { + CATCH3_CHECK_PROPERTY( + Progmasoft::Catch3::Integer<int>( 1, 100 ), + []( int value ) { return value > 0; }, + Progmasoft::Catch3::PropertyOptions{ + .Trials = 25, .Seed = 42, .MaxShrinkSteps = 10 } ); +} diff --git a/tests/meson.build b/tests/meson.build index 0e44eaab..1d20b9ce 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -76,3 +76,15 @@ self_test = executable( ) test('SelfTest', self_test) + +# Validate Progmasoft's C++20 extension without changing Catch2's library +# language requirement or the upstream SelfTest compilation mode. +progmasoft_property_tests = executable( + 'ProgmasoftPropertyTests', + 'Progmasoft/Property.tests.cpp', + include_directories: '../src', + dependencies: [progmasoft_catch3_dep, catch2_with_main_dep], + override_options: ['cpp_std=c++20'], +) + +test('Progmasoft_PropertyTests', progmasoft_property_tests) diff --git a/xmake.lua b/xmake.lua new file mode 100644 index 00000000..221351c3 --- /dev/null +++ b/xmake.lua @@ -0,0 +1,49 @@ +-- Copyright (c) 2026 Progmasoft. +-- SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1 + +set_project("Catch3") +set_version("3.16.0") +set_languages("cxx14") +set_warnings("all") + +local repository_root = os.projectdir() +local generated_include = path.join(repository_root, ".xmake", "generated") +add_moduledirs(path.join(repository_root, "buildsupport")) + +-- Keep upstream Catch2's compilation baseline and project identity intact. +target("catch2") + set_kind("static") + set_languages("cxx14") + on_load(function(target) + -- File I/O is restricted to Xmake's script domain, so generate here + -- rather than while the declarative project file is being evaluated. + local configure_catch2 = import("catch2_config") + configure_catch2.main(generated_include, repository_root) + target:add("includedirs", generated_include, {public = true}) + end) + add_files("src/catch2/**.cpp") + remove_files("src/catch2/internal/catch_main.cpp") + add_includedirs("src", {public = true}) + add_headerfiles("src/catch2/**.hpp", {prefixdir = ""}) + +target("catch2_main") + set_kind("static") + set_languages("cxx14") + add_files("src/catch2/internal/catch_main.cpp") + add_deps("catch2") + add_includedirs("src", generated_include, {public = true}) + +-- This is a header-only C++20 layer over the compatibility engine. +target("ProgmasoftCatch3") + set_kind("headeronly") + set_languages("cxx20") + add_headerfiles("src/Progmasoft/**.hpp", {prefixdir = ""}) + add_includedirs("src", {public = true}) + add_deps("catch2", {public = true}) + +target("ProgmasoftPropertyTests") + set_kind("binary") + set_languages("cxx20") + add_files("tests/Progmasoft/Property.tests.cpp") + add_includedirs("src", generated_include) + add_deps("ProgmasoftCatch3", "catch2_main")