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 neccessarily 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`STATIC_REQUIRE( expr )` is a macro that can be used the same way as a
63`static_assert`, but also registers the success with Catch2, so it is
64reported as a success at runtime. The whole check can also be deferred
65to the runtime, by defining `CATCH_CONFIG_RUNTIME_STATIC_REQUIRE` before
66including the Catch2 header.
67
68Example:
69```cpp
70TEST_CASE("STATIC_REQUIRE showcase", "[traits]") {
71    STATIC_REQUIRE( std::is_void<void>::value );
72    STATIC_REQUIRE_FALSE( std::is_void<int>::value );
73}
74```
75
76## Test case related macros
77
78* `METHOD_AS_TEST_CASE`
79
80`METHOD_AS_TEST_CASE( member-function-pointer, description )` lets you
81register a member function of a class as a Catch2 test case. The class
82will be separately instantiated for each method registered in this way.
83
84```cpp
85class TestClass {
86    std::string s;
87
88public:
89    TestClass()
90        :s( "hello" )
91    {}
92
93    void testCase() {
94        REQUIRE( s == "hello" );
95    }
96};
97
98
99METHOD_AS_TEST_CASE( TestClass::testCase, "Use class's method as a test case", "[class]" )
100```
101
102* `REGISTER_TEST_CASE`
103
104`REGISTER_TEST_CASE( function, description )` let's you register
105a `function` as a test case. The function has to have `void()` signature,
106the description can contain both name and tags.
107
108Example:
109```cpp
110REGISTER_TEST_CASE( someFunction, "ManuallyRegistered", "[tags]" );
111```
112
113_Note that the registration still has to happen before Catch2's session
114is initiated. This means that it either needs to be done in a global
115constructor, or before Catch2's session is created in user's own main._
116
117
118* `ANON_TEST_CASE`
119
120`ANON_TEST_CASE` is a `TEST_CASE` replacement that will autogenerate
121unique name. The advantage of this is that you do not have to think
122of a name for the test case,`the disadvantage is that the name doesn't
123neccessarily remain stable across different links, and thus it might be
124hard to run directly.
125
126Example:
127```cpp
128ANON_TEST_CASE() {
129    SUCCEED("Hello from anonymous test case");
130}
131```
132
133* `DYNAMIC_SECTION`
134
135`DYNAMIC_SECTION` is a `SECTION` where the user can use `operator<<` to
136create the final name for that section. This can be useful with e.g.
137generators, or when creating a `SECTION` dynamically, within a loop.
138
139Example:
140```cpp
141TEST_CASE( "looped SECTION tests" ) {
142    int a = 1;
143
144    for( int b = 0; b < 10; ++b ) {
145        DYNAMIC_SECTION( "b is currently: " << b ) {
146            CHECK( b > a );
147        }
148    }
149}
150```
151