skip to content

In Catch2, how does TEMPLATE_TEST_CASE run one test body over several types, and what trips people up when listing those types?

level: middleimportance: should knowfreq 25%

answer

  1. a separate header in version 3
  2. the type is spelled TestType
  3. one test case per type
  4. commas split macro arguments

basics

~20 s

TEMPLATE_TEST_CASE(name, tags, types...) registers one test case per listed type, named "name - type", with the current type available as TestType. A type containing a comma must be wrapped in parentheses, and Catch2 3 needs catch_template_test_macros.hpp.

solid answer

~40 s

`TEMPLATE_TEST_CASE(name, tags, Type1, Type2, ...)` stamps out the body once per listed type and registers each as its own test case, named after the test plus the type, for example `stacks over several containers - std::deque<int>`. Inside the body the current type is the alias `TestType`. Three things trip people up. In Catch2 3 the macro lives in its own header, `catch2/catch_template_test_macros.hpp`; without it the code fails with unrelated-looking syntax errors. The tags argument is mandatory, although it may be an empty string. And a type such as `std::map<int, std::string>` contains a comma the preprocessor treats as an argument separator, so it must be written `(std::map<int, std::string>)`. Sections work inside as usual, and `TEMPLATE_PRODUCT_TEST_CASE` and `TEMPLATE_LIST_TEST_CASE` cover cross products and reusable type lists.

code

cpp · 19 lines
cpp
#include <catch2/catch_test_macros.hpp>
#include <catch2/catch_template_test_macros.hpp>
#include <deque>
#include <map>
#include <stack>
#include <string>
#include <vector>

TEMPLATE_TEST_CASE("stacks over several containers", "[stack][template]",
                   std::vector<int>, std::deque<int>,
                   (std::stack<int, std::vector<int>>)) {
    TestType c;
    REQUIRE(c.empty());
}

TEMPLATE_TEST_CASE("maps start empty", "", (std::map<int, std::string>)) {
    TestType m;
    REQUIRE(m.empty());
}

go deeper

for a junior

Recall the macro's shape, the TestType alias, and that each listed type becomes its own test case in the report.

for a middle

Explain why commas in a type need parentheses, why the tags argument is mandatory here, and which header Catch2 3 requires.

for a senior

Choose between the product, list and signature forms, share type lists across tests, and keep build time in check when a heavy body is instantiated many times.

for a principal

Decide which types a generic component is contractually tested over, and keep that list as one shared definition rather than per-test choices.

