skip to content

In Catch2, how does GENERATE run one TEST_CASE once per value, and what do the take, filter and range adaptors do?

level: middleimportance: should knowfreq 25%

answer

  1. a generator re-enters the case
  2. two generators multiply
  3. range stops before the end
  4. no local variables inside

basics

~20 s

GENERATE(1, 3, 5) makes Catch2 enter the test case once per value, and several GENERATE calls give their cartesian product. Adaptors build sequences: range(a, b) stops before b, filter keeps matching values, take keeps the first n.

solid answer

~40 s

`auto i = GENERATE(1, 3, 5);` registers a generator at that point of the test case, and Catch2 re-enters the case once for each value, the way it re-enters for each section. Two `GENERATE` calls in the same scope produce the cartesian product: `GENERATE(1, 2)` followed by `GENERATE(10, 20, 30)` runs the case six times. The adaptors in `catch2/generators/catch_generators_adapters.hpp` transform other generators: `filter(pred, gen)` drops values the predicate rejects, `take(n, gen)` stops after `n` values, and `map`, `repeat` and `chunk` reshape them. `range(0, 5)` from `catch_generators_range.hpp` yields 0 to 4, a half-open interval. A `GENERATE` expression may not use local variables, because the generator outlives the current run; `GENERATE_COPY` and `GENERATE_REF` opt in explicitly, and `as<std::string>{}` fixes the value type.

code

cpp · 22 lines
cpp
#include <catch2/catch_test_macros.hpp>
#include <catch2/generators/catch_generators.hpp>
#include <catch2/generators/catch_generators_adapters.hpp>
#include <catch2/generators/catch_generators_range.hpp>
#include <iostream>

TEST_CASE("generate basics", "[gen]") {
    int i = GENERATE(1, 2);
    int j = GENERATE(10, 20, 30);
    std::cout << i << "," << j << " ";
    CHECK(i < j);
}

TEST_CASE("range is half open", "[gen]") {
    int n = GENERATE(range(0, 5));
    std::cout << n << " ";
}

TEST_CASE("adaptors", "[gen]") {
    int n = GENERATE(take(3, filter([](int x) { return x % 2 == 1; }, range(0, 100))));
    std::cout << n << " ";
}

go deeper

for a junior

Recall that GENERATE runs the test case once per value and that two generators give every combination.

for a middle

Explain the re-entry mechanism behind generators, the half-open range, how adaptors nest, and why local variables need GENERATE_COPY.

for a senior

Keep data-driven tests affordable and reproducible: count the product of generators, pin seeds for random inputs, and prefer table for related inputs.

for a principal

Decide where value-parameterised cases belong in a suite, weighing broad input coverage against run time and the readability of failures in CI reports.

