Repository navigation
Catch3 0.3.0
Released 2026-11-01.
Tags of Catch3 are catch3-<version> from this release on.
Language and license
Catch3 is C++17, and its headers work in C++17 and later. Progmasoft-authored
files move to the Progmasoft Linking Exception, Version 2.0; Catch2-derived code
keeps the Boost Software License.
The Catch3 runner
Catch3 keeps Catch2's API for writing tests and replaces its session, command
line and reporters with a runner of its own:
- Tests run in parallel worker processes; a crash, an exit or a hang ends one
test, not the run. - Failures are retried alone to tell deterministic, flaky and order-dependent
failures apart; the test that leaves state behind is found by bisection. - A history of verdicts and durations drives quarantine, learned time limits,
predictive ordering, incremental runs, replay and analytics. - Tests are selected by change, by past failure or by prediction, and sharded
by a stable hash or by recorded duration. - Tags declare serial and isolated tests, shared resources, dependencies,
time limits and retries. - Every failure gets a category, a signature, an analysis and a replay command.
- Reports are console, JUnit XML, JSON and a Chrome trace;
--list=jsonis a
versioned discovery format. - Every test gets a temporary directory of its own.
- A project keeps its options in a
catch3.json, found up to
the root of the repository; the command line wins over it, and
--config=FILEand--no-configchoose another file or none. - JSON is read and written with yyjson
and JUnit XML is written with pugixml,
both MIT and vendored inthird_party/. They are compiled into Catch3's
own translation units with internal linkage or a renamed namespace, so a
project that links its own copy of either library is not affected. The
amalgamated sources include them from a third file,
extras/catch_amalgamated_third_party.hpp.
Breaking changes
- Catch3 has its own build and header names, so that it is never mistaken
for Catch2 and both can be used in one project:- CMake:
find_package(Catch3)withCatch3::Catch3and
Catch3::Catch3WithMain, optionsCATCH3_*, and the scripts
Catch3.cmake(catch3_discover_tests) andCatch3ShardTests.cmake
(catch3_add_sharded_tests). TheProgmasoft::Catch3target is gone:
its code is part ofCatch3::Catch3. - Bazel
//:catch3and//:catch3_main, Mesoncatch3and
catch3-with-main, pkg-configcatch3.pcandcatch3-with-main.pc. - Headers moved from
catch2/toProgmasoft/Catch3/with Progmasoft
names:<catch2/catch_test_macros.hpp>is
<Progmasoft/Catch3/TestMacros.hpp>,<catch2/matchers/catch_matchers_string.hpp>
is<Progmasoft/Catch3/Matchers/String.hpp>, and so on. Test bodies do
not change: the macros and theCatch::namespace keep their names. ParseAndAddCatchTests.cmake, deprecated upstream, was removed.
- CMake:
- Catch2's command line, reporters,
CATCH_REGISTER_REPORTERand listing
were removed; see the command line and
reports. Listeners keep working. - C++17 is the minimum, for the library and for the code that uses it.
- The results model in
Progmasoft/Catch3/Results.hppwas rewritten around
tests and attempts. - Conan packaging was dropped.
Fixes
- The property engine's example database can be written by several
processes at once.