v3.1.0

Closes #2468

.bazelrc

@@ -0,0 +1,4 @@
+build:gcc9 --cxxopt=-std=c++2a
+build:clang13 --cxxopt=-std=c++17
+build:vs2019 --cxxopt=/std:c++17
+build:vs2022 --cxxopt=/std:c++17

.github/workflows/linux-other-builds.yml

@@ -51,6 +51,23 @@ jobs:
             other_pkgs: clang-10
             cmake_configurations: -DCATCH_BUILD_EXTRA_TESTS=ON -DCATCH_BUILD_EXAMPLES=ON
 
+          # Configure tests with Clang-10
+          - cxx: clang++-10
+            build_description: CMake configuration tests
+            build_type: Debug
+            std: 14
+            other_pkgs: clang-10
+            cmake_configurations: -DCATCH_ENABLE_CONFIGURE_TESTS=ON
+
+          # Valgrind test Clang-10
+          - cxx: clang++-10
+            build_description: Valgrind tests
+            build_type: Debug
+            std: 14
+            other_pkgs: clang-10 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@v2
@@ -83,4 +100,4 @@ jobs:
           CTEST_OUTPUT_ON_FAILURE: 1
       working-directory: ${{runner.workspace}}/build
       # Hardcode 2 cores we know are there
-      run: ctest -C ${{matrix.build_type}} -j 2
+      run: ctest -C ${{matrix.build_type}} -j 2 ${{matrix.other_ctest_args}}

.gitignore

@@ -11,11 +11,6 @@ Release
 xcuserdata
 CatchSelfTest.xcscheme
 Breakpoints.xcbkptlist
-projects/VS2010/TestCatch/_UpgradeReport_Files/
-projects/VS2010/TestCatch/TestCatch/TestCatch.vcxproj.filters
-projects/VisualStudio/TestCatch/UpgradeLog.XML
-projects/CMake/.idea
-projects/CMake/cmake-build-debug
 UpgradeLog.XML
 Resources/DWARF
 projects/Generated
@@ -25,9 +20,17 @@ DerivedData
 Build
 .idea
 .vs
+.vscode
 cmake-build-*
 benchmark-dir
 .conan/test_package/build
 bazel-*
 build-fuzzers
 debug-build
+.vscode
+msvc-sln*
+# 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
+*.cache
+compile_commands.json

BUILD.bazel

@@ -1,25 +1,91 @@
 # Load the cc_library rule.
 load("@rules_cc//cc:defs.bzl", "cc_library")
+load("@bazel_skylib//rules:expand_template.bzl", "expand_template")
+
+expand_template(
+    name = "catch_user_config",
+    out = "catch2/catch_user_config.hpp",
+    substitutions = {
+        "#cmakedefine CATCH_CONFIG_ANDROID_LOGWRITE": "",
+        "#cmakedefine CATCH_CONFIG_BAZEL_SUPPORT": "#define CATCH_CONFIG_BAZEL_SUPPORT",
+        "#cmakedefine CATCH_CONFIG_NO_COLOUR_WIN32": "",
+        "#cmakedefine CATCH_CONFIG_COLOUR_WIN32": "",
+        "#cmakedefine CATCH_CONFIG_COUNTER": "",
+        "#cmakedefine CATCH_CONFIG_CPP11_TO_STRING": "",
+        "#cmakedefine CATCH_CONFIG_CPP17_BYTE": "",
+        "#cmakedefine CATCH_CONFIG_CPP17_OPTIONAL": "",
+        "#cmakedefine CATCH_CONFIG_CPP17_STRING_VIEW": "",
+        "#cmakedefine CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS": "",
+        "#cmakedefine CATCH_CONFIG_CPP17_VARIANT": "",
+        "#cmakedefine CATCH_CONFIG_DISABLE_EXCEPTIONS_CUSTOM_HANDLER": "",
+        "#cmakedefine CATCH_CONFIG_DISABLE_EXCEPTIONS": "",
+        "#cmakedefine CATCH_CONFIG_DISABLE_STRINGIFICATION": "",
+        "#cmakedefine CATCH_CONFIG_DISABLE": "",
+        "#cmakedefine CATCH_CONFIG_ENABLE_ALL_STRINGMAKERS": "",
+        "#cmakedefine CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER": "",
+        "#cmakedefine CATCH_CONFIG_ENABLE_PAIR_STRINGMAKER": "",
+        "#cmakedefine CATCH_CONFIG_ENABLE_TUPLE_STRINGMAKER": "",
+        "#cmakedefine CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER": "",
+        "#cmakedefine CATCH_CONFIG_EXPERIMENTAL_REDIRECT": "",
+        "#cmakedefine CATCH_CONFIG_FALLBACK_STRINGIFIER @CATCH_CONFIG_FALLBACK_STRINGIFIER@": "",
+        "#cmakedefine CATCH_CONFIG_FAST_COMPILE": "",
+        "#cmakedefine CATCH_CONFIG_GLOBAL_NEXTAFTER": "",
+        "#cmakedefine CATCH_CONFIG_NO_COUNTER": "",
+        "#cmakedefine CATCH_CONFIG_NO_CPP11_TO_STRING": "",
+        "#cmakedefine CATCH_CONFIG_NO_CPP17_BYTE": "",
+        "#cmakedefine CATCH_CONFIG_NO_CPP17_OPTIONAL": "",
+        "#cmakedefine CATCH_CONFIG_NO_CPP17_STRING_VIEW": "",
+        "#cmakedefine CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS": "",
+        "#cmakedefine CATCH_CONFIG_NO_CPP17_VARIANT": "",
+        "#cmakedefine CATCH_CONFIG_NO_GLOBAL_NEXTAFTER": "",
+        "#cmakedefine CATCH_CONFIG_NO_POSIX_SIGNALS": "",
+        "#cmakedefine CATCH_CONFIG_NO_USE_ASYNC": "",
+        "#cmakedefine CATCH_CONFIG_NO_WCHAR": "",
+        "#cmakedefine CATCH_CONFIG_NO_WINDOWS_SEH": "",
+        "#cmakedefine CATCH_CONFIG_NOSTDOUT": "",
+        "#cmakedefine CATCH_CONFIG_POSIX_SIGNALS": "",
+        "#cmakedefine CATCH_CONFIG_PREFIX_ALL": "",
+        "#cmakedefine CATCH_CONFIG_USE_ASYNC": "",
+        "#cmakedefine CATCH_CONFIG_WCHAR": "",
+        "#cmakedefine CATCH_CONFIG_WINDOWS_CRTDBG": "",
+        "#cmakedefine CATCH_CONFIG_WINDOWS_SEH": "",
+        "#cmakedefine CATCH_CONFIG_NO_ANDROID_LOGWRITE": "",
+        "@CATCH_CONFIG_DEFAULT_REPORTER@": "console",
+        "@CATCH_CONFIG_CONSOLE_WIDTH@": "80",
+    },
+    template = "src/catch2/catch_user_config.hpp.in",
+)
+
+# Generated header library, modifies the include prefix to account for
+# generation path so that we can include <catch2/catch_user_config.hpp>
+# correctly.
+cc_library(
+    name = "catch2_generated",
+    hdrs = ["catch2/catch_user_config.hpp"],
+    include_prefix = ".",  # to manipulate -I of dependenices
+    visibility = ["//visibility:public"],
+)
 
 # Static library, without main.
 cc_library(
     name = "catch2",
+    srcs = glob(
+        ["src/catch2/**/*.cpp"],
+        exclude = ["src/catch2/internal/catch_main.cpp"],
+    ),
     hdrs = glob(["src/catch2/**/*.hpp"]),
-    srcs = glob(["src/catch2/**/*.cpp"],
-                exclude=[ "src/catch2/internal/catch_main.cpp"]),
-    visibility = ["//visibility:public"],
-    copts = ["-std=c++14"],
-    linkstatic = True,
     includes = ["src/"],
+    linkstatic = True,
+    visibility = ["//visibility:public"],
+    deps = [":catch2_generated"],
 )
 
 # Static library, with main.
 cc_library(
     name = "catch2_main",
     srcs = ["src/catch2/internal/catch_main.cpp"],
-    deps = [":catch2"],
-    visibility = ["//visibility:public"],
-    linkstatic = True,
-    copts = ["-std=c++14"],
     includes = ["src/"],
-)
+    linkstatic = True,
+    visibility = ["//visibility:public"],
+    deps = [":catch2"],
+)

CMake/CatchConfigOptions.cmake

@@ -0,0 +1,77 @@
+
+#              Copyright Catch2 Authors
+# Distributed under the Boost Software License, Version 1.0.
+#   (See accompanying file LICENSE_1_0.txt or copy at
+#        https://www.boost.org/LICENSE_1_0.txt)
+
+# SPDX-License-Identifier: BSL-1.0
+
+##
+# This file contains options that are materialized into the Catch2
+# compiled library. All of them default to OFF, as even the positive
+# forms correspond to the user _forcing_ them to ON, while being OFF
+# means that Catch2 can use its own autodetection.
+#
+# For detailed docs look into docs/configuration.md
+
+
+macro(AddOverridableConfigOption OptionBaseName)
+  option(CATCH_CONFIG_${OptionBaseName} "Read docs/configuration.md for details" OFF)
+  option(CATCH_CONFIG_NO_${OptionBaseName} "Read docs/configuration.md for details" OFF)
+endmacro()
+
+macro(AddConfigOption OptionBaseName)
+  option(CATCH_CONFIG_${OptionBaseName} "Read docs/configuration.md for details" OFF)
+endmacro()
+
+set(_OverridableOptions
+  "ANDROID_LOGWRITE"
+  "BAZEL_SUPPORT"
+  "COLOUR_WIN32"
+  "COUNTER"
+  "CPP11_TO_STRING"
+  "CPP17_BYTE"
+  "CPP17_OPTIONAL"
+  "CPP17_STRING_VIEW"
+  "CPP17_UNCAUGHT_EXCEPTIONS"
+  "CPP17_VARIANT"
+  "GLOBAL_NEXTAFTER"
+  "POSIX_SIGNALS"
+  "USE_ASYNC"
+  "WCHAR"
+  "WINDOWS_SEH"
+)
+
+foreach(OptionName ${_OverridableOptions})
+  AddOverridableConfigOption(${OptionName})
+endforeach()
+
+set(_OtherConfigOptions
+  "DISABLE_EXCEPTIONS"
+  "DISABLE_EXCEPTIONS_CUSTOM_HANDLER"
+  "DISABLE"
+  "DISABLE_STRINGIFICATION"
+  "ENABLE_ALL_STRINGMAKERS"
+  "ENABLE_OPTIONAL_STRINGMAKER"
+  "ENABLE_PAIR_STRINGMAKER"
+  "ENABLE_TUPLE_STRINGMAKER"
+  "ENABLE_VARIANT_STRINGMAKER"
+  "EXPERIMENTAL_REDIRECT"
+  "FAST_COMPILE"
+  "NOSTDOUT"
+  "PREFIX_ALL"
+  "WINDOWS_CRTDBG"
+)
+
+
+foreach(OptionName ${_OtherConfigOptions})
+  AddConfigOption(${OptionName})
+endforeach()
+
+set(CATCH_CONFIG_DEFAULT_REPORTER "console" CACHE STRING "Read docs/configuration.md for details. The name of the reporter should be without quotes.")
+set(CATCH_CONFIG_CONSOLE_WIDTH "80" CACHE STRING "Read docs/configuration.md for details. Must form a valid integer literal.")
+
+# There is no good way to both turn this into a CMake cache variable,
+# and keep reasonable default semantics inside the project. Thus we do
+# not define it and users have to provide it as an outside variable.
+#set(CATCH_CONFIG_FALLBACK_STRINGIFIER "" CACHE STRING "Read docs/configuration.md for details.")

CMake/CatchMiscFunctions.cmake

@@ -1,3 +1,11 @@
+
+#              Copyright Catch2 Authors
+# Distributed under the Boost Software License, Version 1.0.
+#   (See accompanying file LICENSE_1_0.txt or copy at
+#        https://www.boost.org/LICENSE_1_0.txt)
+
+# SPDX-License-Identifier: BSL-1.0
+
 include(CheckCXXCompilerFlag)
 function(add_cxx_flag_if_supported_to_targets flagname targets)
     check_cxx_compiler_flag("${flagname}" HAVE_FLAG_${flagname})
@@ -35,35 +43,58 @@ function(add_warnings_to_targets targets)
 
     if (NOT MSVC)
         set(CHECKED_WARNING_FLAGS
-          "-Wall"
-          "-Wextra"
-          "-Wpedantic"
-          "-Wweak-vtables"
-          "-Wunreachable-code"
-          "-Wmissing-declarations"
-          "-Wexit-time-destructors"
-          "-Wglobal-constructors"
-          "-Wmissing-noreturn"
-          "-Wparentheses"
-          "-Wextra-semi"
-          "-Wunreachable-code"
-          "-Wstrict-aliasing"
-          "-Wreturn-std-move"
-          "-Wmissing-braces"
-          "-Wdeprecated"
-          "-Wvla"
-          "-Wundef"
-          "-Wmisleading-indentation"
-          "-Wcatch-value"
           "-Wabsolute-value"
-          "-Wreturn-std-move"
-          "-Wunused-parameter"
-          "-Wunused-function"
+          "-Wall"
+          "-Wc++20-compat"
           "-Wcall-to-pure-virtual-from-ctor-dtor"
+          "-Wcast-align"
+          "-Wcatch-value"
+          "-Wdangling"
+          "-Wdeprecated"
           "-Wdeprecated-register"
-          "-Wsuggest-override"
-          "-Wshadow"
+          "-Wexceptions"
+          "-Wexit-time-destructors"
+          "-Wextra"
+          "-Wextra-semi"
+          "-Wfloat-equal"
+          "-Wglobal-constructors"
+          "-Winit-self"
+          "-Wmisleading-indentation"
+          "-Wmismatched-new-delete"
+          "-Wmismatched-return-types"
+          "-Wmismatched-tags"
+          "-Wmissing-braces"
+          "-Wmissing-declarations"
+          "-Wmissing-noreturn"
+          "-Wmissing-prototypes"
+          "-Wmissing-variable-declarations"
+          "-Wnull-dereference"
           "-Wold-style-cast"
+          "-Woverloaded-virtual"
+          "-Wparentheses"
+          "-Wpedantic"
+          "-Wreorder"
+          "-Wreturn-std-move"
+          "-Wshadow"
+          "-Wstrict-aliasing"
+          "-Wsuggest-destructor-override"
+          "-Wsuggest-override"
+          "-Wundef"
+          "-Wuninitialized"
+          "-Wunneeded-internal-declaration"
+          "-Wunreachable-code"
+          "-Wunused"
+          "-Wunused-function"
+          "-Wunused-parameter"
+          "-Wvla"
+          "-Wweak-vtables"
+
+          # This is a useful warning, but our tests sometimes rely on
+          # functions being present, but not picked (e.g. various checks
+          # for stringification implementation ordering).
+          # Ergo, we should use it every now and then, but we cannot
+          # enable it by default.
+          # "-Wunused-member-function"
         )
         foreach(warning ${CHECKED_WARNING_FLAGS})
             add_cxx_flag_if_supported_to_targets(${warning} "${targets}")

CMake/catch2-with-main.pc.in

