Catch2 testing framework
Go to file
Chris Thrasher 1078e7e95b Fix clang-tidy `bugprone-chained-comparison` warnings
This triggers when running clang-tidy's bugprone-* family of checks
in code which uses Catch2 even if Catch2 headers are marked as
SYSTEM headers due to how code expanded from macros is treated as
first party even if the macro comes from a 3rd party library. The
fix is luckily pretty straightforward.

This check is added in clang-tidy-18 due for release later this year.
2024-01-24 22:41:00 -07:00
.conan Add support for Components 2020-11-02 15:37:35 +01:00
.github Run tests on all cores in GHA jobs 2024-01-15 14:22:45 +01:00
CMake Add Wsubobject-linkage to warning flags 2024-01-14 21:22:09 +01:00
data/artwork Use logo with bit of white background in README 2022-11-22 16:13:37 +01:00
docs Fix typo in release notes for v3.5.2 2024-01-15 14:23:00 +01:00
examples Fix adding Opts with | to lvalue Parser 2024-01-02 23:27:13 +01:00
extras v3.5.2 2024-01-15 14:13:53 +01:00
fuzzing Add nice license headers to files in examples/ and fuzzing/ 2023-08-24 16:34:31 +02:00
src Fix clang-tidy `bugprone-chained-comparison` warnings 2024-01-24 22:41:00 -07:00
tests Add tests for scaled ULP distance between +/- FLT/DBL_MAX 2024-01-14 21:15:02 +01:00
third_party fixing UB 2020-07-22 17:17:33 +02:00
tools Look just for 'Catch2 X.Y.Z' in doc placeholder update 2023-12-11 00:52:22 +01:00
.bazelrc Bazel support: Bump bazel-skylib version to 1.5.0 2023-12-28 23:44:26 +01:00
.clang-format Slightly better clang-format 2023-01-05 23:02:51 +01:00
.gitattributes Update gitattributes 2018-07-23 10:15:52 +02:00
.gitignore Add support for building with Meson (#2530) 2022-10-01 23:28:30 +02:00
BUILD.bazel Introduce CATCH_CONFIG_PREFIX_MESSAGES to only prefix a few logging related macros. (#2544) 2023-07-19 17:04:43 +02:00
CMakeLists.txt v3.5.2 2024-01-15 14:13:53 +01:00
CMakePresets.json Add test scaffolding for catch_discover_tests 2023-06-14 21:14:33 +02:00
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md 2017-08-17 07:45:12 +01:00
Doxyfile Update Doxyfile for newer doxygen 2023-12-23 11:27:46 +01:00
LICENSE.txt Renamed licence file, license should now be detected by github 2017-03-20 08:59:25 +01:00
MODULE.bazel Bazel support: Bump bazel-skylib version to 1.5.0 2023-12-28 23:44:26 +01:00
README.md Mention that the benchmarks are not run by default next to example 2022-12-18 21:42:40 +01:00
SECURITY.md Add SECURITY.md 2021-11-26 00:10:01 +01:00
WORKSPACE.bazel Bazel support: Bump bazel-skylib version to 1.5.0 2023-12-28 23:44:26 +01:00
appveyor.yml Drop VS 2017 support 2023-12-08 23:54:00 +01:00
codecov.yml Sweep out two leftover references to master 2020-10-23 23:02:44 +02:00
conanfile.py Add lib/cmake/Catch2 to conan builddirs in package recipe so extras/*.cmake files are packaged 2022-06-15 10:50:24 +02:00
mdsnippets.json Add infrastructure for embedding code samples in docs. 2020-10-28 11:38:06 +01:00
meson.build v3.5.2 2024-01-15 14:13:53 +01:00
meson_options.txt Add option to disable building unit tests in Meson build file. 2023-05-26 10:05:06 -07:00

README.md

Catch2 logo

Github Releases Linux build status Linux build status MacOS build status Build Status Code Coverage Try online Join the chat in Discord: https://discord.gg/4CWS9zD

What is Catch2?

Catch2 is mainly a unit testing framework for C++, but it also provides basic micro-benchmarking features, and simple BDD macros.

Catch2's main advantage is that using it is both simple and natural. Test names do not have to be valid identifiers, assertions look like normal C++ boolean expressions, and sections provide a nice and local way to share set-up and tear-down code in tests.

Example unit test

#include <catch2/catch_test_macros.hpp>

#include <cstdint>

uint32_t factorial( uint32_t number ) {
    return number <= 1 ? number : factorial(number-1) * number;
}

TEST_CASE( "Factorials are computed", "[factorial]" ) {
    REQUIRE( factorial( 1) == 1 );
    REQUIRE( factorial( 2) == 2 );
    REQUIRE( factorial( 3) == 6 );
    REQUIRE( factorial(10) == 3'628'800 );
}

Example microbenchmark

#include <catch2/catch_test_macros.hpp>
#include <catch2/benchmark/catch_benchmark.hpp>

#include <cstdint>

uint64_t fibonacci(uint64_t number) {
    return number < 2 ? number : fibonacci(number - 1) + fibonacci(number - 2);
}

TEST_CASE("Benchmark Fibonacci", "[!benchmark]") {
    REQUIRE(fibonacci(5) == 5);

    REQUIRE(fibonacci(20) == 6'765);
    BENCHMARK("fibonacci 20") {
        return fibonacci(20);
    };

    REQUIRE(fibonacci(25) == 75'025);
    BENCHMARK("fibonacci 25") {
        return fibonacci(25);
    };
}

Note that benchmarks are not run by default, so you need to run it explicitly with the [!benchmark] tag.

Catch2 v3 has been released!

You are on the devel branch, where the v3 version is being developed. v3 brings a bunch of significant changes, the big one being that Catch2 is no longer a single-header library. Catch2 now behaves as a normal library, with multiple headers and separately compiled implementation.

The documentation is slowly being updated to take these changes into account, but this work is currently still ongoing.

For migrating from the v2 releases to v3, you should look at our documentation. It provides a simple guidelines on getting started, and collects most common migration problems.

For the previous major version of Catch2 look into the v2.x branch here on GitHub.

How to use it

This documentation comprises these three parts:

More