• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<a id="top"></a>
2# Other macros
3
4This page serves as a reference for macros that are not documented
5elsewhere. For now, these macros are separated into 2 rough categories,
6"assertion related macros" and "test case related macros".
7
8## Assertion related macros
9
10* `CHECKED_IF` and `CHECKED_ELSE`
11
12`CHECKED_IF( expr )` is an `if` replacement, that also applies Catch2's
13stringification machinery to the _expr_ and records the result. As with
14`if`, the block after a `CHECKED_IF` is entered only if the expression
15evaluates to `true`. `CHECKED_ELSE( expr )` work similarly, but the block
16is entered only if the _expr_ evaluated to `false`.
17
18Example:
19```cpp
20int a = ...;
21int b = ...;
22CHECKED_IF( a == b ) {
23    // This block is entered when a == b
24} CHECKED_ELSE ( a == b ) {
25    // This block is entered when a != b
26}
27```
28
29* `CHECK_NOFAIL`
30
31`CHECK_NOFAIL( expr )` is a variant of `CHECK` that does not fail the test
32case if _expr_ evaluates to `false`. This can be useful for checking some
33assumption, that might be violated without the test necessarily failing.
34
35Example output:
36```
37main.cpp:6:
38FAILED - but was ok:
39  CHECK_NOFAIL( 1 == 2 )
40
41main.cpp:7:
42PASSED:
43  CHECK( 2 == 2 )
44```
45
46* `SUCCEED`
47
48`SUCCEED( msg )` is mostly equivalent with `INFO( msg ); REQUIRE( true );`.
49In other words, `SUCCEED` is for cases where just reaching a certain line
50means that the test has been a success.
51
52Example usage:
53```cpp
54TEST_CASE( "SUCCEED showcase" ) {
55    int I = 1;
56    SUCCEED( "I is " << I );
57}
58```
59
60* `STATIC_REQUIRE`
61
62> [Introduced](https://github.com/catchorg/Catch2/issues/1362) in Catch 2.4.2.
63
64`STATIC_REQUIRE( expr )` is a macro that can be used the same way as a
65`static_assert`, but also registers the success with Catch2, so it is
66reported as a success at runtime. The whole check can also be deferred
67to the runtime, by defining `CATCH_CONFIG_RUNTIME_STATIC_REQUIRE` before
68including the Catch2 header.
69
70Example:
71```cpp
72TEST_CASE("STATIC_REQUIRE showcase", "[traits]") {
73    STATIC_REQUIRE( std::is_void<void>::value );
74    STATIC_REQUIRE_FALSE( std::is_void<int>::value );
75}
76```
77
78## Test case related macros
79
80* `METHOD_AS_TEST_CASE`
81
82`METHOD_AS_TEST_CASE( member-function-pointer, description )` lets you
83register a member function of a class as a Catch2 test case. The class
84will be separately instantiated for each method registered in this way.
85
86```cpp
87class TestClass {
88    std::string s;
89
90public:
91    TestClass()
92        :s( "hello" )
93    {}
94
95    void testCase() {
96        REQUIRE( s == "hello" );
97    }
98};
99
100
101METHOD_AS_TEST_CASE( TestClass::testCase, "Use class's method as a test case", "[class]" )
102```
103
104* `REGISTER_TEST_CASE`
105
106`REGISTER_TEST_CASE( function, description )` let's you register
107a `function` as a test case. The function has to have `void()` signature,
108the description can contain both name and tags.
109
110Example:
111```cpp
112REGISTER_TEST_CASE( someFunction, "ManuallyRegistered", "[tags]" );
113```
114
115_Note that the registration still has to happen before Catch2's session
116is initiated. This means that it either needs to be done in a global
117constructor, or before Catch2's session is created in user's own main._
118
119
120* `ANON_TEST_CASE`
121
122`ANON_TEST_CASE` is a `TEST_CASE` replacement that will autogenerate
123unique name. The advantage of this is that you do not have to think
124of a name for the test case,`the disadvantage is that the name doesn't
125necessarily remain stable across different links, and thus it might be
126hard to run directly.
127
128Example:
129```cpp
130ANON_TEST_CASE() {
131    SUCCEED("Hello from anonymous test case");
132}
133```
134
135* `DYNAMIC_SECTION`
136
137> Introduced in Catch 2.3.0.
138
139`DYNAMIC_SECTION` is a `SECTION` where the user can use `operator<<` to
140create the final name for that section. This can be useful with e.g.
141generators, or when creating a `SECTION` dynamically, within a loop.
142
143Example:
144```cpp
145TEST_CASE( "looped SECTION tests" ) {
146    int a = 1;
147
148    for( int b = 0; b < 10; ++b ) {
149        DYNAMIC_SECTION( "b is currently: " << b ) {
150            CHECK( b > a );
151        }
152    }
153}
154```
155