Changelog History
Page 1
-
v3.0.0-preview3 Changes
October 08, 2020๐ 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
- Primary development is now on
๐ 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 inmatchers
subfolder,
generators ingenerators
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.
- 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
- Why the big breaking change caused by replacing
catch.hpp
withcatch_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.
- The convenience header
(Potentially) Breaking changes
- Catch2 now uses statically compiled library as its distribution model
- Including
catch.hpp
no longer works
- Including
- โ
ANON_TEST_CASE
has been removed, useTEST_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
- You should use verbosity-modifiers for
--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]
.
- Previously, a
PredicateMatcher
is no longer type erased.- This means that the type of the provided predicate is part of the
PredicateMatcher
's type
- This means that the type of the provided predicate is part of the
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
- You can still write
- ๐ The
[!hide]
tag has been removed.- Use
[.]
or[.foo]
instead.
- Use
- 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
- This does not change
- ๐
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 nowfinal
- Concrete Matchers (e.g.
UnorderedEquals
vector matcher) are nowfinal
- 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
- Link with
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 toEventListenerBase
EventListenerBase
now directly derives fromIStreamingReporter
, instead of deriving fromStreamingReporterBase
๐ 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
, andContains
are provided. - At least
ElementsAre
andUnorderedElementsAre
are planned.
- This includes having templated
- ๐ Some runtime performance improvements
- Significant compilation time improvements
- including
catch_test_macros.hpp
is 80% cheaper than includingcatch.hpp
- including
๐ 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
andCatch2WithMain
.Catch2
is the statically compiled implementation by itselfCatch2WithMain
also links in the default main
- ๐ฆ Catch2's pkg-config integration also provides 2 packages
catch2
is the statically compiled implementation by itselfcatch2-with-main
also links in the default main
-
v3.0.0-preview2 Changes
May 14, 2020Catch2 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 inmatchers
subfolder,
generators ingenerators
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 I intend to provide sqlite-style distribution option, with 1 header and 1 "unity" .cpp file. Do note that the header will have similar problem to the
catch_all.hpp
header.
- No. But I intend to provide sqlite-style distribution option, with 1 header and 1 "unity" .cpp file. Do note that the header will have similar problem to the
- Why the big breaking change caused by replacing
catch.hpp
withcatch_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.
- The convenience header
- Why does CMake/pkg-config/etc report version 3.0.0?
- Lot of tooling does not handle preview versions too well, so we have to use proper new major version. The final release will use version 3.0.1 to avoid conflicts with these preview versions.
(Potentially) Breaking changes
- Catch2 now uses statically compiled library as its distribution model
- Including
catch.hpp
no longer works
- Including
- โ
ANON_TEST_CASE
has been removed, useTEST_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
- You should use verbosity-modifiers for
--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]
.
- Previously, a
PredicateMatcher
is no longer type erased.- This means that the type of the provided predicate is part of the
PredicateMatcher
's type
- This means that the type of the provided predicate is part of the
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
- You can still write
- ๐ The
[!hide]
tag has been removed.- Use
[.]
or[.foo]
instead.
- Use
- 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
- This does not change
- ๐
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 nowfinal
- Concrete Matchers (e.g.
UnorderedEquals
vector matcher) are nowfinal
- 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
- Link with
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.
๐ 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
, andContains
are provided. - At least
ElementsAre
andUnorderedElementsAre
are planned.
- This includes having templated
๐ 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 are always provided
- Catch2's CMake now provides 2 targets,
Catch2
andCatch2WithMain
.Catch2
is the statically compiled implementation by itselfCatch2WithMain
also links in the default main
- ๐ฆ Catch2's pkg-config integration also provides 2 packages
catch2
is the statically compiled implementation by itselfcatch2-with-main
also links in the default main
- Why is Catch2 moving to separate headers?
-
v3.0.0-preview1 Changes
December 28, 2019๐ This is a preview release for the changes in the next (v3) major version. The biggest change is that Catch2 is now primarily provided as a static library. Use
Catch2Main
orCatch2
CMake targets to link against it.(Potentially) Breaking changes
- โ
ANON_TEST_CASE
has been removed, useTEST_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
- You should use verbosity-modifiers for
--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]
.
- Previously, a
PredicateMatcher
is no longer type erased.- This means that the type of the provided predicate is part of the
PredicateMatcher
's type
- This means that the type of the provided predicate is part of the
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 implicitly convertible to it
- You can still write
๐ Fixes
- โ
-
v2.13.3 Changes
October 31, 2020๐ Fixes
- ๐ Fixed possible infinite loop when combining generators with section filter (
-c
option) (#2025)
Miscellaneous
- ๐ Fixed possible infinite loop when combining generators with section filter (
-
v2.13.2 Changes
October 07, 2020๐ 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 supportsTEMPLATE_TEST_CASE
macros (#2031) - ๐ Various documentation fixes and improvements (#2022, #2028, #2034)
-
v2.13.1 Changes
September 07, 2020๐ Improvements
- โ
ParseAndAddCatchTests
handles CMake v3.18.0 correctly (#1984) - ๐ Improved autodetection of
std::byte
(#1992) - โ
Simplified implementation of templated test cases (#2007)
- This should have a tiny positive effect on its compilation throughput
๐ Fixes
- Automatic stringification of ranges handles sentinel ranges properly (#2004)
- โ
-
v2.13.0 Changes
July 12, 2020๐ Improvements
GENERATE
can now follow aSECTION
at the same level of nesting (#1938)- The
SECTION
(s) before theGENERATE
will not be run multiple times, the following ones will.
- The
- โ Added
-D
/--min-duration
command line flag (#1910)- If a test takes longer to finish than the provided value, its name and duration will be printed.
- This flag is overriden by setting
-d
/--duration
.
๐ Fixes
TAPReporter
no longer skips successful assertions (#1983)
-
v2.12.4 Changes
July 05, 2020๐ Yes, the only change in this release is support for MacOS on ARM.
๐ Improvements
- โ Added support for MacOS on ARM (#1971)
-
v2.12.3 Changes
June 29, 2020๐ Fixes
GENERATE
nested in a for loop no longer creates multiple generators (#1913)- โ
Fixed copy paste error breaking
TEMPLATE_TEST_CASE_SIG
for 6 or more arguments (#1954) - ๐ Fixed potential UB when handling non-ASCII characters in CLI args (#1943)
๐ Improvements
- There can be multiple calls to
GENERATE
on a single line - ๐ Improved
fno-except
support for platforms that do not provide shims for exception-related std functions (#1950)- E.g. the Green Hills C++ compiler
- โ
XmlReporter now also reports test-case-level statistics (#1958)
- This is done via a new element,
OverallResultsCases
- This is done via a new element,
Miscellaneous
-
v2.12.2 Changes
May 25, 2020