skip to content

Sections and BDD Macros

TEST_CASE takes a name and tags, and each SECTION re-runs the case from the top so sibling sections share fresh setup. Interviewers ask how sections replace fixtures.

on this pageshow

explore

questions

6

In Catch2, what do the name and tags arguments of TEST_CASE do, and how do tags decide which tests run?

level: juniorimportance: must knowfreq 45%

answer

  1. free-form name, bracketed tags
  2. uniqueness covers name plus tags
  3. a leading dot hides
  4. next to each other means and

basics

~20 s

TEST_CASE takes a free-form quoted name and an optional string of bracketed tags such as "[stack][fast]". Name plus tags must be unique in the binary; tags group cases for selection, and a [.] tag hides one from the default run.

solid answer

~40 s

`TEST_CASE( name [, tags] )` registers a test automatically: the name is any quoted string, and the optional tags argument is one string of bracketed tags, for example `"[stack][fast]"`. Catch2 requires the combination of name and tags to be unique in the executable; a duplicate compiles, but the runner reports it at start-up and runs nothing. Tags are case-insensitive, may contain spaces, and exist so you can select groups: `[stack][fast]` picks cases carrying both tags, `[stack],[fast]` picks either, and `~[slow]` excludes. Tags that start with a non-alphanumeric character are reserved: `[.]`, or the `[.name]` shortcut, hides a case from the default run until it is selected, `[!mayfail]` reports failures without failing the case, `[!shouldfail]` fails it if it passes, and `[!throws]` lets `--nothrow` skip it.

go deeper

for a junior

Recall the two arguments: a free-form name and an optional string of bracketed tags. Know that a dot-prefixed tag hides a case and that name plus tags must be unique.

for a middle

Explain when uniqueness is checked (at registration, not compile time), the and, or and not rules of a tag expression, and what each special tag changes in a run.

for a senior

Show how a tag vocabulary shapes CI: hidden integration cases, cost tags for fast local runs, and why [!mayfail] needs an owner so it does not quietly mute a regression.

for a principal

Frame tags as the contract between test authors and pipelines: a small agreed vocabulary that jobs select on, reviewed like any other interface, rather than ad hoc labels per author.

