Home | History | Annotate | Download | only in docs 
      1 <a id="top"></a>
      2 # Other macros
      3 
      4 This page serves as a reference for macros that are not documented
      5 elsewhere. 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
     13 stringification machinery to the _expr_ and records the result. As with
     14 `if`, the block after a `CHECKED_IF` is entered only if the expression
     15 evaluates to `true`. `CHECKED_ELSE( expr )` work similarly, but the block
     16 is entered only if the _expr_ evaluated to `false`.
     17 
     18 Example:
     19 ```cpp
     20 int a = ...;
     21 int b = ...;
     22 CHECKED_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
     32 case if _expr_ evaluates to `false`. This can be useful for checking some
     33 assumption, that might be violated without the test neccessarily failing.
     34 
     35 Example output:
     36 ```
     37 main.cpp:6:
     38 FAILED - but was ok:
     39   CHECK_NOFAIL( 1 == 2 )
     40 
     41 main.cpp:7:
     42 PASSED:
     43   CHECK( 2 == 2 )
     44 ```
     45 
     46 * `SUCCEED`
     47 
     48 `SUCCEED( msg )` is mostly equivalent with `INFO( msg ); REQUIRE( true );`.
     49 In other words, `SUCCEED` is for cases where just reaching a certain line
     50 means that the test has been a success.
     51 
     52 Example usage:
     53 ```cpp
     54 TEST_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
     64 reported as a success at runtime. The whole check can also be deferred
     65 to the runtime, by defining `CATCH_CONFIG_RUNTIME_STATIC_REQUIRE` before
     66 including the Catch2 header.
     67 
     68 Example:
     69 ```cpp
     70 TEST_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
     81 register a member function of a class as a Catch2 test case. The class
     82 will be separately instantiated for each method registered in this way.
     83 
     84 ```cpp
     85 class TestClass {
     86     std::string s;
     87 
     88 public:
     89     TestClass()
     90         :s( "hello" )
     91     {}
     92 
     93     void testCase() {
     94         REQUIRE( s == "hello" );
     95     }
     96 };
     97 
     98 
     99 METHOD_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
    105 a `function` as a test case. The function has to have `void()` signature,
    106 the description can contain both name and tags.
    107 
    108 Example:
    109 ```cpp
    110 REGISTER_TEST_CASE( someFunction, "ManuallyRegistered", "[tags]" );
    111 ```
    112 
    113 _Note that the registration still has to happen before Catch2's session
    114 is initiated. This means that it either needs to be done in a global
    115 constructor, 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
    121 unique name. The advantage of this is that you do not have to think
    122 of a name for the test case,`the disadvantage is that the name doesn't
    123 neccessarily remain stable across different links, and thus it might be
    124 hard to run directly.
    125 
    126 Example:
    127 ```cpp
    128 ANON_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
    136 create the final name for that section. This can be useful with e.g.
    137 generators, or when creating a `SECTION` dynamically, within a loop.
    138 
    139 Example:
    140 ```cpp
    141 TEST_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