v2.13.9

Fixes

• Fixed issue with -# (filename-as-tag) flag when __FILE__ expands into filename without directories (#2328, #2393)
• Fixed CAPTURE macro not being variadic when disabled through CATCH_CONFIG_DISABLE (#2316, #2378)

v3.0.0-preview4

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 while most documentation has been updated to the new design,
it is still a work in progress.

FAQ

• Why is Catch2 moving to separate headers?
  • The short answer is future extensibility and scalability. The long answer is complex and can be found on my blog, but at the most basic level, it is that providing single-header distribution is at odds with providing variety of useful features. When Catch2 was distributed in a single header, adding a new Matcher would cause overhead for everyone, but was useful only to a subset of users. This meant that the barrier to entry for new Matchers/Generators/etc is high in single header model, but much smaller in the new model.
• Will Catch2 again distribute single-header version in the future?
  • No. But we do provide sqlite-style amalgamated distribution option. This means that you can download just 1 .cpp file and 1 header and place them next to your own sources. However, doing this has downsides similar to using the catch_all.hpp header.
• Why the big breaking change caused by replacing catch.hpp with catch_all.hpp?
  • The convenience header catch_all.hpp exists for two reasons. One of them is to provide a way for quick migration from Catch2, the second one is to provide a simple way to test things with Catch2. Using it for migration has one drawback in that it is big. This means that including it will cause significant compile time drag, and so using it to migrate should be a conscious decision by the user, not something they can just stumble into unknowingly.

(Potentially) Breaking changes

• Catch2 now uses statically compiled library as its distribution model
  • Including catch.hpp no longer works
• Catch2 now uses C++14 as the minimum support language version
• ANON_TEST_CASE has been removed, use TEST_CASE with no arguments instead (#1220)
• --list* commands no longer have non-zero return code (#1410)
• --list-test-names-only has been removed (#1190)
  • You should use verbosity-modifiers for --list-tests instead
• --list* commands are now piped through the reporters
  • The top-level reporter interface provides default implementation that works just as the old one
  • XmlReporter outputs a machine-parseable XML
• TEST_CASE description support has been removed
  • If the second argument has text outside tags, the text will be ignored.
• Hidden test cases are no longer included just because they don't match an exclusion tag
  • Previously, a TEST_CASE("A", "[.foo]") would be included by asking for ~[bar].
• PredicateMatcher is no longer type erased.
  • This means that the type of the provided predicate is part of the PredicateMatcher's type
• SectionInfo no longer contains section description as a member (#1319)
  • You can still write SECTION("ShortName", "Long and wordy description"), but the description is thrown away
  • The description type now must be a const char* or be implicitly convertible to it
• The [!hide] tag has been removed.
  • Use [.] or [.foo] instead.
• Lvalues of composed matchers cannot be composed further
• Uses of REGISTER_TEST_CASE macro need to be followed by a semicolon
  • This does not change TEST_CASE and friends in any way
• IStreamingReporter::IsMulti member function was removed
  • This is very unlikely to actually affect anyone, as it was default-implemented in the interface, and only used internally
• Various classes not designed for user-extension have been made final
  • ListeningReporter is now final
  • Concrete Matchers (e.g. UnorderedEquals vector matcher) are now final
  • All Generators are now final
• Matcher namespacing has been redone
  • Matcher types are no longer in deeply nested namespaces
  • Matcher factory functions are no longer brought into Catch namespace
  • This means that all public-facing matcher-related functionality is now in Catch::Matchers namespace
• Defining CATCH_CONFIG_MAIN will no longer create main in that TU.
  • Link with libCatch2Main.a, or the proper CMake/pkg-config target
  • If you want to write custom main, include catch2/catch_session.hpp
• CATCH_CONFIG_EXTERNAL_INTERFACES has been removed.
  • You should instead include the appropriate headers as needed.
• CATCH_CONFIG_IMPL has been removed.
  • The implementation is now compiled into a static library.
• Event Listener interface has changed
  • TestEventListenerBase was renamed to EventListenerBase
  • EventListenerBase now directly derives from IStreamingReporter, instead of deriving from StreamingReporterBase
• GENERATE decays its arguments (#2012, #2040)
  • This means that str in auto str = GENERATE("aa", "bb", "cc"); is inferred to char const* rather than const char[2].
• --list-* flags write their output to file specified by the -o flag
• Many changes to reporter interfaces
  • 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
• 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.

Improvements

• Matchers have been extended with the ability to use different signatures of match (#1307, #1553, #1554, #1843)
  • This includes having templated match member function
  • See the rewritten Matchers documentation for details
  • Catch2 currently provides some generic matchers, but there should be more before final release of v3
    • IsEmpty, SizeIs which check that the range has specific properties
    • Contains, which checks whether a range contains a specific element
    • AllMatch, AnyMatch, NoneMatch range matchers, which apply matchers over a range of elements
• Significant compilation time improvements
  • including catch_test_macros.hpp is 80% cheaper than including catch.hpp
• Some runtime performance optimizations
  • In all tested cases the v3 branch was faster, so the table below shows the speedup of v3 to v2 at the same task
    

task	debug build	release build
Run 1M REQUIRE(true)	1.10 ± 0.01	1.02 ± 0.06
Run 100 tests, 3^3 sections, 1 REQUIRE each	1.27 ± 0.01	1.04 ± 0.01
Run 3k tests, no names, no tags	1.29 ± 0.01	1.05 ± 0.01
Run 3k tests, names, tags	1.49 ± 0.01	1.22 ± 0.01
Run 1 out of 3k tests no names, no tags	1.68 ± 0.02	1.19 ± 0.22
Run 1 out of 3k tests, names, tags	1.79 ± 0.02	2.06 ± 0.23

• POSIX platforms use gmtime_r, rather than gmtime when constructing a date string (#2008, #2165)
• --list-* flags write their output to file specified by the -o flag (#2061, #2163)
• Approx::operator() is now properly const
• Catch2's internal helper variables no longer use reserved identifiers (#578)
• --rng-seed now accepts string "random-device" to generate random seed using std::random_device
• Catch2 now supports test sharding (#2257)
  • You can ask for the tests to be split into N groups and only run one of them.
  • This greatly simplifies parallelization of tests in a binary through external runner.
• The embedded CLI parser now supports repeatedly callable lambdas
  • A lambda-based option parser can opt into being repeatedly specifiable.
• Added STATIC_CHECK macro, similar to STATIC_REQUIRE (#2318)
  • When deferred tu runtime, it behaves like CHECK, and not like REQUIRE.
• You can have multiple tests with the same name, as long as other parts of the test identity differ (#1915, #1999, #2175)
  • Test identity includes test's name, test's tags and and test's class name if applicable.
• Added new warning, UnmatchedTestSpec, to error on test specs with no matching tests
• The -w, --warn warning flags can now be provided multiple times to enable multiple warnings
• The case-insensitive handling of tags is now more reliable and takes up less memory
• Test case and assertion counting can no longer reasonably overflow on 32 bit systems
  • The count is now kept in uint64_t on all platforms, instead of using size_t type.
• The -o, --out output destination specifiers recognize - as stdout
  • You have to provide it as --out=- to avoid CLI error about missing option
  • The new reporter specification also recognizes - as stdout
• 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 sem...

v2.13.8

Fixes

• Made Approx::operator() const (#2288)
• Improved pkg-config files (#2284)
• Fixed warning suppression leaking out of Catch2 when compiled with clang.exe (#2280)
• The macro-generated names for things like TEST_CASE no longer create reserved identifiers (#2336)

Improvements

• Clang-tidy should no longer warn about missing virtual dispatch in FilterGenerator's constructor (#2314)

v2.13.7

Fixes

• Added missing <iterator> include in benchmarking. (#2231)
• Fixed noexcept build with benchmarking enabled (#2235)
• Fixed build for compilers with C++17 support but without C++17 library support (#2195)
• JUnit only uses 3 decimal places when reporting durations (#2221)
• !mayfail tagged tests are now marked as skipped in JUnit reporter output (#2116)

v2.13.6

Fixes

• Disabling all signal handlers no longer breaks compilation (#2212, #2213)

Miscellaneous

• catch_discover_tests should handle escaped semicolon (;) better (#2214, #2215)

v2.13.5

Improvements

• Detection of MAC and IPHONE platforms has been improved (#2140, #2157)
• Added workaround for bug in XLC 16.1.0.1 (#2155)
• Add detection for LCC when it is masquerading as GCC (#2199)
• Modified posix signal handling so it supports newer libcs (#2178)
  • MINSIGSTKSZ was no longer usable in constexpr context.

Fixes

• Fixed compilation of benchmarking when min and max macros are defined (#2159)
  • Including windows.h without NOMINMAX remains a really bad idea, don't do it

Miscellaneous

• Catch2WithMain target (static library) is no longer built by default (#2142)
  • Building it by default was at best unnecessary overhead for people not using it, and at worst it caused trouble with install paths
  • To have it built, set CMake option CATCH_BUILD_STATIC_LIBRARY to ON
• The check whether Catch2 is being built as a subproject is now more reliable (#2202, #2204)
  • The problem was that if the variable name used internally was defined the project including Catch2 as subproject, it would not be properly overwritten for Catch2's CMake.

v2.13.4

Improvements

• Improved the hashing algorithm used for shuffling test cases (#2070)
  • TEST_CASEs that differ only in the last character should be properly shuffled
  • Note that this means that v2.13.4 gives you a different order of test cases than 2.13.3, even given the same seed.

Miscellaneous

• Deprecated ParseAndAddCatchTests CMake integration (#2092)
  • It is impossible to implement it properly for all the different test case variants Catch2 provides, and there are better options provided.
  • Use catch_discover_tests instead, which uses runtime information about available tests.
• Fixed bug in catch_discover_tests that would cause it to fail when used in specific project structures (#2119)
• Added Bazel build file
• Added an experimental static library target to CMake

v2.13.3

Fixes

• Fixed possible infinite loop when combining generators with section filter (-c option) (#2025)

Miscellaneous

• Fixed ParseAndAddCatchTests not finding TEST_CASEs without tags (#2055, #2056)
• ParseAndAddCatchTests supports CMP0110 policy for changing behaviour of add_test (#2057)
  • This was the shortlived change in CMake 3.18.0 that temporarily broke ParseAndAddCatchTests

v3.0.0-preview3

Changes compared to preview 2

• Incorporated v2 changes up to v2.13.2
• Some runtime performance improvements
• The static library compiles 20-30% faster
• The overhead of including catch_test_macros.hpp is 25-30% smaller
• Amalgamated, 1 .hpp + 1 .cpp, distribution is provided
• Reporter interface has slightly changed
• Listener base renamed
• Rewritten contributing documentation
  • Primary development is now on devel branch
  • v3 is now the primary development version

Changes compared to v2 releases

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.

FAQ

• Why is Catch2 moving to separate headers?
  • The short answer is future extensibility and scalability. The long answer is complex and can be found on my blog, but at the most basic level, it is that providing single-header distribution is at odds with providing variety of useful features. When Catch2 was distributed in a single header, adding a new Matcher would cause overhead for everyone, but was useful only to a subset of users. This meant that the barrier to entry for new Matchers/Generators/etc is high in single header model, but much smaller in the new model.
• Will Catch2 again distribute single-header version in the future?
  • No. But we do provide sqlite-style amalgamated distribution option. This means that you can download just 1 .cpp file and 1 header and place them next to your own sources. However, doing this has downsides similar to using the catch_all.hpp header.
• Why the big breaking change caused by replacing catch.hpp with catch_all.hpp?
  • The convenience header catch_all.hpp exists for two reasons. One of them is to provide a way for quick migration from Catch2, the second one is to provide a simple way to test things with Catch2. Using it for migration has one drawback in that it is big. This means that including it will cause significant compile time drag, and so using it to migrate should be a concious decision by the user, not something they can just stumble into unknowingly.

(Potentially) Breaking changes

• Catch2 now uses statically compiled library as its distribution model
  • Including catch.hpp no longer works
• ANON_TEST_CASE has been removed, use TEST_CASE with no arguments instead (#1220)
• --list* commands no longer have non-zero return code (#1410)
• --list-test-names-only has been removed (#1190)
  • You should use verbosity-modifiers for --list-tests instead
• --list* commands are now piped through the reporters
  • The top-level reporter interface provides default implementation that works just as the old one
  • XmlReporter outputs a machine-parseable XML
• TEST_CASE description support has been removed
  • If the second argument has text outside tags, the text will be ignored.
• Hidden test cases are no longer included just because they don't match an exclusion tag
  • Previously, a TEST_CASE("A", "[.foo]") would be included by asking for ~[bar].
• PredicateMatcher is no longer type erased.
  • This means that the type of the provided predicate is part of the PredicateMatcher's type
• SectionInfo no longer contains section description as a member (#1319)
  • You can still write SECTION("ShortName", "Long and wordy description"), but the description is thrown away
  • The description type now must be a const char* or be implicitly convertible to it
• The [!hide] tag has been removed.
  • Use [.] or [.foo] instead.
• Lvalues of composed matchers cannot be composed further
• Uses of REGISTER_TEST_CASE macro need to be followed by a semicolon
  • This does not change TEST_CASE and friends in any way
• IStreamingReporter::IsMulti member function was removed
  • This is very unlikely to actually affect anyone, as it was default-implemented in the interface, and only used internally
• Various classes not designed for user-extension have been made final
  • ListeningReporter is now final
  • Concrete Matchers (e.g. UnorderedEquals vector matcher) are now final
  • All Generators are now final
• Matcher namespacing has been redone
  • Matcher types are no longer in deeply nested namespaces
  • Matcher factory functions are no longer brought into Catch namespace
  • This means that all public-facing matcher-related functionality is now in Catch::Matchers namespace
• Defining CATCH_CONFIG_MAIN will no longer create main in that TU.
  • Link with libCatch2Main.a, or the proper CMake/pkg-config target
  • If you want to write custom main, include catch2/catch_session.hpp
• CATCH_CONFIG_EXTERNAL_INTERFACES has been removed.
  • You should instead include the appropriate headers as needed.
• CATCH_CONFIG_IMPL has been removed.
  • The implementation is now compiled into a static library.
• Event Listener interface has changed
  • TestEventListenerBase was renamed to EventListenerBase
  • EventListenerBase now directly derives from IStreamingReporter, instead of deriving from StreamingReporterBase

Improvements

• Matchers have been extended with the ability to use different signatures of match (#1307, #1553, #1554, #1843)
  • This includes having templated match member function
  • See the rewritten Matchers documentation for details
  • Catch2 currently provides some generic matchers, but there should be more before final release of v3
    • So far, IsEmpty, SizeIs, and Contains are provided.
    • At least ElementsAre and UnorderedElementsAre are planned.
• Some runtime performance improvements
• Significant compilation time improvements
  • including catch_test_macros.hpp is 80% cheaper than including catch.hpp

Fixes

• The INFO macro no longer contains superfluous semicolon (#1456)
• The --list* family of command line flags now return 0 on success (#1410, #1146)

Other changes

• CATCH_CONFIG_DISABLE_MATCHERS no longer exists.
  • If you do not want to use Matchers in a TU, do not include their header.
• CATCH_CONFIG_ENABLE_CHRONO_STRINGMAKER no longer exists.
  • StringMaker specializations for <chrono> are always provided
• Catch2's CMake now provides 2 targets, Catch2 and Catch2WithMain.
  • Catch2 is the statically compiled implementation by itself
  • Catch2WithMain also links in the default main
• Catch2's pkg-config integration also provides 2 packages
  • catch2 is the statically compiled implementation by itself
  • catch2-with-main also links in the default main

v2.13.2

There are two things of importance here. The first is that after this release, I am making the v3 branch the main development branch, and will instead branch off a maintenance branch for v2.

The other is that you should watch this video by my friend, JeanHeyd Meneide, on his experiences with the C++ community.

Improvements

• Implemented workaround for AppleClang shadowing bug (#2030)
• Implemented workaround for NVCC ICE (#2005, #2027)

Fixes

• Fixed detection of std::uncaught_exceptions support under non-msvc platforms (#2021)
• Fixed the experimental stdout/stderr capture under Windows (#2013)

Miscellaneous

• catch_discover_tests has been improved significantly (#2023, #2039)
  • You can now specify which reporter should be used
  • You can now modify where the output will be written
  • WORKING_DIRECTORY setting is respected
• ParseAndAddCatchTests now supports TEMPLATE_TEST_CASE macros (#2031)
• Various documentation fixes and improvements (#2022, #2028, #2034)