Catch2 C++ Unit Testing Framework

Catch2 is a C++ testing framework designed for ease of use and minimal setup. Key advantages include:

• Minimal Setup: Can be integrated by adding files directly to your project.
• No External Dependencies: Requires only a C++14 compatible compiler and the C++ standard library.
• Self-Registering Tests: Test cases are written as functions or methods that register themselves.
• Section-Based Isolation: Use SECTION blocks to divide test cases. Each section runs in isolation, which eliminates the need for traditional test fixtures.
• BDD Support: Supports Behavior-Driven Development (BDD) style using GIVEN, WHEN, and THEN sections.
• Natural Assertion Syntax: Uses standard C/C++ operators (e.g., ==, !=) within a single core assertion macro. The framework decomposes the expression to log both the left-hand side (lhs) and right-hand side (rhs) values upon failure.
• Free-form Naming: Test cases are identified by free-form strings rather than being restricted to valid C++ identifiers.

Catch2 provides two distinct ways to filter test paths, which behave differently regarding generators.

Old Behaviour (Deprecated)

Trigger: Using only -c or --section.

• Generators: Completely ignored. They are not filtered and do not affect filter depth. If a generator is a sibling to a filtered section, the generator will still run to completion, potentially causing the code outside sections to execute multiple times.
• Example: In a test where a section A is filtered but a sibling generator exists, the generator will still exhaust all its elements.

New Behaviour

Trigger: Using -g or -p.

• Generators: Can be explicitly filtered by index (-g 0) or wildcard (-g *).
• Execution Flow: Unlike sections, a generator must be active. If a generator fails a filter (e.g., a section filter is applied at a depth where a generator exists), the generator cannot proceed, and the test case is skipped (equivalent to SKIP()).
• Precision: Allows for much tighter control over nested generators and dynamic sections.

Instead of using class-based fixtures, idiomatic Catch2 uses SECTION macros to share setup and teardown code.

When a TEST_CASE contains multiple SECTIONs, the TEST_CASE is re-executed from the start for every single section. This ensures that each section (and each leaf section in a nested tree) starts with a fresh state of any local variables declared at the top of the TEST_CASE.

Sections can be nested to create a tree of execution paths. Each run through a TEST_CASE will follow exactly one path from the root to a single leaf section.

TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
    // This setup runs once for every SECTION
    std::vector<int> v( 5 );

    REQUIRE( v.size() == 5 );

    SECTION( "resizing bigger changes size and capacity" ) {
        v.resize( 10 );
        REQUIRE( v.size() == 10 );
    }
    SECTION( "resizing smaller changes size but not capacity" ) {
        v.resize( 0 );
        REQUIRE( v.size() == 0 );
    }
}

Test running events follow a strict lifecycle where every fooStarting event is paired with a fooEnded event. This allows you to track the lifecycle of the entire test run, individual test cases, sections, and assertions.

Key pairs include:

• testRunStarting / testRunEnded: Bookend the entire test execution.
• testCaseStarting / testCaseEnded: Bookend one full run of a specific test case.
• testCasePartialStarting / testCasePartialEnded: Bookend a single partial run of a test case (e.g., a single leaf section or a single GENERATE value).
• sectionStarting / sectionEnded: Emitted only for active SECTIONs that are actually entered.
• assertionStarting / assertionEnded: Emitted around the evaluation of an assertion (e.g., REQUIRE).

void testRunStarting( TestRunInfo const& testRunInfo );
void testRunEnded( TestRunStats const& testRunStats );

void testCaseStarting( TestCaseInfo const& testInfo );
void testCaseEnded( TestCaseStats const& testCaseStats );

void testCasePartialStarting( TestCaseInfo const& testInfo, uint64_t partNumber );
void testCasePartialEnded(TestCaseStats const& testCaseStats, uint64_t partNumber );

void sectionStarting( SectionInfo const& sectionInfo );
void sectionEnded( SectionStats const& sectionStats );

void assertionStarting( AssertionInfo const& assertionInfo );
void assertionEnded( AssertionStats const& assertionStats );

Data generators (parametrized test cases) allow you to reuse the same set of assertions across different input values. When you use a generator, the TEST_CASE or SECTION containing it is re-entered for every value produced by the generator.

Key behaviors:

• Nesting: Generators respect the ordering and nesting of TEST_CASE and SECTION macros. Nested sections are run once per each value in a generator.
• Cartesian Product: If multiple GENERATE macros are used at the same scope, the test case will run a number of times equal to the Cartesian product of all elements (e.g., two generators with 2 and 3 elements result in 6 runs).
• Implicit Sections: GENERATE acts as an implicit SECTION that extends from the point of use to the end of the current scope.

To use generators, you must include:

#include <catch2/generators/catch_generators.hpp>

TEST_CASE("Generators") {
    auto i = GENERATE(1, 3, 5);
    REQUIRE(is_odd(i));
}