| 1 |
# Assertions Reference |
| 2 |
|
| 3 |
This page lists the assertion macros provided by GoogleTest for verifying code |
| 4 |
behavior. To use them, include the header `gtest/gtest.h`. |
| 5 |
|
| 6 |
The majority of the macros listed below come as a pair with an `EXPECT_` variant |
| 7 |
and an `ASSERT_` variant. Upon failure, `EXPECT_` macros generate nonfatal |
| 8 |
failures and allow the current function to continue running, while `ASSERT_` |
| 9 |
macros generate fatal failures and abort the current function. |
| 10 |
|
| 11 |
All assertion macros support streaming a custom failure message into them with |
| 12 |
the `<<` operator, for example: |
| 13 |
|
| 14 |
```cpp |
| 15 |
EXPECT_TRUE(my_condition) << "My condition is not true"; |
| 16 |
``` |
| 17 |
|
| 18 |
Anything that can be streamed to an `ostream` can be streamed to an assertion |
| 19 |
macro—in particular, C strings and string objects. If a wide string (`wchar_t*`, |
| 20 |
`TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is streamed to an |
| 21 |
assertion, it will be translated to UTF-8 when printed. |
| 22 |
|
| 23 |
## Explicit Success and Failure {#success-failure} |
| 24 |
|
| 25 |
The assertions in this section generate a success or failure directly instead of |
| 26 |
testing a value or expression. These are useful when control flow, rather than a |
| 27 |
Boolean expression, determines the test's success or failure, as shown by the |
| 28 |
following example: |
| 29 |
|
| 30 |
```c++ |
| 31 |
switch(expression) { |
| 32 |
case 1: |
| 33 |
... some checks ... |
| 34 |
case 2: |
| 35 |
... some other checks ... |
| 36 |
default: |
| 37 |
FAIL() << "We shouldn't get here."; |
| 38 |
} |
| 39 |
``` |
| 40 |
|
| 41 |
### SUCCEED {#SUCCEED} |
| 42 |
|
| 43 |
`SUCCEED()` |
| 44 |
|
| 45 |
Generates a success. This *does not* make the overall test succeed. A test is |
| 46 |
considered successful only if none of its assertions fail during its execution. |
| 47 |
|
| 48 |
The `SUCCEED` assertion is purely documentary and currently doesn't generate any |
| 49 |
user-visible output. However, we may add `SUCCEED` messages to GoogleTest output |
| 50 |
in the future. |
| 51 |
|
| 52 |
### FAIL {#FAIL} |
| 53 |
|
| 54 |
`FAIL()` |
| 55 |
|
| 56 |
Generates a fatal failure, which returns from the current function. |
| 57 |
|
| 58 |
Can only be used in functions that return `void`. See |
| 59 |
[Assertion Placement](../advanced.md#assertion-placement) for more information. |
| 60 |
|
| 61 |
### ADD_FAILURE {#ADD_FAILURE} |
| 62 |
|
| 63 |
`ADD_FAILURE()` |
| 64 |
|
| 65 |
Generates a nonfatal failure, which allows the current function to continue |
| 66 |
running. |
| 67 |
|
| 68 |
### ADD_FAILURE_AT {#ADD_FAILURE_AT} |
| 69 |
|
| 70 |
`ADD_FAILURE_AT(`*`file_path`*`,`*`line_number`*`)` |
| 71 |
|
| 72 |
Generates a nonfatal failure at the file and line number specified. |
| 73 |
|
| 74 |
## Generalized Assertion {#generalized} |
| 75 |
|
| 76 |
The following assertion allows [matchers](matchers.md) to be used to verify |
| 77 |
values. |
| 78 |
|
| 79 |
### EXPECT_THAT {#EXPECT_THAT} |
| 80 |
|
| 81 |
`EXPECT_THAT(`*`value`*`,`*`matcher`*`)` \ |
| 82 |
`ASSERT_THAT(`*`value`*`,`*`matcher`*`)` |
| 83 |
|
| 84 |
Verifies that *`value`* matches the [matcher](matchers.md) *`matcher`*. |
| 85 |
|
| 86 |
For example, the following code verifies that the string `value1` starts with |
| 87 |
`"Hello"`, `value2` matches a regular expression, and `value3` is between 5 and |
| 88 |
10: |
| 89 |
|
| 90 |
```cpp |
| 91 |
#include "gmock/gmock.h" |
| 92 |
|
| 93 |
using ::testing::AllOf; |
| 94 |
using ::testing::Gt; |
| 95 |
using ::testing::Lt; |
| 96 |
using ::testing::MatchesRegex; |
| 97 |
using ::testing::StartsWith; |
| 98 |
|
| 99 |
... |
| 100 |
EXPECT_THAT(value1, StartsWith("Hello")); |
| 101 |
EXPECT_THAT(value2, MatchesRegex("Line \\d+")); |
| 102 |
ASSERT_THAT(value3, AllOf(Gt(5), Lt(10))); |
| 103 |
``` |
| 104 |
|
| 105 |
Matchers enable assertions of this form to read like English and generate |
| 106 |
informative failure messages. For example, if the above assertion on `value1` |
| 107 |
fails, the resulting message will be similar to the following: |
| 108 |
|
| 109 |
``` |
| 110 |
Value of: value1 |
| 111 |
Actual: "Hi, world!" |
| 112 |
Expected: starts with "Hello" |
| 113 |
``` |
| 114 |
|
| 115 |
GoogleTest provides a built-in library of matchers—see the |
| 116 |
[Matchers Reference](matchers.md). It is also possible to write your own |
| 117 |
matchers—see [Writing New Matchers Quickly](../gmock_cook_book.md#NewMatchers). |
| 118 |
The use of matchers makes `EXPECT_THAT` a powerful, extensible assertion. |
| 119 |
|
| 120 |
*The idea for this assertion was borrowed from Joe Walnes' Hamcrest project, |
| 121 |
which adds `assertThat()` to JUnit.* |
| 122 |
|
| 123 |
## Boolean Conditions {#boolean} |
| 124 |
|
| 125 |
The following assertions test Boolean conditions. |
| 126 |
|
| 127 |
### EXPECT_TRUE {#EXPECT_TRUE} |
| 128 |
|
| 129 |
`EXPECT_TRUE(`*`condition`*`)` \ |
| 130 |
`ASSERT_TRUE(`*`condition`*`)` |
| 131 |
|
| 132 |
Verifies that *`condition`* is true. |
| 133 |
|
| 134 |
### EXPECT_FALSE {#EXPECT_FALSE} |
| 135 |
|
| 136 |
`EXPECT_FALSE(`*`condition`*`)` \ |
| 137 |
`ASSERT_FALSE(`*`condition`*`)` |
| 138 |
|
| 139 |
Verifies that *`condition`* is false. |
| 140 |
|
| 141 |
## Binary Comparison {#binary-comparison} |
| 142 |
|
| 143 |
The following assertions compare two values. The value arguments must be |
| 144 |
comparable by the assertion's comparison operator, otherwise a compiler error |
| 145 |
will result. |
| 146 |
|
| 147 |
If an argument supports the `<<` operator, it will be called to print the |
| 148 |
argument when the assertion fails. Otherwise, GoogleTest will attempt to print |
| 149 |
them in the best way it can—see |
| 150 |
[Teaching GoogleTest How to Print Your Values](../advanced.md#teaching-googletest-how-to-print-your-values). |
| 151 |
|
| 152 |
Arguments are always evaluated exactly once, so it's OK for the arguments to |
| 153 |
have side effects. However, the argument evaluation order is undefined and |
| 154 |
programs should not depend on any particular argument evaluation order. |
| 155 |
|
| 156 |
These assertions work with both narrow and wide string objects (`string` and |
| 157 |
`wstring`). |
| 158 |
|
| 159 |
See also the [Floating-Point Comparison](#floating-point) assertions to compare |
| 160 |
floating-point numbers and avoid problems caused by rounding. |
| 161 |
|
| 162 |
### EXPECT_EQ {#EXPECT_EQ} |
| 163 |
|
| 164 |
`EXPECT_EQ(`*`val1`*`,`*`val2`*`)` \ |
| 165 |
`ASSERT_EQ(`*`val1`*`,`*`val2`*`)` |
| 166 |
|
| 167 |
Verifies that *`val1`*`==`*`val2`*. |
| 168 |
|
| 169 |
Does pointer equality on pointers. If used on two C strings, it tests if they |
| 170 |
are in the same memory location, not if they have the same value. Use |
| 171 |
[`EXPECT_STREQ`](#EXPECT_STREQ) to compare C strings (e.g. `const char*`) by |
| 172 |
value. |
| 173 |
|
| 174 |
When comparing a pointer to `NULL`, use `EXPECT_EQ(`*`ptr`*`, nullptr)` instead |
| 175 |
of `EXPECT_EQ(`*`ptr`*`, NULL)`. |
| 176 |
|
| 177 |
### EXPECT_NE {#EXPECT_NE} |
| 178 |
|
| 179 |
`EXPECT_NE(`*`val1`*`,`*`val2`*`)` \ |
| 180 |
`ASSERT_NE(`*`val1`*`,`*`val2`*`)` |
| 181 |
|
| 182 |
Verifies that *`val1`*`!=`*`val2`*. |
| 183 |
|
| 184 |
Does pointer equality on pointers. If used on two C strings, it tests if they |
| 185 |
are in different memory locations, not if they have different values. Use |
| 186 |
[`EXPECT_STRNE`](#EXPECT_STRNE) to compare C strings (e.g. `const char*`) by |
| 187 |
value. |
| 188 |
|
| 189 |
When comparing a pointer to `NULL`, use `EXPECT_NE(`*`ptr`*`, nullptr)` instead |
| 190 |
of `EXPECT_NE(`*`ptr`*`, NULL)`. |
| 191 |
|
| 192 |
### EXPECT_LT {#EXPECT_LT} |
| 193 |
|
| 194 |
`EXPECT_LT(`*`val1`*`,`*`val2`*`)` \ |
| 195 |
`ASSERT_LT(`*`val1`*`,`*`val2`*`)` |
| 196 |
|
| 197 |
Verifies that *`val1`*`<`*`val2`*. |
| 198 |
|
| 199 |
### EXPECT_LE {#EXPECT_LE} |
| 200 |
|
| 201 |
`EXPECT_LE(`*`val1`*`,`*`val2`*`)` \ |
| 202 |
`ASSERT_LE(`*`val1`*`,`*`val2`*`)` |
| 203 |
|
| 204 |
Verifies that *`val1`*`<=`*`val2`*. |
| 205 |
|
| 206 |
### EXPECT_GT {#EXPECT_GT} |
| 207 |
|
| 208 |
`EXPECT_GT(`*`val1`*`,`*`val2`*`)` \ |
| 209 |
`ASSERT_GT(`*`val1`*`,`*`val2`*`)` |
| 210 |
|
| 211 |
Verifies that *`val1`*`>`*`val2`*. |
| 212 |
|
| 213 |
### EXPECT_GE {#EXPECT_GE} |
| 214 |
|
| 215 |
`EXPECT_GE(`*`val1`*`,`*`val2`*`)` \ |
| 216 |
`ASSERT_GE(`*`val1`*`,`*`val2`*`)` |
| 217 |
|
| 218 |
Verifies that *`val1`*`>=`*`val2`*. |
| 219 |
|
| 220 |
## String Comparison {#c-strings} |
| 221 |
|
| 222 |
The following assertions compare two **C strings**. To compare two `string` |
| 223 |
objects, use [`EXPECT_EQ`](#EXPECT_EQ) or [`EXPECT_NE`](#EXPECT_NE) instead. |
| 224 |
|
| 225 |
These assertions also accept wide C strings (`wchar_t*`). If a comparison of two |
| 226 |
wide strings fails, their values will be printed as UTF-8 narrow strings. |
| 227 |
|
| 228 |
To compare a C string with `NULL`, use `EXPECT_EQ(`*`c_string`*`, nullptr)` or |
| 229 |
`EXPECT_NE(`*`c_string`*`, nullptr)`. |
| 230 |
|
| 231 |
### EXPECT_STREQ {#EXPECT_STREQ} |
| 232 |
|
| 233 |
`EXPECT_STREQ(`*`str1`*`,`*`str2`*`)` \ |
| 234 |
`ASSERT_STREQ(`*`str1`*`,`*`str2`*`)` |
| 235 |
|
| 236 |
Verifies that the two C strings *`str1`* and *`str2`* have the same contents. |
| 237 |
|
| 238 |
### EXPECT_STRNE {#EXPECT_STRNE} |
| 239 |
|
| 240 |
`EXPECT_STRNE(`*`str1`*`,`*`str2`*`)` \ |
| 241 |
`ASSERT_STRNE(`*`str1`*`,`*`str2`*`)` |
| 242 |
|
| 243 |
Verifies that the two C strings *`str1`* and *`str2`* have different contents. |
| 244 |
|
| 245 |
### EXPECT_STRCASEEQ {#EXPECT_STRCASEEQ} |
| 246 |
|
| 247 |
`EXPECT_STRCASEEQ(`*`str1`*`,`*`str2`*`)` \ |
| 248 |
`ASSERT_STRCASEEQ(`*`str1`*`,`*`str2`*`)` |
| 249 |
|
| 250 |
Verifies that the two C strings *`str1`* and *`str2`* have the same contents, |
| 251 |
ignoring case. |
| 252 |
|
| 253 |
### EXPECT_STRCASENE {#EXPECT_STRCASENE} |
| 254 |
|
| 255 |
`EXPECT_STRCASENE(`*`str1`*`,`*`str2`*`)` \ |
| 256 |
`ASSERT_STRCASENE(`*`str1`*`,`*`str2`*`)` |
| 257 |
|
| 258 |
Verifies that the two C strings *`str1`* and *`str2`* have different contents, |
| 259 |
ignoring case. |
| 260 |
|
| 261 |
## Floating-Point Comparison {#floating-point} |
| 262 |
|
| 263 |
The following assertions compare two floating-point values. |
| 264 |
|
| 265 |
Due to rounding errors, it is very unlikely that two floating-point values will |
| 266 |
match exactly, so `EXPECT_EQ` is not suitable. In general, for floating-point |
| 267 |
comparison to make sense, the user needs to carefully choose the error bound. |
| 268 |
|
| 269 |
GoogleTest also provides assertions that use a default error bound based on |
| 270 |
Units in the Last Place (ULPs). To learn more about ULPs, see the article |
| 271 |
[Comparing Floating Point Numbers](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/). |
| 272 |
|
| 273 |
### EXPECT_FLOAT_EQ {#EXPECT_FLOAT_EQ} |
| 274 |
|
| 275 |
`EXPECT_FLOAT_EQ(`*`val1`*`,`*`val2`*`)` \ |
| 276 |
`ASSERT_FLOAT_EQ(`*`val1`*`,`*`val2`*`)` |
| 277 |
|
| 278 |
Verifies that the two `float` values *`val1`* and *`val2`* are approximately |
| 279 |
equal, to within 4 ULPs from each other. |
| 280 |
|
| 281 |
### EXPECT_DOUBLE_EQ {#EXPECT_DOUBLE_EQ} |
| 282 |
|
| 283 |
`EXPECT_DOUBLE_EQ(`*`val1`*`,`*`val2`*`)` \ |
| 284 |
`ASSERT_DOUBLE_EQ(`*`val1`*`,`*`val2`*`)` |
| 285 |
|
| 286 |
Verifies that the two `double` values *`val1`* and *`val2`* are approximately |
| 287 |
equal, to within 4 ULPs from each other. |
| 288 |
|
| 289 |
### EXPECT_NEAR {#EXPECT_NEAR} |
| 290 |
|
| 291 |
`EXPECT_NEAR(`*`val1`*`,`*`val2`*`,`*`abs_error`*`)` \ |
| 292 |
`ASSERT_NEAR(`*`val1`*`,`*`val2`*`,`*`abs_error`*`)` |
| 293 |
|
| 294 |
Verifies that the difference between *`val1`* and *`val2`* does not exceed the |
| 295 |
absolute error bound *`abs_error`*. |
| 296 |
|
| 297 |
## Exception Assertions {#exceptions} |
| 298 |
|
| 299 |
The following assertions verify that a piece of code throws, or does not throw, |
| 300 |
an exception. Usage requires exceptions to be enabled in the build environment. |
| 301 |
|
| 302 |
Note that the piece of code under test can be a compound statement, for example: |
| 303 |
|
| 304 |
```cpp |
| 305 |
EXPECT_NO_THROW({ |
| 306 |
int n = 5; |
| 307 |
DoSomething(&n); |
| 308 |
}); |
| 309 |
``` |
| 310 |
|
| 311 |
### EXPECT_THROW {#EXPECT_THROW} |
| 312 |
|
| 313 |
`EXPECT_THROW(`*`statement`*`,`*`exception_type`*`)` \ |
| 314 |
`ASSERT_THROW(`*`statement`*`,`*`exception_type`*`)` |
| 315 |
|
| 316 |
Verifies that *`statement`* throws an exception of type *`exception_type`*. |
| 317 |
|
| 318 |
### EXPECT_ANY_THROW {#EXPECT_ANY_THROW} |
| 319 |
|
| 320 |
`EXPECT_ANY_THROW(`*`statement`*`)` \ |
| 321 |
`ASSERT_ANY_THROW(`*`statement`*`)` |
| 322 |
|
| 323 |
Verifies that *`statement`* throws an exception of any type. |
| 324 |
|
| 325 |
### EXPECT_NO_THROW {#EXPECT_NO_THROW} |
| 326 |
|
| 327 |
`EXPECT_NO_THROW(`*`statement`*`)` \ |
| 328 |
`ASSERT_NO_THROW(`*`statement`*`)` |
| 329 |
|
| 330 |
Verifies that *`statement`* does not throw any exception. |
| 331 |
|
| 332 |
## Predicate Assertions {#predicates} |
| 333 |
|
| 334 |
The following assertions enable more complex predicates to be verified while |
| 335 |
printing a more clear failure message than if `EXPECT_TRUE` were used alone. |
| 336 |
|
| 337 |
### EXPECT_PRED* {#EXPECT_PRED} |
| 338 |
|
| 339 |
`EXPECT_PRED1(`*`pred`*`,`*`val1`*`)` \ |
| 340 |
`EXPECT_PRED2(`*`pred`*`,`*`val1`*`,`*`val2`*`)` \ |
| 341 |
`EXPECT_PRED3(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \ |
| 342 |
`EXPECT_PRED4(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)` \ |
| 343 |
`EXPECT_PRED5(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)` |
| 344 |
|
| 345 |
`ASSERT_PRED1(`*`pred`*`,`*`val1`*`)` \ |
| 346 |
`ASSERT_PRED2(`*`pred`*`,`*`val1`*`,`*`val2`*`)` \ |
| 347 |
`ASSERT_PRED3(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \ |
| 348 |
`ASSERT_PRED4(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)` \ |
| 349 |
`ASSERT_PRED5(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)` |
| 350 |
|
| 351 |
Verifies that the predicate *`pred`* returns `true` when passed the given values |
| 352 |
as arguments. |
| 353 |
|
| 354 |
The parameter *`pred`* is a function or functor that accepts as many arguments |
| 355 |
as the corresponding macro accepts values. If *`pred`* returns `true` for the |
| 356 |
given arguments, the assertion succeeds, otherwise the assertion fails. |
| 357 |
|
| 358 |
When the assertion fails, it prints the value of each argument. Arguments are |
| 359 |
always evaluated exactly once. |
| 360 |
|
| 361 |
As an example, see the following code: |
| 362 |
|
| 363 |
```cpp |
| 364 |
// Returns true if m and n have no common divisors except 1. |
| 365 |
bool MutuallyPrime(int m, int n) { ... } |
| 366 |
... |
| 367 |
const int a = 3; |
| 368 |
const int b = 4; |
| 369 |
const int c = 10; |
| 370 |
... |
| 371 |
EXPECT_PRED2(MutuallyPrime, a, b); // Succeeds |
| 372 |
EXPECT_PRED2(MutuallyPrime, b, c); // Fails |
| 373 |
``` |
| 374 |
|
| 375 |
In the above example, the first assertion succeeds, and the second fails with |
| 376 |
the following message: |
| 377 |
|
| 378 |
``` |
| 379 |
MutuallyPrime(b, c) is false, where |
| 380 |
b is 4 |
| 381 |
c is 10 |
| 382 |
``` |
| 383 |
|
| 384 |
Note that if the given predicate is an overloaded function or a function |
| 385 |
template, the assertion macro might not be able to determine which version to |
| 386 |
use, and it might be necessary to explicitly specify the type of the function. |
| 387 |
For example, for a Boolean function `IsPositive()` overloaded to take either a |
| 388 |
single `int` or `double` argument, it would be necessary to write one of the |
| 389 |
following: |
| 390 |
|
| 391 |
```cpp |
| 392 |
EXPECT_PRED1(static_cast<bool (*)(int)>(IsPositive), 5); |
| 393 |
EXPECT_PRED1(static_cast<bool (*)(double)>(IsPositive), 3.14); |
| 394 |
``` |
| 395 |
|
| 396 |
Writing simply `EXPECT_PRED1(IsPositive, 5);` would result in a compiler error. |
| 397 |
Similarly, to use a template function, specify the template arguments: |
| 398 |
|
| 399 |
```cpp |
| 400 |
template <typename T> |
| 401 |
bool IsNegative(T x) { |
| 402 |
return x < 0; |
| 403 |
} |
| 404 |
... |
| 405 |
EXPECT_PRED1(IsNegative<int>, -5); // Must specify type for IsNegative |
| 406 |
``` |
| 407 |
|
| 408 |
If a template has multiple parameters, wrap the predicate in parentheses so the |
| 409 |
macro arguments are parsed correctly: |
| 410 |
|
| 411 |
```cpp |
| 412 |
ASSERT_PRED2((MyPredicate<int, int>), 5, 0); |
| 413 |
``` |
| 414 |
|
| 415 |
### EXPECT_PRED_FORMAT* {#EXPECT_PRED_FORMAT} |
| 416 |
|
| 417 |
`EXPECT_PRED_FORMAT1(`*`pred_formatter`*`,`*`val1`*`)` \ |
| 418 |
`EXPECT_PRED_FORMAT2(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`)` \ |
| 419 |
`EXPECT_PRED_FORMAT3(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \ |
| 420 |
`EXPECT_PRED_FORMAT4(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)` |
| 421 |
\ |
| 422 |
`EXPECT_PRED_FORMAT5(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)` |
| 423 |
|
| 424 |
`ASSERT_PRED_FORMAT1(`*`pred_formatter`*`,`*`val1`*`)` \ |
| 425 |
`ASSERT_PRED_FORMAT2(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`)` \ |
| 426 |
`ASSERT_PRED_FORMAT3(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \ |
| 427 |
`ASSERT_PRED_FORMAT4(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)` |
| 428 |
\ |
| 429 |
`ASSERT_PRED_FORMAT5(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)` |
| 430 |
|
| 431 |
Verifies that the predicate *`pred_formatter`* succeeds when passed the given |
| 432 |
values as arguments. |
| 433 |
|
| 434 |
The parameter *`pred_formatter`* is a *predicate-formatter*, which is a function |
| 435 |
or functor with the signature: |
| 436 |
|
| 437 |
```cpp |
| 438 |
testing::AssertionResult PredicateFormatter(const char* expr1, |
| 439 |
const char* expr2, |
| 440 |
... |
| 441 |
const char* exprn, |
| 442 |
T1 val1, |
| 443 |
T2 val2, |
| 444 |
... |
| 445 |
Tn valn); |
| 446 |
``` |
| 447 |
|
| 448 |
where *`val1`*, *`val2`*, ..., *`valn`* are the values of the predicate |
| 449 |
arguments, and *`expr1`*, *`expr2`*, ..., *`exprn`* are the corresponding |
| 450 |
expressions as they appear in the source code. The types `T1`, `T2`, ..., `Tn` |
| 451 |
can be either value types or reference types; if an argument has type `T`, it |
| 452 |
can be declared as either `T` or `const T&`, whichever is appropriate. For more |
| 453 |
about the return type `testing::AssertionResult`, see |
| 454 |
[Using a Function That Returns an AssertionResult](../advanced.md#using-a-function-that-returns-an-assertionresult). |
| 455 |
|
| 456 |
As an example, see the following code: |
| 457 |
|
| 458 |
```cpp |
| 459 |
// Returns the smallest prime common divisor of m and n, |
| 460 |
// or 1 when m and n are mutually prime. |
| 461 |
int SmallestPrimeCommonDivisor(int m, int n) { ... } |
| 462 |
|
| 463 |
// Returns true if m and n have no common divisors except 1. |
| 464 |
bool MutuallyPrime(int m, int n) { ... } |
| 465 |
|
| 466 |
// A predicate-formatter for asserting that two integers are mutually prime. |
| 467 |
testing::AssertionResult AssertMutuallyPrime(const char* m_expr, |
| 468 |
const char* n_expr, |
| 469 |
int m, |
| 470 |
int n) { |
| 471 |
if (MutuallyPrime(m, n)) return testing::AssertionSuccess(); |
| 472 |
|
| 473 |
return testing::AssertionFailure() << m_expr << " and " << n_expr |
| 474 |
<< " (" << m << " and " << n << ") are not mutually prime, " |
| 475 |
<< "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n); |
| 476 |
} |
| 477 |
|
| 478 |
... |
| 479 |
const int a = 3; |
| 480 |
const int b = 4; |
| 481 |
const int c = 10; |
| 482 |
... |
| 483 |
EXPECT_PRED_FORMAT2(AssertMutuallyPrime, a, b); // Succeeds |
| 484 |
EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c); // Fails |
| 485 |
``` |
| 486 |
|
| 487 |
In the above example, the final assertion fails and the predicate-formatter |
| 488 |
produces the following failure message: |
| 489 |
|
| 490 |
``` |
| 491 |
b and c (4 and 10) are not mutually prime, as they have a common divisor 2 |
| 492 |
``` |
| 493 |
|
| 494 |
## Windows HRESULT Assertions {#HRESULT} |
| 495 |
|
| 496 |
The following assertions test for `HRESULT` success or failure. For example: |
| 497 |
|
| 498 |
```cpp |
| 499 |
CComPtr<IShellDispatch2> shell; |
| 500 |
ASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application")); |
| 501 |
CComVariant empty; |
| 502 |
ASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty)); |
| 503 |
``` |
| 504 |
|
| 505 |
The generated output contains the human-readable error message associated with |
| 506 |
the returned `HRESULT` code. |
| 507 |
|
| 508 |
### EXPECT_HRESULT_SUCCEEDED {#EXPECT_HRESULT_SUCCEEDED} |
| 509 |
|
| 510 |
`EXPECT_HRESULT_SUCCEEDED(`*`expression`*`)` \ |
| 511 |
`ASSERT_HRESULT_SUCCEEDED(`*`expression`*`)` |
| 512 |
|
| 513 |
Verifies that *`expression`* is a success `HRESULT`. |
| 514 |
|
| 515 |
### EXPECT_HRESULT_FAILED {#EXPECT_HRESULT_FAILED} |
| 516 |
|
| 517 |
`EXPECT_HRESULT_FAILED(`*`expression`*`)` \ |
| 518 |
`EXPECT_HRESULT_FAILED(`*`expression`*`)` |
| 519 |
|
| 520 |
Verifies that *`expression`* is a failure `HRESULT`. |
| 521 |
|
| 522 |
## Death Assertions {#death} |
| 523 |
|
| 524 |
The following assertions verify that a piece of code causes the process to |
| 525 |
terminate. For context, see [Death Tests](../advanced.md#death-tests). |
| 526 |
|
| 527 |
These assertions spawn a new process and execute the code under test in that |
| 528 |
process. How that happens depends on the platform and the variable |
| 529 |
`::testing::GTEST_FLAG(death_test_style)`, which is initialized from the |
| 530 |
command-line flag `--gtest_death_test_style`. |
| 531 |
|
| 532 |
* On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the |
| 533 |
child, after which: |
| 534 |
* If the variable's value is `"fast"`, the death test statement is |
| 535 |
immediately executed. |
| 536 |
* If the variable's value is `"threadsafe"`, the child process re-executes |
| 537 |
the unit test binary just as it was originally invoked, but with some |
| 538 |
extra flags to cause just the single death test under consideration to |
| 539 |
be run. |
| 540 |
* On Windows, the child is spawned using the `CreateProcess()` API, and |
| 541 |
re-executes the binary to cause just the single death test under |
| 542 |
consideration to be run - much like the `"threadsafe"` mode on POSIX. |
| 543 |
|
| 544 |
Other values for the variable are illegal and will cause the death test to fail. |
| 545 |
Currently, the flag's default value is |
| 546 |
**`"fast"`**. |
| 547 |
|
| 548 |
If the death test statement runs to completion without dying, the child process |
| 549 |
will nonetheless terminate, and the assertion fails. |
| 550 |
|
| 551 |
Note that the piece of code under test can be a compound statement, for example: |
| 552 |
|
| 553 |
```cpp |
| 554 |
EXPECT_DEATH({ |
| 555 |
int n = 5; |
| 556 |
DoSomething(&n); |
| 557 |
}, "Error on line .* of DoSomething()"); |
| 558 |
``` |
| 559 |
|
| 560 |
### EXPECT_DEATH {#EXPECT_DEATH} |
| 561 |
|
| 562 |
`EXPECT_DEATH(`*`statement`*`,`*`matcher`*`)` \ |
| 563 |
`ASSERT_DEATH(`*`statement`*`,`*`matcher`*`)` |
| 564 |
|
| 565 |
Verifies that *`statement`* causes the process to terminate with a nonzero exit |
| 566 |
status and produces `stderr` output that matches *`matcher`*. |
| 567 |
|
| 568 |
The parameter *`matcher`* is either a [matcher](matchers.md) for a `const |
| 569 |
std::string&`, or a regular expression (see |
| 570 |
[Regular Expression Syntax](../advanced.md#regular-expression-syntax))—a bare |
| 571 |
string *`s`* (with no matcher) is treated as |
| 572 |
[`ContainsRegex(s)`](matchers.md#string-matchers), **not** |
| 573 |
[`Eq(s)`](matchers.md#generic-comparison). |
| 574 |
|
| 575 |
For example, the following code verifies that calling `DoSomething(42)` causes |
| 576 |
the process to die with an error message that contains the text `My error`: |
| 577 |
|
| 578 |
```cpp |
| 579 |
EXPECT_DEATH(DoSomething(42), "My error"); |
| 580 |
``` |
| 581 |
|
| 582 |
### EXPECT_DEATH_IF_SUPPORTED {#EXPECT_DEATH_IF_SUPPORTED} |
| 583 |
|
| 584 |
`EXPECT_DEATH_IF_SUPPORTED(`*`statement`*`,`*`matcher`*`)` \ |
| 585 |
`ASSERT_DEATH_IF_SUPPORTED(`*`statement`*`,`*`matcher`*`)` |
| 586 |
|
| 587 |
If death tests are supported, behaves the same as |
| 588 |
[`EXPECT_DEATH`](#EXPECT_DEATH). Otherwise, verifies nothing. |
| 589 |
|
| 590 |
### EXPECT_DEBUG_DEATH {#EXPECT_DEBUG_DEATH} |
| 591 |
|
| 592 |
`EXPECT_DEBUG_DEATH(`*`statement`*`,`*`matcher`*`)` \ |
| 593 |
`ASSERT_DEBUG_DEATH(`*`statement`*`,`*`matcher`*`)` |
| 594 |
|
| 595 |
In debug mode, behaves the same as [`EXPECT_DEATH`](#EXPECT_DEATH). When not in |
| 596 |
debug mode (i.e. `NDEBUG` is defined), just executes *`statement`*. |
| 597 |
|
| 598 |
### EXPECT_EXIT {#EXPECT_EXIT} |
| 599 |
|
| 600 |
`EXPECT_EXIT(`*`statement`*`,`*`predicate`*`,`*`matcher`*`)` \ |
| 601 |
`ASSERT_EXIT(`*`statement`*`,`*`predicate`*`,`*`matcher`*`)` |
| 602 |
|
| 603 |
Verifies that *`statement`* causes the process to terminate with an exit status |
| 604 |
that satisfies *`predicate`*, and produces `stderr` output that matches |
| 605 |
*`matcher`*. |
| 606 |
|
| 607 |
The parameter *`predicate`* is a function or functor that accepts an `int` exit |
| 608 |
status and returns a `bool`. GoogleTest provides two predicates to handle common |
| 609 |
cases: |
| 610 |
|
| 611 |
```cpp |
| 612 |
// Returns true if the program exited normally with the given exit status code. |
| 613 |
::testing::ExitedWithCode(exit_code); |
| 614 |
|
| 615 |
// Returns true if the program was killed by the given signal. |
| 616 |
// Not available on Windows. |
| 617 |
::testing::KilledBySignal(signal_number); |
| 618 |
``` |
| 619 |
|
| 620 |
The parameter *`matcher`* is either a [matcher](matchers.md) for a `const |
| 621 |
std::string&`, or a regular expression (see |
| 622 |
[Regular Expression Syntax](../advanced.md#regular-expression-syntax))—a bare |
| 623 |
string *`s`* (with no matcher) is treated as |
| 624 |
[`ContainsRegex(s)`](matchers.md#string-matchers), **not** |
| 625 |
[`Eq(s)`](matchers.md#generic-comparison). |
| 626 |
|
| 627 |
For example, the following code verifies that calling `NormalExit()` causes the |
| 628 |
process to print a message containing the text `Success` to `stderr` and exit |
| 629 |
with exit status code 0: |
| 630 |
|
| 631 |
```cpp |
| 632 |
EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success"); |
| 633 |
``` |