In Catch2, how do INFO and CAPTURE add context to a failing assertion, and how long does each message stay attached?
answer
- context for the next failures
- a scoped object, not a print
- name := value
- unscoped lasts one assertion
basics
~20 sINFO 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.
solid answer
~40 s`INFO("tip index " << i)` declares a scoped message object: it is attached to every assertion that follows in the same block, and the console reporter prints it only beside a failure, so passing runs stay quiet. When the block ends, the message is removed, which makes it the right tool inside a loop: a failure in iteration 1 reports `tip index 1`, and an assertion after the loop no longer carries it. `CAPTURE(x, y)` is a shortcut that logs each expression with its value, printing `x := 2.0` and `y := 0.0`. Outer messages remain attached inside inner blocks, so a failure lists the whole stack of context. `UNSCOPED_INFO` instead attaches to the next assertion only, which suits helper functions, and `UNSCOPED_CAPTURE` arrived in Catch2 3.13.0. `WARN` always prints and never fails.
code
cpp · 23 lines#include <catch2/catch_test_macros.hpp>
#include <cmath>
#include <stdexcept>
#include <vector>
struct Point { double x, y; };
double triangleArea(Point a, Point b, Point c) {
double twice = (b.x - a.x) * (c.y - a.y) - (c.x - a.x) * (b.y - a.y);
if (twice == 0.0) throw std::invalid_argument("degenerate triangle");
return std::fabs(twice) / 2.0;
}
TEST_CASE("areas of a fan of triangles", "[geometry]") {
const std::vector<Point> tips{{1, 1}, {2, 0}, {3, 3}};
INFO("base is (0,0)-(1,0)");
for (std::size_t i = 0; i < tips.size(); ++i) {
INFO("tip index " << i);
double x = tips[i].x, y = tips[i].y;
CAPTURE(x, y);
CHECK_NOTHROW(triangleArea({0, 0}, {1, 0}, tips[i]));
}
CHECK(tips.size() == 4);
}go deeper
Recall that INFO and CAPTURE add context that appears with a failing assertion, and that CAPTURE prints name := value.
Explain the scope rule: messages attach to assertions in their block, vanish at its end, and stack with outer messages, which is why they suit loops.
Make failures self-diagnosing in data-driven tests, use unscoped messages from helpers, and recognise when heavy logging means an assertion should be split.
Set the expectation that a red test explains itself from its report alone, which keeps triage cheap when failures arrive from CI rather than a local debugger.
## The problem they solve An assertion inside a loop or a helper often fails with operands that do not identify the case: `CHECK_NOTHROW(triangleArea(base0, base1, tips[i]))` fails, but for which `i`? Printing with `std::cout` floods the output on every passing run. Catch2's **logging macros** attach context to assertions instead, and the reporter shows it only where it matters. ## INFO: a scoped message `INFO( message expression )` takes a streamed expression without a leading `<<`, as in `INFO("tip index " << i)`. In the Catch2 3.16.1 source it declares a local `ScopedMessage` object, so its lifetime is the enclosing block. The documented behaviour: - The message is associated with **every assertion in its scope**, passing or failing. - The console reporter prints it only with assertions it reports, which by default means failures; `-s` shows passing assertions and their messages too. - When the block ends, the message is removed from the buffer. - Messages from outer blocks remain attached inside inner ones, so a failure lists all the context that is in scope. ## CAPTURE: name and value `CAPTURE(expr1, expr2, ...)` logs each expression's text and its value at the moment of capture. `CAPTURE(x, y)` produces `x := 2.0` and `y := 0.0`. It accepts any expression, such as `a + b` or a function call. An expression containing a template argument list with a comma, such as `std::pair<int, int>{1, 2}`, must be wrapped in parentheses so the preprocessor does not split it. `CAPTURE` has the same scope rules as `INFO`. ## A loop of triangles ```cpp TEST_CASE("areas of a fan of triangles", "[geometry]") { const std::vector<Point> tips{{1, 1}, {2, 0}, {3, 3}}; INFO("base is (0,0)-(1,0)"); for (std::size_t i = 0; i < tips.size(); ++i) { INFO("tip index " << i); double x = tips[i].x, y = tips[i].y; CAPTURE(x, y); CHECK_NOTHROW(triangleArea({0, 0}, {1, 0}, tips[i])); } CHECK(tips.size() == 4); } ``` The tip `(2, 0)` is collinear with the base, so iteration 1 throws. The report for that failure lists the outer `INFO`, then `tip index 1`, `x := 2.0`, `y := 0.0`, and the exception's message. The final `CHECK` fails too, and its report carries only `base is (0,0)-(1,0)`: the loop's messages ended with their iteration. Iterations 0 and 2 passed and printed nothing. ## Unscoped variants Sometimes the context is produced somewhere whose scope ends before the assertion, typically a helper function: | Macro | Attached to | Removed | |---|---|---| | `INFO`, `CAPTURE` | every assertion in the enclosing scope | at the end of the scope | | `UNSCOPED_INFO` | the first following assertion | after that assertion, section or test case, whichever comes first | | `UNSCOPED_CAPTURE` | as `UNSCOPED_INFO` | as `UNSCOPED_INFO`; added in Catch2 3.13.0 | Unscoped messages are never carried from one test case into the next. ## Related message macros - `WARN(msg)` always prints its message and does not fail the test. - `FAIL(msg)` reports the message and fails the test case, aborting like `REQUIRE`; `FAIL_CHECK(msg)` fails without aborting. - `SUCCEED(msg)` records the message as a passing result. ## Messages and sections Scope rules combine with the section model. A message logged at the top of a test case is attached to assertions in every section, because each run executes it again. A message logged inside a section is attached only to the assertions in that section. The Catch2 documentation's own example logs one message at the top and one in each of two sections: a failure in section A reports the top message and section A's message, while a failing assertion after both sections reports only the top message. ## Why not print statements - A `std::cout` line prints on every run, passing or failing, and its output is not tied to any particular assertion. - Reporters other than the console one, such as the JUnit and XML reporters, receive messages as part of the assertion they belong to, so the context reaches a CI dashboard instead of a scrolled-away log. ## Using them well 1. Put `INFO` or `CAPTURE` **before** the assertion it explains; a message logged after the last assertion in its scope is attached to nothing. 2. Inside loops, log the loop variable and the input, not the expected output, which the assertion already prints. 3. Prefer `CAPTURE` for raw values and `INFO` for a sentence that names the scenario. 4. Do not use them as a substitute for decomposition: a failure that prints `false` plus five `CAPTURE` lines usually means the assertion should be split.
- Why does an INFO written after the last assertion in a Catch2 block never appear?An `INFO` message is attached to assertions that run while it is in scope. If no assertion follows it before the block ends, the message object is destroyed with nothing to attach to. Logging context must come before the assertion it explains, which is the opposite habit from printing a trace after the fact.
- When would you use UNSCOPED_INFO instead of INFO in Catch2?When the context is produced inside a helper function or an inner block that ends before the assertion runs. A scoped `INFO` would be removed at the helper's closing brace; `UNSCOPED_INFO` survives that and attaches to the first assertion that follows, then is cleared after that assertion, section or test case.
- INFO prints its message immediately, like a log statement.
- An INFO inside a loop keeps every iteration's message until the test ends.
- CAPTURE only works with plain variable names.
- INFO messages are shown for every passing assertion by default.
- WARN makes the test case fail.