skip to content

REQUIRE and CHECK

REQUIRE stops a case while CHECK continues, and both decompose a plain expression to print each operand. Interviewers ask how matchers and approximate comparisons work.

on this pageshow

explore

questions

5

In Catch2, what is the difference between REQUIRE and CHECK when the asserted expression is false?

level: juniorimportance: must knowfreq 50%

answer

  1. both fail the test case
  2. one aborts, one continues
  3. aborting is done by throwing
  4. guard what later lines depend on

basics

~20 s

Both 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
cpp
#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

for a junior

Recall that REQUIRE stops the test case at the first failure and CHECK keeps going, and that both make the test case fail.

for a middle

Explain that REQUIRE aborts by throwing, what that means for catch-all blocks and destructors, and how an exception from the expression is reported.

for a senior

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.

for a principal

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.
open as a page

In Catch2 3, how do you compare a computed double against an expected value, and when do WithinRel and WithinAbs differ?

level: middleimportance: must knowfreq 40%

basics

~20 s

Use REQUIRE_THAT with Catch::Matchers::WithinRel or WithinAbs instead of ==. WithinRel scales its tolerance with the values' magnitude, defaulting to 100 machine epsilons; WithinAbs uses a fixed margin, which is what works when the expected value is zero.

open as a page

In Catch2, how do INFO and CAPTURE add context to a failing assertion, and how long does each message stay attached?

level: middleimportance: should knowfreq 30%

basics

~20 s

INFO streams a message and CAPTURE logs "expression := value"; both attach to every assertion in their enclosing scope and print only beside failures. Each disappears at the end of its block, so loop context resets per iteration.

open as a page

In Catch2, how do REQUIRE_THROWS_AS, REQUIRE_THROWS_WITH and REQUIRE_THROWS_MATCHES differ when testing that a degenerate triangle throws?

level: middleimportance: should knowfreq 35%

basics

~20 s

REQUIRE_THROWS_AS checks the exception's type, accepting derived types. REQUIRE_THROWS_WITH checks its message as a string, exactly or through a string matcher. REQUIRE_THROWS_MATCHES checks the type and then applies a matcher, such as Message, to the caught exception.

open as a page

Why does REQUIRE(p.x == 3.0 && p.y == 4.0) fail to compile in Catch2, and what do you lose by wrapping it in parentheses?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Catch2 decomposes an assertion through overloaded operators to print both operands, and deliberately rejects && and || with a static_assert. Extra parentheses compile but turn the expression into one bool, so a failure prints only "false"; split it instead.

open as a page