@@ -7,4 +7,4 @@ Description: A modern, C++-native test framework for C++14 and above (links in d
 Version: ${pkg_version}
 Requires: catch2 = ${pkg_version}
 Cflags: -I${includedir}
-Libs: -L${libdir} -lCatch2WithMain
+Libs: -L${libdir} -lCatch2Main

CMakeLists.txt

@@ -9,7 +9,7 @@ else()
 endif()
 
 option(CATCH_INSTALL_DOCS "Install documentation alongside library" ON)
-option(CATCH_INSTALL_EXTRAS "Install extras alongside library" ON)
+option(CATCH_INSTALL_EXTRAS "Install extras (CMake scripts, debugger helpers) alongside library" ON)
 option(CATCH_DEVELOPMENT_BUILD "Build tests, enable warnings, enable Werror, etc" OFF)
 
 include(CMakeDependentOption)
@@ -20,6 +20,7 @@ cmake_dependent_option(CATCH_BUILD_FUZZERS "Build fuzzers" OFF "CATCH_DEVELOPMEN
 cmake_dependent_option(CATCH_ENABLE_COVERAGE "Generate coverage for codecov.io" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
 cmake_dependent_option(CATCH_ENABLE_WERROR "Enables Werror during build" ON "CATCH_DEVELOPMENT_BUILD" OFF)
 cmake_dependent_option(CATCH_BUILD_SURROGATES "Enable generating and building surrogate TUs for the main headers" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
+cmake_dependent_option(CATCH_ENABLE_CONFIGURE_TESTS "Enable CMake configuration tests. WARNING: VERY EXPENSIVE" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
 
 
 # Catch2's build breaks if done in-tree. You probably should not build
@@ -35,12 +36,29 @@ if(CMAKE_VERSION VERSION_GREATER 3.8)
 endif()
 
 
-project(Catch2 LANGUAGES CXX VERSION 3.0.0)
+project(Catch2
+  VERSION 3.1.0 # CML version placeholder, don't delete
+  LANGUAGES CXX
+  # HOMEPAGE_URL is not supported until CMake version 3.12, which
+  # we do not target yet.
+  # HOMEPAGE_URL "https://github.com/catchorg/Catch2"
+  DESCRIPTION "A modern, C++-native, unit test framework."
+)
 
-# Provide path for scripts
+
+# Provide path for scripts. We first add path to the scripts we don't use,
+# but projects including us might, and set the path up to parent scope.
+# Then we also add path that we use to configure the project, but is of
+# no use to top level projects.
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/extras")
+if (NOT NOT_SUBPROJECT)
+  set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH}" PARENT_SCOPE)
+endif()
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/CMake")
+
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
+include(CatchConfigOptions)
 if(CATCH_DEVELOPMENT_BUILD)
   include(CTest)
 endif()
@@ -93,16 +111,6 @@ if (CATCH_DEVELOPMENT_BUILD)
     add_warnings_to_targets("${CATCH_WARNING_TARGETS}")
 endif()
 
-
-#option(CATCH_USE_VALGRIND "Perform SelfTests with Valgrind" OFF)
-#option(CATCH_ENABLE_WERROR "Enable all warnings as errors" ON)
-#
-#set_property(GLOBAL PROPERTY USE_FOLDERS ON)
-#
-#
-#
-#
-#
 # Only perform the installation steps when Catch is not being used as
 # a subproject via `add_subdirectory`, or the destinations will break,
 # see https://github.com/catchorg/Catch2/issues/1373
@@ -135,6 +143,7 @@ if (NOT_SUBPROJECT)
           docs/
         DESTINATION
           "${CMAKE_INSTALL_DOCDIR}"
+        PATTERN "doxygen" EXCLUDE
       )
     endif()
 

CMakePresets.json

@@ -0,0 +1,25 @@
+{
+    "version": 3,
+    "configurePresets": [
+        {
+            "name": "basic-tests",
+            "displayName": "Basic development build",
+            "description": "Enables development build with basic tests that are cheap to build and run",
+            "cacheVariables": {
+                "CATCH_DEVELOPMENT_BUILD": "ON"
+            }
+        },
+        {
+            "name": "all-tests",
+            "inherits": "basic-tests",
+            "displayName": "Full development build",
+            "description": "Enables development build with examples and ALL tests",
+            "cacheVariables": {
+                "CATCH_BUILD_EXAMPLES": "ON",
+                "CATCH_BUILD_EXTRA_TESTS": "ON",
+                "CATCH_BUILD_SURROGATES": "ON",
+                "CATCH_ENABLE_CONFIGURE_TESTS": "ON"
+            }
+        }
+    ]   
+}

README.md

@@ -7,7 +7,7 @@
 [![MacOS build status](https://github.com/catchorg/Catch2/actions/workflows/mac-builds.yml/badge.svg)](https://github.com/catchorg/Catch2/actions/workflows/mac-builds.yml)
 [![Build Status](https://ci.appveyor.com/api/projects/status/github/catchorg/Catch2?svg=true&branch=devel)](https://ci.appveyor.com/project/catchorg/catch2)
 [![Code Coverage](https://codecov.io/gh/catchorg/Catch2/branch/devel/graph/badge.svg)](https://codecov.io/gh/catchorg/Catch2)
-[![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://godbolt.org/z/9x9qoM)
+[![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://godbolt.org/z/EdoY15q9G)
 [![Join the chat in Discord: https://discord.gg/4CWS9zD](https://img.shields.io/badge/Discord-Chat!-brightgreen.svg)](https://discord.gg/4CWS9zD)
 
 

WORKSPACE

@@ -0,0 +1,14 @@
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "bazel_skylib",
+    strip_prefix = "bazel-skylib-2a87d4a62af886fb320883aba102255aba87275e",
+    urls = [
+        "https://github.com/bazelbuild/bazel-skylib/archive/2a87d4a62af886fb320883aba102255aba87275e.tar.gz",
+    ],
+    sha256 = "d847b08d6702d2779e9eb399b54ff8920fa7521dc45e3e53572d1d8907767de7",
+)
+
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+
+bazel_skylib_workspace()

appveyor.yml

@@ -51,9 +51,10 @@ test_script:
 # build explicitly.
 environment:
   matrix:
-    - FLAVOR: VS 2019 x64 Debug Surrogates
+    - FLAVOR: VS 2019 x64 Debug Surrogates Configure Tests
       APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
       surrogates: 1
+      configure_tests: 1
       platform: x64
       configuration: Debug
     

conanfile.py

@@ -20,7 +20,7 @@ class CatchConan(ConanFile):
         cmake = CMake(self)
         cmake.definitions["BUILD_TESTING"] = "OFF"
         cmake.definitions["CATCH_INSTALL_DOCS"] = "OFF"
-        cmake.definitions["CATCH_INSTALL_HELPERS"] = "ON"
+        cmake.definitions["CATCH_INSTALL_EXTRAS"] = "ON"
         cmake.configure(build_folder="build")
         return cmake
 
@@ -42,16 +42,19 @@ conan_basic_setup()'''.format(line_to_replace, self.install_folder.replace("\\",
         cmake.install()
 
     def package_info(self):
+        lib_suffix = "d" if self.settings.build_type == "Debug" else ""
+
         self.cpp_info.names["cmake_find_package"] = "Catch2"
         self.cpp_info.names["cmake_find_package_multi"] = "Catch2"
         # Catch2
         self.cpp_info.components["catch2base"].names["cmake_find_package"] = "Catch2"
         self.cpp_info.components["catch2base"].names["cmake_find_package_multi"] = "Catch2"
         self.cpp_info.components["catch2base"].names["pkg_config"] = "Catch2"
-        self.cpp_info.components["catch2base"].libs = ["Catch2"]
+        self.cpp_info.components["catch2base"].libs = ["Catch2" + lib_suffix]
+        self.cpp_info.components["catch2base"].builddirs.append("lib/cmake/Catch2")
         # Catch2WithMain
         self.cpp_info.components["catch2main"].names["cmake_find_package"] = "Catch2WithMain"
         self.cpp_info.components["catch2main"].names["cmake_find_package_multi"] = "Catch2WithMain"
         self.cpp_info.components["catch2main"].names["pkg_config"] = "Catch2WithMain"
-        self.cpp_info.components["catch2main"].libs = ["Catch2Main"]
+        self.cpp_info.components["catch2main"].libs = ["Catch2Main" + lib_suffix]
         self.cpp_info.components["catch2main"].requires = ["catch2base"]

docs/Readme.md

@@ -26,6 +26,7 @@ Running:
 
 Odds and ends:
 * [Frequently Asked Questions (FAQ)](faq.md#top)
+* [Best practices and other tips](usage-tips.md#top)
 * [CMake integration](cmake-integration.md#top)
 * [CI and other miscellaneous pieces](ci-and-misc.md#top)
 * [Known limitations](limitations.md#top)

docs/cmake-integration.md

@@ -5,6 +5,7 @@
 [CMake targets](#cmake-targets)<br>
 [Automatic test registration](#automatic-test-registration)<br>
 [CMake project options](#cmake-project-options)<br>
+[`CATCH_CONFIG_*` customization options in CMake](#catch_config_-customization-options-in-cmake)<br>
 [Installing Catch2 from git repository](#installing-catch2-from-git-repository)<br>
 [Installing Catch2 from vcpkg](#installing-catch2-from-vcpkg)<br>
 
@@ -50,7 +51,7 @@ Include(FetchContent)
 FetchContent_Declare(
   Catch2
   GIT_REPOSITORY https://github.com/catchorg/Catch2.git
-  GIT_TAG        v3.0.0-preview3
+  GIT_TAG        v3.0.1 # or a later release
 )
 
 FetchContent_MakeAvailable(Catch2)
@@ -62,17 +63,19 @@ target_link_libraries(tests PRIVATE Catch2::Catch2WithMain)
 
 ## Automatic test registration
 
-Catch2's repository also contains two CMake scripts that help users
+Catch2's repository also contains three CMake scripts that help users
 with automatically registering their `TEST_CASE`s with CTest. They
 can be found in the `extras` folder, and are
 
 1) `Catch.cmake` (and its dependency `CatchAddTests.cmake`)
 2) `ParseAndAddCatchTests.cmake` (deprecated)
+3) `CatchShardTests.cmake` (and its dependency `CatchShardTestsImpl.cmake`)
 
 If Catch2 has been installed in system, both of these can be used after
 doing `find_package(Catch2 REQUIRED)`. Otherwise you need to add them
 to your CMake module path.
 
+<a id="catch_discover_tests"></a>
 ### `Catch.cmake` and `CatchAddTests.cmake`
 
 `Catch.cmake` provides function `catch_discover_tests` to get tests from
@@ -256,6 +259,49 @@ unset(OptionalCatchTestLauncher)
 ParseAndAddCatchTests(bar)
 ```
 
+
+### `CatchShardTests.cmake`
+
+> `CatchShardTests.cmake` was introduced in Catch2 3.1.0.
+
+`CatchShardTests.cmake` provides a function
+`catch_add_sharded_tests(TEST_BINARY)` that splits tests from `TEST_BINARY`
+into multiple shards. The tests in each shard and their order is randomized,
+and the seed changes every invocation of CTest.
+
+Currently there are 3 customization points for this script:
+
+ * SHARD_COUNT - number of shards to split target's tests into
+ * REPORTER    - reporter spec to use for tests
+ * TEST_SPEC   - test spec used for filtering tests
+
+Example usage:
+
+```
+include(CatchShardTests)
+
+catch_add_sharded_tests(foo-tests
+  SHARD_COUNT 4
+  REPORTER "xml::out=-"
+  TEST_SPEC "A"
+)
+
+catch_add_sharded_tests(tests
+  SHARD_COUNT 8
+  REPORTER "xml::out=-"
+  TEST_SPEC "B"
+)
+```
+
+This registers total of 12 CTest tests (4 + 8 shards) to run shards
+from `foo-tests` test binary, filtered by a test spec.
+
+_Note that this script is currently a proof-of-concept for reseeding
+shards per CTest run, and thus does not support (nor does it currently
+aim to support) all customization points from
+[`catch_discover_tests`](#catch_discover_tests)._
+
+
 ## CMake project options
 
 Catch2's CMake project also provides some options for other projects
@@ -265,8 +311,9 @@ that consume it. These are:
 Catch2's test binary will be built. Defaults to `ON`.
 * `CATCH_INSTALL_DOCS` -- When `ON`, Catch2's documentation will be
 included in the installation. Defaults to `ON`.
-* `CATCH_INSTALL_HELPERS` -- When `ON`, Catch2's extras folder will be
-included in the installation. Defaults to `ON`.
+* `CATCH_INSTALL_EXTRAS` -- When `ON`, Catch2's extras folder (the CMake
+scripts mentioned above, debugger helpers) will be included in the
+installation. Defaults to `ON`.
 * `CATCH_DEVELOPMENT_BUILD` -- When `ON`, configures the build for development
 of Catch2. This means enabling test projects, warnings and so on.
 Defaults to `OFF`.
@@ -292,6 +339,31 @@ compiled separately to ensure that they are self-sufficient.
 Defaults to `OFF`.
 
 
+## `CATCH_CONFIG_*` customization options in CMake
+
+> CMake support for `CATCH_CONFIG_*` options was introduced in Catch2 3.0.1
+
+Due to the new separate compilation model, all the options from the
+[Compile-time configuration docs](configuration.md#top) can also be set
+through Catch2's CMake. To set them, define the option you want as `ON`,
+e.g. `-DCATCH_CONFIG_NOSTDOUT=ON`.
+
+Note that setting the option to `OFF` doesn't disable it. To force disable
+an option, you need to set the `_NO_` form of it to `ON`, e.g.
+`-DCATCH_CONFIG_NO_COLOUR_WIN32=ON`.
+
+
+To summarize the configuration option behaviour with an example:
+
+| `-DCATCH_CONFIG_COLOUR_WIN32` | `-DCATCH_CONFIG_NO_COLOUR_WIN32` |      Result |
+|-------------------------------|----------------------------------|-------------|
+|                          `ON` |                             `ON` |       error |
+|                          `ON` |                            `OFF` |    force-on |
+|                         `OFF` |                             `ON` |   force-off |
+|                         `OFF` |                            `OFF` | auto-detect |
+
+
+
 ## Installing Catch2 from git repository
 
 If you cannot install Catch2 from a package manager (e.g. Ubuntu 16.04

docs/command-line.md

@@ -15,11 +15,11 @@
 [Warnings](#warnings)<br>
 [Reporting timings](#reporting-timings)<br>
 [Load test names to run from a file](#load-test-names-to-run-from-a-file)<br>
-[Just test names](#just-test-names)<br>
 [Specify the order test cases are run](#specify-the-order-test-cases-are-run)<br>
 [Specify a seed for the Random Number Generator](#specify-a-seed-for-the-random-number-generator)<br>
 [Identify framework and version according to the libIdentify standard](#identify-framework-and-version-according-to-the-libidentify-standard)<br>
 [Wait for key before continuing](#wait-for-key-before-continuing)<br>
+[Skip all benchmarks](#skip-all-benchmarks)<br>
 [Specify the number of benchmark samples to collect](#specify-the-number-of-benchmark-samples-to-collect)<br>
 [Specify the number of resamples for bootstrapping](#specify-the-number-of-resamples-for-bootstrapping)<br>
 [Specify the confidence-interval for bootstrapping](#specify-the-confidence-interval-for-bootstrapping)<br>
@@ -31,6 +31,7 @@
 [Override output colouring](#override-output-colouring)<br>
 [Test Sharding](#test-sharding)<br>
 [Allow running the binary without tests](#allow-running-the-binary-without-tests)<br>
+[Output verbosity](#output-verbosity)<br>
 
 Catch works quite nicely without any command line options at all - but for those times when you want greater control the following options are available.
 Click one of the following links to take you straight to that option - or scroll on to browse the available options.
@@ -58,16 +59,18 @@ Click one of the following links to take you straight to that option - or scroll
 <a href="#listing-available-tests-tags-or-reporters">   `    --list-tests`</a><br />
 <a href="#listing-available-tests-tags-or-reporters">   `    --list-tags`</a><br />
 <a href="#listing-available-tests-tags-or-reporters">   `    --list-reporters`</a><br />
+<a href="#listing-available-tests-tags-or-reporters">   `    --list-listeners`</a><br />
 <a href="#order">                                       `    --order`</a><br />
 <a href="#rng-seed">                                    `    --rng-seed`</a><br />
 <a href="#libidentify">                                 `    --libidentify`</a><br />
 <a href="#wait-for-keypress">                           `    --wait-for-keypress`</a><br />
+<a href="#skip-benchmarks">                             `    --skip-benchmarks`</a><br />
 <a href="#benchmark-samples">                           `    --benchmark-samples`</a><br />
 <a href="#benchmark-resamples">                         `    --benchmark-resamples`</a><br />
 <a href="#benchmark-confidence-interval">               `    --benchmark-confidence-interval`</a><br />
 <a href="#benchmark-no-analysis">                       `    --benchmark-no-analysis`</a><br />
 <a href="#benchmark-warmup-time">                       `    --benchmark-warmup-time`</a><br />
-<a href="#use-colour">                                  `    --use-colour`</a><br />
+<a href="#colour-mode">                                 `    --colour-mode`</a><br />
 <a href="#test-sharding">                               `    --shard-count`</a><br />
 <a href="#test-sharding">                               `    --shard-index`</a><br />
 <a href=#no-tests-override>                             `    --allow-running-no-tests`</a><br />
@@ -123,22 +126,33 @@ Test names containing special characters, such as `,` or `[` can specify them on
 <a id="choosing-a-reporter-to-use"></a>
 ## Choosing a reporter to use
 
-<pre>-r, --reporter &lt;reporter[::output-file]&gt;</pre>
-
-> Support for providing output-file through the `-r`, `--reporter` flag was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 X.Y.Z
+<pre>-r, --reporter &lt;reporter[::key=value]*&gt;</pre>
 
 Reporters are how the output from Catch2 (results of assertions, tests,
 benchmarks and so on) is formatted and written out. The default reporter
 is called the "Console" reporter and is intended to provide relatively
 verbose and human-friendly output.
 
-There are multiple built-in reporters, you can see what they do by using the 
+Reporters are also individually configurable. To pass configuration options
+to the reporter, you append `::key=value` to the reporter specification
+as many times as you want, e.g. `--reporter xml::out=someFile.xml`.
+
+The keys must either be prefixed by "X", in which case they are not parsed
+by Catch2 and are only passed down to the reporter, or one of options
+hardcoded into Catch2. Currently there are only 2,
+["out"](#sending-output-to-a-file), and ["colour-mode"](#colour-mode).
+
+_Note that the reporter might still check the X-prefixed options for
+validity, and throw an error if they are wrong._
+
+> Support for passing arguments to reporters through the `-r`, `--reporter` flag was introduced in Catch2 3.0.1
+
+There are multiple built-in reporters, you can see what they do by using the
 [`--list-reporter`](command-line.md#listing-available-tests-tags-or-reporters)
 flag. If you need a reporter providing custom format outside of the already
 provided ones, look at the ["write your own reporter" part of the reporter
 documentation](reporters.md#writing-your-own-reporter).
 
-
 This option may be passed multiple times to use multiple (different)
 reporters  at the same time. See the [reporter documentation](reporters.md#multiple-reporters)
 for details on what the resulting behaviour is. Also note that at most one
@@ -146,15 +160,14 @@ reporter can be provided without the output-file part of reporter spec.
 This reporter will use the "default" output destination, based on
 the [`-o`, `--out`](#sending-output-to-a-file) option.
 
-> Support for using multiple different reporters at the same time was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 X.Y.Z
+> Support for using multiple different reporters at the same time was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 3.0.1
 
-As with the `--out` option, using `-` for the output file name sends the
-output to stdout.
 
 _Note: There is currently no way to escape `::` in the reporter spec,
-and thus reporter/file names with `::` in them will not work properly.
-As `::` in paths is relatively obscure (unlike `:`), we do not consider
-this an issue._
+and thus the reporter names, or configuration keys and values, cannot
+contain `::`. As `::` in paths is relatively obscure (unlike ':'), we do
+not consider this an issue._
+
 
 <a id="breaking-into-the-debugger"></a>
 ## Breaking into the debugger
@@ -188,9 +201,12 @@ Sometimes this results in a flood of failure messages and you'd rather just see
 --list-tests
 --list-tags
 --list-reporters
+--list-listeners
 ```
 
-> The `--list*` options became customizable through reporters in Catch2 X.Y.Z
+> The `--list*` options became customizable through reporters in Catch2 3.0.1
+
+> The `--list-listeners` option was added in Catch2 3.0.1
 
 `--list-tests` lists all registered tests matching specified test spec.
 Usually this listing also includes tags, and potentially also other
@@ -202,17 +218,40 @@ similar information.
 
 `--list-reporters` lists all available reporters and their descriptions.
 
+`--list-listeners` lists all registered listeners and their descriptions.
+
+The [`--verbosity` argument](#output-verbosity) modifies the level of detail provided by the default `--list*` options
+as follows:
+
+| Option             | `normal` (default)              | `quiet`             | `high`                                  |
+|--------------------|---------------------------------|---------------------|-----------------------------------------|
+| `--list-tests`     | Test names and tags             | Test names only     | Same as `normal`, plus source code line |
+| `--list-tags`      | Tags and counts                 | Same as `normal`    | Same as `normal`                        |
+| `--list-reporters` | Reporter names and descriptions | Reporter names only | Same as `normal`                        |
+| `--list-listeners` | Listener names and descriptions | Same as `normal`    | Same as `normal`                        |
 
 <a id="sending-output-to-a-file"></a>
 ## Sending output to a file
 <pre>-o, --out &lt;filename&gt;
 </pre>
 
-Use this option to send all output to a file. By default output is sent to stdout (note that uses of stdout and stderr *from within test cases* are redirected and included in the report - so even stderr will effectively end up on stdout).
+Use this option to send all output to a file, instead of stdout. You can
+use `-` as the filename to explicitly send the output to stdout (this is
+useful e.g. when using multiple reporters).
 
-Using `-` as the filename sends the output to stdout.
+> Support for `-` as the filename was introduced in Catch2 3.0.1
 
-> Support for `-` as the filename was introduced in Catch2 X.Y.Z
+Filenames starting with "%" (percent symbol) are reserved by Catch2 for
+meta purposes, e.g. using `%debug` as the filename opens stream that
+writes to platform specific debugging/logging mechanism.
+
+Catch2 currently recognizes 3 meta streams:
+
+* `%debug` - writes to platform specific debugging/logging output
+* `%stdout` - writes to stdout
+* `%stderr` - writes to stderr
+
+> Support for `%stdout` and `%stderr` was introduced in Catch2 3.0.1
 
 
 <a id="naming-a-test-run"></a>
@@ -260,7 +299,7 @@ There are currently two warnings implemented:
                         // not match any tests.
 ```
 
-> `UnmatchedTestSpec` was introduced in Catch2 X.Y.Z.
+> `UnmatchedTestSpec` was introduced in Catch2 3.0.1.
 
 
 <a id="reporting-timings"></a>
@@ -310,13 +349,19 @@ Lexicographic order. Tests are sorted by their name, their tags are ignored.
 
 ### rand
 
-Randomly sorted. The order is dependent on Catch2's random seed (see
+Randomly ordered. The order is dependent on Catch2's random seed (see
 [`--rng-seed`](#rng-seed)), and is subset invariant. What this means
 is that as long as the random seed is fixed, running only some tests
 (e.g. via tag) does not change their relative order.
 
 > The subset stability was introduced in Catch2 v2.12.0
 
+Since the random order was made subset stable, we promise that given
+the same random seed, the order of test cases will be the same across
+different platforms, as long as the tests were compiled against identical
+version of Catch2. We reserve the right to change the relative order
+of tests cases between Catch2 versions, but it is unlikely to happen often.
+
 
 <a id="rng-seed"></a>
 ## Specify a seed for the Random Number Generator
@@ -348,6 +393,16 @@ See [The LibIdentify repo for more information and examples](https://github.com/
 Will cause the executable to print a message and wait until the return/ enter key is pressed before continuing -
 either before running any tests, after running all tests - or both, depending on the argument.
 
+<a id="skip-benchmarks"></a>
+## Skip all benchmarks
+<pre>--skip-benchmarks</pre>
+
+> [Introduced](https://github.com/catchorg/Catch2/issues/2408) in Catch2 3.0.1.
+
+This flag tells Catch2 to skip running all benchmarks. Benchmarks in this
+case mean code blocks in `BENCHMARK` and `BENCHMARK_ADVANCED` macros, not
+test cases with the `[!benchmark]` tag.
+
 <a id="benchmark-samples"></a>
 ## Specify the number of benchmark samples to collect
 <pre>--benchmark-samples &lt;# of samples&gt;</pre>
@@ -457,35 +512,53 @@ filename it is found in, with any extension stripped, prefixed with the `#` char
 
 So, for example,  tests within the file `~\Dev\MyProject\Ferrets.cpp` would be tagged `[#Ferrets]`.
 
-<a id="use-colour"></a>
+<a id="colour-mode"></a>
 ## Override output colouring
-<pre>--use-colour &lt;yes|no|auto&gt;</pre>
+<pre>--colour-mode &lt;ansi|win32|none|default&gt;</pre>
 
-Catch colours output for terminals, but omits colouring when it detects that
-output is being sent to a pipe. This is done to avoid interfering with automated
-processing of output.
+> The `--colour-mode` option replaced the old `--colour` option in Catch2 3.0.1
+
+
+Catch2 support two different ways of colouring terminal output, and by
+default it attempts to make a good guess on which implementation to use
+(and whether to even use it, e.g. Catch2 tries to avoid writing colour
+codes when writing the results into a file).
+
+`--colour-mode` allows the user to explicitly select what happens.
+
+* `--colour-mode ansi` tells Catch2 to always use ANSI colour codes, even
+when writing to a file
+* `--colour-mode win32` tells Catch2 to use colour implementation based
+  on Win32 terminal API
+* `--colour-mode none` tells Catch2 to disable colours completely
+* `--colour-mode default` lets Catch2 decide
+
+`--colour-mode default` is the default setting.
 
-`--use-colour yes` forces coloured output, `--use-colour no` disables coloured
-output. The default behaviour is `--use-colour auto`.
 
 <a id="test-sharding"></a>
 ## Test Sharding
 <pre>--shard-count <#number of shards>, --shard-index <#shard index to run></pre>
 
-> [Introduced](https://github.com/catchorg/Catch2/pull/2257) in Catch2 X.Y.Z.
+> [Introduced](https://github.com/catchorg/Catch2/pull/2257) in Catch2 3.0.1.
 
-When `--shard-count <#number of shards>` is used, the tests to execute will be split evenly in to the given number of sets,
-identified by indicies starting at 0. The tests in the set given by `--shard-index <#shard index to run>` will be executed.
-The default shard count is `1`, and the default index to run is `0`. It is an error to specify a shard index greater than
-the number of shards.
+When `--shard-count <#number of shards>` is used, the tests to execute
+will be split evenly in to the given number of sets, identified by indices
+starting at 0. The tests in the set given by
+`--shard-index <#shard index to run>` will be executed. The default shard
+count is `1`, and the default index to run is `0`.
+
+_It is an error to specify a shard index greater than the number of shards._
+
+Sharding is useful when you want to split test execution across multiple
+processes, as is done with the [Bazel test sharding](https://docs.bazel.build/versions/main/test-encyclopedia.html#test-sharding).
 
-This is useful when you want to split test execution across multiple processes, as is done with [Bazel test sharding](https://docs.bazel.build/versions/main/test-encyclopedia.html#test-sharding). 
 
 <a id="no-tests-override"></a>
 ## Allow running the binary without tests
 <pre>--allow-running-no-tests</pre>
 
-> Introduced in Catch2 X.Y.Z.
+> Introduced in Catch2 3.0.1.
 
 By default, Catch2 test binaries return non-0 exit code if no tests were
 run, e.g. if the binary was compiled with no tests, or the provided test

docs/commercial-users.md

@@ -13,6 +13,7 @@ with you sharing this fact.
  - Locksley.CZ
  - [Makimo](https://makimo.pl/)
  - NASA
+ - [Nexus Software Systems](https://nexwebsites.com)
  - [UX3D](https://ux3d.io)
  - [King](https://king.com)
  

docs/configuration.md

@@ -8,17 +8,19 @@
 [stdout](#stdout)<br>
 [Fallback stringifier](#fallback-stringifier)<br>
 [Default reporter](#default-reporter)<br>
+[Bazel support](#bazel-support)<br>
 [C++11 toggles](#c11-toggles)<br>
 [C++17 toggles](#c17-toggles)<br>
 [Other toggles](#other-toggles)<br>
-[Windows header clutter](#windows-header-clutter)<br>
 [Enabling stringification](#enabling-stringification)<br>
 [Disabling exceptions](#disabling-exceptions)<br>
 [Overriding Catch's debug break (`-b`)](#overriding-catchs-debug-break--b)<br>
 
-Catch is designed to "just work" as much as possible. For most people the only configuration needed is telling Catch which source file should host all the implementation code (```CATCH_CONFIG_MAIN```).
-
-Nonetheless there are still some occasions where finer control is needed. For these occasions Catch exposes a set of macros for configuring how it is built.
+Catch2 is designed to "just work" as much as possible, and most of the
+configuration options below are changed automatically during compilation,
+according to the detected environment. However, this detection can also
+be overriden by users, using macros documented below, and/or CMake options
+with the same name.
 
 
 ## Prefixing Catch macros
@@ -30,19 +32,18 @@ To keep test code clean and uncluttered Catch uses short macro names (e.g. ```TE
 
 ## Terminal colour
 
-    CATCH_CONFIG_COLOUR_NONE      // completely disables all text colouring
-    CATCH_CONFIG_COLOUR_WINDOWS   // forces the Win32 console API to be used
-    CATCH_CONFIG_COLOUR_ANSI      // forces ANSI colour codes to be used
+    CATCH_CONFIG_COLOUR_WIN32     // Force enables compiling colouring impl based on Win32 console API
+    CATCH_CONFIG_NO_COLOUR_WIN32  // Force disables ...
 
-Yes, I am English, so I will continue to spell "colour" with a 'u'.
+Yes, Catch2 uses the british spelling of colour.
 
-When sending output to the terminal, if it detects that it can, Catch will use colourised text. On Windows the Win32 API, ```SetConsoleTextAttribute```, is used. On POSIX systems ANSI colour escape codes are inserted into the stream.
+Catch2 attempts to autodetect whether the Win32 console colouring API,
+`SetConsoleTextAttribute`, is available, and if it is available it compiles
+in a console colouring implementation that uses it.
 
-For finer control you can define one of the above identifiers (these are mutually exclusive - but that is not checked so may behave unexpectedly if you mix them):
+This option can be used to override Catch2's autodetection and force the
+compilation either ON or OFF.
 
-Note that when ANSI colour codes are used "unistd.h" must be includable - along with a definition of ```isatty()```
-
-Typically you should place the ```#define``` before #including "catch.hpp" in your main source file - but if you prefer you can define it for your whole project by whatever your IDE or build system provides for you to do so.
 
 ## Console width
 
@@ -96,6 +97,14 @@ This means that defining `CATCH_CONFIG_DEFAULT_REPORTER` to `"console"`
 is equivalent with the out-of-the-box experience.
 
 
+## Bazel support
+When `CATCH_CONFIG_BAZEL_SUPPORT` is defined or when `BAZEL_TEST=1` (which is set by the Bazel inside of a test environment), 
+Catch2 will register a `JUnit` reporter writing to a path pointed by `XML_OUTPUT_FILE` provided by Bazel.
+
+> `CATCH_CONFIG_BAZEL_SUPPORT` was [introduced](https://github.com/catchorg/Catch2/pull/2399) in Catch2 3.0.1.
+
+> `CATCH_CONFIG_BAZEL_SUPPORT` was [deprecated](https://github.com/catchorg/Catch2/pull/2459) in Catch2 3.1.0.
+
 ## C++11 toggles
 
     CATCH_CONFIG_CPP11_TO_STRING // Use `std::to_string`
@@ -179,13 +188,6 @@ This feature is considered experimental and might change at any point.
 
 _Inspired by Doctest's `DOCTEST_CONFIG_DISABLE`_
 
-## Windows header clutter
-
-On Windows Catch includes `windows.h`. To minimize global namespace clutter in the implementation file, it defines `NOMINMAX` and `WIN32_LEAN_AND_MEAN` before including it. You can control this behaviour via two macros:
-
-    CATCH_CONFIG_NO_NOMINMAX            // Stops Catch from using NOMINMAX macro 
-    CATCH_CONFIG_NO_WIN32_LEAN_AND_MEAN // Stops Catch from using WIN32_LEAN_AND_MEAN macro
-
 
 ## Enabling stringification
 

docs/contributing.md

@@ -62,18 +62,23 @@ test using an external check script. Catch2 integration tests are written
 using CTest, either as a direct command invocation + pass/fail regex,
 or by delegating the check to a Python script.
 
-There are also two more kinds of tests, examples and "ExtraTests".
+Catch2 is slowly gaining more and more types of tests, currently Catch2
+project also has buildable examples, "ExtraTests", and CMake config tests.
 Examples present a small and self-contained snippets of code that
 use Catch2's facilities for specific purpose. Currently they are assumed
-passing if they compile. ExtraTests then are expensive tests, that we
-do not want to run all the time. This can be either because they take
-a long time to run, or because they take a long time to compile, e.g.
-because they test compile time configuration and require separate
-compilation.
+passing if they compile.
 
-Examples and ExtraTests are not compiled by default. To compile them,
-add `-DCATCH_BUILD_EXAMPLES=ON` and `-DCATCH_BUILD_EXTRA_TESTS=ON` to
-the invocation of CMake configuration step.
+ExtraTests then are expensive tests, that we do not want to run all the
+time. This can be either because they take a long time to run, or because
+they take a long time to compile, e.g. because they test compile time
+configuration and require separate compilation.
+
+Finally, CMake config tests test that you set Catch2's compile-time
+configuration options through CMake, using CMake options of the same name.
+
+None of these tests are enabled by default. To enable them, add
+`-DCATCH_BUILD_EXAMPLES=ON`, `-DCATCH_BUILD_EXTRA_TESTS=ON`, and
+`-DCATCH_ENABLE_CONFIGURE_TESTS=ON` when configuration the CMake build.
 
 Bringing this all together, the steps below should configure, build,
 and run all tests in the `Debug` compilation.
@@ -85,7 +90,7 @@ and run all tests in the `Debug` compilation.
 ./tools/scripts/generateAmalgamatedFiles.py
 
 # 2. Configure the full test build
-cmake -Bdebug-build -H. -DCMAKE_BUILD_TYPE=Debug -DCATCH_BUILD_EXAMPLES=ON -DCATCH_BUILD_EXTRA_TESTS=ON -DCATCH_DEVELOPMENT_BUILD=ON
+cmake -Bdebug-build -H. -DCMAKE_BUILD_TYPE=Debug -DCATCH_DEVELOPMENT_BUILD=ON -DCATCH_BUILD_EXAMPLES=ON -DCATCH_BUILD_EXTRA_TESTS=ON
 
 # 3. Run the actual build
 cmake --build debug-build
@@ -131,6 +136,8 @@ should use. It provides you with the top anchor mentioned to link to
 <a id="top"></a>
 # Cool feature
 
+> [Introduced](https://github.com/catchorg/Catch2/pull/123456) in Catch2 X.Y.Z
+
 Text that explains how to use the cool feature.
 
 
@@ -291,9 +298,9 @@ Specifically, every source file should start with the licence header:
 ```
 
 The include guards for header files should follow the pattern `{FILENAME}_INCLUDED`.
-This means that for file `catch_matchers_foo`, the include guard should
-be `CATCH_MATCHERS_FOO_INCLUDED`, for `catch_generators_bar`, the include
-guard should be `CATCH_GENERATORS_BAR_INCLUDED`, and so on.
+This means that for file `catch_matchers_foo.hpp`, the include guard should
+be `CATCH_MATCHERS_FOO_HPP_INCLUDED`, for `catch_generators_bar.hpp`, the include
+guard should be `CATCH_GENERATORS_BAR_HPP_INCLUDED`, and so on.
 
 
 ## CoC

docs/deprecations.md

@@ -17,13 +17,14 @@ as it can be replaced by `Catch.cmake` that provides the function
 command line interface instead of parsing C++ code with regular expressions.
 
 
-## Planned changes
-
-### Console Colour API
-
-The API for Catch2's console colour will be changed to take an extra
-argument, the stream to which the colour code should be applied.
+### `CATCH_CONFIG_BAZEL_SUPPORT`
 
+Catch2 supports writing the Bazel JUnit XML output file when it is aware
+that is within a bazel testing environment. Originally there was no way
+to accurately probe the environment for this information so the flag
+`CATCH_CONFIG_BAZEL_SUPPORT` was added. This now deprecated. Bazel has now had a change
+where it will export `BAZEL_TEST=1` for purposes like the above. Catch2
+will now instead inspect the environment instead of relying on build configuration.
 
 ---
 

docs/faq.md

@@ -1,6 +1,13 @@
 <a id="top"></a>
 # Frequently Asked Questions (FAQ)
 
+**Contents**<br>
+[How do I run global setup/teardown only if tests will be run?](#how-do-i-run-global-setupteardown-only-if-tests-will-be-run)<br>
+[How do I clean up global state between running different tests?](#how-do-i-clean-up-global-state-between-running-different-tests)<br>
+[Why cannot I derive from the built-in reporters?](#why-cannot-i-derive-from-the-built-in-reporters)<br>
+[What is Catch2's ABI stability policy?](#what-is-catch2s-abi-stability-policy)<br>
+[What is Catch2's API stability policy?](#what-is-catch2s-api-stability-policy)<br>
+
 ## How do I run global setup/teardown only if tests will be run?
 
 Write a custom [event listener](event-listeners.md#top) and place the
@@ -22,6 +29,34 @@ forbidding users from using them as a base class, we can refactor them
 as needed later.
 
 
+## What is Catch2's ABI stability policy?
+
+Catch2 provides no ABI stability guarantees whatsoever. Catch2 provides
+rich C++ interface, and trying to freeze its ABI would take a lot of
+pointless work.
+
+Catch2 is not designed to be distributed as dynamic library, and you
+should really be able to compile everything with the same compiler binary.
+
+
+## What is Catch2's API stability policy?
+
+Catch2 follows [semver](https://semver.org/) to the best of our ability.
+This means that we will not knowingly make backwards-incompatible changes
+without incrementing the major version number.
+
+
+## Does Catch2 support running tests in parallel?
+
+Not natively, no. We see running tests in parallel as the job of an
+external test runner, that can also run them in separate processes,
+support test execution timeouts and so on.
+
+However, Catch2 provides some tools that make the job of external test
+runners easier. [See the relevant section in our page on best
+practices](usage-tips.md#parallel-tests).
+
+
 ---
 
 [Home](Readme.md#top)

docs/list-of-examples.md

@@ -3,7 +3,6 @@
 
 ## Already available
 
-- Catch main: [Catch-provided main](../examples/000-CatchMain.cpp)
 - Test Case: [Single-file](../examples/010-TestCase.cpp)
 - Test Case: [Multiple-file 1](../examples/020-TestCase-1.cpp), [2](../examples/020-TestCase-2.cpp)
 - Assertion: [REQUIRE, CHECK](../examples/030-Asn-Require-Check.cpp)

docs/matchers.md

@@ -248,7 +248,7 @@ Note that `DerivedException` in the example above has to derive from
 
 ### Generic range Matchers
 
-> Generic range matchers were introduced in Catch2 X.Y.Z
+> Generic range matchers were introduced in Catch2 3.0.1
 
 Catch2 also provides some matchers that use the new style matchers
 definitions to handle generic range-like types. These are:
@@ -258,6 +258,12 @@ definitions to handle generic range-like types. These are:
 * `SizeIs(Matcher size_matcher)`
 * `Contains(T&& target_element, Comparator = std::equal_to<>{})`
 * `Contains(Matcher element_matcher)`
+* `AllMatch(Matcher element_matcher)`
+* `NoneMatch(Matcher element_matcher)`
+* `AnyMatch(Matcher element_matcher)`
+* `AllTrue()`
+* `NoneTrue()`
+* `AnyTrue()`
 
 `IsEmpty` should be self-explanatory. It successfully matches objects
 that are empty according to either `std::empty`, or ADL-found `empty`
@@ -275,6 +281,14 @@ the target element. The other variant is constructed from a matcher,
 in which case a range is accepted if any of its elements is accepted
 by the provided matcher.
 
+`AllMatch`, `NoneMatch`, and `AnyMatch` match ranges for which either
+all, none, or any of the contained elements matches the given matcher, 
+respectively.
+
+`AllTrue`, `NoneTrue`, and `AnyTrue` match ranges for which either
+all, none, or any of the contained elements are `true`, respectively. 
+It works for ranges of `bool`s and ranges of elements (explicitly) 
+convertible to `bool`.
 
 ## Writing custom matchers (old style)
 
@@ -350,7 +364,7 @@ style matchers arbitrarily.
 
 ## Writing custom matchers (new style)
 
-> New style matchers were introduced in Catch2 X.Y.Z
+> New style matchers were introduced in Catch2 3.0.1
 
 To create a new-style matcher, you have to create your own type that
 derives from `Catch::Matchers::MatcherGenericBase`. Your type has to

docs/migrate-v2-to-v3.md

@@ -50,7 +50,8 @@ compilation times in the v3 version. The basic steps to do so are:
 
 1. Change your CMakeLists.txt to link against `Catch2WithMain` target if
 you use Catch2's default main. (If you do not, keep linking against
-the `Catch2` target.)
+the `Catch2` target.). If you use pkg-config, change `pkg-config catch2` to
+`pkg-config catch2-with-main`.
 2. Delete TU with `CATCH_CONFIG_RUNNER` or `CATCH_CONFIG_MAIN` defined,
 as it is no longer needed.
 3. Change `#include <catch2/catch.hpp>` to `#include <catch2/catch_all.hpp>`

docs/opensource-users.md

@@ -17,6 +17,9 @@ maintainer's explicit consent._
 
 ## Libraries & Frameworks
 
+### [accessorpp](https://github.com/wqking/accessorpp)
+C++ library for implementing property and data binding.
+
 ### [alpaka](https://github.com/alpaka-group/alpaka)
 A header-only C++14 abstraction library for accelerator development.
 
@@ -50,6 +53,9 @@ Header-only C++11 library to encode/decode base64, base64url, base32, base32hex
 ### [DtCraft](https://github.com/twhuang-uiuc/DtCraft)
 A High-performance Cluster Computing Engine.
 
+### [eventpp](https://github.com/wqking/eventpp)
+C++ event library for callbacks, event dispatcher, and event queue. With eventpp you can easily implement signal and slot mechanism, publisher and subscriber pattern, or observer pattern.
+
 ### [forest](https://github.com/xorz57/forest)
 Template Library of Tree Data Structures.
 
@@ -77,6 +83,9 @@ A small C++ library wrapper for the native C ODBC API.
 ### [Nonius](https://github.com/libnonius/nonius)
 A header-only framework for benchmarking small snippets of C++ code.
 
+### [OpenALpp](https://github.com/Laguna1989/OpenALpp)
+A modern OOP C++14 audio library built on OpenAL for Windows, Linux and web (emscripten).
+
 ### [polymorphic_value](https://github.com/jbcoe/polymorphic_value)
 A polymorphic value-type for C++.
 
@@ -109,6 +118,9 @@ A high available cloud native micro-service application management platform impl
 ### [ArangoDB](https://github.com/arangodb/arangodb)
 ArangoDB is a native multi-model database with flexible data models for documents, graphs, and key-values.
 
+### [Cytopia](https://github.com/CytopiaTeam/Cytopia)
+Cytopia is a free, open source retro pixel-art city building game with a big focus on mods. It utilizes a custom isometric rendering engine based on SDL2.
+
 ### [d-SEAMS](https://github.com/d-SEAMS/seams-core)
 Open source molecular dynamics simulation structure analysis suite of tools in modern C++.
 

docs/other-macros.md

@@ -15,7 +15,7 @@ stringification machinery to the _expr_ and records the result. As with
 evaluates to `true`. `CHECKED_ELSE( expr )` work similarly, but the block
 is entered only if the _expr_ evaluated to `false`.
 
-> `CHECKED_X` macros were changed to not count as failure in Catch2 X.Y.Z.
+> `CHECKED_X` macros were changed to not count as failure in Catch2 3.0.1.
 
 Example:
 ```cpp
@@ -77,7 +77,7 @@ TEST_CASE("STATIC_REQUIRE showcase", "[traits]") {
 }
 ```
 
-> `STATIC_CHECK` was [introduced](https://github.com/catchorg/Catch2/pull/2318) in Catch2 X.Y.Z.
+> `STATIC_CHECK` was [introduced](https://github.com/catchorg/Catch2/pull/2318) in Catch2 3.0.1.
 
 `STATIC_CHECK( expr )` is equivalent to `STATIC_REQUIRE( expr )`, with the
 difference that when `CATCH_CONFIG_RUNTIME_STATIC_REQUIRE` is defined, it

docs/release-notes.md

@@ -2,7 +2,8 @@
 
 # Release notes
 **Contents**<br>
-[3.0.1 (in progress)](#301-in-progress)<br>
+[3.1.0](#310)<br>
+[3.0.1](#301)<br>
 [2.13.7](#2137)<br>
 [2.13.6](#2136)<br>
 [2.13.5](#2135)<br>
@@ -49,25 +50,54 @@
 [Even Older versions](#even-older-versions)<br>
 
 
-## 3.0.1 (in progress)
+## 3.1.0
+
+### Improvements
+* Improved suppression of `-Wparentheses` for older GCCs
+  * Turns out that even GCC 9 does not properly handle `_Pragma`s in the C++ frontend.
+* Added type constraints onto `random` generator (#2433)
+  * These constraints copy what the standard says for the underlying `std::uniform_int_distribution`
+* Suppressed -Wunused-variable from nvcc (#2306, #2427)
+* Suppressed -Wunused-variable from MinGW (#2132)
+* Added All/Any/NoneTrue range matchers (#2319)
+  * These check that all/any/none of boolean values in a range are true.
+* The JUnit reporter now normalizes classnames from C++ namespaces to Java-like namespaces (#2468)
+  * This provides better support for other JUnit based tools.
+* The Bazel support now understands `BAZEL_TEST` environment variable (#2459)
+  * The `CATCH_CONFIG_BAZEL_SUPPORT` configuration option is also still supported.
+* Returned support for compiling Catch2 with GCC 5 (#2448)
+  * This required removing inherited constructors from Catch2's internals.
+  * I recommend updating to a newer GCC anyway.
+* `catch_discover_tests` now has a new options for setting library load path(s) when running the Catch2 binary (#2467)
+
+
+### Fixes
+* Fixed crash when listing listeners without any registered listeners (#2442)
+* Fixed nvcc compilation error in constructor benchmarking helper (#2477)
+* Catch2's CMakeList supports pre-3.12 CMake again (#2428)
+  * The gain from requiring CMake 3.12 was very minor, but y'all should really update to newer CMake
+
+
+### Miscellaneous
+* Fixed SelfTest build on MinGW (#2447)
+* The in-repo conan recipe exports the CMake helper (#2460)
+* Added experimental CMake script to showcase using test case sharding together with CTest
+  * Compared to `catch_discover_tests`, it supports very limited number of options and customization
+* Added documentation page on best practices when running Catch2 tests
+* Catch2 can be built as a dynamic library (#2397, #2398)
+  * Note that Catch2 does not have visibility annotations, and you are responsible for ensuring correct visibility built into the resulting library.
+
+
+
+## 3.0.1
 
 **Catch2 now uses statically compiled library as its distribution model.
 This also means that to get all of Catch2's functionality in a test file,
 you have to include multiple headers.**
 
-For quick'n'dirty migration, you can replace the old `#include <catch2/catch.hpp>`
-with `#include <catch2/catch_all.hpp>`. This is a (one of) convenience
-header(s) that brings in _all_ of headers in Catch2. By doing this,
-you should be able to migrate instantly, but at the cost of (significantly)
-increased compilation times. You should prefer piecemeal including
-headers that are actually required by your test code.
-
-The basic set of functionality (`TEST_CASE`, `SECTION`, `REQUIRE`) is in
-`catch2/catch_test_macros.hpp`. Matchers are in `matchers` subfolder,
-generators in `generators` subfolder, and so on.
-
-Note that documentation has not yet been updated to account for the
-new design.
+You probably want to look into the [migration docs](migrate-v2-to-v3.md#top),
+which were written to help people coming from v2.x.x versions to the
+v3 releases.
 
 
 ### FAQ
@@ -132,11 +162,14 @@ new design.
   * With the exception of the XmlReporter, the outputs of first party reporters should remain the same
   * New pair of events were added
   * One obsolete event was removed
+  * The base class has been renamed
+  * The built-in reporter class hierarchy has been redone
 * Catch2 generates a random seed if one hasn't been specified by the user
 * The short flag for `--list-tests`, `-l`, has been removed.
   * This is not a commonly used flag and does not need to use up valuable single-letter space.
 * The short flag for `--list-tags`, `-t`, has been removed.
   * This is not a commonly used flag and does not need to use up valuable single-letter space.
+* The `--colour` option has been replaced with `--colour-mode` option
 
 
 ### Improvements
@@ -188,6 +221,18 @@ new design.
 * Multiple reporters can now run at the same time and write to different files (#1712, #2183)
   * To support this, the `-r`, `--reporter` flag now also accepts optional output destination
   * For full overview of the semantics of using multiple reporters, look into the reporter documentation
+  * To enable the new syntax, reporter names can no longer contain `::`.
+* Console colour support has been rewritten and significantly improved
+  * The colour implementation based on ANSI colour codes is always available
+  * Colour implementations respect their associated stream
+    * previously e.g. Win32 impl would change console colour even if Catch2 was writing to a file
+  * The colour API is resilient against changing evaluation order of expressions
+  * The associated CLI flag and compile-time configuration options have changed
+    * For details see the docs for command-line and compile-time Catch2 configuration
+* Added a support for Bazel integration with `XML_OUTPUT_FILE` env var (#2399)
+  * This has to be enabled during compilation.
+* Added `--skip-benchmarks` flag to run tests without any `BENCHMARK`s (#2392, #2408)
+* Added option to list all listeners in the binary via `--list-listeners`
 
 
 ### Fixes
@@ -200,6 +245,8 @@ new design.
   * Previously it forced lower cased name, which would fail for reporters with upper case characters in name
 * The cumulative reporter base stores benchmark results alongside assertion results
 * Catch2's SE handling should no longer interferes with ASan on Windows (#2334)
+* Fixed Windows console colour handling for tests that redirect stdout (#2345)
+* Fixed issue with the `random` generators returning the same value over and over again
 
 
 ### Other changes
@@ -217,6 +264,11 @@ new design.
 * Running 0 tests (e.g. due to empty binary, or test spec not matching anything) returns non-0 exit code
   * Flag `--allow-running-no-tests` overrides this behaviour.
   * `NoTests` warning has been removed because it is fully subsumed by this change.
+* Catch2's compile-time configuration options (`CATCH_CONFIG_FOO`) can be set through CMake options of the same name
+  * They use the same semantics as C++ defines, including the `CATCH_CONFIG_NO_FOO` overrides,
+    * `-DCATCH_CONFIG_DEFAULT_REPORTER=compact` changes default reporter to "compact"
+    * `-DCATCH_CONFIG_NO_ANDROID_LOGWRITE=ON` forces android logwrite to off
+    * `-DCATCH_CONFIG_ANDROID_LOGWRITE=OFF` does nothing (the define will not exist)
 
 
 

docs/release-process.md

@@ -40,14 +40,10 @@ After version number is incremented, single-include header is regenerated and re
 After pushing changes to GitHub, GitHub release *needs* to be created.
 Tag version and release title should be same as the new version,
 description should contain the release notes for the current release.
-Single header version of `catch.hpp` *needs* to be attached as a binary,
-as that is where the official download link links to. Preferably
-it should use linux line endings. All non-bundled reporters (Automake, TAP,
-TeamCity, SonarQube) should also be attached as binaries, as they might be
-dependent on a specific version of the single-include header.
+We also attach the two amalgamated files as "binaries".
 
-Since 2.5.0, the release tag and the "binaries" (headers) should be PGP
-signed.
+Since 2.5.0, the release tag and the "binaries" (amalgamated files) should
+be PGP signed.
 
 #### Signing a tag
 
@@ -57,16 +53,14 @@ is the version being released, e.g. `git tag -s v2.6.0`.
 Use the version name as the short message and the release notes as
 the body (long) message.
 
-#### Signing the headers
+#### Signing the amalgamated files
 
-This will create ASCII-armored signatures for the headers that are
-uploaded to the GitHub release:
+This will create ASCII-armored signatures for the two amalgamated files
+that are uploaded to the GitHub release:
 
 ```
-$ gpg2 --armor --output catch.hpp.asc --detach-sig catch.hpp
-$ gpg2 --armor --output catch_reporter_automake.hpp.asc --detach-sig catch_reporter_automake.hpp
-$ gpg2 --armor --output catch_reporter_teamcity.hpp.asc --detach-sig catch_reporter_teamcity.hpp
-$ gpg2 --armor --output catch_reporter_tap.hpp.asc --detach-sig catch_reporter_tap.hpp
+gpg --armor --output extras/catch_amalgamated.hpp.asc --detach-sig extras/catch_amalgamated.hpp
+gpg --armor --output extras/catch_amalgamated.cpp.asc --detach-sig extras/catch_amalgamated.cpp
 ```
 
 _GPG does not support signing multiple files in single invocation._

docs/reporter-events.md

@@ -56,7 +56,7 @@ are handled by a different event.
 
 ### `testCasePartial` events
 
-> Introduced in Catch2 X.Y.Z
+> Introduced in Catch2 3.0.1
 
 ```cpp
 void testCasePartialStarting( TestCaseInfo const& testInfo, uint64_t partNumber );
@@ -135,7 +135,7 @@ benchmarking itself fails.
 
 ## Listings events
 
-> Introduced in Catch2 X.Y.Z.
+> Introduced in Catch2 3.0.1.
 
 Listings events are events that correspond to the test binary being
 invoked with `--list-foo` flag. 

docs/reporters.md

@@ -30,7 +30,7 @@ reporters](#multiple-reporters) to avoid any surprises from doing so.
 <a id="multiple-reporters"></a>
 ## Using multiple reporters
 
-> Support for having multiple parallel reporters was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 X.Y.Z
+> Support for having multiple parallel reporters was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 3.0.1
 
 Catch2 supports using multiple reporters at the same time while having
 them write into different destinations. The two main uses of this are
@@ -43,9 +43,14 @@ them write into different destinations. The two main uses of this are
 
 Specifying multiple reporter looks like this:
 ```
---reporter console::- --reporter JUnit::result-junit.xml
+--reporter JUnit::out=result-junit.xml --reporter console::out=-::colour-mode=ansi
 ```
 
+This tells Catch2 to use two reporters, `JUnit` reporter that writes
+its machine-readable XML output to file `result-junit.xml`, and the
+`console` reporter that writes its user-friendly output to stdout and
+uses ANSI colour codes for colouring the output.
+
 Using multiple reporters (or one reporter and one-or-more [event
 listeners](event-listener.md#top)) can have surprisingly complex semantics
 when using customization points provided to reporters by Catch2, namely
@@ -70,7 +75,7 @@ out in batch after each runthrough of a test case is finished.
 You can also write your own custom reporter and tell Catch2 to use it.
 When writing your reporter, you have two options:
 
-* Derive from `Catch::IStreamingReporter`. When doing this, you will have
+* Derive from `Catch::ReporterBase`. When doing this, you will have
   to provide handling for all [reporter events](reporter-events.md#top).
 * Derive from one of the provided [utility reporter bases in
   Catch2](#utility-reporter-bases).
@@ -162,6 +167,26 @@ Currently there are two customization options:
    format includes passing assertions even without the `-s` flag.
 
 
+### Per-reporter configuration
+
+> Per-reporter configuration was introduced in Catch2 3.0.1
+
+Catch2 supports some configuration to happen per reporter. The configuration
+options fall into one of two categories:
+
+* Catch2-recognized options
+* Reporter-specific options
+
+The former is a small set of universal options that Catch2 handles for
+the reporters, e.g. output file or console colour mode. The latter are
+options that the reporters have to handle themselves, but the keys and
+values can be arbitrary strings, as long as they don't contain `::`. This
+allows writing reporters that can be significantly customized at runtime.
+
+Reporter-specific options always have to be prefixed with "X" (large
+letter X).
+
+
 ### Other expected functionality of a reporter
 
 When writing a custom reporter, there are few more things that you should

docs/test-cases-and-sections.md

@@ -72,7 +72,8 @@ All tag names beginning with non-alphanumeric characters are reserved by Catch.
 
 * `[@<alias>]` - tag aliases all begin with `@` (see below).
 
-* `[!benchmark]` - this test case is actually a benchmark. This is an experimental feature, and currently has no documentation. If you want to try it out, look at `projects/SelfTest/Benchmark.tests.cpp` for details.
+* `[!benchmark]` - this test case is actually a benchmark. Currently this only serves to hide the test case by default, to avoid the execution time costs.
+
 
 ## Tag aliases
 
@@ -153,7 +154,7 @@ Scenario : vector can be sized and resized
   Then   : The size changes
 ```
 
-See also [runnable example on godbolt](https://godbolt.org/z/e5vPPM),
+See also [runnable example on godbolt](https://godbolt.org/z/eY5a64r99),
 with a more complicated (and failing) example.
 
 > `AND_GIVEN` was [introduced](https://github.com/catchorg/Catch2/issues/1360) in Catch2 2.4.0.

docs/test-fixtures.md

@@ -59,7 +59,10 @@ struct Template_Fixture {
     T m_a;
 };
 
-TEMPLATE_TEST_CASE_METHOD(Template_Fixture,"A TEMPLATE_TEST_CASE_METHOD based test run that succeeds", "[class][template]", int, float, double) {
+TEMPLATE_TEST_CASE_METHOD(Template_Fixture,
+                          "A TEMPLATE_TEST_CASE_METHOD based test run that succeeds",
+                          "[class][template]",
+                          int, float, double) {
     REQUIRE( Template_Fixture<TestType>::m_a == 1 );
 }
 
@@ -77,7 +80,11 @@ struct Foo_class {
     }
 };
 
-TEMPLATE_PRODUCT_TEST_CASE_METHOD(Template_Template_Fixture, "A TEMPLATE_PRODUCT_TEST_CASE_METHOD based test succeeds", "[class][template]", (Foo_class, std::vector), int) {
+TEMPLATE_PRODUCT_TEST_CASE_METHOD(Template_Template_Fixture,
+                                  "A TEMPLATE_PRODUCT_TEST_CASE_METHOD based test succeeds",
+                                  "[class][template]",
+                                  (Foo_class, std::vector),
+                                  int) {
     REQUIRE( Template_Template_Fixture<TestType>::m_a.size() == 0 );
 }
 ```
@@ -101,7 +108,12 @@ struct Nttp_Fixture{
     int value = V;
 };
 
-TEMPLATE_TEST_CASE_METHOD_SIG(Nttp_Fixture, "A TEMPLATE_TEST_CASE_METHOD_SIG based test run that succeeds", "[class][template][nttp]",((int V), V), 1, 3, 6) {
+TEMPLATE_TEST_CASE_METHOD_SIG(
+    Nttp_Fixture,
+    "A TEMPLATE_TEST_CASE_METHOD_SIG based test run that succeeds",
+    "[class][template][nttp]",
+    ((int V), V),
+    1, 3, 6) {
     REQUIRE(Nttp_Fixture<V>::value > 0);
 }
 
@@ -117,8 +129,13 @@ struct Template_Foo_2 {
     size_t size() { return V; }
 };
 
-TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG(Template_Fixture_2, "A TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG based test run that succeeds", "[class][template][product][nttp]", ((typename T, size_t S), T, S),(std::array, Template_Foo_2), ((int,2), (float,6)))
-{
+TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG(
+    Template_Fixture_2, 
+    "A TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG based test run that succeeds", 
+    "[class][template][product][nttp]", 
+    ((typename T, size_t S), T, S),
+    (std::array, Template_Foo_2),
+    ((int,2), (float,6))) {
     REQUIRE(Template_Fixture_2<TestType>{}.m_a.size() >= 2);
 }
 ```
@@ -132,8 +149,10 @@ only difference is the source of types. This allows you to reuse the template ty
 Example:
 ```cpp
 using MyTypes = std::tuple<int, char, double>;
-TEMPLATE_LIST_TEST_CASE_METHOD(Template_Fixture, "Template test case method with test types specified inside std::tuple", "[class][template][list]", MyTypes)
-{
+TEMPLATE_LIST_TEST_CASE_METHOD(Template_Fixture,
+                               "Template test case method with test types specified inside std::tuple",
+                               "[class][template][list]",
+                               MyTypes) {
     REQUIRE( Template_Fixture<TestType>::m_a == 1 );
 }
 ```

docs/tutorial.md

@@ -94,7 +94,7 @@ before we move on.
 * The test automatically self-registers with the test runner, and user
   does not have do anything more to ensure that it is picked up by the test
   framework. _Note that you can run specific test, or set of tests,
-  through the [command line](command-line#top)._
+  through the [command line](command-line.md#top)._
 * The individual test assertions are written using the `REQUIRE` macro.
   It accepts a boolean expression, and uses expression templates to
   internally decompose it, so that it can be individually stringified

docs/usage-tips.md

@@ -0,0 +1,95 @@
+<a id="top"></a>
+# Best practices and other tips on using Catch2
+
+## Running tests
+
+Your tests should be run in a manner roughly equivalent with:
+
+```
+./tests --order rand --warn NoAssertions
+```
+
+Notice that all the tests are run in a large batch, their relative order
+is randomized, and that you ask Catch2 to fail test whose leaf-path
+does not contain an assertion.
+
+The reason I recommend running all your tests in the same process is that
+this exposes your tests to interference from their runs. This can be both
+positive interference, where the changes in global state from previous
+test allow later tests to pass, but also negative interference, where
+changes in global state from previous test causes later tests to fail.
+
+In my experience, interference, especially destructive interference,
+usually comes from errors in the code under test, rather than the tests
+themselves. This means that by allowing interference to happen, our tests
+can find these issues. Obviously, to shake out interference coming from
+different orderings of tests, the test order also need to be shuffled
+between runs.
+
+However, running all tests in a single batch eventually becomes impractical
+as they will take too long to run, and you will want to run your tests
+in parallel.
+
+
+<a id="parallel-tests"></a>
+## Running tests in parallel
+
+There are multiple ways of running tests in parallel, with various level
+of structure. If you are using CMake and CTest, then we provide a helper
+function [`catch_discover_tests`](cmake-integration.md#automatic-test-registration)
+that registers each Catch2 `TEST_CASE` as a single CTest test, which
+is then run in a separate process. This is an easy way to set up parallel
+tests if you are already using CMake & CTest to run your tests, but you
+will lose the advantage of running tests in batches.
+
+
+Catch2 also supports [splitting tests in a binary into multiple
+shards](command-line.md#test-sharding). This can be used by any test
+runner to run batches of tests in parallel. Do note that when selecting
+on the number of shards, you should have more shards than there are cores,
+to avoid issues with long running tests getting accidentally grouped in
+the same shard, and causing long-tailed execution time.
+
+**Note that naively composing sharding and random ordering of tests will break.**
+
+Invoking Catch2 test executable like this
+
+```text
+./tests --order rand --shard-index 0 --shard-count 3
+./tests --order rand --shard-index 1 --shard-count 3
+./tests --order rand --shard-index 2 --shard-count 3
+```
+
+does not guarantee covering all tests inside the executable, because
+each invocation will have its own random seed, thus it will have its own
+random order of tests and thus the partitioning of tests into shards will
+be different as well.
+
+To do this properly, you need the individual shards to share the random
+seed, e.g.
+```text
+./tests --order rand --shard-index 0 --shard-count 3 --rng-seed 0xBEEF
+./tests --order rand --shard-index 1 --shard-count 3 --rng-seed 0xBEEF
+./tests --order rand --shard-index 2 --shard-count 3 --rng-seed 0xBEEF
+```
+
+
+## Organizing tests into binaries
+
+Both overly large and overly small test binaries can cause issues. Overly
+large test binaries have to be recompiled and relinked often, and the
+link times are usually also long. Overly small test binaries in turn pay
+significant overhead from linking against Catch2 more often per compiled
+test case, and also make it hard/impossible to run tests in batches.
+
+Because there is no hard and fast rule for the right size of a test binary,
+I recommend having 1:1 correspondence between libraries in project and test
+binaries. (At least if it is possible, in some cases it is not.) Having
+a test binary for each library in project keeps related tests together,
+and makes tests easy to navigate by reflecting the project's organizational
+structure.
+
+
+---
+
+[Home](Readme.md#top)

examples/000-CatchMain.cpp

@@ -1,13 +0,0 @@
-// 000-CatchMain.cpp
-
-// It is generally recommended to have a single file provide the main
-// of a testing binary, and other test files to link against it.
-
-// Let Catch provide main():
-#include <catch2/internal/catch_default_main.hpp>
-
-// That's it
-
-// Compile implementation of Catch for use with files that do contain tests:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -c 000-CatchMain.cpp
-// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% -c 000-CatchMain.cpp

examples/010-TestCase.cpp

@@ -19,7 +19,7 @@ TEST_CASE( "Factorials of 1 and higher are computed (pass)", "[single-file]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 010-TestCase 010-TestCase.cpp && 010-TestCase --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 010-TestCase 010-TestCase.cpp && 010-TestCase --success
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 010-TestCase.cpp && 010-TestCase --success
 
 // Expected compact output (all assertions):

examples/020-TestCase-1.cpp

@@ -10,8 +10,8 @@ TEST_CASE( "1: All test cases reside in other .cpp files (empty)", "[multi-file:
 // Here just to show there are two source files via option --list-tests.
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -c 020-TestCase-1.cpp
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 020-TestCase TestCase-1.o 020-TestCase-2.cpp && 020-TestCase --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -c 020-TestCase-1.cpp
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 020-TestCase TestCase-1.o 020-TestCase-2.cpp && 020-TestCase --success
 //
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% -c 020-TestCase-1.cpp
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% -Fe020-TestCase.exe 020-TestCase-1.obj 020-TestCase-2.cpp && 020-TestCase --success

examples/030-Asn-Require-Check.cpp

@@ -8,7 +8,7 @@
 // - REQUIRE_FALSE() stops at first failure.
 // - CHECK_FALSE() continues after failure.
 
-// main() provided in 000-CatchMain.cpp
+// main() provided by linkage to Catch2WithMain
 
 #include <catch2/catch_test_macros.hpp>
 
@@ -53,8 +53,8 @@ TEST_CASE( "Assert that something is false (continue after failure)", "[check-fa
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 030-Asn-Require-Check 030-Asn-Require-Check.cpp 000-CatchMain.o && 030-Asn-Require-Check --success
-// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 030-Asn-Require-Check.cpp 000-CatchMain.obj && 030-Asn-Require-Check --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 030-Asn-Require-Check 030-Asn-Require-Check.cpp && 030-Asn-Require-Check --success
+// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 030-Asn-Require-Check.cpp && 030-Asn-Require-Check --success
 
 // Expected compact output (all assertions):
 //

examples/100-Fix-Section.cpp

@@ -4,7 +4,7 @@
 // - Sections (this file)
 // - Traditional class-based fixtures
 
-// main() provided in 000-CatchMain.cpp
+// main() provided by linkage to Catch2WithMain
 
 #include <catch2/catch_test_macros.hpp>
 #include <vector>
@@ -45,8 +45,8 @@ TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 100-Fix-Section 100-Fix-Section.cpp 000-CatchMain.o && 100-Fix-Section --success
-// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 100-Fix-Section.cpp 000-CatchMain.obj && 100-Fix-Section --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 100-Fix-Section 100-Fix-Section.cpp && 100-Fix-Section --success
+// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 100-Fix-Section.cpp && 100-Fix-Section --success
 
 // Expected compact output (all assertions):
 //

examples/110-Fix-ClassFixture.cpp

@@ -4,7 +4,7 @@
 // - Sections
 // - Traditional class-based fixtures (this file)
 
-// main() provided in 000-CatchMain.cpp
+// main() provided by linkage to Catch2WithMain
 
 #include <catch2/catch_test_macros.hpp>
 
@@ -52,8 +52,11 @@ TEST_CASE_METHOD( UniqueTestsFixture, "Create Employee/Normal", "[create]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 110-Fix-ClassFixture 110-Fix-ClassFixture.cpp 000-CatchMain.o && 110-Fix-ClassFixture --success
-// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 110-Fix-ClassFixture.cpp 000-CatchMain.obj && 110-Fix-ClassFixture --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 110-Fix-ClassFixture 110-Fix-ClassFixture.cpp && 110-Fix-ClassFixture --success
+// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 110-Fix-ClassFixture.cpp && 110-Fix-ClassFixture --success
+//
+// Compile with pkg-config:
+// - g++ -std=c++14 -Wall $(pkg-config catch2-with-main --cflags)  -o 110-Fix-ClassFixture 110-Fix-ClassFixture.cpp $(pkg-config catch2-with-main --libs)
 
 // Expected compact output (all assertions):
 //

examples/120-Bdd-ScenarioGivenWhenThen.cpp

@@ -1,6 +1,6 @@
 // 120-Bdd-ScenarioGivenWhenThen.cpp
 
-// main() provided in 000-CatchMain.cpp
+// main() provided by linkage with Catch2WithMain
 
 #include <catch2/catch_test_macros.hpp>
 
@@ -48,8 +48,8 @@ SCENARIO( "vectors can be sized and resized", "[vector]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 120-Bdd-ScenarioGivenWhenThen 120-Bdd-ScenarioGivenWhenThen.cpp 000-CatchMain.o && 120-Bdd-ScenarioGivenWhenThen --success
-// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 120-Bdd-ScenarioGivenWhenThen.cpp 000-CatchMain.obj && 120-Bdd-ScenarioGivenWhenThen --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 120-Bdd-ScenarioGivenWhenThen 120-Bdd-ScenarioGivenWhenThen.cpp && 120-Bdd-ScenarioGivenWhenThen --success
+// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 120-Bdd-ScenarioGivenWhenThen.cpp && 120-Bdd-ScenarioGivenWhenThen --success
 
 // Expected compact output (all assertions):
 //

examples/210-Evt-EventListeners.cpp

@@ -308,7 +308,7 @@ struct MyListener : Catch::EventListenerBase {
     using EventListenerBase::EventListenerBase; // inherit constructor
 
     // Get rid of Wweak-tables
-    ~MyListener();
+    ~MyListener() override;
 
     // The whole test run starting
     void testRunStarting( Catch::TestRunInfo const& testRunInfo ) override {
@@ -420,8 +420,8 @@ TEST_CASE_METHOD( Fixture, "3: Testcase with class-based fixture", "[tag-C][tag-
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 210-Evt-EventListeners 210-Evt-EventListeners.cpp 000-CatchMain.o && 210-Evt-EventListeners --success
-// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 210-Evt-EventListeners.cpp 000-CatchMain.obj && 210-Evt-EventListeners --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 210-Evt-EventListeners 210-Evt-EventListeners.cpp && 210-Evt-EventListeners --success
+// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 210-Evt-EventListeners.cpp && 210-Evt-EventListeners --success
 
 // Expected compact output (all assertions):
 //

extras/Catch.cmake

@@ -116,6 +116,13 @@ same as the Catch name; see also ``TEST_PREFIX`` and ``TEST_SUFFIX``.
     ``--out dir/<test_name>suffix``. This can be used to add a file extension to
     the output e.g. ".xml".
 
+  ``DL_PATHS path...``
+    Specifies paths that need to be set for the dynamic linker to find shared
+    libraries/DLLs when running the test executable (PATH/LD_LIBRARY_PATH respectively).
+    These paths will both be set when retrieving the list of test cases from the
+    test executable and when the tests are executed themselves. This requires
+    cmake/ctest >= 3.22.
+
 #]=======================================================================]
 
 #------------------------------------------------------------------------------
@@ -124,7 +131,7 @@ function(catch_discover_tests TARGET)
     ""
     ""
     "TEST_PREFIX;TEST_SUFFIX;WORKING_DIRECTORY;TEST_LIST;REPORTER;OUTPUT_DIR;OUTPUT_PREFIX;OUTPUT_SUFFIX"
-    "TEST_SPEC;EXTRA_ARGS;PROPERTIES"
+    "TEST_SPEC;EXTRA_ARGS;PROPERTIES;DL_PATHS"
     ${ARGN}
   )
 
@@ -135,6 +142,12 @@ function(catch_discover_tests TARGET)
     set(_TEST_LIST ${TARGET}_TESTS)
   endif()
 
+  if (_DL_PATHS)
+    if(${CMAKE_VERSION} VERSION_LESS "3.22.0")
+        message(FATAL_ERROR "The DL_PATHS option requires at least cmake 3.22")
+    endif()
+  endif()
+
   ## Generate a unique name based on the extra arguments
   string(SHA1 args_hash "${_TEST_SPEC} ${_EXTRA_ARGS} ${_REPORTER} ${_OUTPUT_DIR} ${_OUTPUT_PREFIX} ${_OUTPUT_SUFFIX}")
   string(SUBSTRING ${args_hash} 0 7 args_hash)
@@ -164,6 +177,7 @@ function(catch_discover_tests TARGET)
             -D "TEST_OUTPUT_DIR=${_OUTPUT_DIR}"
             -D "TEST_OUTPUT_PREFIX=${_OUTPUT_PREFIX}"
             -D "TEST_OUTPUT_SUFFIX=${_OUTPUT_SUFFIX}"
+            -D "TEST_DL_PATHS=${_DL_PATHS}"
             -D "CTEST_FILE=${ctest_tests_file}"
             -P "${_CATCH_DISCOVER_TESTS_SCRIPT}"
     VERBATIM

extras/CatchAddTests.cmake

@@ -10,10 +10,17 @@ set(reporter ${TEST_REPORTER})
 set(output_dir ${TEST_OUTPUT_DIR})
 set(output_prefix ${TEST_OUTPUT_PREFIX})
 set(output_suffix ${TEST_OUTPUT_SUFFIX})
+set(dl_paths ${TEST_DL_PATHS})
 set(script)
 set(suite)
 set(tests)
 
+if(WIN32)
+  set(dl_paths_variable_name PATH)
+else()
+  set(dl_paths_variable_name LD_LIBRARY_PATH)
+endif()
+
 function(add_command NAME)
   set(_args "")
   # use ARGV* instead of ARGN, because ARGN splits arrays into multiple arguments
@@ -35,6 +42,12 @@ if(NOT EXISTS "${TEST_EXECUTABLE}")
     "Specified test executable '${TEST_EXECUTABLE}' does not exist"
   )
 endif()
+
+if(dl_paths)
+  cmake_path(CONVERT "${dl_paths}" TO_NATIVE_PATH_LIST paths)
+  set(ENV{${dl_paths_variable_name}} "${paths}")
+endif()
+
 execute_process(
   COMMAND ${TEST_EXECUTOR} "${TEST_EXECUTABLE}" ${spec} --list-tests --verbosity quiet
   OUTPUT_VARIABLE output
@@ -85,6 +98,13 @@ if(output_dir AND NOT IS_ABSOLUTE ${output_dir})
   endif()
 endif()
 
+if(dl_paths)
+  foreach(path ${dl_paths})
+    cmake_path(NATIVE_PATH path native_path)
+    list(APPEND environment_modifications "${dl_paths_variable_name}=path_list_prepend:${native_path}")
+  endforeach()
+endif()
+
 # Parse output
 foreach(line ${output})
   set(test ${line})
@@ -115,6 +135,14 @@ foreach(line ${output})
     WORKING_DIRECTORY "${TEST_WORKING_DIR}"
     ${properties}
   )
+
+   if(environment_modifications)
+     add_command(set_tests_properties
+       "${prefix}${test}${suffix}"
+       PROPERTIES
+       ENVIRONMENT_MODIFICATION "${environment_modifications}")
+   endif()
+
   list(APPEND tests "${prefix}${test}${suffix}")
 endforeach()
 

extras/CatchShardTests.cmake

@@ -0,0 +1,66 @@
+
+#              Copyright Catch2 Authors
+# Distributed under the Boost Software License, Version 1.0.
+#   (See accompanying file LICENSE_1_0.txt or copy at
+#        https://www.boost.org/LICENSE_1_0.txt)
+
+# SPDX-License-Identifier: BSL-1.0
+
+# Supported optional args:
+#  * SHARD_COUNT - number of shards to split target's tests into
+#  * REPORTER    - reporter spec to use for tests
+#  * TEST_SPEC   - test spec used for filtering tests
+function(catch_add_sharded_tests TARGET)
+  if (${CMAKE_VERSION} VERSION_LESS "3.10.0")
+    message(FATAL_ERROR "add_sharded_catch_tests only supports CMake versions 3.10.0 and up")
+  endif()
+
+  cmake_parse_arguments(
+    ""
+    ""
+    "SHARD_COUNT;REPORTER;TEST_SPEC"
+    ""
+    ${ARGN}
+  )
+  
+  if (NOT DEFINED _SHARD_COUNT)
+    set(_SHARD_COUNT 2)
+  endif()
+
+  # Generate a unique name based on the extra arguments
+  string(SHA1 args_hash "${_TEST_SPEC} ${_EXTRA_ARGS} ${_REPORTER} ${_OUTPUT_DIR} ${_OUTPUT_PREFIX} ${_OUTPUT_SUFFIX} ${_SHARD_COUNT}")
+  string(SUBSTRING ${args_hash} 0 7 args_hash)
+
+  set(ctest_include_file "${CMAKE_CURRENT_BINARY_DIR}/${TARGET}-sharded-tests-include-${args_hash}.cmake")
+  set(ctest_tests_file "${CMAKE_CURRENT_BINARY_DIR}/${TARGET}-sharded-tests-impl-${args_hash}.cmake")
+
+  file(WRITE "${ctest_include_file}"
+    "if(EXISTS \"${ctest_tests_file}\")\n"
+    "  include(\"${ctest_tests_file}\")\n"
+    "else()\n"
+    "  add_test(${TARGET}_NOT_BUILT-${args_hash} ${TARGET}_NOT_BUILT-${args_hash})\n"
+    "endif()\n"
+  )
+
+  set_property(DIRECTORY
+    APPEND PROPERTY TEST_INCLUDE_FILES "${ctest_include_file}"
+  )
+
+  set(shard_impl_script_file "${CMAKE_CURRENT_LIST_DIR}/CatchShardTestsImpl.cmake")
+
+  add_custom_command(
+    TARGET ${TARGET} POST_BUILD
+    BYPRODUCTS "${ctest_tests_file}"
+    COMMAND "${CMAKE_COMMAND}"
+            -D "TARGET_NAME=${TARGET}"
+            -D "TEST_BINARY=$<TARGET_FILE:${TARGET}>"
+            -D "CTEST_FILE=${ctest_tests_file}"
+            -D "SHARD_COUNT=${_SHARD_COUNT}"
+            -D "REPORTER_SPEC=${_REPORTER}"
+            -D "TEST_SPEC=${_TEST_SPEC}"
+            -P "${shard_impl_script_file}"
+    VERBATIM
+  )
+
+
+endfunction()

extras/CatchShardTestsImpl.cmake

@@ -0,0 +1,52 @@
+
+#              Copyright Catch2 Authors
+# Distributed under the Boost Software License, Version 1.0.
+#   (See accompanying file LICENSE_1_0.txt or copy at
+#        https://www.boost.org/LICENSE_1_0.txt)
+
+# SPDX-License-Identifier: BSL-1.0
+
+# Indirection for CatchShardTests that allows us to delay the script
+# file generation until build time.
+
+# Expected args:
+#  * TEST_BINARY - full path to the test binary to run sharded
+#  * CTEST_FILE  - full path to ctest script file to write to
+#  * TARGET_NAME - name of the target to shard (used for test names)
+#  * SHARD_COUNT - number of shards to split the binary into
+# Optional args:
+#  * REPORTER_SPEC - reporter specs to be passed down to the binary
+#  * TEST_SPEC     - test spec to pass down to the test binary
+
+if(NOT EXISTS "${TEST_BINARY}")
+  message(FATAL_ERROR
+    "Specified test binary '${TEST_BINARY}' does not exist"
+  )
+endif()
+
+set(other_args "")
+if (TEST_SPEC)
+  set(other_args "${other_args} ${TEST_SPEC}")
+endif()
+if (REPORTER_SPEC)
+  set(other_args "${other_args} --reporter ${REPORTER_SPEC}")
+endif()
+
+# foreach RANGE in cmake is inclusive of the end, so we have to adjust it
+math(EXPR adjusted_shard_count "${SHARD_COUNT} - 1")
+
+file(WRITE "${CTEST_FILE}"
+  "string(RANDOM LENGTH 8 ALPHABET \"0123456789abcdef\" rng_seed)\n"
+  "\n"
+  "foreach(shard_idx RANGE ${adjusted_shard_count})\n"
+  "  add_test(${TARGET_NAME}-shard-" [[${shard_idx}]] "/${adjusted_shard_count}\n"
+  "    ${TEST_BINARY}"
+  " --shard-index " [[${shard_idx}]]
+  " --shard-count ${SHARD_COUNT}"
+  " --rng-seed " [[0x${rng_seed}]]
+  " --order rand"
+  "${other_args}"
+  "\n"
+  "  )\n"
+  "endforeach()\n"
+)

src/CMakeLists.txt

@@ -1,4 +1,11 @@
-include(MiscFunctions)
+include(CatchMiscFunctions)
+
+# CMake derives a Visual Studio project GUID from the file path but can be overridden via a property
+# (see https://gitlab.kitware.com/cmake/cmake/-/commit/c85367f4).  Using a non-constant GUID
+# can cause problems if other projects/repos want to reference the vcxproj file,
+# so we force a constant GUID here.
+set(Catch2_GUID_CMAKE "8d538cbe-01bf-4a2e-a98a-6c368fdf13d7" CACHE INTERNAL "Project GUID")
+set(Catch2WithMain_GUID_CMAKE "8bd3552a-2cfb-4a59-ab15-2031b97ada1e" CACHE INTERNAL "Project GUID")
 
 # Please keep these ordered alphabetically
 set(BENCHMARK_HEADERS
@@ -24,13 +31,17 @@ set(BENCHMARK_HEADERS
     ${SOURCES_DIR}/benchmark/detail/catch_timing.hpp
 )
 set(BENCHMARK_SOURCES
-    ${SOURCES_DIR}/benchmark/internal/catch_benchmark_combined_tu.cpp
+    ${SOURCES_DIR}/benchmark/catch_chronometer.cpp
+    ${SOURCES_DIR}/benchmark/detail/catch_benchmark_function.cpp
+    ${SOURCES_DIR}/benchmark/detail/catch_run_for_at_least.cpp
     ${SOURCES_DIR}/benchmark/detail/catch_stats.cpp
 )
 
 SOURCE_GROUP("benchmark" FILES ${BENCHMARK_HEADERS} ${BENCHMARK_SOURCES})
 
 set(INTERNAL_HEADERS
+   "${CMAKE_BINARY_DIR}/generated-includes/catch2/catch_user_config.hpp"
+   "${SOURCES_DIR}/catch_user_config.hpp.in"
     ${SOURCES_DIR}/catch_all.hpp
     ${SOURCES_DIR}/matchers/catch_matchers_all.hpp
     ${SOURCES_DIR}/generators/catch_generators_all.hpp
@@ -67,6 +78,7 @@ set(INTERNAL_HEADERS
     ${SOURCES_DIR}/internal/catch_exception_translator_registry.hpp
     ${SOURCES_DIR}/internal/catch_fatal_condition_handler.hpp
     ${SOURCES_DIR}/internal/catch_floating_point_helpers.hpp
+    ${SOURCES_DIR}/internal/catch_istream.hpp
     ${SOURCES_DIR}/internal/catch_unique_name.hpp
     ${SOURCES_DIR}/internal/catch_sharding.hpp
     ${SOURCES_DIR}/generators/catch_generator_exception.hpp
@@ -107,18 +119,20 @@ set(INTERNAL_HEADERS
     ${SOURCES_DIR}/internal/catch_platform.hpp
     ${SOURCES_DIR}/internal/catch_polyfills.hpp
     ${SOURCES_DIR}/internal/catch_preprocessor.hpp
+    ${SOURCES_DIR}/internal/catch_preprocessor_remove_parens.hpp
     ${SOURCES_DIR}/internal/catch_random_number_generator.hpp
     ${SOURCES_DIR}/internal/catch_random_seed_generation.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_registrars.hpp
     ${SOURCES_DIR}/internal/catch_reporter_registry.hpp
+    ${SOURCES_DIR}/internal/catch_reporter_spec_parser.hpp
     ${SOURCES_DIR}/internal/catch_result_type.hpp
     ${SOURCES_DIR}/internal/catch_run_context.hpp
     ${SOURCES_DIR}/internal/catch_section.hpp
+    ${SOURCES_DIR}/internal/catch_stdstreams.hpp
     ${SOURCES_DIR}/catch_section_info.hpp
     ${SOURCES_DIR}/catch_session.hpp
     ${SOURCES_DIR}/internal/catch_singletons.hpp
     ${SOURCES_DIR}/internal/catch_startup_exception_registry.hpp
-    ${SOURCES_DIR}/internal/catch_stream.hpp
+    ${SOURCES_DIR}/internal/catch_reusable_string_stream.hpp
     ${SOURCES_DIR}/internal/catch_stream_end_stop.hpp
     ${SOURCES_DIR}/internal/catch_string_manip.hpp
     ${SOURCES_DIR}/internal/catch_stringref.hpp
@@ -148,12 +162,12 @@ set(INTERNAL_HEADERS
     ${SOURCES_DIR}/internal/catch_wildcard_pattern.hpp
     ${SOURCES_DIR}/internal/catch_windows_h_proxy.hpp
     ${SOURCES_DIR}/internal/catch_xmlwriter.hpp
+    ${SOURCES_DIR}/internal/catch_test_case_info_hasher.hpp
 )
 set(IMPL_SOURCES
     ${SOURCES_DIR}/catch_approx.cpp
     ${SOURCES_DIR}/internal/catch_assertion_handler.cpp
     ${SOURCES_DIR}/catch_assertion_result.cpp
-    ${SOURCES_DIR}/matchers/internal/catch_matchers_combined_tu.cpp
     ${SOURCES_DIR}/internal/catch_clara.cpp
     ${SOURCES_DIR}/internal/catch_commandline.cpp
     ${SOURCES_DIR}/internal/catch_source_line_info.cpp
@@ -168,26 +182,28 @@ set(IMPL_SOURCES
     ${SOURCES_DIR}/internal/catch_exception_translator_registry.cpp
     ${SOURCES_DIR}/internal/catch_fatal_condition_handler.cpp
     ${SOURCES_DIR}/internal/catch_floating_point_helpers.cpp
-    ${SOURCES_DIR}/generators/internal/catch_generators_combined_tu.cpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_combined_tu.cpp
+    ${SOURCES_DIR}/internal/catch_istream.cpp
+    ${SOURCES_DIR}/interfaces/catch_interfaces_generatortracker.cpp
     ${SOURCES_DIR}/interfaces/catch_interfaces_reporter.cpp
     ${SOURCES_DIR}/internal/catch_list.cpp
     ${SOURCES_DIR}/matchers/catch_matchers_floating_point.cpp
+    ${SOURCES_DIR}/matchers/catch_matchers_quantifiers.cpp
     ${SOURCES_DIR}/matchers/catch_matchers_string.cpp
     ${SOURCES_DIR}/matchers/catch_matchers_templated.cpp
     ${SOURCES_DIR}/catch_message.cpp
     ${SOURCES_DIR}/internal/catch_output_redirect.cpp
     ${SOURCES_DIR}/catch_registry_hub.cpp
-    ${SOURCES_DIR}/internal/catch_combined_tu.cpp
     ${SOURCES_DIR}/internal/catch_random_number_generator.cpp
     ${SOURCES_DIR}/internal/catch_random_seed_generation.cpp
     ${SOURCES_DIR}/internal/catch_reporter_registry.cpp
+    ${SOURCES_DIR}/internal/catch_reporter_spec_parser.cpp
     ${SOURCES_DIR}/internal/catch_result_type.cpp
     ${SOURCES_DIR}/internal/catch_run_context.cpp
     ${SOURCES_DIR}/internal/catch_section.cpp
+    ${SOURCES_DIR}/internal/catch_stdstreams.cpp
     ${SOURCES_DIR}/catch_session.cpp
     ${SOURCES_DIR}/internal/catch_singletons.cpp
-    ${SOURCES_DIR}/internal/catch_stream.cpp
+    ${SOURCES_DIR}/internal/catch_reusable_string_stream.cpp
     ${SOURCES_DIR}/internal/catch_stringref.cpp
     ${SOURCES_DIR}/internal/catch_string_manip.cpp
     ${SOURCES_DIR}/internal/catch_tag_alias_registry.cpp
@@ -204,6 +220,31 @@ set(IMPL_SOURCES
     ${SOURCES_DIR}/catch_version.cpp
     ${SOURCES_DIR}/internal/catch_wildcard_pattern.cpp
     ${SOURCES_DIR}/internal/catch_xmlwriter.cpp
+    ${SOURCES_DIR}/internal/catch_test_case_info_hasher.cpp
+    ${SOURCES_DIR}/generators/catch_generators_random.cpp
+    ${SOURCES_DIR}/generators/catch_generator_exception.cpp
+    ${SOURCES_DIR}/generators/catch_generators.cpp
+    ${SOURCES_DIR}/matchers/catch_matchers.cpp
+    ${SOURCES_DIR}/matchers/catch_matchers_container_properties.cpp
+    ${SOURCES_DIR}/matchers/catch_matchers_exception.cpp
+    ${SOURCES_DIR}/matchers/catch_matchers_predicate.cpp
+    ${SOURCES_DIR}/matchers/internal/catch_matchers_impl.cpp
+    ${SOURCES_DIR}/catch_tag_alias_autoregistrar.cpp
+    ${SOURCES_DIR}/internal/catch_decomposer.cpp
+    ${SOURCES_DIR}/internal/catch_errno_guard.cpp
+    ${SOURCES_DIR}/internal/catch_lazy_expr.cpp
+    ${SOURCES_DIR}/internal/catch_leak_detector.cpp
+    ${SOURCES_DIR}/internal/catch_message_info.cpp
+    ${SOURCES_DIR}/internal/catch_polyfills.cpp
+    ${SOURCES_DIR}/internal/catch_startup_exception_registry.cpp
+    ${SOURCES_DIR}/internal/catch_uncaught_exceptions.cpp
+    ${SOURCES_DIR}/interfaces/catch_interfaces_capture.cpp
+    ${SOURCES_DIR}/interfaces/catch_interfaces_config.cpp
+    ${SOURCES_DIR}/interfaces/catch_interfaces_exception.cpp
+    ${SOURCES_DIR}/interfaces/catch_interfaces_registry_hub.cpp
+    ${SOURCES_DIR}/interfaces/catch_interfaces_reporter_factory.cpp
+    ${SOURCES_DIR}/interfaces/catch_interfaces_reporter_registry.cpp
+    ${SOURCES_DIR}/interfaces/catch_interfaces_testcase.cpp
 )
 set(INTERNAL_FILES ${IMPL_SOURCES} ${INTERNAL_HEADERS})
 
@@ -211,13 +252,15 @@ set(INTERNAL_FILES ${IMPL_SOURCES} ${INTERNAL_HEADERS})
 set(REPORTER_HEADERS
     ${SOURCES_DIR}/reporters/catch_reporters_all.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_automake.hpp
+    ${SOURCES_DIR}/reporters/catch_reporter_common_base.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_compact.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_console.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_cumulative_base.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_event_listener.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_helpers.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_junit.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_listening.hpp
+    ${SOURCES_DIR}/reporters/catch_reporter_multi.hpp
+    ${SOURCES_DIR}/reporters/catch_reporter_registrars.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_sonarqube.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_streaming_base.hpp
     ${SOURCES_DIR}/reporters/catch_reporter_tap.hpp
@@ -226,12 +269,15 @@ set(REPORTER_HEADERS
 )
 set(REPORTER_SOURCES
     ${SOURCES_DIR}/reporters/catch_reporter_automake.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_combined_tu.cpp
+    ${SOURCES_DIR}/reporters/catch_reporter_common_base.cpp
     ${SOURCES_DIR}/reporters/catch_reporter_compact.cpp
     ${SOURCES_DIR}/reporters/catch_reporter_console.cpp
     ${SOURCES_DIR}/reporters/catch_reporter_cumulative_base.cpp
+    ${SOURCES_DIR}/reporters/catch_reporter_event_listener.cpp
+    ${SOURCES_DIR}/reporters/catch_reporter_helpers.cpp
     ${SOURCES_DIR}/reporters/catch_reporter_junit.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_listening.cpp
+    ${SOURCES_DIR}/reporters/catch_reporter_multi.cpp
+    ${SOURCES_DIR}/reporters/catch_reporter_registrars.cpp
     ${SOURCES_DIR}/reporters/catch_reporter_sonarqube.cpp
     ${SOURCES_DIR}/reporters/catch_reporter_streaming_base.cpp
     ${SOURCES_DIR}/reporters/catch_reporter_tap.cpp
@@ -240,9 +286,7 @@ set(REPORTER_SOURCES
 )
 set(REPORTER_FILES ${REPORTER_HEADERS} ${REPORTER_SOURCES})
 
-# Fixme: STATIC because for dynamic, we would need to handle visibility
-# and I don't want to do the annotations right now
-add_library(Catch2 STATIC
+add_library(Catch2
   ${REPORTER_FILES}
   ${INTERNAL_FILES}
   ${BENCHMARK_HEADERS}
@@ -282,14 +326,20 @@ target_compile_features(Catch2
     cxx_variadic_macros
 )
 
+configure_file(
+  "${SOURCES_DIR}/catch_user_config.hpp.in"
+  "${CMAKE_BINARY_DIR}/generated-includes/catch2/catch_user_config.hpp"
+)
+
 target_include_directories(Catch2
   PUBLIC
     $<BUILD_INTERFACE:${SOURCES_DIR}/..>
+    $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/generated-includes>
     $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 
 
-add_library(Catch2WithMain STATIC
+add_library(Catch2WithMain
     ${SOURCES_DIR}/internal/catch_main.cpp
 )
 add_build_reproducibility_settings(Catch2WithMain)
@@ -323,7 +373,15 @@ if (NOT_SUBPROJECT)
         ${CATCH_CMAKE_CONFIG_DESTINATION}
     )
     # Install the headers
-    install(DIRECTORY ${SOURCES_DIR} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} FILES_MATCHING PATTERN "*.h*")
+    install(
+      DIRECTORY
+        "${SOURCES_DIR}"
+        "${CMAKE_BINARY_DIR}/generated-includes/catch2" # Also install the generated header
+      DESTINATION
+        "${CMAKE_INSTALL_INCLUDEDIR}"
+      FILES_MATCHING
+        PATTERN "*.hpp"
+    )
 endif()
 
 # Some tests require a full recompilation of Catch2 lib with different
@@ -342,6 +400,7 @@ if (CATCH_BUILD_EXAMPLES OR CATCH_BUILD_EXTRA_TESTS)
     target_include_directories(Catch2_buildall_interface
       INTERFACE
         $<BUILD_INTERFACE:${SOURCES_DIR}/..>
+        $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/generated-includes>
         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
     )
     target_compile_features(Catch2_buildall_interface
@@ -371,3 +430,27 @@ endif()
 
 list(APPEND CATCH_WARNING_TARGETS Catch2 Catch2WithMain)
 set(CATCH_WARNING_TARGETS ${CATCH_WARNING_TARGETS} PARENT_SCOPE)
+
+
+# We still do not support building dynamic library with hidden visibility
+# so we want to check & warn users if they do this. However, we won't abort
+# the configuration step so that we don't have to also provide an override.
+if (BUILD_SHARED_LIBS)
+    if (MSVC)
+        set_target_properties(Catch2 Catch2WithMain
+          PROPERTIES
+            WINDOWS_EXPORT_ALL_SYMBOLS ON
+        )
+    endif()
+
+    get_target_property(_VisPreset Catch2 CXX_VISIBILITY_PRESET)
+    if (NOT MSVC AND _VisPreset STREQUAL "hidden")
+        set_target_properties(Catch2 Catch2WithMain
+          PROPERTIES
+            CXX_VISIBILITY_PRESET "default"
+            VISIBILITY_INLINES_HIDDEN OFF
+        )
+        message(WARNING "Setting Catch2's visibility to default."
+                        " Hidden visibility is not supported.")
+    endif()
+endif()

src/catch2/benchmark/catch_benchmark.hpp

@@ -95,8 +95,11 @@ namespace Catch {
             // sets lambda to be used in fun *and* executes benchmark!
             template <typename Fun, std::enable_if_t<!Detail::is_related<Fun, Benchmark>::value, int> = 0>
                 Benchmark & operator=(Fun func) {
-                fun = Detail::BenchmarkFunction(func);
-                run();
+                auto const* cfg = getCurrentContext().getConfig();
+                if (!cfg->skipBenchmarks()) {
+                    fun = Detail::BenchmarkFunction(func);
+                    run();
+                }
                 return *this;
             }
 

src/catch2/benchmark/catch_chronometer.cpp

@@ -0,0 +1,17 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/benchmark/catch_chronometer.hpp>
+
+namespace Catch {
+    namespace Benchmark {
+        namespace Detail {
+            ChronometerConcept::~ChronometerConcept() = default;
+        } // namespace Detail
+    } // namespace Benchmark
+} // namespace Catch

src/catch2/benchmark/catch_constructor.hpp

@@ -20,9 +20,7 @@ namespace Catch {
             template <typename T, bool Destruct>
             struct ObjectStorage
             {
-                using TStorage = std::aligned_storage_t<sizeof(T), std::alignment_of<T>::value>;
-
-                ObjectStorage() : data() {}
+                ObjectStorage() = default;
 
                 ObjectStorage(const ObjectStorage& other)
                 {
@@ -31,7 +29,7 @@ namespace Catch {
 
                 ObjectStorage(ObjectStorage&& other)
                 {
-                    new(&data) T(CATCH_MOVE(other.stored_object()));
+                    new(data) T(CATCH_MOVE(other.stored_object()));
                 }
 
                 ~ObjectStorage() { destruct_on_exit<T>(); }
@@ -39,7 +37,7 @@ namespace Catch {
                 template <typename... Args>
                 void construct(Args&&... args)
                 {
-                    new (&data) T(CATCH_FORWARD(args)...);
+                    new (data) T(CATCH_FORWARD(args)...);
                 }
 
                 template <bool AllowManualDestruction = !Destruct>
@@ -51,21 +49,21 @@ namespace Catch {
             private:
                 // If this is a constructor benchmark, destruct the underlying object
                 template <typename U>
-                void destruct_on_exit(std::enable_if_t<Destruct, U>* = 0) { destruct<true>(); }
+                void destruct_on_exit(std::enable_if_t<Destruct, U>* = nullptr) { destruct<true>(); }
                 // Otherwise, don't
                 template <typename U>
-                void destruct_on_exit(std::enable_if_t<!Destruct, U>* = 0) { }
+                void destruct_on_exit(std::enable_if_t<!Destruct, U>* = nullptr) { }
 
                 T& stored_object() {
-                    return *static_cast<T*>(static_cast<void*>(&data));
+                    return *static_cast<T*>(static_cast<void*>(data));
                 }
 
                 T const& stored_object() const {
-                    return *static_cast<T*>(static_cast<void*>(&data));
+                    return *static_cast<T const*>(static_cast<void const*>(data));
                 }
 
 
-                TStorage data;
+                alignas( T ) unsigned char data[sizeof( T )]{};
             };
         } // namespace Detail
 

src/catch2/benchmark/detail/catch_benchmark_function.cpp

@@ -0,0 +1,17 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/benchmark/detail/catch_benchmark_function.hpp>
+
+namespace Catch {
+    namespace Benchmark {
+        namespace Detail {
+            BenchmarkFunction::callable::~callable() = default;
+        } // namespace Detail
+    } // namespace Benchmark
+} // namespace Catch

src/catch2/benchmark/detail/catch_run_for_at_least.cpp

@@ -0,0 +1,30 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/benchmark/detail/catch_run_for_at_least.hpp>
+#include <exception>
+#include <catch2/internal/catch_enforce.hpp>
+
+namespace Catch {
+    namespace Benchmark {
+        namespace Detail {
+            struct optimized_away_error : std::exception {
+                const char* what() const noexcept override;
+            };
+
+            const char* optimized_away_error::what() const noexcept {
+                return "could not measure benchmark, maybe it was optimized away";
+            }
+
+            void throw_optimized_away_error() {
+                Catch::throw_exception(optimized_away_error{});
+            }
+
+        } // namespace Detail
+    } // namespace Benchmark
+} // namespace Catch

src/catch2/benchmark/detail/catch_stats.cpp

@@ -12,6 +12,7 @@
 #include <catch2/internal/catch_compiler_capabilities.hpp>
 
 #include <cassert>
+#include <cstddef>
 #include <iterator>
 #include <random>
 
@@ -119,11 +120,15 @@ using Catch::Benchmark::Detail::sample;
 
     double standard_deviation(std::vector<double>::iterator first, std::vector<double>::iterator last) {
         auto m = Catch::Benchmark::Detail::mean(first, last);
-        double variance = std::accumulate(first, last, 0., [m](double a, double b) {
-            double diff = b - m;
-            return a + diff * diff;
-            }) / (last - first);
-            return std::sqrt(variance);
+        double variance = std::accumulate( first,
+                                           last,
+                                           0.,
+                                           [m]( double a, double b ) {
+                                               double diff = b - m;
+                                               return a + diff * diff;
+                                           } ) /
+                          ( last - first );
+        return std::sqrt( variance );
     }
 
 }
@@ -132,6 +137,15 @@ namespace Catch {
     namespace Benchmark {
         namespace Detail {
 
+#if defined( __GNUC__ ) || defined( __clang__ )
+#    pragma GCC diagnostic push
+#    pragma GCC diagnostic ignored "-Wfloat-equal"
+#endif
+            bool directCompare( double lhs, double rhs ) { return lhs == rhs; }
+#if defined( __GNUC__ ) || defined( __clang__ )
+#    pragma GCC diagnostic pop
+#endif
+
             double weighted_average_quantile(int k, int q, std::vector<double>::iterator first, std::vector<double>::iterator last) {
                 auto count = last - first;
                 double idx = (count - 1) * k / static_cast<double>(q);
@@ -139,7 +153,9 @@ namespace Catch {
                 double g = idx - j;
                 std::nth_element(first, first + j, last);
                 auto xj = first[j];
-                if (g == 0) return xj;
+                if ( directCompare( g, 0 ) ) {
+                    return xj;
+                }
 
                 auto xj1 = *std::min_element(first + (j + 1), last);
                 return xj + g * (xj1 - xj);

src/catch2/benchmark/detail/catch_stats.hpp

@@ -24,6 +24,10 @@ namespace Catch {
         namespace Detail {
             using sample = std::vector<double>;
 
+            // Used when we know we want == comparison of two doubles
+            // to centralize warning suppression
+            bool directCompare( double lhs, double rhs );
+
             double weighted_average_quantile(int k, int q, std::vector<double>::iterator first, std::vector<double>::iterator last);
 
             template <typename Iterator>
@@ -54,7 +58,7 @@ namespace Catch {
             double mean(Iterator first, Iterator last) {
                 auto count = last - first;
                 double sum = std::accumulate(first, last, 0.);
-                return sum / count;
+                return sum / static_cast<double>(count);
             }
 
             template <typename Estimator, typename Iterator>
@@ -100,22 +104,25 @@ namespace Catch {
                 });
 
                 double accel = sum_cubes / (6 * std::pow(sum_squares, 1.5));
-                int n = static_cast<int>(resample.size());
+                long n = static_cast<long>(resample.size());
                 double prob_n = std::count_if(resample.begin(), resample.end(), [point](double x) { return x < point; }) / static_cast<double>(n);
                 // degenerate case with uniform samples
-                if (prob_n == 0) return { point, point, point, confidence_level };
+                if ( directCompare( prob_n, 0. ) ) {
+                    return { point, point, point, confidence_level };
+                }
 
                 double bias = normal_quantile(prob_n);
                 double z1 = normal_quantile((1. - confidence_level) / 2.);
 
-                auto cumn = [n](double x) -> int {
-                    return std::lround(normal_cdf(x) * n); };
+                auto cumn = [n]( double x ) -> long {
+                    return std::lround( normal_cdf( x ) * static_cast<double>(n) );
+                };
                 auto a = [bias, accel](double b) { return bias + b / (1. - accel * b); };
                 double b1 = bias + z1;
                 double b2 = bias - z1;
                 double a1 = a(b1);
                 double a2 = a(b2);
-                auto lo = static_cast<size_t>((std::max)(cumn(a1), 0));
+                auto lo = static_cast<size_t>((std::max)(cumn(a1), 0l));
                 auto hi = static_cast<size_t>((std::min)(cumn(a2), n - 1));
 
                 return { point, resample[lo], resample[hi], confidence_level };

src/catch2/benchmark/internal/catch_benchmark_combined_tu.cpp

@@ -1,75 +0,0 @@
-
-//              Copyright Catch2 Authors
-// Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
-//        https://www.boost.org/LICENSE_1_0.txt)
-
-// SPDX-License-Identifier: BSL-1.0
-/** \file
- * This is a special TU that combines what would otherwise be a very
- * small benchmarking-related TUs into one bigger TU.
- *
- * The reason for this is compilation performance improvements by
- * avoiding reparsing headers for many small TUs, instead having this
- * one TU include bit more, but having it all parsed only once.
- *
- * To avoid heavy-tail problem with compilation times, each "subpart"
- * of Catch2 has its own combined TU like this.
- */
-
-////////////////////////////////////////////
-// vvv formerly catch_chronometer.cpp vvv //
-////////////////////////////////////////////
-
-#include <catch2/benchmark/catch_chronometer.hpp>
-
-namespace Catch {
-    namespace Benchmark {
-        namespace Detail {
-            ChronometerConcept::~ChronometerConcept() = default;
-        } // namespace Detail
-    } // namespace Benchmark
-} // namespace Catch
-
-
-///////////////////////////////////////////////////
-// vvv formerly catch_benchmark_function.cpp vvv //
-///////////////////////////////////////////////////
-
-#include <catch2/benchmark/detail/catch_benchmark_function.hpp>
-
-namespace Catch {
-    namespace Benchmark {
-        namespace Detail {
-            BenchmarkFunction::callable::~callable() = default;
-            } // namespace Detail
-    } // namespace Benchmark
-} // namespace Catch
-
-
-/////////////////////////////////////////////////
-// vvv formerly catch_run_for_at_least.cpp vvv //
-/////////////////////////////////////////////////
-
-#include <catch2/benchmark/detail/catch_run_for_at_least.hpp>
-#include <exception>
-#include <catch2/internal/catch_enforce.hpp>
-
-namespace Catch {
-    namespace Benchmark {
-        namespace Detail {
-            struct optimized_away_error : std::exception {
-                const char* what() const noexcept override;
-            };
-
-            const char* optimized_away_error::what() const noexcept {
-                return "could not measure benchmark, maybe it was optimized away";
-            }
-
-            void throw_optimized_away_error() {
-                Catch::throw_exception(optimized_away_error{});
-            }
-
-        } // namespace Detail
-    } // namespace Benchmark
-} // namespace Catch

src/catch2/catch_all.hpp

@@ -67,6 +67,7 @@
 #include <catch2/internal/catch_exception_translator_registry.hpp>
 #include <catch2/internal/catch_fatal_condition_handler.hpp>
 #include <catch2/internal/catch_floating_point_helpers.hpp>
+#include <catch2/internal/catch_istream.hpp>
 #include <catch2/internal/catch_lazy_expr.hpp>
 #include <catch2/internal/catch_leak_detector.hpp>
 #include <catch2/internal/catch_list.hpp>
@@ -79,22 +80,26 @@
 #include <catch2/internal/catch_platform.hpp>
 #include <catch2/internal/catch_polyfills.hpp>
 #include <catch2/internal/catch_preprocessor.hpp>
+#include <catch2/internal/catch_preprocessor_remove_parens.hpp>
 #include <catch2/internal/catch_random_number_generator.hpp>
 #include <catch2/internal/catch_random_seed_generation.hpp>
 #include <catch2/internal/catch_reporter_registry.hpp>
+#include <catch2/internal/catch_reporter_spec_parser.hpp>
 #include <catch2/internal/catch_result_type.hpp>
+#include <catch2/internal/catch_reusable_string_stream.hpp>
 #include <catch2/internal/catch_run_context.hpp>
 #include <catch2/internal/catch_section.hpp>
 #include <catch2/internal/catch_sharding.hpp>
 #include <catch2/internal/catch_singletons.hpp>
 #include <catch2/internal/catch_source_line_info.hpp>
 #include <catch2/internal/catch_startup_exception_registry.hpp>
-#include <catch2/internal/catch_stream.hpp>
+#include <catch2/internal/catch_stdstreams.hpp>
 #include <catch2/internal/catch_stream_end_stop.hpp>
 #include <catch2/internal/catch_string_manip.hpp>
 #include <catch2/internal/catch_stringref.hpp>
 #include <catch2/internal/catch_tag_alias_registry.hpp>
 #include <catch2/internal/catch_template_test_registry.hpp>
+#include <catch2/internal/catch_test_case_info_hasher.hpp>
 #include <catch2/internal/catch_test_case_registry_impl.hpp>
 #include <catch2/internal/catch_test_case_tracker.hpp>
 #include <catch2/internal/catch_test_failure_exception.hpp>

src/catch2/catch_approx.cpp

@@ -7,6 +7,7 @@
 // SPDX-License-Identifier: BSL-1.0
 #include <catch2/catch_approx.hpp>
 #include <catch2/internal/catch_enforce.hpp>
+#include <catch2/internal/catch_reusable_string_stream.hpp>
 
 #include <cmath>
 #include <limits>

src/catch2/catch_approx.hpp

@@ -86,14 +86,14 @@ namespace Catch {
 
         template <typename T, typename = std::enable_if_t<std::is_constructible<double, T>::value>>
         Approx& epsilon( T const& newEpsilon ) {
-            double epsilonAsDouble = static_cast<double>(newEpsilon);
+            const auto epsilonAsDouble = static_cast<double>(newEpsilon);
             setEpsilon(epsilonAsDouble);
             return *this;
         }
 
         template <typename T, typename = std::enable_if_t<std::is_constructible<double, T>::value>>
         Approx& margin( T const& newMargin ) {
-            double marginAsDouble = static_cast<double>(newMargin);
+            const auto marginAsDouble = static_cast<double>(newMargin);
             setMargin(marginAsDouble);
             return *this;
         }

src/catch2/catch_assertion_result.cpp

@@ -6,7 +6,7 @@
 
 // SPDX-License-Identifier: BSL-1.0
 #include <catch2/catch_assertion_result.hpp>
-#include <catch2/internal/catch_stream.hpp>
+#include <catch2/internal/catch_reusable_string_stream.hpp>
 
 namespace Catch {
 

src/catch2/catch_config.cpp

@@ -6,46 +6,47 @@
 
 // SPDX-License-Identifier: BSL-1.0
 #include <catch2/catch_config.hpp>
+#include <catch2/catch_user_config.hpp>
 #include <catch2/internal/catch_enforce.hpp>
-#include <catch2/internal/catch_stream.hpp>
 #include <catch2/internal/catch_stringref.hpp>
 #include <catch2/internal/catch_string_manip.hpp>
 #include <catch2/internal/catch_test_spec_parser.hpp>
 #include <catch2/interfaces/catch_interfaces_tag_alias_registry.hpp>
 
-#include <ostream>
+namespace {
+    bool provideBazelReporterOutput() {
+#ifdef CATCH_CONFIG_BAZEL_SUPPORT
+        return true;
+#else
+
+#    if defined( _MSC_VER )
+        // On Windows getenv throws a warning as there is no input validation,
+        // since the switch is hardcoded, this should not be an issue.
+#        pragma warning( push )
+#        pragma warning( disable : 4996 )
+#    endif
+
+        return std::getenv( "BAZEL_TEST" ) != nullptr;
+
+#    if defined( _MSC_VER )
+#        pragma warning( pop )
+#    endif
+#endif
+    }
+}
 
 namespace Catch {
-    namespace Detail {
-        namespace {
-            class RDBufStream : public IStream {
-                mutable std::ostream m_os;
 
-            public:
-                //! The streambuf `sb` must outlive the constructed object.
-                RDBufStream( std::streambuf* sb ): m_os( sb ) {}
-                ~RDBufStream() override = default;
-
-            public: // IStream
-                std::ostream& stream() const override { return m_os; }
-            };
-        } // unnamed namespace
-    }     // namespace Detail
-
-    std::ostream& operator<<( std::ostream& os,
-                              ConfigData::ReporterAndFile const& reporter ) {
-        os << "{ " << reporter.reporterName << ", ";
-        if ( reporter.outputFileName ) {
-            os << *reporter.outputFileName;
-        } else {
-            os << "<default-output>";
-        }
-        return os << " }";
+    bool operator==( ProcessedReporterSpec const& lhs,
+                     ProcessedReporterSpec const& rhs ) {
+        return lhs.name == rhs.name &&
+               lhs.outputFilename == rhs.outputFilename &&
+               lhs.colourMode == rhs.colourMode &&
+               lhs.customOptions == rhs.customOptions;
     }
 
     Config::Config( ConfigData const& data ):
-        m_data( data ),
-        m_defaultStream( openStream( data.defaultOutputFilename ) ) {
+        m_data( data ) {
         // We need to trim filter specs to avoid trouble with superfluous
         // whitespace (esp. important for bdd macros, as those are manually
         // aligned with whitespace).
@@ -57,6 +58,7 @@ namespace Catch {
             elem = trim(elem);
         }
 
+
         TestSpecParser parser(ITagAliasRegistry::get());
         if (!m_data.testsOrTags.empty()) {
             m_hasTestFilters = true;
@@ -66,15 +68,62 @@ namespace Catch {
         }
         m_testSpec = parser.testSpec();
 
-        m_reporterStreams.reserve( m_data.reporterSpecifications.size() );
-        for ( auto const& reporterAndFile : m_data.reporterSpecifications ) {
-            if ( reporterAndFile.outputFileName.none() ) {
-                m_reporterStreams.emplace_back( new Detail::RDBufStream(
-                    m_defaultStream->stream().rdbuf() ) );
-            } else {
-                m_reporterStreams.emplace_back(
-                    openStream( *reporterAndFile.outputFileName ) );
+
+        // Insert the default reporter if user hasn't asked for a specfic one
+        if ( m_data.reporterSpecifications.empty() ) {
+            m_data.reporterSpecifications.push_back( {
+#if defined( CATCH_CONFIG_DEFAULT_REPORTER )
+                CATCH_CONFIG_DEFAULT_REPORTER,
+#else
+                "console",
+#endif
+                {}, {}, {}
+            } );
+        }
+
+    if(provideBazelReporterOutput()){
+            // Register a JUnit reporter for Bazel. Bazel sets an environment
+            // variable with the path to XML output. If this file is written to
+            // during test, Bazel will not generate a default XML output.
+            // This allows the XML output file to contain higher level of detail
+            // than what is possible otherwise.
+#    if defined( _MSC_VER )
+            // On Windows getenv throws a warning as there is no input validation,
+            // since the key is hardcoded, this should not be an issue.
+#           pragma warning( push )
+#           pragma warning( disable : 4996 )
+#    endif
+            const auto bazelOutputFilePtr = std::getenv( "XML_OUTPUT_FILE" );
+#    if defined( _MSC_VER )
+#        pragma warning( pop )
+#    endif
+            if ( bazelOutputFilePtr != nullptr ) {
+                m_data.reporterSpecifications.push_back(
+                    { "junit", std::string( bazelOutputFilePtr ), {}, {} } );
             }
+    }
+
+
+        // We now fixup the reporter specs to handle default output spec,
+        // default colour spec, etc
+        bool defaultOutputUsed = false;
+        for ( auto const& reporterSpec : m_data.reporterSpecifications ) {
+            // We do the default-output check separately, while always
+            // using the default output below to make the code simpler
+            // and avoid superfluous copies.
+            if ( reporterSpec.outputFile().none() ) {
+                CATCH_ENFORCE( !defaultOutputUsed,
+                               "Internal error: cannot use default output for "
+                               "multiple reporters" );
+                defaultOutputUsed = true;
+            }
+
+            m_processedReporterSpecs.push_back( ProcessedReporterSpec{
+                reporterSpec.name(),
+                reporterSpec.outputFile() ? *reporterSpec.outputFile()
+                                          : data.defaultOutputFilename,
+                reporterSpec.colourMode().valueOr( data.defaultColourMode ),
+                reporterSpec.customOptions() } );
         }
     }
 
@@ -84,16 +133,18 @@ namespace Catch {
     bool Config::listTests() const          { return m_data.listTests; }
     bool Config::listTags() const           { return m_data.listTags; }
     bool Config::listReporters() const      { return m_data.listReporters; }
+    bool Config::listListeners() const      { return m_data.listListeners; }
 
     std::vector<std::string> const& Config::getTestsOrTags() const { return m_data.testsOrTags; }
     std::vector<std::string> const& Config::getSectionsToRun() const { return m_data.sectionsToRun; }
 
-    std::vector<ConfigData::ReporterAndFile> const& Config::getReportersAndOutputFiles() const {
+    std::vector<ReporterSpec> const& Config::getReporterSpecs() const {
         return m_data.reporterSpecifications;
     }
 
-    std::ostream& Config::getReporterOutputStream(std::size_t reporterIdx) const {
-        return m_reporterStreams.at(reporterIdx)->stream();
+    std::vector<ProcessedReporterSpec> const&
+    Config::getProcessedReporterSpecs() const {
+        return m_processedReporterSpecs;
     }
 
     TestSpec const& Config::testSpec() const { return m_testSpec; }
@@ -103,7 +154,6 @@ namespace Catch {
 
     // IConfig interface
     bool Config::allowThrows() const                   { return !m_data.noThrow; }
-    std::ostream& Config::defaultStream() const        { return m_defaultStream->stream(); }
     StringRef Config::name() const { return m_data.name.empty() ? m_data.processName : m_data.name; }
     bool Config::includeSuccessfulResults() const      { return m_data.showSuccessfulTests; }
     bool Config::warnAboutMissingAssertions() const {
@@ -119,20 +169,17 @@ namespace Catch {
     uint32_t Config::rngSeed() const                   { return m_data.rngSeed; }
     unsigned int Config::shardCount() const            { return m_data.shardCount; }
     unsigned int Config::shardIndex() const            { return m_data.shardIndex; }
-    UseColour Config::useColour() const                { return m_data.useColour; }
+    ColourMode Config::defaultColourMode() const       { return m_data.defaultColourMode; }
     bool Config::shouldDebugBreak() const              { return m_data.shouldDebugBreak; }
     int Config::abortAfter() const                     { return m_data.abortAfter; }
     bool Config::showInvisibles() const                { return m_data.showInvisibles; }
     Verbosity Config::verbosity() const                { return m_data.verbosity; }
 
+    bool Config::skipBenchmarks() const                           { return m_data.skipBenchmarks; }
     bool Config::benchmarkNoAnalysis() const                      { return m_data.benchmarkNoAnalysis; }
     unsigned int Config::benchmarkSamples() const                 { return m_data.benchmarkSamples; }
     double Config::benchmarkConfidenceInterval() const            { return m_data.benchmarkConfidenceInterval; }
     unsigned int Config::benchmarkResamples() const               { return m_data.benchmarkResamples; }
     std::chrono::milliseconds Config::benchmarkWarmupTime() const { return std::chrono::milliseconds(m_data.benchmarkWarmupTime); }
 
-    Detail::unique_ptr<IStream const> Config::openStream(std::string const& outputFileName) {
-        return Catch::makeStream(outputFileName);
-    }
-
 } // end namespace Catch

src/catch2/catch_config.hpp

@@ -12,32 +12,43 @@
 #include <catch2/interfaces/catch_interfaces_config.hpp>
 #include <catch2/internal/catch_unique_ptr.hpp>
 #include <catch2/internal/catch_optional.hpp>
+#include <catch2/internal/catch_stringref.hpp>
 #include <catch2/internal/catch_random_seed_generation.hpp>
+#include <catch2/internal/catch_reporter_spec_parser.hpp>
 
-#include <iosfwd>
-#include <vector>
+#include <chrono>
+#include <map>
 #include <string>
+#include <vector>
 
 namespace Catch {
 
-    struct IStream;
+    class IStream;
+
+    /**
+     * `ReporterSpec` but with the defaults filled in.
+     *
+     * Like `ReporterSpec`, the semantics are unchecked.
+     */
+    struct ProcessedReporterSpec {
+        std::string name;
+        std::string outputFilename;
+        ColourMode colourMode;
+        std::map<std::string, std::string> customOptions;
+        friend bool operator==( ProcessedReporterSpec const& lhs,
+                                ProcessedReporterSpec const& rhs );
+        friend bool operator!=( ProcessedReporterSpec const& lhs,
+                                ProcessedReporterSpec const& rhs ) {
+            return !( lhs == rhs );
+        }
+    };
 
     struct ConfigData {
-        struct ReporterAndFile {
-            std::string reporterName;
-
-            // If none, the output goes to the default output.
-            Optional<std::string> outputFileName;
-
-            friend bool operator==(ReporterAndFile const& lhs, ReporterAndFile const& rhs) {
-                return lhs.reporterName == rhs.reporterName && lhs.outputFileName == rhs.outputFileName;
-            }
-            friend std::ostream& operator<<(std::ostream &os, ReporterAndFile const& reporter);
-        };
 
         bool listTests = false;
         bool listTags = false;
         bool listReporters = false;
+        bool listListeners = false;
 
         bool showSuccessfulTests = false;
         bool shouldDebugBreak = false;
@@ -54,6 +65,7 @@ namespace Catch {
         unsigned int shardCount = 1;
         unsigned int shardIndex = 0;
 
+        bool skipBenchmarks = false;
         bool benchmarkNoAnalysis = false;
         unsigned int benchmarkSamples = 100;
         double benchmarkConfidenceInterval = 0.95;
@@ -65,21 +77,13 @@ namespace Catch {
         ShowDurations showDurations = ShowDurations::DefaultForReporter;
         double minDuration = -1;
         TestRunOrder runOrder = TestRunOrder::Declared;
-        UseColour useColour = UseColour::Auto;
+        ColourMode defaultColourMode = ColourMode::PlatformDefault;
         WaitForKeypress::When waitForKeypress = WaitForKeypress::Never;
 
         std::string defaultOutputFilename;
         std::string name;
         std::string processName;
-#ifndef CATCH_CONFIG_DEFAULT_REPORTER
-#define CATCH_CONFIG_DEFAULT_REPORTER "console"
-#endif
-        std::vector<ReporterAndFile> reporterSpecifications = {
-            {CATCH_CONFIG_DEFAULT_REPORTER, {}}
-        };
-        // Internal: used as parser state
-        bool _nonDefaultReporterSpecifications = false;
-#undef CATCH_CONFIG_DEFAULT_REPORTER
+        std::vector<ReporterSpec> reporterSpecifications;
 
         std::vector<std::string> testsOrTags;
         std::vector<std::string> sectionsToRun;
@@ -96,9 +100,11 @@ namespace Catch {
         bool listTests() const;
         bool listTags() const;
         bool listReporters() const;
+        bool listListeners() const;
 
-        std::vector<ConfigData::ReporterAndFile> const& getReportersAndOutputFiles() const;
-        std::ostream& getReporterOutputStream(std::size_t reporterIdx) const;
+        std::vector<ReporterSpec> const& getReporterSpecs() const;
+        std::vector<ProcessedReporterSpec> const&
+        getProcessedReporterSpecs() const;
 
         std::vector<std::string> const& getTestsOrTags() const override;
         std::vector<std::string> const& getSectionsToRun() const override;
@@ -110,7 +116,6 @@ namespace Catch {
 
         // IConfig interface
         bool allowThrows() const override;
-        std::ostream& defaultStream() const override;
         StringRef name() const override;
         bool includeSuccessfulResults() const override;
         bool warnAboutMissingAssertions() const override;
@@ -122,11 +127,12 @@ namespace Catch {
         uint32_t rngSeed() const override;
         unsigned int shardCount() const override;
         unsigned int shardIndex() const override;
-        UseColour useColour() const override;
+        ColourMode defaultColourMode() const override;
         bool shouldDebugBreak() const override;
         int abortAfter() const override;
         bool showInvisibles() const override;
         Verbosity verbosity() const override;
+        bool skipBenchmarks() const override;
         bool benchmarkNoAnalysis() const override;
         unsigned int benchmarkSamples() const override;
         double benchmarkConfidenceInterval() const override;
@@ -134,11 +140,8 @@ namespace Catch {
         std::chrono::milliseconds benchmarkWarmupTime() const override;
 
     private:
-        Detail::unique_ptr<IStream const> openStream(std::string const& outputFileName);
         ConfigData m_data;
-
-        Detail::unique_ptr<IStream const> m_defaultStream;
-        std::vector<Detail::unique_ptr<IStream const>> m_reporterStreams;
+        std::vector<ProcessedReporterSpec> m_processedReporterSpecs;
         TestSpec m_testSpec;
         bool m_hasTestFilters = false;
     };

src/catch2/catch_message.hpp

@@ -9,7 +9,7 @@
 #define CATCH_MESSAGE_HPP_INCLUDED
 
 #include <catch2/internal/catch_result_type.hpp>
-#include <catch2/internal/catch_stream.hpp>
+#include <catch2/internal/catch_reusable_string_stream.hpp>
 #include <catch2/internal/catch_stream_end_stop.hpp>
 #include <catch2/internal/catch_message_info.hpp>
 #include <catch2/interfaces/catch_interfaces_capture.hpp>

src/catch2/catch_registry_hub.cpp

@@ -51,7 +51,7 @@ namespace Catch {
             void registerReporter( std::string const& name, IReporterFactoryPtr factory ) override {
                 m_reporterRegistry.registerReporter( name, CATCH_MOVE(factory) );
             }
-            void registerListener( IReporterFactoryPtr factory ) override {
+            void registerListener( Detail::unique_ptr<EventListenerFactory> factory ) override {
                 m_reporterRegistry.registerListener( CATCH_MOVE(factory) );
             }
             void registerTest( Detail::unique_ptr<TestCaseInfo>&& testInfo, Detail::unique_ptr<ITestInvoker>&& invoker ) override {

src/catch2/catch_session.cpp

@@ -11,7 +11,6 @@
 #include <catch2/internal/catch_list.hpp>
 #include <catch2/internal/catch_context.hpp>
 #include <catch2/internal/catch_run_context.hpp>
-#include <catch2/internal/catch_stream.hpp>
 #include <catch2/catch_test_spec.hpp>
 #include <catch2/catch_version.hpp>
 #include <catch2/interfaces/catch_interfaces_reporter.hpp>
@@ -19,10 +18,12 @@
 #include <catch2/internal/catch_sharding.hpp>
 #include <catch2/internal/catch_textflow.hpp>
 #include <catch2/internal/catch_windows_h_proxy.hpp>
-#include <catch2/reporters/catch_reporter_listening.hpp>
+#include <catch2/reporters/catch_reporter_multi.hpp>
 #include <catch2/interfaces/catch_interfaces_reporter_registry.hpp>
 #include <catch2/interfaces/catch_interfaces_reporter_factory.hpp>
 #include <catch2/internal/catch_move_and_forward.hpp>
+#include <catch2/internal/catch_stdstreams.hpp>
+#include <catch2/internal/catch_istream.hpp>
 
 #include <algorithm>
 #include <cassert>
@@ -34,31 +35,40 @@ namespace Catch {
     namespace {
         const int MaxExitCode = 255;
 
-        IStreamingReporterPtr createReporter(std::string const& reporterName, ReporterConfig const& config) {
-            auto reporter = Catch::getRegistryHub().getReporterRegistry().create(reporterName, config);
+        IEventListenerPtr createReporter(std::string const& reporterName, ReporterConfig&& config) {
+            auto reporter = Catch::getRegistryHub().getReporterRegistry().create(reporterName, CATCH_MOVE(config));
             CATCH_ENFORCE(reporter, "No reporter registered with name: '" << reporterName << '\'');
 
             return reporter;
         }
 
-        IStreamingReporterPtr makeReporter(Config const* config) {
+        IEventListenerPtr prepareReporters(Config const* config) {
             if (Catch::getRegistryHub().getReporterRegistry().getListeners().empty()
-                    && config->getReportersAndOutputFiles().size() == 1) {
-                auto& stream = config->getReporterOutputStream(0);
-                return createReporter(config->getReportersAndOutputFiles()[0].reporterName, ReporterConfig(config, stream));
+                    && config->getProcessedReporterSpecs().size() == 1) {
+                auto const& spec = config->getProcessedReporterSpecs()[0];
+                return createReporter(
+                    spec.name,
+                    ReporterConfig( config,
+                                    makeStream( spec.outputFilename ),
+                                    spec.colourMode,
+                                    spec.customOptions ) );
             }
 
-            auto multi = Detail::make_unique<ListeningReporter>(config);
+            auto multi = Detail::make_unique<MultiReporter>(config);
 
             auto const& listeners = Catch::getRegistryHub().getReporterRegistry().getListeners();
             for (auto const& listener : listeners) {
-                multi->addListener(listener->create(Catch::ReporterConfig(config, config->defaultStream())));
+                multi->addListener(listener->create(config));
             }
 
             std::size_t reporterIdx = 0;
-            for (auto const& reporterAndFile : config->getReportersAndOutputFiles()) {
-                auto& stream = config->getReporterOutputStream(reporterIdx);
-                multi->addReporter(createReporter(reporterAndFile.reporterName, ReporterConfig(config, stream)));
+            for ( auto const& reporterSpec : config->getProcessedReporterSpecs() ) {
+                multi->addReporter( createReporter(
+                    reporterSpec.name,
+                    ReporterConfig( config,
+                                    makeStream( reporterSpec.outputFilename ),
+                                    reporterSpec.colourMode,
+                                    reporterSpec.customOptions ) ) );
                 reporterIdx++;
             }
 
@@ -67,7 +77,7 @@ namespace Catch {
 
         class TestGroup {
         public:
-            explicit TestGroup(IStreamingReporterPtr&& reporter, Config const* config):
+            explicit TestGroup(IEventListenerPtr&& reporter, Config const* config):
                 m_reporter(reporter.get()),
                 m_config{config},
                 m_context{config, CATCH_MOVE(reporter)} {
@@ -120,7 +130,7 @@ namespace Catch {
 
 
         private:
-            IStreamingReporter* m_reporter;
+            IEventListener* m_reporter;
             Config const* m_config;
             RunContext m_context;
             std::set<TestCaseHandle const*> m_tests;
@@ -151,14 +161,17 @@ namespace Catch {
             getCurrentMutableContext().setConfig(m_config.get());
 
             m_startupExceptions = true;
-            Colour colourGuard( Colour::Red );
-            Catch::cerr() << "Errors occurred during startup!" << '\n';
+            auto errStream = makeStream( "%stderr" );
+            auto colourImpl = makeColourImpl(
+                ColourMode::PlatformDefault, errStream.get() );
+            auto guard = colourImpl->guardColour( Colour::Red );
+            errStream->stream() << "Errors occurred during startup!" << '\n';
             // iterate over all exceptions and notify user
             for ( const auto& ex_ptr : exceptions ) {
                 try {
                     std::rethrow_exception(ex_ptr);
                 } catch ( std::exception const& ex ) {
-                    Catch::cerr() << TextFlow::Column( ex.what() ).indent(2) << '\n';
+                    errStream->stream() << TextFlow::Column( ex.what() ).indent(2) << '\n';
                 }
             }
         }
@@ -173,7 +186,7 @@ namespace Catch {
 
     void Session::showHelp() const {
         Catch::cout()
-                << "\nCatch v" << libraryVersion() << '\n'
+                << "\nCatch2 v" << libraryVersion() << '\n'
                 << m_cli << '\n'
                 << "For more detailed usage please see the project docs\n\n" << std::flush;
     }
@@ -181,7 +194,7 @@ namespace Catch {
         Catch::cout()
                 << std::left << std::setw(16) << "description: " << "A Catch2 test executable\n"
                 << std::left << std::setw(16) << "category: " << "testframework\n"
-                << std::left << std::setw(16) << "framework: " << "Catch Test\n"
+                << std::left << std::setw(16) << "framework: " << "Catch2\n"
                 << std::left << std::setw(16) << "version: " << libraryVersion() << '\n' << std::flush;
     }
 
@@ -194,12 +207,15 @@ namespace Catch {
         if( !result ) {
             config();
             getCurrentMutableContext().setConfig(m_config.get());
-            Catch::cerr()
-                << Colour( Colour::Red )
+            auto errStream = makeStream( "%stderr" );
+            auto colour = makeColourImpl( ColourMode::PlatformDefault, errStream.get() );
+
+            errStream->stream()
+                << colour->guardColour( Colour::Red )
                 << "\nError(s) in input:\n"
                 << TextFlow::Column( result.errorMessage() ).indent( 2 )
                 << "\n\n";
-            Catch::cerr() << "Run with -? for usage\n\n" << std::flush;
+            errStream->stream() << "Run with -? for usage\n\n" << std::flush;
             return MaxExitCode;
         }
 
@@ -298,7 +314,7 @@ namespace Catch {
             getCurrentMutableContext().setConfig(m_config.get());
 
             // Create reporter(s) so we can route listings through them
-            auto reporter = makeReporter(m_config.get());
+            auto reporter = prepareReporters(m_config.get());
 
             auto const& invalidSpecs = m_config->testSpec().getInvalidSpecs();
             if ( !invalidSpecs.empty() ) {
@@ -330,7 +346,7 @@ namespace Catch {
             // Note that on unices only the lower 8 bits are usually used, clamping
             // the return value to 255 prevents false negative when some multiple
             // of 256 tests has failed
-            return (std::min) (MaxExitCode, (std::max) (totals.error, static_cast<int>(totals.assertions.failed)));
+            return (std::min) (MaxExitCode, static_cast<int>(totals.assertions.failed));
         }
 #if !defined(CATCH_CONFIG_DISABLE_EXCEPTIONS)
         catch( std::exception& ex ) {

src/catch2/catch_tag_alias_autoregistrar.cpp

@@ -0,0 +1,24 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/catch_tag_alias_autoregistrar.hpp>
+#include <catch2/internal/catch_compiler_capabilities.hpp>
+#include <catch2/interfaces/catch_interfaces_registry_hub.hpp>
+
+namespace Catch {
+
+    RegistrarForTagAliases::RegistrarForTagAliases(char const* alias, char const* tag, SourceLineInfo const& lineInfo) {
+        CATCH_TRY {
+            getMutableRegistryHub().registerTagAlias(alias, tag, lineInfo);
+        } CATCH_CATCH_ALL {
+            // Do not throw when constructing global objects, instead register the exception to be processed later
+            getMutableRegistryHub().registerStartupException();
+        }
+    }
+
+}

src/catch2/catch_test_case_info.cpp

@@ -7,8 +7,6 @@
 // SPDX-License-Identifier: BSL-1.0
 #include <catch2/catch_test_case_info.hpp>
 #include <catch2/internal/catch_enforce.hpp>
-#include <catch2/catch_test_spec.hpp>
-#include <catch2/interfaces/catch_interfaces_testcase.hpp>
 #include <catch2/internal/catch_string_manip.hpp>
 #include <catch2/internal/catch_case_insensitive_comparisons.hpp>
 
@@ -60,7 +58,7 @@ namespace Catch {
             else if( tag == "!nonportable"_sr )
                 return TestCaseProperties::NonPortable;
             else if( tag == "!benchmark"_sr )
-                return static_cast<TestCaseProperties>(TestCaseProperties::Benchmark | TestCaseProperties::IsHidden );
+                return TestCaseProperties::Benchmark | TestCaseProperties::IsHidden;
             else
                 return TestCaseProperties::None;
         }

src/catch2/catch_test_case_info.hpp

@@ -42,7 +42,7 @@ namespace Catch {
         friend bool operator==( Tag const& lhs, Tag const& rhs );
     };
 
-    struct ITestInvoker;
+    class ITestInvoker;
 
     enum class TestCaseProperties : uint8_t {
         None = 0,

src/catch2/catch_test_macros.hpp

@@ -10,7 +10,7 @@
 
 #include <catch2/internal/catch_test_macro_impl.hpp>
 #include <catch2/catch_message.hpp>
-#include <catch2/internal/catch_preprocessor.hpp>
+#include <catch2/catch_user_config.hpp>
 #include <catch2/internal/catch_section.hpp>
 #include <catch2/internal/catch_test_registry.hpp>
 #include <catch2/internal/catch_unique_name.hpp>

src/catch2/catch_test_spec.hpp

@@ -21,7 +21,7 @@
 
 namespace Catch {
 
-    struct IConfig;
+    class IConfig;
     struct TestCaseInfo;
     class TestCaseHandle;
 

src/catch2/catch_tostring.hpp

@@ -17,7 +17,7 @@
 
 #include <catch2/internal/catch_compiler_capabilities.hpp>
 #include <catch2/internal/catch_config_wchar.hpp>
-#include <catch2/internal/catch_stream.hpp>
+#include <catch2/internal/catch_reusable_string_stream.hpp>
 #include <catch2/internal/catch_void_type.hpp>
 #include <catch2/interfaces/catch_interfaces_enum_values_registry.hpp>
 

src/catch2/catch_totals.hpp

@@ -8,7 +8,6 @@
 #ifndef CATCH_TOTALS_HPP_INCLUDED
 #define CATCH_TOTALS_HPP_INCLUDED
 
-#include <cstddef>
 #include <cstdint>
 
 namespace Catch {
@@ -33,7 +32,6 @@ namespace Catch {
 
         Totals delta( Totals const& prevTotals ) const;
 
-        int error = 0;
         Counts assertions;
         Counts testCases;
     };

src/catch2/catch_translate_exception.hpp

@@ -81,4 +81,4 @@ namespace Catch {
 #endif
 
 
-#endif // CATCH_TRANSLATE_EXCEPTION_HPP_INCLUDED
+#endif // CATCH_TRANSLATE_EXCEPTION_HPP_INCLUDED

src/catch2/catch_user_config.hpp.in

@@ -0,0 +1,198 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+/**\file
+ * **AUTOGENERATED FROM CMAKE CONFIGURATION**
+ *
+ * Contains materialized compile-time configuration provided to Catch2's
+ * CMake configuration. All compile-time configuration options need to
+ * be here, and also documented in `docs/configuration.md`.
+ */
+
+#ifndef CATCH_USER_CONFIG_HPP_INCLUDED
+#define CATCH_USER_CONFIG_HPP_INCLUDED
+
+
+// ------
+// Overridable compilation flags,
+// these can have 3 "states": Force Yes, Force No, Use Default.
+// Setting both Force Yes and Force No is an error
+// ------
+
+#cmakedefine CATCH_CONFIG_ANDROID_LOGWRITE
+#cmakedefine CATCH_CONFIG_NO_ANDROID_LOGWRITE
+
+#if defined( CATCH_CONFIG_ANDROID_LOGWRITE ) && \
+    defined( CATCH_CONFIG_NO_ANDROID_LOGWRITE )
+#    error Cannot force ANDROID_LOGWRITE to both ON and OFF
+#endif
+
+#cmakedefine CATCH_CONFIG_COLOUR_WIN32
+#cmakedefine CATCH_CONFIG_NO_COLOUR_WIN32
+
+#if defined( CATCH_CONFIG_COLOUR_WIN32 ) && \
+    defined( CATCH_CONFIG_NO_COLOUR_WIN32 )
+#    error Cannot force COLOUR_WIN32 to be ON and OFF
+#endif
+
+#cmakedefine CATCH_CONFIG_COUNTER
+#cmakedefine CATCH_CONFIG_NO_COUNTER
+
+#if defined( CATCH_CONFIG_COUNTER ) && \
+    defined( CATCH_CONFIG_NO_COUNTER )
+#    error Cannot force COUNTER to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_CPP11_TO_STRING
+#cmakedefine CATCH_CONFIG_NO_CPP11_TO_STRING
+
+#if defined( CATCH_CONFIG_CPP11_TO_STRING ) && \
+    defined( CATCH_CONFIG_NO_CPP11_TO_STRING )
+#    error Cannot force CPP11_TO_STRING to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_CPP17_BYTE
+#cmakedefine CATCH_CONFIG_NO_CPP17_BYTE
+
+#if defined( CATCH_CONFIG_CPP17_BYTE ) && \
+    defined( CATCH_CONFIG_NO_CPP17_BYTE )
+#    error Cannot force CPP17_BYTE to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_CPP17_OPTIONAL
+#cmakedefine CATCH_CONFIG_NO_CPP17_OPTIONAL
+
+#if defined( CATCH_CONFIG_CPP17_OPTIONAL ) && \
+    defined( CATCH_CONFIG_NO_CPP17_OPTIONAL )
+#    error Cannot force CPP17_OPTIONAL to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_CPP17_STRING_VIEW
+#cmakedefine CATCH_CONFIG_NO_CPP17_STRING_VIEW
+
+#if defined( CATCH_CONFIG_CPP17_STRING_VIEW ) && \
+    defined( CATCH_CONFIG_NO_CPP17_STRING_VIEW )
+#    error Cannot force CPP17_STRING_VIEW to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS
+#cmakedefine CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS
+
+#if defined( CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS ) && \
+    defined( CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS )
+#    error Cannot force CPP17_UNCAUGHT_EXCEPTIONS to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_CPP17_VARIANT
+#cmakedefine CATCH_CONFIG_NO_CPP17_VARIANT
+
+#if defined( CATCH_CONFIG_CPP17_VARIANT ) && \
+    defined( CATCH_CONFIG_NO_CPP17_VARIANT )
+#    error Cannot force CPP17_VARIANT to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_GLOBAL_NEXTAFTER
+#cmakedefine CATCH_CONFIG_NO_GLOBAL_NEXTAFTER
+
+#if defined( CATCH_CONFIG_GLOBAL_NEXTAFTER ) && \
+    defined( CATCH_CONFIG_NO_GLOBAL_NEXTAFTER )
+#    error Cannot force GLOBAL_NEXTAFTER to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_POSIX_SIGNALS
+#cmakedefine CATCH_CONFIG_NO_POSIX_SIGNALS
+
+#if defined( CATCH_CONFIG_POSIX_SIGNALS ) && \
+    defined( CATCH_CONFIG_NO_POSIX_SIGNALS )
+#    error Cannot force POSIX_SIGNALS to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_USE_ASYNC
+#cmakedefine CATCH_CONFIG_NO_USE_ASYNC
+
+#if defined( CATCH_CONFIG_USE_ASYNC ) && \
+    defined( CATCH_CONFIG_NO_USE_ASYNC )
+#    error Cannot force USE_ASYNC to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_WCHAR
+#cmakedefine CATCH_CONFIG_NO_WCHAR
+
+#if defined( CATCH_CONFIG_WCHAR ) && \
+    defined( CATCH_CONFIG_NO_WCHAR )
+#    error Cannot force WCHAR to both ON and OFF
+#endif
+
+
+
+#cmakedefine CATCH_CONFIG_WINDOWS_SEH
+#cmakedefine CATCH_CONFIG_NO_WINDOWS_SEH
+
+#if defined( CATCH_CONFIG_WINDOWS_SEH ) && \
+    defined( CATCH_CONFIG_NO_WINDOWS_SEH )
+#    error Cannot force WINDOWS_SEH to both ON and OFF
+#endif
+
+
+// ------
+// Simple toggle defines
+// their value is never used and they cannot be overriden
+// ------
+
+
+#cmakedefine CATCH_CONFIG_BAZEL_SUPPORT
+#cmakedefine CATCH_CONFIG_DISABLE_EXCEPTIONS
+#cmakedefine CATCH_CONFIG_DISABLE_EXCEPTIONS_CUSTOM_HANDLER
+#cmakedefine CATCH_CONFIG_DISABLE
+#cmakedefine CATCH_CONFIG_DISABLE_STRINGIFICATION
+#cmakedefine CATCH_CONFIG_ENABLE_ALL_STRINGMAKERS
+#cmakedefine CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER
+#cmakedefine CATCH_CONFIG_ENABLE_PAIR_STRINGMAKER
+#cmakedefine CATCH_CONFIG_ENABLE_TUPLE_STRINGMAKER
+#cmakedefine CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER
+#cmakedefine CATCH_CONFIG_EXPERIMENTAL_REDIRECT
+#cmakedefine CATCH_CONFIG_FAST_COMPILE
+#cmakedefine CATCH_CONFIG_NOSTDOUT
+#cmakedefine CATCH_CONFIG_PREFIX_ALL
+#cmakedefine CATCH_CONFIG_WINDOWS_CRTDBG
+
+
+// ------
+// "Variable" defines, these have actual values
+// ------
+
+#define CATCH_CONFIG_DEFAULT_REPORTER "@CATCH_CONFIG_DEFAULT_REPORTER@"
+#define CATCH_CONFIG_CONSOLE_WIDTH @CATCH_CONFIG_CONSOLE_WIDTH@
+
+// Unlike the macros above, CATCH_CONFIG_FALLBACK_STRINGIFIER does not
+// have a good default value, so we cannot always define it, and cannot
+// even expose it as a variable in CMake. The users will have to find
+// out about it from docs and set it only if they use it.
+#cmakedefine CATCH_CONFIG_FALLBACK_STRINGIFIER @CATCH_CONFIG_FALLBACK_STRINGIFIER@
+
+#endif // CATCH_USER_CONFIG_HPP_INCLUDED

src/catch2/catch_version.cpp

@@ -36,7 +36,7 @@ namespace Catch {
     }
 
     Version const& libraryVersion() {
-        static Version version( 3, 0, 0, "preview", 4 );
+        static Version version( 3, 1, 0, "", 0 );
         return version;
     }
 

src/catch2/catch_version_macros.hpp

@@ -9,7 +9,7 @@
 #define CATCH_VERSION_MACROS_HPP_INCLUDED
 
 #define CATCH_VERSION_MAJOR 3
-#define CATCH_VERSION_MINOR 0
+#define CATCH_VERSION_MINOR 1
 #define CATCH_VERSION_PATCH 0
 
 #endif // CATCH_VERSION_MACROS_HPP_INCLUDED

src/catch2/generators/catch_generator_exception.cpp

@@ -0,0 +1,17 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/generators/catch_generator_exception.hpp>
+
+namespace Catch {
+
+    const char* GeneratorException::what() const noexcept {
+        return m_msg;
+    }
+
+} // end namespace Catch

src/catch2/generators/catch_generators.cpp

@@ -5,36 +5,6 @@
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
-/** \file
- * This is a special TU that combines what would otherwise be a very
- * small generator-related TUs into one bigger TU.
- *
- * The reason for this is compilation performance improvements by
- * avoiding reparsing headers for many small TUs, instead having this
- * one TU include bit more, but having it all parsed only once.
- *
- * To avoid heavy-tail problem with compilation times, each "subpart"
- * of Catch2 has its own combined TU like this.
- */
-
-////////////////////////////////////////////////////
-// vvv formerly catch_generator_exception.cpp vvv //
-////////////////////////////////////////////////////
-
-#include <catch2/generators/catch_generator_exception.hpp>
-
-namespace Catch {
-
-    const char* GeneratorException::what() const noexcept {
-        return m_msg;
-    }
-
-} // end namespace Catch
-
-
-///////////////////////////////////////////
-// vvv formerly catch_generators.cpp vvv //
-///////////////////////////////////////////
 
 #include <catch2/generators/catch_generators.hpp>
 #include <catch2/internal/catch_enforce.hpp>

src/catch2/generators/catch_generators.hpp

@@ -8,10 +8,13 @@
 #ifndef CATCH_GENERATORS_HPP_INCLUDED
 #define CATCH_GENERATORS_HPP_INCLUDED
 
+#include <catch2/catch_tostring.hpp>
 #include <catch2/interfaces/catch_interfaces_generatortracker.hpp>
 #include <catch2/internal/catch_source_line_info.hpp>
 #include <catch2/internal/catch_stringref.hpp>
 #include <catch2/internal/catch_move_and_forward.hpp>
+#include <catch2/internal/catch_unique_name.hpp>
+#include <catch2/internal/catch_preprocessor.hpp>
 
 #include <vector>
 #include <tuple>
@@ -29,7 +32,12 @@ namespace Detail {
 } // end namespace detail
 
     template<typename T>
-    struct IGenerator : GeneratorUntypedBase {
+    class IGenerator : public GeneratorUntypedBase {
+        std::string stringifyImpl() const override {
+            return ::Catch::Detail::stringify( get() );
+        }
+
+    public:
         ~IGenerator() override = default;
         IGenerator() = default;
         IGenerator(IGenerator const&) = default;
@@ -61,7 +69,7 @@ namespace Detail {
             return m_generator->get();
         }
         bool next() {
-            return m_generator->next();
+            return m_generator->countedNext();
         }
     };
 

src/catch2/generators/catch_generators_random.cpp

@@ -0,0 +1,13 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/generators/catch_generators_random.hpp>
+
+#include <catch2/internal/catch_context.hpp>
+
+std::uint32_t Catch::Generators::Detail::getSeed() { return sharedRng()(); }

src/catch2/generators/catch_generators_random.hpp

@@ -16,16 +16,21 @@
 
 namespace Catch {
 namespace Generators {
+namespace Detail {
+    // Returns a suitable seed for a random floating generator based off
+    // the primary internal rng. It does so by taking current value from
+    // the rng and returning it as the seed.
+    std::uint32_t getSeed();
+}
 
 template <typename Float>
 class RandomFloatingGenerator final : public IGenerator<Float> {
-    Catch::SimplePcg32& m_rng;
+    Catch::SimplePcg32 m_rng;
     std::uniform_real_distribution<Float> m_dist;
     Float m_current_number;
 public:
-
-    RandomFloatingGenerator(Float a, Float b):
-        m_rng(rng()),
+    RandomFloatingGenerator( Float a, Float b, std::uint32_t seed ):
+        m_rng(seed),
         m_dist(a, b) {
         static_cast<void>(next());
     }
@@ -41,13 +46,12 @@ public:
 
 template <typename Integer>
 class RandomIntegerGenerator final : public IGenerator<Integer> {
-    Catch::SimplePcg32& m_rng;
+    Catch::SimplePcg32 m_rng;
     std::uniform_int_distribution<Integer> m_dist;
     Integer m_current_number;
 public:
-
-    RandomIntegerGenerator(Integer a, Integer b):
-        m_rng(rng()),
+    RandomIntegerGenerator( Integer a, Integer b, std::uint32_t seed ):
+        m_rng(seed),
         m_dist(a, b) {
         static_cast<void>(next());
     }
@@ -61,14 +65,19 @@ public:
     }
 };
 
-// TODO: Ideally this would be also constrained against the various char types,
-//       but I don't expect users to run into that in practice.
 template <typename T>
-std::enable_if_t<std::is_integral<T>::value && !std::is_same<T, bool>::value,
-GeneratorWrapper<T>>
+std::enable_if_t<std::is_integral<T>::value, GeneratorWrapper<T>>
 random(T a, T b) {
+    static_assert(
+        !std::is_same<T, char>::value &&
+        !std::is_same<T, int8_t>::value &&
+        !std::is_same<T, uint8_t>::value &&
+        !std::is_same<T, signed char>::value &&
+        !std::is_same<T, unsigned char>::value &&
+        !std::is_same<T, bool>::value,
+        "The requested type is not supported by the underlying random distributions from std" );
     return GeneratorWrapper<T>(
-        Catch::Detail::make_unique<RandomIntegerGenerator<T>>(a, b)
+        Catch::Detail::make_unique<RandomIntegerGenerator<T>>(a, b, Detail::getSeed())
     );
 }
 
@@ -77,7 +86,7 @@ std::enable_if_t<std::is_floating_point<T>::value,
 GeneratorWrapper<T>>
 random(T a, T b) {
     return GeneratorWrapper<T>(
-        Catch::Detail::make_unique<RandomFloatingGenerator<T>>(a, b)
+        Catch::Detail::make_unique<RandomFloatingGenerator<T>>(a, b, Detail::getSeed())
     );
 }
 

src/catch2/interfaces/catch_interfaces_capture.cpp

@@ -0,0 +1,13 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/interfaces/catch_interfaces_capture.hpp>
+
+namespace Catch {
+    IResultCapture::~IResultCapture() = default;
+}

src/catch2/interfaces/catch_interfaces_capture.hpp

@@ -26,15 +26,15 @@ namespace Catch {
     struct AssertionReaction;
     struct SourceLineInfo;
 
-    struct ITransientExpression;
-    struct IGeneratorTracker;
+    class ITransientExpression;
+    class IGeneratorTracker;
 
     struct BenchmarkInfo;
     template <typename Duration = std::chrono::duration<double, std::nano>>
     struct BenchmarkStats;
 
-    struct IResultCapture {
-
+    class IResultCapture {
+    public:
         virtual ~IResultCapture();
 
         virtual bool sectionStarted(    SectionInfo const& sectionInfo,

src/catch2/interfaces/catch_interfaces_combined_tu.cpp

@@ -1,89 +0,0 @@
-
-//              Copyright Catch2 Authors
-// Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
-//        https://www.boost.org/LICENSE_1_0.txt)
-
-// SPDX-License-Identifier: BSL-1.0
-/** \file
- * This is a special TU that combines what would otherwise be a very
- * small interfaces-related TUs into one bigger TU.
- *
- * The reason for this is compilation performance improvements by
- * avoiding reparsing headers for many small TUs, instead having this
- * one TU include bit more, but having it all parsed only once.
- *
- * To avoid heavy-tail problem with compilation times, each "subpart"
- * of Catch2 has its own combined TU like this.
- */
-
-///////////////////////////////////////////////////
-// vvv formerly catch_interfaces_capture.cpp vvv //
-///////////////////////////////////////////////////
-
-#include <catch2/interfaces/catch_interfaces_capture.hpp>
-
-namespace Catch {
-    IResultCapture::~IResultCapture() = default;
-}
-
-
-//////////////////////////////////////////////////
-// vvv formerly catch_interfaces_config.cpp vvv //
-//////////////////////////////////////////////////
-
-#include <catch2/interfaces/catch_interfaces_config.hpp>
-
-namespace Catch {
-    IConfig::~IConfig() = default;
-}
-
-
-/////////////////////////////////////////////////////
-// vvv formerly catch_interfaces_exception.cpp vvv //
-/////////////////////////////////////////////////////
-
-#include <catch2/interfaces/catch_interfaces_exception.hpp>
-
-namespace Catch {
-    IExceptionTranslator::~IExceptionTranslator() = default;
-    IExceptionTranslatorRegistry::~IExceptionTranslatorRegistry() = default;
-}
-
-
-////////////////////////////////////////////////////////
-// vvv formerly catch_interfaces_registry_hub.cpp vvv //
-////////////////////////////////////////////////////////
-
-#include <catch2/interfaces/catch_interfaces_registry_hub.hpp>
-
-namespace Catch {
-    IRegistryHub::~IRegistryHub() = default;
-    IMutableRegistryHub::~IMutableRegistryHub() = default;
-}
-
-
-////////////////////////////////////////////////////
-// vvv formerly catch_interfaces_testcase.cpp vvv //
-////////////////////////////////////////////////////
-
-#include <catch2/interfaces/catch_interfaces_testcase.hpp>
-
-namespace Catch {
-    ITestInvoker::~ITestInvoker() = default;
-    ITestCaseRegistry::~ITestCaseRegistry() = default;
-}
-
-
-#include <catch2/interfaces/catch_interfaces_reporter_registry.hpp>
-
-namespace Catch {
-    IReporterRegistry::~IReporterRegistry() = default;
-}
-
-
-#include <catch2/interfaces/catch_interfaces_reporter_factory.hpp>
-
-namespace Catch {
-    IReporterFactory::~IReporterFactory() = default;
-}

src/catch2/interfaces/catch_interfaces_config.cpp

@@ -0,0 +1,13 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/interfaces/catch_interfaces_config.hpp>
+
+namespace Catch {
+    IConfig::~IConfig() = default;
+}

src/catch2/interfaces/catch_interfaces_config.hpp

@@ -42,10 +42,15 @@ namespace Catch {
         LexicographicallySorted,
         Randomized
     };
-    enum class UseColour {
-        Auto,
-        Yes,
-        No
+    enum class ColourMode : std::uint8_t {
+        //! Let Catch2 pick implementation based on platform detection
+        PlatformDefault,
+        //! Use ANSI colour code escapes
+        ANSI,
+        //! Use Win32 console colour API
+        Win32,
+        //! Don't use any colour
+        None
     };
     struct WaitForKeypress { enum When {
         Never,
@@ -55,13 +60,13 @@ namespace Catch {
     }; };
 
     class TestSpec;
+    class IStream;
 
-    struct IConfig : Detail::NonCopyable {
-
+    class IConfig : public Detail::NonCopyable {
+    public:
         virtual ~IConfig();
 
         virtual bool allowThrows() const = 0;
-        virtual std::ostream& defaultStream() const = 0;
         virtual StringRef name() const = 0;
         virtual bool includeSuccessfulResults() const = 0;
         virtual bool shouldDebugBreak() const = 0;
@@ -79,10 +84,11 @@ namespace Catch {
         virtual uint32_t rngSeed() const = 0;
         virtual unsigned int shardCount() const = 0;
         virtual unsigned int shardIndex() const = 0;
-        virtual UseColour useColour() const = 0;
+        virtual ColourMode defaultColourMode() const = 0;
         virtual std::vector<std::string> const& getSectionsToRun() const = 0;
         virtual Verbosity verbosity() const = 0;
 
+        virtual bool skipBenchmarks() const = 0;
         virtual bool benchmarkNoAnalysis() const = 0;
         virtual unsigned int benchmarkSamples() const = 0;
         virtual double benchmarkConfidenceInterval() const = 0;

src/catch2/interfaces/catch_interfaces_enum_values_registry.hpp

@@ -25,7 +25,8 @@ namespace Catch {
         };
     } // namespace Detail
 
-    struct IMutableEnumValuesRegistry {
+    class IMutableEnumValuesRegistry {
+    public:
         virtual ~IMutableEnumValuesRegistry(); // = default;
 
         virtual Detail::EnumInfo const& registerEnum( StringRef enumName, StringRef allEnums, std::vector<int> const& values ) = 0;

src/catch2/interfaces/catch_interfaces_exception.cpp

@@ -0,0 +1,14 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/interfaces/catch_interfaces_exception.hpp>
+
+namespace Catch {
+    IExceptionTranslator::~IExceptionTranslator() = default;
+    IExceptionTranslatorRegistry::~IExceptionTranslatorRegistry() = default;
+}

src/catch2/interfaces/catch_interfaces_exception.hpp

@@ -17,17 +17,18 @@
 namespace Catch {
     using exceptionTranslateFunction = std::string(*)();
 
-    struct IExceptionTranslator;
+    class IExceptionTranslator;
     using ExceptionTranslators = std::vector<Detail::unique_ptr<IExceptionTranslator const>>;
 
-    struct IExceptionTranslator {
+    class IExceptionTranslator {
+    public:
         virtual ~IExceptionTranslator(); // = default
         virtual std::string translate( ExceptionTranslators::const_iterator it, ExceptionTranslators::const_iterator itEnd ) const = 0;
     };
 
-    struct IExceptionTranslatorRegistry {
+    class IExceptionTranslatorRegistry {
+    public:
         virtual ~IExceptionTranslatorRegistry(); // = default
-
         virtual std::string translateActiveException() const = 0;
     };
 

src/catch2/interfaces/catch_interfaces_generatortracker.cpp

@@ -0,0 +1,32 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/interfaces/catch_interfaces_generatortracker.hpp>
+#include <string>
+
+namespace Catch {
+    namespace Generators {
+
+        bool GeneratorUntypedBase::countedNext() {
+            auto ret = next();
+            if ( ret ) {
+                m_stringReprCache.clear();
+                ++m_currentElementIndex;
+            }
+            return ret;
+        }
+
+        StringRef GeneratorUntypedBase::currentElementAsString() const {
+            if ( m_stringReprCache.empty() ) {
+                m_stringReprCache = stringifyImpl();
+            }
+            return m_stringReprCache;
+        }
+
+    } // namespace Generators
+} // namespace Catch

src/catch2/interfaces/catch_interfaces_generatortracker.hpp

@@ -9,11 +9,32 @@
 #define CATCH_INTERFACES_GENERATORTRACKER_HPP_INCLUDED
 
 #include <catch2/internal/catch_unique_ptr.hpp>
+#include <catch2/internal/catch_stringref.hpp>
+
+#include <string>
 
 namespace Catch {
 
     namespace Generators {
         class GeneratorUntypedBase {
+            // Caches result from `toStringImpl`, assume that when it is an
+            // empty string, the cache is invalidated.
+            mutable std::string m_stringReprCache;
+
+            // Counts based on `next` returning true
+            std::size_t m_currentElementIndex = 0;
+
+            /**
+             * Attempts to move the generator to the next element
+             *
+             * Returns true iff the move succeeded (and a valid element
+             * can be retrieved).
+             */
+            virtual bool next() = 0;
+
+            //! Customization point for `currentElementAsString`
+            virtual std::string stringifyImpl() const = 0;
+
         public:
             GeneratorUntypedBase() = default;
             // Generation of copy ops is deprecated (and Clang will complain)
@@ -23,17 +44,41 @@ namespace Catch {
 
             virtual ~GeneratorUntypedBase(); // = default;
 
-            // Attempts to move the generator to the next element
-            //
-            // Returns true iff the move succeeded (and a valid element
-            // can be retrieved).
-            virtual bool next() = 0;
+            /**
+             * Attempts to move the generator to the next element
+             *
+             * Serves as a non-virtual interface to `next`, so that the
+             * top level interface can provide sanity checking and shared
+             * features.
+             *
+             * As with `next`, returns true iff the move succeeded and
+             * the generator has new valid element to provide.
+             */
+            bool countedNext();
+
+            std::size_t currentElementIndex() const { return m_currentElementIndex; }
+
+            /**
+             * Returns generator's current element as user-friendly string.
+             *
+             * By default returns string equivalent to calling
+             * `Catch::Detail::stringify` on the current element, but generators
+             * can customize their implementation as needed.
+             *
+             * Not thread-safe due to internal caching.
+             *
+             * The returned ref is valid only until the generator instance
+             * is destructed, or it moves onto the next element, whichever
+             * comes first.
+             */
+            StringRef currentElementAsString() const;
         };
         using GeneratorBasePtr = Catch::Detail::unique_ptr<GeneratorUntypedBase>;
 
     } // namespace Generators
 
-    struct IGeneratorTracker {
+    class IGeneratorTracker {
+    public:
         virtual ~IGeneratorTracker(); // = default;
         virtual auto hasGenerator() const -> bool = 0;
         virtual auto getGenerator() const -> Generators::GeneratorBasePtr const& = 0;

src/catch2/interfaces/catch_interfaces_registry_hub.cpp

@@ -0,0 +1,14 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/interfaces/catch_interfaces_registry_hub.hpp>
+
+namespace Catch {
+    IRegistryHub::~IRegistryHub() = default;
+    IMutableRegistryHub::~IMutableRegistryHub() = default;
+}

src/catch2/interfaces/catch_interfaces_registry_hub.hpp

@@ -16,21 +16,23 @@ namespace Catch {
 
     class TestCaseHandle;
     struct TestCaseInfo;
-    struct ITestCaseRegistry;
-    struct IExceptionTranslatorRegistry;
-    struct IExceptionTranslator;
-    struct IReporterRegistry;
-    struct IReporterFactory;
-    struct ITagAliasRegistry;
-    struct ITestInvoker;
-    struct IMutableEnumValuesRegistry;
+    class ITestCaseRegistry;
+    class IExceptionTranslatorRegistry;
+    class IExceptionTranslator;
+    class IReporterRegistry;
+    class IReporterFactory;
+    class ITagAliasRegistry;
+    class ITestInvoker;
+    class IMutableEnumValuesRegistry;
     struct SourceLineInfo;
 
     class StartupExceptionRegistry;
+    class EventListenerFactory;
 
     using IReporterFactoryPtr = Detail::unique_ptr<IReporterFactory>;
 
-    struct IRegistryHub {
+    class IRegistryHub {
+    public:
         virtual ~IRegistryHub(); // = default
 
         virtual IReporterRegistry const& getReporterRegistry() const = 0;
@@ -42,10 +44,11 @@ namespace Catch {
         virtual StartupExceptionRegistry const& getStartupExceptionRegistry() const = 0;
     };
 
-    struct IMutableRegistryHub {
+    class IMutableRegistryHub {
+    public:
         virtual ~IMutableRegistryHub(); // = default
         virtual void registerReporter( std::string const& name, IReporterFactoryPtr factory ) = 0;
-        virtual void registerListener( IReporterFactoryPtr factory ) = 0;
+        virtual void registerListener( Detail::unique_ptr<EventListenerFactory> factory ) = 0;
         virtual void registerTest(Detail::unique_ptr<TestCaseInfo>&& testInfo, Detail::unique_ptr<ITestInvoker>&& invoker) = 0;
         virtual void registerTranslator( Detail::unique_ptr<IExceptionTranslator>&& translator ) = 0;
         virtual void registerTagAlias( std::string const& alias, std::string const& tag, SourceLineInfo const& lineInfo ) = 0;

src/catch2/interfaces/catch_interfaces_reporter.cpp

@@ -14,17 +14,38 @@
 #include <catch2/internal/catch_string_manip.hpp>
 #include <catch2/catch_test_case_info.hpp>
 #include <catch2/reporters/catch_reporter_helpers.hpp>
+#include <catch2/internal/catch_move_and_forward.hpp>
+#include <catch2/internal/catch_istream.hpp>
 
 #include <algorithm>
+#include <cassert>
 #include <iomanip>
 
 namespace Catch {
 
-    ReporterConfig::ReporterConfig( IConfig const* _fullConfig, std::ostream& _stream )
-    :   m_stream( &_stream ), m_fullConfig( _fullConfig ) {}
+    ReporterConfig::ReporterConfig(
+        IConfig const* _fullConfig,
+        Detail::unique_ptr<IStream> _stream,
+        ColourMode colourMode,
+        std::map<std::string, std::string> customOptions ):
+        m_stream( CATCH_MOVE(_stream) ),
+        m_fullConfig( _fullConfig ),
+        m_colourMode( colourMode ),
+        m_customOptions( CATCH_MOVE( customOptions ) ) {}
 
-    std::ostream& ReporterConfig::stream() const { return *m_stream; }
+    Detail::unique_ptr<IStream> ReporterConfig::takeStream() && {
+        assert( m_stream );
+        return CATCH_MOVE( m_stream );
+    }
     IConfig const * ReporterConfig::fullConfig() const { return m_fullConfig; }
+    ColourMode ReporterConfig::colourMode() const { return m_colourMode; }
+
+    std::map<std::string, std::string> const&
+    ReporterConfig::customOptions() const {
+        return m_customOptions;
+    }
+
+    ReporterConfig::~ReporterConfig() = default;
 
     AssertionStats::AssertionStats( AssertionResult const& _assertionResult,
                                     std::vector<MessageInfo> const& _infoMessages,
@@ -78,6 +99,6 @@ namespace Catch {
         aborting( _aborting )
     {}
 
-    IStreamingReporter::~IStreamingReporter() = default;
+    IEventListener::~IEventListener() = default;
 
 } // end namespace Catch

src/catch2/interfaces/catch_interfaces_reporter.hpp

@@ -19,6 +19,7 @@
 #include <catch2/benchmark/catch_outlier_classification.hpp>
 
 
+#include <map>
 #include <string>
 #include <vector>
 #include <iosfwd>
@@ -26,20 +27,34 @@
 namespace Catch {
 
     struct ReporterDescription;
+    struct ListenerDescription;
     struct TagInfo;
     struct TestCaseInfo;
     class TestCaseHandle;
-    struct IConfig;
+    class IConfig;
+    class IStream;
+    enum class ColourMode : std::uint8_t;
 
     struct ReporterConfig {
-        ReporterConfig( IConfig const* _fullConfig, std::ostream& _stream );
+        ReporterConfig( IConfig const* _fullConfig,
+                        Detail::unique_ptr<IStream> _stream,
+                        ColourMode colourMode,
+                        std::map<std::string, std::string> customOptions );
 
-        std::ostream& stream() const;
+        ReporterConfig( ReporterConfig&& ) = default;
+        ReporterConfig& operator=( ReporterConfig&& ) = default;
+        ~ReporterConfig(); // = default
+
+        Detail::unique_ptr<IStream> takeStream() &&;
         IConfig const* fullConfig() const;
+        ColourMode colourMode() const;
+        std::map<std::string, std::string> const& customOptions() const;
 
     private:
-        std::ostream* m_stream;
+        Detail::unique_ptr<IStream> m_stream;
         IConfig const* m_fullConfig;
+        ColourMode m_colourMode;
+        std::map<std::string, std::string> m_customOptions;
     };
 
     struct TestRunInfo {
@@ -149,8 +164,19 @@ namespace Catch {
         bool shouldReportAllAssertions = false;
     };
 
-    //! The common base for all reporters and event listeners
-    struct IStreamingReporter {
+    /**
+     * The common base for all reporters and event listeners
+     *
+     * Implementing classes must also implement:
+     *
+     *     //! User-friendly description of the reporter/listener type
+     *     static std::string getDescription()
+     *
+     * Generally shouldn't be derived from by users of Catch2 directly,
+     * instead they should derive from one of the utility bases that
+     * derive from this class.
+     */
+    class IEventListener {
     protected:
         //! Derived classes can set up their preferences here
         ReporterPreferences m_preferences;
@@ -158,9 +184,9 @@ namespace Catch {
         IConfig const* m_config;
 
     public:
-        IStreamingReporter( IConfig const* config ): m_config( config ) {}
+        IEventListener( IConfig const* config ): m_config( config ) {}
 
-        virtual ~IStreamingReporter(); // = default;
+        virtual ~IEventListener(); // = default;
 
         // Implementing class must also provide the following static methods:
         // static std::string getDescription();
@@ -224,13 +250,14 @@ namespace Catch {
 
         //! Writes out information about provided reporters using reporter-specific format
         virtual void listReporters(std::vector<ReporterDescription> const& descriptions) = 0;
+        //! Writes out the provided listeners descriptions using reporter-specific format
+        virtual void listListeners(std::vector<ListenerDescription> const& descriptions) = 0;
         //! Writes out information about provided tests using reporter-specific format
         virtual void listTests(std::vector<TestCaseHandle> const& tests) = 0;
         //! Writes out information about the provided tags using reporter-specific format
         virtual void listTags(std::vector<TagInfo> const& tags) = 0;
-
     };
-    using IStreamingReporterPtr = Detail::unique_ptr<IStreamingReporter>;
+    using IEventListenerPtr = Detail::unique_ptr<IEventListener>;
 
 } // end namespace Catch
 

src/catch2/interfaces/catch_interfaces_reporter_factory.cpp

@@ -0,0 +1,14 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/interfaces/catch_interfaces_reporter_factory.hpp>
+
+namespace Catch {
+    IReporterFactory::~IReporterFactory() = default;
+    EventListenerFactory::~EventListenerFactory() = default;
+}

src/catch2/interfaces/catch_interfaces_reporter_factory.hpp

@@ -9,24 +9,37 @@
 #define CATCH_INTERFACES_REPORTER_FACTORY_HPP_INCLUDED
 
 #include <catch2/internal/catch_unique_ptr.hpp>
+#include <catch2/internal/catch_stringref.hpp>
 
 #include <string>
 
 namespace Catch {
 
     struct ReporterConfig;
-    struct IStreamingReporter;
-    using IStreamingReporterPtr = Detail::unique_ptr<IStreamingReporter>;
+    class IConfig;
+    class IEventListener;
+    using IEventListenerPtr = Detail::unique_ptr<IEventListener>;
 
 
-    struct IReporterFactory {
+    class IReporterFactory {
+    public:
         virtual ~IReporterFactory(); // = default
 
-        virtual IStreamingReporterPtr
-        create( ReporterConfig const& config ) const = 0;
+        virtual IEventListenerPtr
+        create( ReporterConfig&& config ) const = 0;
         virtual std::string getDescription() const = 0;
     };
     using IReporterFactoryPtr = Detail::unique_ptr<IReporterFactory>;
+
+    class EventListenerFactory {
+    public:
+        virtual ~EventListenerFactory(); // = default
+        virtual IEventListenerPtr create( IConfig const* config ) const = 0;
+        //! Return a meaningful name for the listener, e.g. its type name
+        virtual StringRef getName() const = 0;
+        //! Return listener's description if available
+        virtual std::string getDescription() const = 0;
+    };
 } // namespace Catch
 
 #endif // CATCH_INTERFACES_REPORTER_FACTORY_HPP_INCLUDED

src/catch2/interfaces/catch_interfaces_reporter_registry.cpp

@@ -0,0 +1,13 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/interfaces/catch_interfaces_reporter_registry.hpp>
+
+namespace Catch {
+    IReporterRegistry::~IReporterRegistry() = default;
+}

src/catch2/interfaces/catch_interfaces_reporter_registry.hpp

@@ -17,20 +17,22 @@
 
 namespace Catch {
 
-    struct IConfig;
+    class IConfig;
 
-    struct IStreamingReporter;
-    using IStreamingReporterPtr = Detail::unique_ptr<IStreamingReporter>;
-    struct IReporterFactory;
+    class IEventListener;
+    using IEventListenerPtr = Detail::unique_ptr<IEventListener>;
+    class IReporterFactory;
     using IReporterFactoryPtr = Detail::unique_ptr<IReporterFactory>;
     struct ReporterConfig;
+    class EventListenerFactory;
 
-    struct IReporterRegistry {
+    class IReporterRegistry {
+    public:
         using FactoryMap = std::map<std::string, IReporterFactoryPtr, Detail::CaseInsensitiveLess>;
-        using Listeners = std::vector<IReporterFactoryPtr>;
+        using Listeners = std::vector<Detail::unique_ptr<EventListenerFactory>>;
 
         virtual ~IReporterRegistry(); // = default
-        virtual IStreamingReporterPtr create( std::string const& name, ReporterConfig const& config ) const = 0;
+        virtual IEventListenerPtr create( std::string const& name, ReporterConfig&& config ) const = 0;
         virtual FactoryMap const& getFactories() const = 0;
         virtual Listeners const& getListeners() const = 0;
     };