## Data-driven cases without loops A **generator** lets one test case run its assertions over several input values. In Catch2 it is introduced with the `GENERATE` macro from `catch2/generators/catch_generators.hpp`: ```cpp TEST_CASE("polygon side counts", "[gen]") { int sides = GENERATE(3, 4, 6); REQUIRE(sides >= 3); } ``` The test case is entered **three times**, with `sides` equal to 3, 4 and 6 in turn. This is the same re-entry mechanism sections use: everything before the `GENERATE` runs on every pass, and each value gets fresh locals. Unlike a hand-written loop, each value is a separate pass, so a failure for one value does not hide the others, and the report shows which value failed when the value is logged or used in an assertion. ## Several generators multiply Two `GENERATE` calls in the same scope give the **cartesian product**. With `GENERATE(1, 2)` followed by `GENERATE(10, 20, 30)`, a run printed `1,10 1,20 1,30 2,10 2,20 2,30`: six passes, the later generator varying fastest. That growth is the main cost to watch; three generators of ten values each mean a thousand passes. ## Building sequences with adaptors Catch2 3.16.1 provides generator helpers, each in a documented header: | Helper | Yields | Header | |---|---|---| | `values({...})`, `value(x)` | listed values | `catch_generators.hpp` | | `table<Ts...>({...})` | tuples, for several inputs per pass | `catch_generators.hpp` | | `range(start, end)`, `range(start, end, step)` | arithmetic values in `[start, end)` | `catch_generators_range.hpp` | | `from_range(first, last)`, `from_range(container)` | copies of a container's elements | `catch_generators_range.hpp` | | `random(a, b)` | uniform random values in the closed interval `[a, b]` | `catch_generators_random.hpp` | | `filter(pred, gen)`, `take(n, gen)`, `repeat(n, gen)`, `map(f, gen)`, `chunk(n, gen)` | transformed sequences | `catch_generators_adapters.hpp` | | `cat(gens...)` | several generators in sequence, added in 3.13.0 | `catch_generators_adapters.hpp` | The half-open range is a frequent slip: `range(0, 5)` produced `0 1 2 3 4`. Adaptors nest, so `take(3, filter(is_odd, range(0, 100)))` produced `1 3 5`. `GENERATE` itself also mixes plain values and generators, as in `GENERATE(0, 2, take(100, random(300, 3000)))`, which runs a few known awkward inputs first. ## The variable restriction A generator is created on the first pass and kept for later passes, so it **outlives** the scope in which `GENERATE` appears. To stop accidental dangling references, the macro builds its expression in a lambda with no captures. Using a local variable therefore fails to compile; clang 21 reported: ```plaintext error: variable 'limit' cannot be implicitly captured in a lambda with no capture-default specified ``` Two explicit forms exist: 1. `GENERATE_COPY(1, limit)` copies the variables it uses, which is safe for values. 2. `GENERATE_REF(...)` captures by reference, which is only safe when the referenced objects outlive every pass, for example a `static` table. ## Typing the values `GENERATE("a", "bb", "ccc")` deduces `const char*`. Passing `as<std::string>{}` first, as in `GENERATE(as<std::string>{}, "a", "bb")`, makes the values `std::string`. `map<T>(f, gen)` performs an explicit conversion inside the pipeline. ## Random values and reproducibility - `random(a, b)` produces values in the closed interval `[a, b]`; since Catch2 3.5.0 these are Catch2's own distributions rather than thin wrappers over `<random>`. - The values follow the run's random seed, which is printed at the start of every run and can be fixed with `--rng-seed`, so a failing random input can be reproduced. - The documentation states that, for the same seed, the integral generators give the same output on every platform. ## Failures and the report Each value is a separate pass, so a failing `REQUIRE` ends only that pass. A case generating `3, 2, 6` with `REQUIRE(sides >= 3)` failed for 2, printed the expansion `2 >= 3`, and still ran the pass for 6: three assertions, one failed. Two habits keep such failures readable: - Use the generated value **inside** the assertion, so decomposition prints it. - When the value is not part of the failing expression, log it with `CAPTURE` before asserting, so the report says which input broke. ## When a generator is the right tool - The same assertions over a handful of inputs: a generator keeps one body and a separate pass per value. - Inputs that need a name in the report, or set-up that differs per input: sections, or separate test cases, read better. - Generators combine with sections in ways that multiply passes quickly, which is worth counting before committing to a design.

  • How do you feed several related inputs and an expected result into one Catch2 generator?
    Use `table<Ts...>` with tuples, for example `auto [w, h, area] = GENERATE(table<int, int, int>({ {2, 3, 6}, {4, 5, 20} }));`. Each tuple is one pass, and structured bindings (C++17) unpack it. This keeps the inputs and the expected value together, which a cartesian product of separate generators cannot do.
  • How do you reproduce a failure that came from Catch2's random generator?
    Rerun the binary with `--rng-seed` set to the seed printed at the start of the failing run. The random generators draw from that seed, so the same seed reproduces the same sequence of values, and the documentation states the integral generators give the same output across platforms for a given seed.

  • GENERATE evaluates all its values in one pass through the test case.
  • Two GENERATE calls in one scope run their values in parallel pairs.
  • range(0, 5) includes 5.
  • A local variable can be used inside GENERATE like any other expression.
  • Random generator values in Catch2 cannot be reproduced.