docs/reference/assertions.md

   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 ```