In Catch2, what is the difference between REQUIRE and CHECK when the asserted expression is false?
answer
- both fail the test case
- one aborts, one continues
- aborting is done by throwing
- guard what later lines depend on
basics
~20 sBoth record a failure and fail the test case. REQUIRE then aborts the current run, while CHECK continues so later assertions still report. Use REQUIRE where later code depends on the condition and CHECK for independent facts.
solid answer
~40 s`REQUIRE(expr)` and `CHECK(expr)` evaluate the same expression and report it the same way, operands included. The difference is what happens after a failure. `REQUIRE` aborts the current run of the test case, so nothing after it executes; `CHECK` records the failure and carries on, so a series of independent checks all report in one run. Either way the test case is marked failed. The rule of thumb: `REQUIRE` guards preconditions that later lines rely on, such as a container being non-empty before indexing it, and `CHECK` covers independent observations, such as several properties of one result. If the expression throws, both catch the exception and count it as a failure. `REQUIRE_FALSE` and `CHECK_FALSE` assert that something is false, because a leading `!` cannot be decomposed.
code
cpp · 18 lines#include <catch2/catch_test_macros.hpp>
#include <cmath>
#include <iostream>
struct Point { double x, y; };
double distance(Point a, Point b) { return std::hypot(b.x - a.x, b.y - a.y); }
TEST_CASE("CHECK keeps going", "[geometry]") {
CHECK(distance({0, 0}, {3, 4}) == 4.0);
CHECK(distance({0, 0}, {0, 0}) == 1.0);
std::cout << "reached the end of the CHECK case\n";
}
TEST_CASE("REQUIRE stops", "[geometry]") {
REQUIRE(distance({0, 0}, {3, 4}) == 4.0);
std::cout << "never printed\n";
REQUIRE(distance({0, 0}, {0, 0}) == 1.0);
}go deeper
Recall that REQUIRE stops the test case at the first failure and CHECK keeps going, and that both make the test case fail.
Explain that REQUIRE aborts by throwing, what that means for catch-all blocks and destructors, and how an exception from the expression is reported.
Structure assertions so a single run diagnoses as much as possible: REQUIRE for the preconditions later lines depend on, CHECK for every independent fact after them.
Set a review norm for assertion choice, so failures arrive as a complete picture rather than one rebuild per broken property.
## Two families, one expression syntax Catch2 has no `_EQUALS` or `_GREATER_THAN` macros. It takes an ordinary C++ comparison, `REQUIRE(a == b)`, and reports both sides when it fails. Almost every assertion comes in two forms that differ only in **what happens after a failure**: | Fatal form | Continuing form | Checks | |---|---|---| | `REQUIRE(expr)` | `CHECK(expr)` | the expression is true | | `REQUIRE_FALSE(expr)` | `CHECK_FALSE(expr)` | the expression is false | | `REQUIRE_THROWS_AS(expr, T)` | `CHECK_THROWS_AS(expr, T)` | an exception of type `T` | | `REQUIRE_THAT(value, matcher)` | `CHECK_THAT(value, matcher)` | a matcher accepts the value | In Catch2 3 they come from `catch2/catch_test_macros.hpp` (the matcher forms also need the matcher headers). ## What a failure does - **Both** record the failed assertion with its source line and expansion, and **both** mark the test case as failed. A `CHECK` failure is not a warning. - **`REQUIRE` aborts** the current run of the test case: the rest of the function does not execute. With sections, only the current run ends; the next run for the next section still happens. - **`CHECK` continues** with the next statement, so every independent assertion reports in one go. A run with a distance function shows the difference: ```cpp TEST_CASE("CHECK keeps going", "[geometry]") { CHECK(distance({0, 0}, {3, 4}) == 4.0); // fails: 5.0 == 4.0 CHECK(distance({0, 0}, {0, 0}) == 1.0); // fails: 0.0 == 1.0 std::cout << "reached the end\n"; // printed } TEST_CASE("REQUIRE stops", "[geometry]") { REQUIRE(distance({0, 0}, {3, 4}) == 4.0); // fails: 5.0 == 4.0 std::cout << "never printed\n"; // not reached } ``` The first case reports two failures and prints its last line; the second reports one failure and stops. ## How REQUIRE aborts `REQUIRE` stops the test by **throwing** an internal exception type after the failure has been recorded. Two consequences follow: 1. A `catch (...)` block around a `REQUIRE` swallows the abort. The failure is still recorded and the test case still fails, but the lines after the `try` block keep running, which can then crash on the very state the `REQUIRE` was guarding. 2. A failing `REQUIRE` inside a destructor, which is `noexcept` by default, or inside any other `noexcept` function throws out of a function that may not throw, so the program terminates. In a run with libc++, the binary printed `terminating due to uncaught exception of type Catch::TestFailureException` and aborted, taking every remaining test with it. A `CHECK` is the safe form there. ## Exceptions from the expression If evaluating the expression itself throws, both forms catch the exception, report it with its message, and count the assertion as failed. A degenerate triangle passed to an area function that throws `std::invalid_argument` therefore shows up as: ```plaintext a.cpp:16: FAILED: REQUIRE( triangleArea({0, 0}, {1, 1}, {2, 2}) > 0.0 ) due to unexpected exception with message: degenerate triangle ``` An unexpected exception in a `CHECK` does not abort the run either. ## Asserting that something is false The decomposer cannot see through a leading `!`. For a type that converts to `bool`, such as a status object, `REQUIRE_FALSE(status)` asserts it is false and can still print its value. For a plain `bool` variable there is nothing extra to print, so `CHECK(!ok)` and `CHECK_FALSE(ok)` say the same thing. ## What the summary counts The run summary counts assertions that actually executed. In the run above, the two cases produced `assertions: 3 | 3 failed`: two from the `CHECK` case and one from the `REQUIRE` case, whose second assertion never ran. That has practical consequences: - A `REQUIRE` that fails early **hides** every later assertion in that run, so the summary understates how much is broken. - After a fix, a previously hidden assertion can fail next, which looks like a new regression but was there all along. - Comparing assertion counts between two runs is only meaningful when both ran to the same point. The test-case line, `test cases: 2 | 2 failed`, is the same for both forms: one failed assertion of either kind is enough to fail its case. ## Choosing between them - **`REQUIRE` for preconditions**: a pointer is non-null before it is dereferenced, a vector is non-empty before `front()`, a parse succeeded before its result is inspected. Continuing after these would only produce noise or undefined behaviour. - **`CHECK` for independent facts**: the x and y of a computed point, every field of a parsed record, every element of a small table. One run then shows the whole picture. - **Mix them**: one `REQUIRE` that the result exists, followed by several `CHECK`s on its contents, is the most common healthy shape. - **Avoid `REQUIRE` everywhere by habit**: the first failure hides the rest, and fixing one at a time costs a build per failure.
- What happens when a Catch2 REQUIRE fails inside a try block with a catch (...) handler?The failure is recorded first, so the test case still fails. But `REQUIRE` aborts by throwing an internal exception, and `catch (...)` swallows it, so execution continues after the `try` block. The lines that the `REQUIRE` was meant to protect then run anyway. Catch specific exception types in test code, or keep assertions outside catch-all blocks.
- Does a failed Catch2 CHECK in one section stop the other sections of the test case?No. A `CHECK` does not even stop its own section; execution continues to the next statement. A `REQUIRE` ends only the current run of the test case, and Catch2 still re-enters the case for each remaining section. In both cases the test case is reported as failed.
- A failed CHECK is only a warning; the test case still passes.
- REQUIRE stops the entire test binary on failure.
- CHECK should be avoided because it hides failures.
- An exception thrown inside REQUIRE's expression crashes the test run.
- REQUIRE(!status) prints the value of status when it fails.