Home | History | Annotate | Download | only in docs 
      1 <a id="top"></a>
      2 # Assertion Macros
      3 
      4 **Contents**<br>
      5 [Natural Expressions](#natural-expressions)<br>
      6 [Exceptions](#exceptions)<br>
      7 [Matcher expressions](#matcher-expressions)<br>
      8 [Thread Safety](#thread-safety)<br>
      9 [Expressions with commas](#expressions-with-commas)<br>
     10 
     11 Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (```_EQUALS```, ```_NOTEQUALS```, ```_GREATER_THAN``` etc).
     12 
     13 Catch is different. Because it decomposes natural C-style conditional expressions most of these forms are reduced to one or two that you will use all the time. That said there are a rich set of auxiliary macros as well. We'll describe all of these here.
     14 
     15 Most of these macros come in two forms:
     16 
     17 ## Natural Expressions
     18 
     19 The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails.
     20 The ```CHECK``` family are equivalent but execution continues in the same test case even if the assertion fails. This is useful if you have a series of essentially orthogonal assertions and it is useful to see all the results rather than stopping at the first failure.
     21 
     22 * **REQUIRE(** _expression_ **)** and  
     23 * **CHECK(** _expression_ **)**
     24 
     25 Evaluates the expression and records the result. If an exception is thrown, it is caught, reported, and counted as a failure. These are the macros you will use most of the time.
     26 
     27 Examples:
     28 ```
     29 CHECK( str == "string value" );
     30 CHECK( thisReturnsTrue() );
     31 REQUIRE( i == 42 );
     32 ```
     33 
     34 * **REQUIRE_FALSE(** _expression_ **)** and  
     35 * **CHECK_FALSE(** _expression_ **)**
     36 
     37 Evaluates the expression and records the _logical NOT_ of the result. If an exception is thrown it is caught, reported, and counted as a failure.
     38 (these forms exist as a workaround for the fact that ! prefixed expressions cannot be decomposed).
     39 
     40 Example:
     41 ```
     42 REQUIRE_FALSE( thisReturnsFalse() );
     43 ```
     44 
     45 Do note that "overly complex" expressions cannot be decomposed and thus will not compile. This is done partly for practical reasons (to keep the underlying expression template machinery to minimum) and partly for philosophical reasons (assertions should be simple and deterministic).
     46 
     47 Examples:
     48 * `CHECK(a == 1 && b == 2);`
     49 This expression is too complex because of the `&&` operator. If you want to check that 2 or more properties hold, you can either put the expression into parenthesis, which stops decomposition from working, or you need to decompose the expression into two assertions: `CHECK( a == 1 ); CHECK( b == 2);`
     50 * `CHECK( a == 2 || b == 1 );`
     51 This expression is too complex because of the `||` operator. If you want to check that one of several properties hold, you can put the expression into parenthesis (unlike with `&&`, expression decomposition into several `CHECK`s is not possible).
     52 
     53 
     54 ### Floating point comparisons
     55 
     56 When comparing floating point numbers - especially if at least one of them has been computed - great care must be taken to allow for rounding errors and inexact representations.
     57 
     58 Catch provides a way to perform tolerant comparisons of floating point values through use of a wrapper class called `Approx`. `Approx` can be used on either side of a comparison expression. It overloads the comparisons operators to take a tolerance into account. Here's a simple example:
     59 
     60 ```cpp
     61 REQUIRE( performComputation() == Approx( 2.1 ) );
     62 ```
     63 
     64 Catch also provides a UDL for `Approx`; `_a`. It resides in
     65 the `Catch::literals` namespace and can be used like so:
     66 ```cpp
     67 using namespace Catch::literals;
     68 REQUIRE( performComputation() == 2.1_a );
     69 ```
     70 
     71 `Approx` is constructed with defaults that should cover most simple cases.
     72 For the more complex cases, `Approx` provides 3 customization points:
     73 
     74 * __epsilon__ - epsilon serves to set the coefficient by which a result
     75 can differ from `Approx`'s value before it is rejected.
     76 _By default set to `std::numeric_limits<float>::epsilon()*100`._
     77 * __margin__ - margin serves to set the the absolute value by which
     78 a result can differ from `Approx`'s value before it is rejected.
     79 _By default set to `0.0`._
     80 * __scale__ - scale is used to change the magnitude of `Approx` for relative check.
     81 _By default set to `0.0`._
     82 
     83 #### epsilon example
     84 ```cpp
     85 Approx target = Approx(100).epsilon(0.01);
     86 100.0 == target; // Obviously true
     87 200.0 == target; // Obviously still false
     88 100.5 == target; // True, because we set target to allow up to 1% difference
     89 ```
     90 
     91 #### margin example
     92 ```cpp
     93 Approx target = Approx(100).margin(5);
     94 100.0 == target; // Obviously true
     95 200.0 == target; // Obviously still false
     96 104.0 == target; // True, because we set target to allow absolute difference of at most 5
     97 ```
     98 
     99 #### scale
    100 Scale can be useful if the computation leading to the result worked
    101 on different scale than is used by the results. Since allowed difference
    102 between Approx's value and compared value is based primarily on Approx's value
    103 (the allowed difference is computed as
    104 `(Approx::scale + Approx::value) * epsilon`), the resulting comparison could
    105 need rescaling to be correct.
    106 
    107 
    108 ## Exceptions
    109 
    110 * **REQUIRE_NOTHROW(** _expression_ **)** and  
    111 * **CHECK_NOTHROW(** _expression_ **)**
    112 
    113 Expects that no exception is thrown during evaluation of the expression.
    114 
    115 * **REQUIRE_THROWS(** _expression_ **)** and  
    116 * **CHECK_THROWS(** _expression_ **)**
    117 
    118 Expects that an exception (of any type) is be thrown during evaluation of the expression.
    119 
    120 * **REQUIRE_THROWS_AS(** _expression_, _exception type_ **)** and  
    121 * **CHECK_THROWS_AS(** _expression_, _exception type_ **)**
    122 
    123 Expects that an exception of the _specified type_ is thrown during evaluation of the expression. Note that the _exception type_ is extended with `const&` and you should not include it yourself.
    124 
    125 * **REQUIRE_THROWS_WITH(** _expression_, _string or string matcher_ **)** and  
    126 * **CHECK_THROWS_WITH(** _expression_, _string or string matcher_ **)**
    127 
    128 Expects that an exception is thrown that, when converted to a string, matches the _string_ or _string matcher_ provided (see next section for Matchers).
    129 
    130 e.g.
    131 ```cpp
    132 REQUIRE_THROWS_WITH( openThePodBayDoors(), Contains( "afraid" ) && Contains( "can't do that" ) );
    133 REQUIRE_THROWS_WITH( dismantleHal(), "My mind is going" );
    134 ```
    135 
    136 * **REQUIRE_THROWS_MATCHES(** _expression_, _exception type_, _matcher for given exception type_ **)** and
    137 * **CHECK_THROWS_MATCHES(** _expression_, _exception type_, _matcher for given exception type_ **)**
    138 
    139 Expects that exception of _exception type_ is thrown and it matches provided matcher (see next section for Matchers).
    140 
    141 
    142 _Please note that the `THROW` family of assertions expects to be passed a single expression, not a statement or series of statements. If you want to check a more complicated sequence of operations, you can use a C++11 lambda function._
    143 
    144 ```cpp
    145 REQUIRE_NOTHROW([&](){
    146     int i = 1;
    147     int j = 2;
    148     auto k = i + j;
    149     if (k == 3) {
    150         throw 1;
    151     }
    152 }());
    153 ```
    154 
    155 
    156 
    157 ## Matcher expressions
    158 
    159 To support Matchers a slightly different form is used. Matchers have [their own documentation](matchers.md#top).
    160 
    161 * **REQUIRE_THAT(** _lhs_, _matcher expression_ **)** and  
    162 * **CHECK_THAT(** _lhs_, _matcher expression_ **)**  
    163 
    164 Matchers can be composed using `&&`, `||` and `!` operators.
    165 
    166 ## Thread Safety
    167 
    168 Currently assertions in Catch are not thread safe.
    169 For more details, along with workarounds, see the section on [the limitations page](limitations.md#thread-safe-assertions).
    170 
    171 ## Expressions with commas
    172 
    173 Because the preprocessor parses code using different rules than the
    174 compiler, multiple-argument assertions (e.g. `REQUIRE_THROWS_AS`) have
    175 problems with commas inside the provided expressions. As an example
    176 `REQUIRE_THROWS_AS(std::pair<int, int>(1, 2), std::invalid_argument);`
    177 will fail to compile, because the preprocessor sees 3 arguments provided,
    178 but the macro accepts only 2. There are two possible workarounds.
    179 
    180 1) Use typedef:
    181 ```cpp
    182 using int_pair = std::pair<int, int>;
    183 REQUIRE_THROWS_AS(int_pair(1, 2), std::invalid_argument);
    184 ```
    185 
    186 This solution is always applicable, but makes the meaning of the code
    187 less clear.
    188 
    189 2) Parenthesize the expression:
    190 ```cpp
    191 TEST_CASE_METHOD((Fixture<int, int>), "foo", "[bar]") {
    192     SUCCEED();
    193 }
    194 ```
    195 
    196 This solution is not always applicable, because it might require extra
    197 changes on the Catch's side to work.
    198 
    199 ---
    200 
    201 [Home](Readme.md#top)
    202