skip to content

A Catch2 test wraps a stack pop in SECTION("pop once") inside a three-iteration for loop, yet the section body runs only once. Why, and how do you fix it?

level: seniorimportance: should knowfreq 25%

answer

  1. how does Catch2 recognise a section
  2. same name, same line
  3. one leaf per run, then skip
  4. a name built at run time

basics

~20 s

Catch2 identifies a section by name and source location, so every iteration meets one section: it runs once, later iterations skip it, and it is then complete. DYNAMIC_SECTION("pop with i = " << i) makes one section, and one run, per iteration.

solid answer

~50 s

Catch2 keeps a tracker per section keyed by its **name and source location**. In a loop, every iteration reaches the same `SECTION("pop once")` on the same line, so they are one section, not three. On the first run the section is entered at `i == 0`; once that leaf completes, Catch2 enters no further section in that run, so iterations 1 and 2 skip it. The tracker is then complete, the case has no unfinished leaf, and there is no second run. The fix is `DYNAMIC_SECTION("pop with i = " << i)`, whose name is built at run time: each iteration now names a distinct section, each becomes a leaf with its own run from the top, and each pops a freshly built stack. If the pops were meant to accumulate on one stack, the loop belongs inside a single section instead.

code

cpp · 27 lines
cpp
#include <catch2/catch_test_macros.hpp>
#include <iostream>
#include <vector>

TEST_CASE("pop in a loop", "[stack][loop]") {
    std::vector<int> stack{1, 2, 3};
    std::cout << "run starts\n";
    for (int i = 0; i < 3; ++i) {
        SECTION("pop once") {
            std::cout << "  SECTION entered, i = " << i << '\n';
            stack.pop_back();
            CHECK(stack.size() == 2u);
        }
    }
}

TEST_CASE("pop in a loop, fixed", "[stack][loop]") {
    std::vector<int> stack{1, 2, 3};
    std::cout << "run starts\n";
    for (int i = 0; i < 3; ++i) {
        DYNAMIC_SECTION("pop with i = " << i) {
            std::cout << "  DYNAMIC_SECTION entered, i = " << i << '\n';
            stack.pop_back();
            CHECK(stack.size() == 2u);
        }
    }
}

go deeper

for a junior

Recall that SECTION blocks are entered or skipped by the runner, and that DYNAMIC_SECTION takes a name built with the stream operator.

for a middle

Explain that sections are tracked by name and source location, and trace why repeated encounters in one run are skipped.

for a senior

Diagnose the silent gap from an assertion count, choose between dynamic sections, one cumulative section or generators, and catch the helper-function variant in review.

for a principal

Push for test reviews that check assertion counts and section names, so silent coverage gaps from structure, not logic, are caught before they mislead a team.

## The symptom A test author wants to check that popping a three-element stack leaves two elements, and to repeat the check for several values of a loop variable. The natural code puts a `SECTION` inside a `for` loop. The test passes, but a print inside the section shows it ran only for `i == 0`. Nothing failed, so the gap is easy to miss in review and only shows up when someone counts assertions. ## How Catch2 recognises a section Sections are not functions; they are blocks that Catch2 decides to enter or skip on each run of the test case. To make that decision it keeps a tree of **trackers**, one per section. In the Catch2 3.16.1 source, a section's tracker is looked up among its parent's children by **name and source location** (`NameAndLocation`). Three facts matter here: - Two encounters with the same name on the same line find the **same tracker**. - Once a leaf section has completed in the current run, the run's cycle is complete and no further section opens in that run. - A tracker that has completed never opens again in later runs. ## Tracing the loop ```cpp TEST_CASE("pop in a loop", "[stack][loop]") { std::vector<int> stack{1, 2, 3}; for (int i = 0; i < 3; ++i) { SECTION("pop once") { stack.pop_back(); CHECK(stack.size() == 2u); } } } ``` 1. Run 1 starts and builds the stack. 2. At `i == 0` the section is met for the first time, opened and executed: one pop, one check. 3. At `i == 1` and `i == 2` the same tracker is found, but a leaf has already completed in this run, so the body is skipped. 4. At the end of run 1 the section's tracker is complete. The case has no other sections, so it is finished. Result: one run, one assertion, `i == 0` only. A print in the setup confirms `run starts` appears once. ## The fix: a run-time name `DYNAMIC_SECTION` accepts a streamed expression, so its name is built while the test runs: ```cpp for (int i = 0; i < 3; ++i) { DYNAMIC_SECTION("pop with i = " << i) { stack.pop_back(); CHECK(stack.size() == 2u); } } ``` Now each iteration produces a different name, so there are three trackers and three leaves: | Run | Section entered | Stack before the pop | |---|---|---| | 1 | pop with i = 0 | `{1, 2, 3}` | | 2 | pop with i = 1 | `{1, 2, 3}` | | 3 | pop with i = 2 | `{1, 2, 3}` | Each run executes the whole loop, enters only the one section that has not run, and skips the others. Each section therefore pops a freshly built stack and the size check passes three times. The names also appear in failure reports, so a failure says which iteration broke. ## Choosing the right shape The two shapes test different things, and the choice comes before the macro: - **Independent scenarios per value**: use `DYNAMIC_SECTION` in the loop. Each value gets fresh setup and its own entry in the report. - **One cumulative scenario**: put the loop inside one ordinary `SECTION`, or in the test body, so the pops accumulate on the same stack. - **Values as data**: Catch2's value generators run a case once per value without a hand-written loop, a mechanism covered with the generator material. ## Related traps with the same cause - **Copy-pasted sibling sections with the same name** on different lines are distinct, because the location differs. They run separately but are indistinguishable in a report; give them different names. - **A `SECTION` in a helper function called twice** in one test case hits the same name and line twice, so the second call's section is skipped in that run. Pass a distinguishing name and use `DYNAMIC_SECTION`. - **A section filter on the command line** must match a dynamic section's generated name, such as `pop with i = 2`, which is another reason to keep those names short and predictable. ## Reviewing for it - Search test code for `SECTION(` lexically inside `for`, `while` or range-for bodies. - Compare the assertion count in the run summary with the count the author expects; a loop of three that contributes one assertion is the tell.

  • Why does each DYNAMIC_SECTION in the fixed Catch2 loop see a stack of three elements rather than a shrinking one?
    Because each dynamic section is a separate leaf, and Catch2 gives every leaf its own run of the test case from the top. Each run constructs the vector again, executes the whole loop, enters only the one section that has not run yet and skips the rest, so exactly one `pop_back` happens per run.
  • In Catch2, what goes wrong when a helper function containing a SECTION is called twice from one test case?
    Both calls reach a section with the same name on the same line, so Catch2 sees one section. The first call enters it; the second call, in the same run, finds a leaf already completed and skips it, and later runs skip it as complete. Passing a distinguishing name into the helper and using `DYNAMIC_SECTION` makes the two calls separate sections.

  • Catch2 runs a SECTION inside a loop once per iteration.
  • Catch2 identifies a section by its name alone.
  • The fix is to move the stack's construction inside the section.
  • A skipped section in Catch2 is reported as a failure.