## What TEST_CASE declares In Catch2 a test is a block of code introduced by the `TEST_CASE` macro. The macro expands to a uniquely named function plus a static object that **registers** that function with the runner before `main` starts, so nothing else has to list the test anywhere. In Catch2 3 the macro lives in `catch2/catch_test_macros.hpp`. ```cpp #include <catch2/catch_test_macros.hpp> #include <vector> TEST_CASE("a new stack is empty", "[stack][fast]") { std::vector<int> stack; REQUIRE(stack.empty()); } ``` The two arguments are: - **The test name**: a free-form quoted string. It is what reports print and what a name filter matches, so it should read like a sentence about behaviour. - **The tags**: an optional quoted string holding one or more tags, each in square brackets. `TEST_CASE` works with no tags at all; the templated test macros, by contrast, require the tags argument even if it is an empty string. ## The uniqueness rule The documentation states that the **combination of test name and tags must be unique** within the executable. A clash is not a compile error, because each expansion gets its own function name. It is caught when the runner starts. Two cases declared identically produced this, and the binary ran nothing and exited with a failure status: ```plaintext error: test case "stack starts empty", with tags "[stack]" already defined. First seen at e.cpp:2 Redefined at e.cpp:3 ``` The same name with different tags does register both cases. That is legal and usually a mistake: listings show two identical names and a filter by that name selects both. ## Tag syntax - Tags are **not case-sensitive**: `[Stack]` and `[stack]` are the same tag. - A tag may contain any ASCII character, spaces included, so `[tag with spaces]` is valid. Escapes are not supported, so `[\]]` is not a tag. - Writing the same tag twice on one case keeps one instance. - A case may carry any number of tags; a tag is a label, not a hierarchy. ## Reserved and special tags Every tag that begins with a non-alphanumeric character is reserved by Catch2. The ones the runner gives meaning to: | Tag | Effect | |---|---| | `[.]` | Hides the case from the default run; it runs only when selected by a tag or a name | | `[.integration]` | Shortcut for `[.][integration]`: hidden, but selectable as `[integration]` | | `[!throws]` | Marks a case likely to throw; `-e` / `--nothrow` skips it | | `[!mayfail]` | Failed assertions are reported but do not fail the case | | `[!shouldfail]` | Like `[!mayfail]`, but the case fails if it passes | | `[!nonportable]` | Documents that behaviour may vary between platforms or compilers | | `[!benchmark]` | Marks a benchmark case, which currently only hides it by default | | `[#file]` | Added automatically when the runner is started with `-#` | ## Selecting cases by tag Tags exist so a run can pick a group of cases. A **tag expression** follows three rules: 1. Tags written next to each other must all match: `[widget][gadget]` selects cases carrying both. 2. A comma means or: `[widget],[gadget]` selects cases carrying either. 3. A tilde negates: `[stack]~[slow]` selects cases tagged `stack` that are not tagged `slow`. A hidden case is still selected when an expression names one of its tags, which is the point of `[.integration]`: the default developer run stays fast, and a CI job asks for `[integration]` explicitly. The full command-line filter syntax, with wildcarded names and section filters, belongs to the material on running the test binary. ## Tag aliases A long expression used often can be given a name in code with `CATCH_REGISTER_TAG_ALIAS`. Aliases must begin with `@`: ```cpp CATCH_REGISTER_TAG_ALIAS("[@nhf]", "[failing]~[.]") ``` Passing `[@nhf]` then selects every case tagged `failing` that is not hidden. ## Conventions that pay off - Name cases after behaviour (`"pop on an empty stack throws"`), not after functions, so a failure line explains itself. - Keep a small, stable tag vocabulary: one tag per component (`[stack]`), one per cost class (`[slow]`), one per environment need (`[.integration]`). - Treat `[!mayfail]` as a tracked debt, not a mute button; `[!shouldfail]` tells you when a known bug has been fixed by accident.

  • Can two Catch2 test cases share a name if their tags differ?
    Yes. The uniqueness rule covers the combination of name and tags, so `TEST_CASE("stack starts empty", "[stack]")` and the same name with `"[stack][slow]"` both register and run. It is still a poor idea: `--list-tests` shows two identical names, and a filter by that name selects both cases.
  • How do you keep slow integration cases out of a developer's default Catch2 run but still run them in CI?
    Tag them `[.integration]`, the shortcut for `[.][integration]`. The dot hides the case from the default run, while the `integration` tag stays selectable, so the CI job runs the binary with the tag expression `[integration]`. A hidden case also runs when selected by its exact name. A longer expression can be named once with `CATCH_REGISTER_TAG_ALIAS`.

  • Every Catch2 TEST_CASE must be given at least one tag.
  • Two Catch2 test cases with the same name and tags simply both run.
  • A duplicate Catch2 test case name is rejected by the compiler.
  • The [!mayfail] tag hides a test case from the default run.
  • A comma between Catch2 tags means both tags must match.
open as a page

In Catch2, how does a TEST_CASE containing several SECTIONs execute, and why does each section start from fresh setup?

level: middleimportance: must knowfreq 50%

basics

~20 s

Catch2 runs a TEST_CASE once per leaf SECTION, each time from the top. Each run repeats the setup and enters exactly one leaf, so every section sees freshly built locals; a parent section is entered once per leaf beneath it.

open as a page

In Catch2, how do SCENARIO, GIVEN, WHEN and THEN map onto TEST_CASE and SECTION, and where does AND_WHEN go?

level: middleimportance: should knowfreq 30%

basics

~20 s

SCENARIO is a TEST_CASE whose name gains a "Scenario: " prefix, and GIVEN, WHEN and THEN are sections with prefixed names. AND_GIVEN, AND_WHEN and AND_THEN go inside the clause they depend on; Catch2 enforces no ordering.

open as a page

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%

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.

open as a page

In Catch2, how often is a TEST_CASE_METHOD fixture constructed when its case has sections, and when would you reach for TEST_CASE_PERSISTENT_FIXTURE instead?

level: seniorimportance: should knowfreq 25%

basics

~20 s

TEST_CASE_METHOD builds a fresh fixture for every partial run, once per leaf section. TEST_CASE_PERSISTENT_FIXTURE, added in Catch2 3.7.0, builds one fixture for the whole case; it suits expensive setup, but state then carries between sections and members must be mutable.

open as a page

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%

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.

open as a page