## One body, many types A container adaptor, a numeric routine or a generic algorithm often has to behave the same for several types. Writing the same test three times invites drift, so Catch2 offers **type-parametrised test cases**. The main macro is: ```cpp TEMPLATE_TEST_CASE( name, tags, Type1, Type2, ..., TypeN ) ``` For each listed type Catch2 instantiates the body and registers a separate test case. Inside the body the type being tested is available as **`TestType`**. How template instantiation works in the language is a subject of its own; here what matters is what the macro registers and how to feed it. ## A stack test over three containers ```cpp #include <catch2/catch_test_macros.hpp> #include <catch2/catch_template_test_macros.hpp> #include <deque> #include <stack> #include <vector> TEMPLATE_TEST_CASE("stacks over several containers", "[stack][template]", std::vector<int>, std::deque<int>, (std::stack<int, std::vector<int>>)) { TestType c; REQUIRE(c.empty()); } ``` Listing the tests shows three separate cases, one per type: ```plaintext stacks over several containers - std::vector<int> stacks over several containers - std::deque<int> stacks over several containers - std::stack<int, std::vector<int>> ``` Because each is a full test case, a failure names the type, and each case can contain sections that follow the usual re-entry rules. ## The traps 1. **The header.** In Catch2 3 the library is split into per-feature headers, and the templated macros are in `catch2/catch_template_test_macros.hpp`, not in `catch_test_macros.hpp`. Without the include, the macro is an unknown identifier and clang 21 reported `error: a type specifier is required for all declarations` on that line, which does not mention templates at all. Catch2 2's single header contained everything, which is why older examples omit the include. 2. **The tags argument is required.** For `TEST_CASE` tags are optional; for `TEMPLATE_TEST_CASE` the tags string must be present because the type list follows it, though it may be empty: `TEMPLATE_TEST_CASE("starts empty", "", int, long)`. 3. **Commas inside a type.** The preprocessor splits macro arguments at every top-level comma and does not understand angle brackets. `std::map<int, std::string>` becomes two arguments, `std::map<int` and `std::string>`. Clang reported `error: too few template arguments for class template 'map'`. Wrapping the type in parentheses, `(std::map<int, std::string>)`, keeps it as one argument, and Catch2 strips the parentheses. ## The rest of the family | Macro | Registers | Typical use | |---|---|---| | `TEMPLATE_TEST_CASE` | One case per listed type | A few concrete types | | `TEMPLATE_PRODUCT_TEST_CASE` | One case per template applied to each argument, n times m | `(std::vector, std::deque)` crossed with `(int, float)` | | `TEMPLATE_LIST_TEST_CASE` | One case per type in a type list such as `std::tuple<int, char, float>` | Reusing one list across many tests | | `TEMPLATE_TEST_CASE_SIG` | One case per argument set matching a signature | Non-type parameters, such as a size | | `TEMPLATE_TEST_CASE_METHOD` | The templated version of a fixture-based case | Templated fixtures | `TEMPLATE_LIST_TEST_CASE` is the one to reach for when the same set of types appears in several tests: define `using StackTypes = std::tuple<...>;` once and pass it to each. ## How the registered cases behave Once registered, the instantiations are ordinary, independent test cases: - **Each one can be selected by its full name**, such as `stacks over several containers - std::deque<int>`, so a failure for one type can be rerun alone. - **All instantiations share the tags** given in the macro, so a tag expression selects the whole family at once. - **They are ordered like any other cases.** Since Catch2 3.9.0 the default run order is random, so the instantiations need not run next to each other or in the listed order, and nothing may depend on that order. - **Sections inside the body re-run per type.** Each instantiation has its own leaf sections and its own runs from the top. - **A failing type does not stop the others.** Each instantiation reports its own result, which is the main advantage over a hand-written loop over types inside one test case. ## Practical advice - Keep the type list short and meaningful; each type multiplies run time and report lines. - Prefer a named type list over repeating the same types in several macros. - Put the type-independent setup in the body and the type-specific expectations in sections or helper traits, so the test reads the same for every type. - Remember that each instantiation compiles the body again, so a heavy body over many types slows the build as well as the run.

  • When would you use Catch2's TEMPLATE_LIST_TEST_CASE instead of TEMPLATE_TEST_CASE?
    When the same set of types is tested in several places. `TEMPLATE_LIST_TEST_CASE(name, tags, TypeList)` takes any type list with a `template <typename...>` signature, such as `std::tuple<int, char, float>`, so the list is defined once as an alias and reused, instead of repeating the types in every macro and letting the lists drift apart.
  • How does TEMPLATE_PRODUCT_TEST_CASE in Catch2 decide how many test cases to register?
    It takes a list of templates and a list of template arguments and registers one case per combination, so n templates and m arguments give n times m cases. For example `(std::vector, std::deque)` with `(int, float)` registers four cases, and `TestType` is each resulting type, such as `std::deque<float>`.

  • In a Catch2 template test the current type is called TypeParam.
  • TEMPLATE_TEST_CASE is available from catch_test_macros.hpp in Catch2 3.
  • A TEMPLATE_TEST_CASE can omit the tags argument like TEST_CASE.
  • Catch2 runs all listed types inside a single test case.
  • Angle brackets protect a type's comma inside a macro argument.

Assumes Catch2 3, where the templated test macros live in catch2/catch_template_test_macros.hpp; Catch2 2's single header bundled them.