In Catch2, what do the name and tags arguments of TEST_CASE do, and how do tags decide which tests run?
answer
- free-form name, bracketed tags
- uniqueness covers name plus tags
- a leading dot hides
- next to each other means and
basics
~20 sTEST_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
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.
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.
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.
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.