1# Advanced googletest Topics 2 3## Introduction 4 5Now that you have read the [googletest Primer](primer.md) and learned how to 6write tests using googletest, it's time to learn some new tricks. This document 7will show you more assertions as well as how to construct complex failure 8messages, propagate fatal failures, reuse and speed up your test fixtures, and 9use various flags with your tests. 10 11## More Assertions 12 13This section covers some less frequently used, but still significant, 14assertions. 15 16### Explicit Success and Failure 17 18These three assertions do not actually test a value or expression. Instead, they 19generate a success or failure directly. Like the macros that actually perform a 20test, you may stream a custom failure message into them. 21 22```c++ 23SUCCEED(); 24``` 25 26Generates a success. This does **NOT** make the overall test succeed. A test is 27considered successful only if none of its assertions fail during its execution. 28 29{: .callout .note} 30NOTE: `SUCCEED()` is purely documentary and currently doesn't generate any 31user-visible output. However, we may add `SUCCEED()` messages to googletest's 32output in the future. 33 34```c++ 35FAIL(); 36ADD_FAILURE(); 37ADD_FAILURE_AT("file_path", line_number); 38``` 39 40`FAIL()` generates a fatal failure, while `ADD_FAILURE()` and `ADD_FAILURE_AT()` 41generate a nonfatal failure. These are useful when control flow, rather than a 42Boolean expression, determines the test's success or failure. For example, you 43might want to write something like: 44 45```c++ 46switch(expression) { 47 case 1: 48 ... some checks ... 49 case 2: 50 ... some other checks ... 51 default: 52 FAIL() << "We shouldn't get here."; 53} 54``` 55 56{: .callout .note} 57NOTE: you can only use `FAIL()` in functions that return `void`. See the 58[Assertion Placement section](#assertion-placement) for more information. 59 60### Exception Assertions 61 62These are for verifying that a piece of code throws (or does not throw) an 63exception of the given type: 64 65Fatal assertion | Nonfatal assertion | Verifies 66------------------------------------------ | ------------------------------------------ | -------- 67`ASSERT_THROW(statement, exception_type);` | `EXPECT_THROW(statement, exception_type);` | `statement` throws an exception of the given type 68`ASSERT_ANY_THROW(statement);` | `EXPECT_ANY_THROW(statement);` | `statement` throws an exception of any type 69`ASSERT_NO_THROW(statement);` | `EXPECT_NO_THROW(statement);` | `statement` doesn't throw any exception 70 71Examples: 72 73```c++ 74ASSERT_THROW(Foo(5), bar_exception); 75 76EXPECT_NO_THROW({ 77 int n = 5; 78 Bar(&n); 79}); 80``` 81 82**Availability**: requires exceptions to be enabled in the build environment 83 84### Predicate Assertions for Better Error Messages 85 86Even though googletest has a rich set of assertions, they can never be complete, 87as it's impossible (nor a good idea) to anticipate all scenarios a user might 88run into. Therefore, sometimes a user has to use `EXPECT_TRUE()` to check a 89complex expression, for lack of a better macro. This has the problem of not 90showing you the values of the parts of the expression, making it hard to 91understand what went wrong. As a workaround, some users choose to construct the 92failure message by themselves, streaming it into `EXPECT_TRUE()`. However, this 93is awkward especially when the expression has side-effects or is expensive to 94evaluate. 95 96googletest gives you three different options to solve this problem: 97 98#### Using an Existing Boolean Function 99 100If you already have a function or functor that returns `bool` (or a type that 101can be implicitly converted to `bool`), you can use it in a *predicate 102assertion* to get the function arguments printed for free: 103 104 105| Fatal assertion | Nonfatal assertion | Verifies | 106| --------------------------------- | --------------------------------- | --------------------------- | 107| `ASSERT_PRED1(pred1, val1)` | `EXPECT_PRED1(pred1, val1)` | `pred1(val1)` is true | 108| `ASSERT_PRED2(pred2, val1, val2)` | `EXPECT_PRED2(pred2, val1, val2)` | `pred2(val1, val2)` is true | 109| `...` | `...` | `...` | 110 111In the above, `predn` is an `n`-ary predicate function or functor, where `val1`, 112`val2`, ..., and `valn` are its arguments. The assertion succeeds if the 113predicate returns `true` when applied to the given arguments, and fails 114otherwise. When the assertion fails, it prints the value of each argument. In 115either case, the arguments are evaluated exactly once. 116 117Here's an example. Given 118 119```c++ 120// Returns true if m and n have no common divisors except 1. 121bool MutuallyPrime(int m, int n) { ... } 122 123const int a = 3; 124const int b = 4; 125const int c = 10; 126``` 127 128the assertion 129 130```c++ 131 EXPECT_PRED2(MutuallyPrime, a, b); 132``` 133 134will succeed, while the assertion 135 136```c++ 137 EXPECT_PRED2(MutuallyPrime, b, c); 138``` 139 140will fail with the message 141 142```none 143MutuallyPrime(b, c) is false, where 144b is 4 145c is 10 146``` 147 148{: .callout .note} 149> NOTE: 150> 151> 1. If you see a compiler error "no matching function to call" when using 152> `ASSERT_PRED*` or `EXPECT_PRED*`, please see 153> [this](faq.md#the-compiler-complains-no-matching-function-to-call-when-i-use-assert_pred-how-do-i-fix-it) 154> for how to resolve it. 155 156#### Using a Function That Returns an AssertionResult 157 158While `EXPECT_PRED*()` and friends are handy for a quick job, the syntax is not 159satisfactory: you have to use different macros for different arities, and it 160feels more like Lisp than C++. The `::testing::AssertionResult` class solves 161this problem. 162 163An `AssertionResult` object represents the result of an assertion (whether it's 164a success or a failure, and an associated message). You can create an 165`AssertionResult` using one of these factory functions: 166 167```c++ 168namespace testing { 169 170// Returns an AssertionResult object to indicate that an assertion has 171// succeeded. 172AssertionResult AssertionSuccess(); 173 174// Returns an AssertionResult object to indicate that an assertion has 175// failed. 176AssertionResult AssertionFailure(); 177 178} 179``` 180 181You can then use the `<<` operator to stream messages to the `AssertionResult` 182object. 183 184To provide more readable messages in Boolean assertions (e.g. `EXPECT_TRUE()`), 185write a predicate function that returns `AssertionResult` instead of `bool`. For 186example, if you define `IsEven()` as: 187 188```c++ 189testing::AssertionResult IsEven(int n) { 190 if ((n % 2) == 0) 191 return testing::AssertionSuccess(); 192 else 193 return testing::AssertionFailure() << n << " is odd"; 194} 195``` 196 197instead of: 198 199```c++ 200bool IsEven(int n) { 201 return (n % 2) == 0; 202} 203``` 204 205the failed assertion `EXPECT_TRUE(IsEven(Fib(4)))` will print: 206 207```none 208Value of: IsEven(Fib(4)) 209 Actual: false (3 is odd) 210Expected: true 211``` 212 213instead of a more opaque 214 215```none 216Value of: IsEven(Fib(4)) 217 Actual: false 218Expected: true 219``` 220 221If you want informative messages in `EXPECT_FALSE` and `ASSERT_FALSE` as well 222(one third of Boolean assertions in the Google code base are negative ones), and 223are fine with making the predicate slower in the success case, you can supply a 224success message: 225 226```c++ 227testing::AssertionResult IsEven(int n) { 228 if ((n % 2) == 0) 229 return testing::AssertionSuccess() << n << " is even"; 230 else 231 return testing::AssertionFailure() << n << " is odd"; 232} 233``` 234 235Then the statement `EXPECT_FALSE(IsEven(Fib(6)))` will print 236 237```none 238 Value of: IsEven(Fib(6)) 239 Actual: true (8 is even) 240 Expected: false 241``` 242 243#### Using a Predicate-Formatter 244 245If you find the default message generated by `(ASSERT|EXPECT)_PRED*` and 246`(ASSERT|EXPECT)_(TRUE|FALSE)` unsatisfactory, or some arguments to your 247predicate do not support streaming to `ostream`, you can instead use the 248following *predicate-formatter assertions* to *fully* customize how the message 249is formatted: 250 251Fatal assertion | Nonfatal assertion | Verifies 252------------------------------------------------ | ------------------------------------------------ | -------- 253`ASSERT_PRED_FORMAT1(pred_format1, val1);` | `EXPECT_PRED_FORMAT1(pred_format1, val1);` | `pred_format1(val1)` is successful 254`ASSERT_PRED_FORMAT2(pred_format2, val1, val2);` | `EXPECT_PRED_FORMAT2(pred_format2, val1, val2);` | `pred_format2(val1, val2)` is successful 255`...` | `...` | ... 256 257The difference between this and the previous group of macros is that instead of 258a predicate, `(ASSERT|EXPECT)_PRED_FORMAT*` take a *predicate-formatter* 259(`pred_formatn`), which is a function or functor with the signature: 260 261```c++ 262testing::AssertionResult PredicateFormattern(const char* expr1, 263 const char* expr2, 264 ... 265 const char* exprn, 266 T1 val1, 267 T2 val2, 268 ... 269 Tn valn); 270``` 271 272where `val1`, `val2`, ..., and `valn` are the values of the predicate arguments, 273and `expr1`, `expr2`, ..., and `exprn` are the corresponding expressions as they 274appear in the source code. The types `T1`, `T2`, ..., and `Tn` can be either 275value types or reference types. For example, if an argument has type `Foo`, you 276can declare it as either `Foo` or `const Foo&`, whichever is appropriate. 277 278As an example, let's improve the failure message in `MutuallyPrime()`, which was 279used with `EXPECT_PRED2()`: 280 281```c++ 282// Returns the smallest prime common divisor of m and n, 283// or 1 when m and n are mutually prime. 284int SmallestPrimeCommonDivisor(int m, int n) { ... } 285 286// A predicate-formatter for asserting that two integers are mutually prime. 287testing::AssertionResult AssertMutuallyPrime(const char* m_expr, 288 const char* n_expr, 289 int m, 290 int n) { 291 if (MutuallyPrime(m, n)) return testing::AssertionSuccess(); 292 293 return testing::AssertionFailure() << m_expr << " and " << n_expr 294 << " (" << m << " and " << n << ") are not mutually prime, " 295 << "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n); 296} 297``` 298 299With this predicate-formatter, we can use 300 301```c++ 302 EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c); 303``` 304 305to generate the message 306 307```none 308b and c (4 and 10) are not mutually prime, as they have a common divisor 2. 309``` 310 311As you may have realized, many of the built-in assertions we introduced earlier 312are special cases of `(EXPECT|ASSERT)_PRED_FORMAT*`. In fact, most of them are 313indeed defined using `(EXPECT|ASSERT)_PRED_FORMAT*`. 314 315### Floating-Point Comparison 316 317Comparing floating-point numbers is tricky. Due to round-off errors, it is very 318unlikely that two floating-points will match exactly. Therefore, `ASSERT_EQ` 's 319naive comparison usually doesn't work. And since floating-points can have a wide 320value range, no single fixed error bound works. It's better to compare by a 321fixed relative error bound, except for values close to 0 due to the loss of 322precision there. 323 324In general, for floating-point comparison to make sense, the user needs to 325carefully choose the error bound. If they don't want or care to, comparing in 326terms of Units in the Last Place (ULPs) is a good default, and googletest 327provides assertions to do this. Full details about ULPs are quite long; if you 328want to learn more, see 329[here](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/). 330 331#### Floating-Point Macros 332 333 334| Fatal assertion | Nonfatal assertion | Verifies | 335| ------------------------------- | ------------------------------- | ---------------------------------------- | 336| `ASSERT_FLOAT_EQ(val1, val2);` | `EXPECT_FLOAT_EQ(val1, val2);` | the two `float` values are almost equal | 337| `ASSERT_DOUBLE_EQ(val1, val2);` | `EXPECT_DOUBLE_EQ(val1, val2);` | the two `double` values are almost equal | 338 339 340By "almost equal" we mean the values are within 4 ULP's from each other. 341 342The following assertions allow you to choose the acceptable error bound: 343 344 345| Fatal assertion | Nonfatal assertion | Verifies | 346| ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- | 347| `ASSERT_NEAR(val1, val2, abs_error);` | `EXPECT_NEAR(val1, val2, abs_error);` | the difference between `val1` and `val2` doesn't exceed the given absolute error | 348 349 350#### Floating-Point Predicate-Format Functions 351 352Some floating-point operations are useful, but not that often used. In order to 353avoid an explosion of new macros, we provide them as predicate-format functions 354that can be used in predicate assertion macros (e.g. `EXPECT_PRED_FORMAT2`, 355etc). 356 357```c++ 358EXPECT_PRED_FORMAT2(testing::FloatLE, val1, val2); 359EXPECT_PRED_FORMAT2(testing::DoubleLE, val1, val2); 360``` 361 362Verifies that `val1` is less than, or almost equal to, `val2`. You can replace 363`EXPECT_PRED_FORMAT2` in the above table with `ASSERT_PRED_FORMAT2`. 364 365### Asserting Using gMock Matchers 366 367gMock comes with a library of *matchers* for validating arguments passed to mock 368objects. A gMock matcher is basically a predicate that knows how to describe 369itself. It can be used in these assertion macros: 370 371 372| Fatal assertion | Nonfatal assertion | Verifies | 373| ------------------------------ | ------------------------------ | --------------------- | 374| `ASSERT_THAT(value, matcher);` | `EXPECT_THAT(value, matcher);` | value matches matcher | 375 376 377For example, `StartsWith(prefix)` is a matcher that matches a string starting 378with `prefix`, and you can write: 379 380```c++ 381using ::testing::StartsWith; 382... 383 // Verifies that Foo() returns a string starting with "Hello". 384 EXPECT_THAT(Foo(), StartsWith("Hello")); 385``` 386 387See 388[Using Matchers in googletest Assertions](gmock_cook_book.md#using-matchers-in-googletest-assertions) 389in the gMock Cookbook for more details. For a list of built-in matchers, see the 390[Matchers Reference](reference/matchers.md). You can also write your own 391matchers—see [Writing New Matchers Quickly](gmock_cook_book.md#NewMatchers). 392 393gMock is bundled with googletest, so you don't need to add any build dependency 394in order to take advantage of this. Just include `"gmock/gmock.h"` 395and you're ready to go. 396 397### More String Assertions 398 399(Please read the [previous](#asserting-using-gmock-matchers) section first if 400you haven't.) 401 402You can use the gMock [string matchers](reference/matchers.md#string-matchers) 403with `EXPECT_THAT()` or `ASSERT_THAT()` to do more string comparison tricks 404(sub-string, prefix, suffix, regular expression, and etc). For example, 405 406```c++ 407using ::testing::HasSubstr; 408using ::testing::MatchesRegex; 409... 410 ASSERT_THAT(foo_string, HasSubstr("needle")); 411 EXPECT_THAT(bar_string, MatchesRegex("\\w*\\d+")); 412``` 413 414If the string contains a well-formed HTML or XML document, you can check whether 415its DOM tree matches an 416[XPath expression](http://www.w3.org/TR/xpath/#contents): 417 418```c++ 419// Currently still in //template/prototemplate/testing:xpath_matcher 420#include "template/prototemplate/testing/xpath_matcher.h" 421using ::prototemplate::testing::MatchesXPath; 422EXPECT_THAT(html_string, MatchesXPath("//a[text()='click here']")); 423``` 424 425### Windows HRESULT assertions 426 427These assertions test for `HRESULT` success or failure. 428 429Fatal assertion | Nonfatal assertion | Verifies 430-------------------------------------- | -------------------------------------- | -------- 431`ASSERT_HRESULT_SUCCEEDED(expression)` | `EXPECT_HRESULT_SUCCEEDED(expression)` | `expression` is a success `HRESULT` 432`ASSERT_HRESULT_FAILED(expression)` | `EXPECT_HRESULT_FAILED(expression)` | `expression` is a failure `HRESULT` 433 434The generated output contains the human-readable error message associated with 435the `HRESULT` code returned by `expression`. 436 437You might use them like this: 438 439```c++ 440CComPtr<IShellDispatch2> shell; 441ASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application")); 442CComVariant empty; 443ASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty)); 444``` 445 446### Type Assertions 447 448You can call the function 449 450```c++ 451::testing::StaticAssertTypeEq<T1, T2>(); 452``` 453 454to assert that types `T1` and `T2` are the same. The function does nothing if 455the assertion is satisfied. If the types are different, the function call will 456fail to compile, the compiler error message will say that 457`T1 and T2 are not the same type` and most likely (depending on the compiler) 458show you the actual values of `T1` and `T2`. This is mainly useful inside 459template code. 460 461**Caveat**: When used inside a member function of a class template or a function 462template, `StaticAssertTypeEq<T1, T2>()` is effective only if the function is 463instantiated. For example, given: 464 465```c++ 466template <typename T> class Foo { 467 public: 468 void Bar() { testing::StaticAssertTypeEq<int, T>(); } 469}; 470``` 471 472the code: 473 474```c++ 475void Test1() { Foo<bool> foo; } 476``` 477 478will not generate a compiler error, as `Foo<bool>::Bar()` is never actually 479instantiated. Instead, you need: 480 481```c++ 482void Test2() { Foo<bool> foo; foo.Bar(); } 483``` 484 485to cause a compiler error. 486 487### Assertion Placement 488 489You can use assertions in any C++ function. In particular, it doesn't have to be 490a method of the test fixture class. The one constraint is that assertions that 491generate a fatal failure (`FAIL*` and `ASSERT_*`) can only be used in 492void-returning functions. This is a consequence of Google's not using 493exceptions. By placing it in a non-void function you'll get a confusing compile 494error like `"error: void value not ignored as it ought to be"` or `"cannot 495initialize return object of type 'bool' with an rvalue of type 'void'"` or 496`"error: no viable conversion from 'void' to 'string'"`. 497 498If you need to use fatal assertions in a function that returns non-void, one 499option is to make the function return the value in an out parameter instead. For 500example, you can rewrite `T2 Foo(T1 x)` to `void Foo(T1 x, T2* result)`. You 501need to make sure that `*result` contains some sensible value even when the 502function returns prematurely. As the function now returns `void`, you can use 503any assertion inside of it. 504 505If changing the function's type is not an option, you should just use assertions 506that generate non-fatal failures, such as `ADD_FAILURE*` and `EXPECT_*`. 507 508{: .callout .note} 509NOTE: Constructors and destructors are not considered void-returning functions, 510according to the C++ language specification, and so you may not use fatal 511assertions in them; you'll get a compilation error if you try. Instead, either 512call `abort` and crash the entire test executable, or put the fatal assertion in 513a `SetUp`/`TearDown` function; see 514[constructor/destructor vs. `SetUp`/`TearDown`](faq.md#CtorVsSetUp) 515 516{: .callout .warning} 517WARNING: A fatal assertion in a helper function (private void-returning method) 518called from a constructor or destructor does not terminate the current test, as 519your intuition might suggest: it merely returns from the constructor or 520destructor early, possibly leaving your object in a partially-constructed or 521partially-destructed state! You almost certainly want to `abort` or use 522`SetUp`/`TearDown` instead. 523 524## Skipping test execution 525 526Related to the assertions `SUCCEED()` and `FAIL()`, you can prevent further test 527execution at runtime with the `GTEST_SKIP()` macro. This is useful when you need 528to check for preconditions of the system under test during runtime and skip 529tests in a meaningful way. 530 531`GTEST_SKIP()` can be used in individual test cases or in the `SetUp()` methods 532of classes derived from either `::testing::Environment` or `::testing::Test`. 533For example: 534 535```c++ 536TEST(SkipTest, DoesSkip) { 537 GTEST_SKIP() << "Skipping single test"; 538 EXPECT_EQ(0, 1); // Won't fail; it won't be executed 539} 540 541class SkipFixture : public ::testing::Test { 542 protected: 543 void SetUp() override { 544 GTEST_SKIP() << "Skipping all tests for this fixture"; 545 } 546}; 547 548// Tests for SkipFixture won't be executed. 549TEST_F(SkipFixture, SkipsOneTest) { 550 EXPECT_EQ(5, 7); // Won't fail 551} 552``` 553 554As with assertion macros, you can stream a custom message into `GTEST_SKIP()`. 555 556## Teaching googletest How to Print Your Values 557 558When a test assertion such as `EXPECT_EQ` fails, googletest prints the argument 559values to help you debug. It does this using a user-extensible value printer. 560 561This printer knows how to print built-in C++ types, native arrays, STL 562containers, and any type that supports the `<<` operator. For other types, it 563prints the raw bytes in the value and hopes that you the user can figure it out. 564 565As mentioned earlier, the printer is *extensible*. That means you can teach it 566to do a better job at printing your particular type than to dump the bytes. To 567do that, define `<<` for your type: 568 569```c++ 570#include <ostream> 571 572namespace foo { 573 574class Bar { // We want googletest to be able to print instances of this. 575... 576 // Create a free inline friend function. 577 friend std::ostream& operator<<(std::ostream& os, const Bar& bar) { 578 return os << bar.DebugString(); // whatever needed to print bar to os 579 } 580}; 581 582// If you can't declare the function in the class it's important that the 583// << operator is defined in the SAME namespace that defines Bar. C++'s look-up 584// rules rely on that. 585std::ostream& operator<<(std::ostream& os, const Bar& bar) { 586 return os << bar.DebugString(); // whatever needed to print bar to os 587} 588 589} // namespace foo 590``` 591 592Sometimes, this might not be an option: your team may consider it bad style to 593have a `<<` operator for `Bar`, or `Bar` may already have a `<<` operator that 594doesn't do what you want (and you cannot change it). If so, you can instead 595define a `PrintTo()` function like this: 596 597```c++ 598#include <ostream> 599 600namespace foo { 601 602class Bar { 603 ... 604 friend void PrintTo(const Bar& bar, std::ostream* os) { 605 *os << bar.DebugString(); // whatever needed to print bar to os 606 } 607}; 608 609// If you can't declare the function in the class it's important that PrintTo() 610// is defined in the SAME namespace that defines Bar. C++'s look-up rules rely 611// on that. 612void PrintTo(const Bar& bar, std::ostream* os) { 613 *os << bar.DebugString(); // whatever needed to print bar to os 614} 615 616} // namespace foo 617``` 618 619If you have defined both `<<` and `PrintTo()`, the latter will be used when 620googletest is concerned. This allows you to customize how the value appears in 621googletest's output without affecting code that relies on the behavior of its 622`<<` operator. 623 624If you want to print a value `x` using googletest's value printer yourself, just 625call `::testing::PrintToString(x)`, which returns an `std::string`: 626 627```c++ 628vector<pair<Bar, int> > bar_ints = GetBarIntVector(); 629 630EXPECT_TRUE(IsCorrectBarIntVector(bar_ints)) 631 << "bar_ints = " << testing::PrintToString(bar_ints); 632``` 633 634## Death Tests 635 636In many applications, there are assertions that can cause application failure if 637a condition is not met. These sanity checks, which ensure that the program is in 638a known good state, are there to fail at the earliest possible time after some 639program state is corrupted. If the assertion checks the wrong condition, then 640the program may proceed in an erroneous state, which could lead to memory 641corruption, security holes, or worse. Hence it is vitally important to test that 642such assertion statements work as expected. 643 644Since these precondition checks cause the processes to die, we call such tests 645_death tests_. More generally, any test that checks that a program terminates 646(except by throwing an exception) in an expected fashion is also a death test. 647 648Note that if a piece of code throws an exception, we don't consider it "death" 649for the purpose of death tests, as the caller of the code could catch the 650exception and avoid the crash. If you want to verify exceptions thrown by your 651code, see [Exception Assertions](#ExceptionAssertions). 652 653If you want to test `EXPECT_*()/ASSERT_*()` failures in your test code, see 654Catching Failures 655 656### How to Write a Death Test 657 658googletest has the following macros to support death tests: 659 660Fatal assertion | Nonfatal assertion | Verifies 661------------------------------------------------ | ------------------------------------------------ | -------- 662`ASSERT_DEATH(statement, matcher);` | `EXPECT_DEATH(statement, matcher);` | `statement` crashes with the given error 663`ASSERT_DEATH_IF_SUPPORTED(statement, matcher);` | `EXPECT_DEATH_IF_SUPPORTED(statement, matcher);` | if death tests are supported, verifies that `statement` crashes with the given error; otherwise verifies nothing 664`ASSERT_DEBUG_DEATH(statement, matcher);` | `EXPECT_DEBUG_DEATH(statement, matcher);` | `statement` crashes with the given error **in debug mode**. When not in debug (i.e. `NDEBUG` is defined), this just executes `statement` 665`ASSERT_EXIT(statement, predicate, matcher);` | `EXPECT_EXIT(statement, predicate, matcher);` | `statement` exits with the given error, and its exit code matches `predicate` 666 667where `statement` is a statement that is expected to cause the process to die, 668`predicate` is a function or function object that evaluates an integer exit 669status, and `matcher` is either a gMock matcher matching a `const std::string&` 670or a (Perl) regular expression - either of which is matched against the stderr 671output of `statement`. For legacy reasons, a bare string (i.e. with no matcher) 672is interpreted as `ContainsRegex(str)`, **not** `Eq(str)`. Note that `statement` 673can be *any valid statement* (including *compound statement*) and doesn't have 674to be an expression. 675 676As usual, the `ASSERT` variants abort the current test function, while the 677`EXPECT` variants do not. 678 679{: .callout .note} 680> NOTE: We use the word "crash" here to mean that the process terminates with a 681> *non-zero* exit status code. There are two possibilities: either the process 682> has called `exit()` or `_exit()` with a non-zero value, or it may be killed by 683> a signal. 684> 685> This means that if *`statement`* terminates the process with a 0 exit code, it 686> is *not* considered a crash by `EXPECT_DEATH`. Use `EXPECT_EXIT` instead if 687> this is the case, or if you want to restrict the exit code more precisely. 688 689A predicate here must accept an `int` and return a `bool`. The death test 690succeeds only if the predicate returns `true`. googletest defines a few 691predicates that handle the most common cases: 692 693```c++ 694::testing::ExitedWithCode(exit_code) 695``` 696 697This expression is `true` if the program exited normally with the given exit 698code. 699 700```c++ 701testing::KilledBySignal(signal_number) // Not available on Windows. 702``` 703 704This expression is `true` if the program was killed by the given signal. 705 706The `*_DEATH` macros are convenient wrappers for `*_EXIT` that use a predicate 707that verifies the process' exit code is non-zero. 708 709Note that a death test only cares about three things: 710 7111. does `statement` abort or exit the process? 7122. (in the case of `ASSERT_EXIT` and `EXPECT_EXIT`) does the exit status 713 satisfy `predicate`? Or (in the case of `ASSERT_DEATH` and `EXPECT_DEATH`) 714 is the exit status non-zero? And 7153. does the stderr output match `matcher`? 716 717In particular, if `statement` generates an `ASSERT_*` or `EXPECT_*` failure, it 718will **not** cause the death test to fail, as googletest assertions don't abort 719the process. 720 721To write a death test, simply use one of the above macros inside your test 722function. For example, 723 724```c++ 725TEST(MyDeathTest, Foo) { 726 // This death test uses a compound statement. 727 ASSERT_DEATH({ 728 int n = 5; 729 Foo(&n); 730 }, "Error on line .* of Foo()"); 731} 732 733TEST(MyDeathTest, NormalExit) { 734 EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success"); 735} 736 737TEST(MyDeathTest, KillMyself) { 738 EXPECT_EXIT(KillMyself(), testing::KilledBySignal(SIGKILL), 739 "Sending myself unblockable signal"); 740} 741``` 742 743verifies that: 744 745* calling `Foo(5)` causes the process to die with the given error message, 746* calling `NormalExit()` causes the process to print `"Success"` to stderr and 747 exit with exit code 0, and 748* calling `KillMyself()` kills the process with signal `SIGKILL`. 749 750The test function body may contain other assertions and statements as well, if 751necessary. 752 753### Death Test Naming 754 755{: .callout .important} 756IMPORTANT: We strongly recommend you to follow the convention of naming your 757**test suite** (not test) `*DeathTest` when it contains a death test, as 758demonstrated in the above example. The 759[Death Tests And Threads](#death-tests-and-threads) section below explains why. 760 761If a test fixture class is shared by normal tests and death tests, you can use 762`using` or `typedef` to introduce an alias for the fixture class and avoid 763duplicating its code: 764 765```c++ 766class FooTest : public testing::Test { ... }; 767 768using FooDeathTest = FooTest; 769 770TEST_F(FooTest, DoesThis) { 771 // normal test 772} 773 774TEST_F(FooDeathTest, DoesThat) { 775 // death test 776} 777``` 778 779### Regular Expression Syntax 780 781On POSIX systems (e.g. Linux, Cygwin, and Mac), googletest uses the 782[POSIX extended regular expression](http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04) 783syntax. To learn about this syntax, you may want to read this 784[Wikipedia entry](http://en.wikipedia.org/wiki/Regular_expression#POSIX_Extended_Regular_Expressions). 785 786On Windows, googletest uses its own simple regular expression implementation. It 787lacks many features. For example, we don't support union (`"x|y"`), grouping 788(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among 789others. Below is what we do support (`A` denotes a literal character, period 790(`.`), or a single `\\ ` escape sequence; `x` and `y` denote regular 791expressions.): 792 793Expression | Meaning 794---------- | -------------------------------------------------------------- 795`c` | matches any literal character `c` 796`\\d` | matches any decimal digit 797`\\D` | matches any character that's not a decimal digit 798`\\f` | matches `\f` 799`\\n` | matches `\n` 800`\\r` | matches `\r` 801`\\s` | matches any ASCII whitespace, including `\n` 802`\\S` | matches any character that's not a whitespace 803`\\t` | matches `\t` 804`\\v` | matches `\v` 805`\\w` | matches any letter, `_`, or decimal digit 806`\\W` | matches any character that `\\w` doesn't match 807`\\c` | matches any literal character `c`, which must be a punctuation 808`.` | matches any single character except `\n` 809`A?` | matches 0 or 1 occurrences of `A` 810`A*` | matches 0 or many occurrences of `A` 811`A+` | matches 1 or many occurrences of `A` 812`^` | matches the beginning of a string (not that of each line) 813`$` | matches the end of a string (not that of each line) 814`xy` | matches `x` followed by `y` 815 816To help you determine which capability is available on your system, googletest 817defines macros to govern which regular expression it is using. The macros are: 818`GTEST_USES_SIMPLE_RE=1` or `GTEST_USES_POSIX_RE=1`. If you want your death 819tests to work in all cases, you can either `#if` on these macros or use the more 820limited syntax only. 821 822### How It Works 823 824Under the hood, `ASSERT_EXIT()` spawns a new process and executes the death test 825statement in that process. The details of how precisely that happens depend on 826the platform and the variable `::testing::GTEST_FLAG(death_test_style)` (which is 827initialized from the command-line flag `--gtest_death_test_style`). 828 829* On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the 830 child, after which: 831 * If the variable's value is `"fast"`, the death test statement is 832 immediately executed. 833 * If the variable's value is `"threadsafe"`, the child process re-executes 834 the unit test binary just as it was originally invoked, but with some 835 extra flags to cause just the single death test under consideration to 836 be run. 837* On Windows, the child is spawned using the `CreateProcess()` API, and 838 re-executes the binary to cause just the single death test under 839 consideration to be run - much like the `threadsafe` mode on POSIX. 840 841Other values for the variable are illegal and will cause the death test to fail. 842Currently, the flag's default value is 843**`"fast"`**. 844 8451. the child's exit status satisfies the predicate, and 8462. the child's stderr matches the regular expression. 847 848If the death test statement runs to completion without dying, the child process 849will nonetheless terminate, and the assertion fails. 850 851### Death Tests And Threads 852 853The reason for the two death test styles has to do with thread safety. Due to 854well-known problems with forking in the presence of threads, death tests should 855be run in a single-threaded context. Sometimes, however, it isn't feasible to 856arrange that kind of environment. For example, statically-initialized modules 857may start threads before main is ever reached. Once threads have been created, 858it may be difficult or impossible to clean them up. 859 860googletest has three features intended to raise awareness of threading issues. 861 8621. A warning is emitted if multiple threads are running when a death test is 863 encountered. 8642. Test suites with a name ending in "DeathTest" are run before all other 865 tests. 8663. It uses `clone()` instead of `fork()` to spawn the child process on Linux 867 (`clone()` is not available on Cygwin and Mac), as `fork()` is more likely 868 to cause the child to hang when the parent process has multiple threads. 869 870It's perfectly fine to create threads inside a death test statement; they are 871executed in a separate process and cannot affect the parent. 872 873### Death Test Styles 874 875The "threadsafe" death test style was introduced in order to help mitigate the 876risks of testing in a possibly multithreaded environment. It trades increased 877test execution time (potentially dramatically so) for improved thread safety. 878 879The automated testing framework does not set the style flag. You can choose a 880particular style of death tests by setting the flag programmatically: 881 882```c++ 883testing::FLAGS_gtest_death_test_style="threadsafe" 884``` 885 886You can do this in `main()` to set the style for all death tests in the binary, 887or in individual tests. Recall that flags are saved before running each test and 888restored afterwards, so you need not do that yourself. For example: 889 890```c++ 891int main(int argc, char** argv) { 892 testing::InitGoogleTest(&argc, argv); 893 testing::FLAGS_gtest_death_test_style = "fast"; 894 return RUN_ALL_TESTS(); 895} 896 897TEST(MyDeathTest, TestOne) { 898 testing::FLAGS_gtest_death_test_style = "threadsafe"; 899 // This test is run in the "threadsafe" style: 900 ASSERT_DEATH(ThisShouldDie(), ""); 901} 902 903TEST(MyDeathTest, TestTwo) { 904 // This test is run in the "fast" style: 905 ASSERT_DEATH(ThisShouldDie(), ""); 906} 907``` 908 909### Caveats 910 911The `statement` argument of `ASSERT_EXIT()` can be any valid C++ statement. If 912it leaves the current function via a `return` statement or by throwing an 913exception, the death test is considered to have failed. Some googletest macros 914may return from the current function (e.g. `ASSERT_TRUE()`), so be sure to avoid 915them in `statement`. 916 917Since `statement` runs in the child process, any in-memory side effect (e.g. 918modifying a variable, releasing memory, etc) it causes will *not* be observable 919in the parent process. In particular, if you release memory in a death test, 920your program will fail the heap check as the parent process will never see the 921memory reclaimed. To solve this problem, you can 922 9231. try not to free memory in a death test; 9242. free the memory again in the parent process; or 9253. do not use the heap checker in your program. 926 927Due to an implementation detail, you cannot place multiple death test assertions 928on the same line; otherwise, compilation will fail with an unobvious error 929message. 930 931Despite the improved thread safety afforded by the "threadsafe" style of death 932test, thread problems such as deadlock are still possible in the presence of 933handlers registered with `pthread_atfork(3)`. 934 935 936## Using Assertions in Sub-routines 937 938{: .callout .note} 939Note: If you want to put a series of test assertions in a subroutine to check 940for a complex condition, consider using 941[a custom GMock matcher](gmock_cook_book.md#NewMatchers) 942instead. This lets you provide a more readable error message in case of failure 943and avoid all of the issues described below. 944 945### Adding Traces to Assertions 946 947If a test sub-routine is called from several places, when an assertion inside it 948fails, it can be hard to tell which invocation of the sub-routine the failure is 949from. You can alleviate this problem using extra logging or custom failure 950messages, but that usually clutters up your tests. A better solution is to use 951the `SCOPED_TRACE` macro or the `ScopedTrace` utility: 952 953```c++ 954SCOPED_TRACE(message); 955``` 956```c++ 957ScopedTrace trace("file_path", line_number, message); 958``` 959 960where `message` can be anything streamable to `std::ostream`. `SCOPED_TRACE` 961macro will cause the current file name, line number, and the given message to be 962added in every failure message. `ScopedTrace` accepts explicit file name and 963line number in arguments, which is useful for writing test helpers. The effect 964will be undone when the control leaves the current lexical scope. 965 966For example, 967 968```c++ 96910: void Sub1(int n) { 97011: EXPECT_EQ(Bar(n), 1); 97112: EXPECT_EQ(Bar(n + 1), 2); 97213: } 97314: 97415: TEST(FooTest, Bar) { 97516: { 97617: SCOPED_TRACE("A"); // This trace point will be included in 97718: // every failure in this scope. 97819: Sub1(1); 97920: } 98021: // Now it won't. 98122: Sub1(9); 98223: } 983``` 984 985could result in messages like these: 986 987```none 988path/to/foo_test.cc:11: Failure 989Value of: Bar(n) 990Expected: 1 991 Actual: 2 992Google Test trace: 993path/to/foo_test.cc:17: A 994 995path/to/foo_test.cc:12: Failure 996Value of: Bar(n + 1) 997Expected: 2 998 Actual: 3 999``` 1000 1001Without the trace, it would've been difficult to know which invocation of 1002`Sub1()` the two failures come from respectively. (You could add an extra 1003message to each assertion in `Sub1()` to indicate the value of `n`, but that's 1004tedious.) 1005 1006Some tips on using `SCOPED_TRACE`: 1007 10081. With a suitable message, it's often enough to use `SCOPED_TRACE` at the 1009 beginning of a sub-routine, instead of at each call site. 10102. When calling sub-routines inside a loop, make the loop iterator part of the 1011 message in `SCOPED_TRACE` such that you can know which iteration the failure 1012 is from. 10133. Sometimes the line number of the trace point is enough for identifying the 1014 particular invocation of a sub-routine. In this case, you don't have to 1015 choose a unique message for `SCOPED_TRACE`. You can simply use `""`. 10164. You can use `SCOPED_TRACE` in an inner scope when there is one in the outer 1017 scope. In this case, all active trace points will be included in the failure 1018 messages, in reverse order they are encountered. 10195. The trace dump is clickable in Emacs - hit `return` on a line number and 1020 you'll be taken to that line in the source file! 1021 1022### Propagating Fatal Failures 1023 1024A common pitfall when using `ASSERT_*` and `FAIL*` is not understanding that 1025when they fail they only abort the _current function_, not the entire test. For 1026example, the following test will segfault: 1027 1028```c++ 1029void Subroutine() { 1030 // Generates a fatal failure and aborts the current function. 1031 ASSERT_EQ(1, 2); 1032 1033 // The following won't be executed. 1034 ... 1035} 1036 1037TEST(FooTest, Bar) { 1038 Subroutine(); // The intended behavior is for the fatal failure 1039 // in Subroutine() to abort the entire test. 1040 1041 // The actual behavior: the function goes on after Subroutine() returns. 1042 int* p = nullptr; 1043 *p = 3; // Segfault! 1044} 1045``` 1046 1047To alleviate this, googletest provides three different solutions. You could use 1048either exceptions, the `(ASSERT|EXPECT)_NO_FATAL_FAILURE` assertions or the 1049`HasFatalFailure()` function. They are described in the following two 1050subsections. 1051 1052#### Asserting on Subroutines with an exception 1053 1054The following code can turn ASSERT-failure into an exception: 1055 1056```c++ 1057class ThrowListener : public testing::EmptyTestEventListener { 1058 void OnTestPartResult(const testing::TestPartResult& result) override { 1059 if (result.type() == testing::TestPartResult::kFatalFailure) { 1060 throw testing::AssertionException(result); 1061 } 1062 } 1063}; 1064int main(int argc, char** argv) { 1065 ... 1066 testing::UnitTest::GetInstance()->listeners().Append(new ThrowListener); 1067 return RUN_ALL_TESTS(); 1068} 1069``` 1070 1071This listener should be added after other listeners if you have any, otherwise 1072they won't see failed `OnTestPartResult`. 1073 1074#### Asserting on Subroutines 1075 1076As shown above, if your test calls a subroutine that has an `ASSERT_*` failure 1077in it, the test will continue after the subroutine returns. This may not be what 1078you want. 1079 1080Often people want fatal failures to propagate like exceptions. For that 1081googletest offers the following macros: 1082 1083Fatal assertion | Nonfatal assertion | Verifies 1084------------------------------------- | ------------------------------------- | -------- 1085`ASSERT_NO_FATAL_FAILURE(statement);` | `EXPECT_NO_FATAL_FAILURE(statement);` | `statement` doesn't generate any new fatal failures in the current thread. 1086 1087Only failures in the thread that executes the assertion are checked to determine 1088the result of this type of assertions. If `statement` creates new threads, 1089failures in these threads are ignored. 1090 1091Examples: 1092 1093```c++ 1094ASSERT_NO_FATAL_FAILURE(Foo()); 1095 1096int i; 1097EXPECT_NO_FATAL_FAILURE({ 1098 i = Bar(); 1099}); 1100``` 1101 1102Assertions from multiple threads are currently not supported on Windows. 1103 1104#### Checking for Failures in the Current Test 1105 1106`HasFatalFailure()` in the `::testing::Test` class returns `true` if an 1107assertion in the current test has suffered a fatal failure. This allows 1108functions to catch fatal failures in a sub-routine and return early. 1109 1110```c++ 1111class Test { 1112 public: 1113 ... 1114 static bool HasFatalFailure(); 1115}; 1116``` 1117 1118The typical usage, which basically simulates the behavior of a thrown exception, 1119is: 1120 1121```c++ 1122TEST(FooTest, Bar) { 1123 Subroutine(); 1124 // Aborts if Subroutine() had a fatal failure. 1125 if (HasFatalFailure()) return; 1126 1127 // The following won't be executed. 1128 ... 1129} 1130``` 1131 1132If `HasFatalFailure()` is used outside of `TEST()` , `TEST_F()` , or a test 1133fixture, you must add the `::testing::Test::` prefix, as in: 1134 1135```c++ 1136if (testing::Test::HasFatalFailure()) return; 1137``` 1138 1139Similarly, `HasNonfatalFailure()` returns `true` if the current test has at 1140least one non-fatal failure, and `HasFailure()` returns `true` if the current 1141test has at least one failure of either kind. 1142 1143## Logging Additional Information 1144 1145In your test code, you can call `RecordProperty("key", value)` to log additional 1146information, where `value` can be either a string or an `int`. The *last* value 1147recorded for a key will be emitted to the 1148[XML output](#generating-an-xml-report) if you specify one. For example, the 1149test 1150 1151```c++ 1152TEST_F(WidgetUsageTest, MinAndMaxWidgets) { 1153 RecordProperty("MaximumWidgets", ComputeMaxUsage()); 1154 RecordProperty("MinimumWidgets", ComputeMinUsage()); 1155} 1156``` 1157 1158will output XML like this: 1159 1160```xml 1161 ... 1162 <testcase name="MinAndMaxWidgets" status="run" time="0.006" classname="WidgetUsageTest" MaximumWidgets="12" MinimumWidgets="9" /> 1163 ... 1164``` 1165 1166{: .callout .note} 1167> NOTE: 1168> 1169> * `RecordProperty()` is a static member of the `Test` class. Therefore it 1170> needs to be prefixed with `::testing::Test::` if used outside of the 1171> `TEST` body and the test fixture class. 1172> * *`key`* must be a valid XML attribute name, and cannot conflict with the 1173> ones already used by googletest (`name`, `status`, `time`, `classname`, 1174> `type_param`, and `value_param`). 1175> * Calling `RecordProperty()` outside of the lifespan of a test is allowed. 1176> If it's called outside of a test but between a test suite's 1177> `SetUpTestSuite()` and `TearDownTestSuite()` methods, it will be 1178> attributed to the XML element for the test suite. If it's called outside 1179> of all test suites (e.g. in a test environment), it will be attributed to 1180> the top-level XML element. 1181 1182## Sharing Resources Between Tests in the Same Test Suite 1183 1184googletest creates a new test fixture object for each test in order to make 1185tests independent and easier to debug. However, sometimes tests use resources 1186that are expensive to set up, making the one-copy-per-test model prohibitively 1187expensive. 1188 1189If the tests don't change the resource, there's no harm in their sharing a 1190single resource copy. So, in addition to per-test set-up/tear-down, googletest 1191also supports per-test-suite set-up/tear-down. To use it: 1192 11931. In your test fixture class (say `FooTest` ), declare as `static` some member 1194 variables to hold the shared resources. 11952. Outside your test fixture class (typically just below it), define those 1196 member variables, optionally giving them initial values. 11973. In the same test fixture class, define a `static void SetUpTestSuite()` 1198 function (remember not to spell it as **`SetupTestSuite`** with a small 1199 `u`!) to set up the shared resources and a `static void TearDownTestSuite()` 1200 function to tear them down. 1201 1202That's it! googletest automatically calls `SetUpTestSuite()` before running the 1203*first test* in the `FooTest` test suite (i.e. before creating the first 1204`FooTest` object), and calls `TearDownTestSuite()` after running the *last test* 1205in it (i.e. after deleting the last `FooTest` object). In between, the tests can 1206use the shared resources. 1207 1208Remember that the test order is undefined, so your code can't depend on a test 1209preceding or following another. Also, the tests must either not modify the state 1210of any shared resource, or, if they do modify the state, they must restore the 1211state to its original value before passing control to the next test. 1212 1213Here's an example of per-test-suite set-up and tear-down: 1214 1215```c++ 1216class FooTest : public testing::Test { 1217 protected: 1218 // Per-test-suite set-up. 1219 // Called before the first test in this test suite. 1220 // Can be omitted if not needed. 1221 static void SetUpTestSuite() { 1222 shared_resource_ = new ...; 1223 } 1224 1225 // Per-test-suite tear-down. 1226 // Called after the last test in this test suite. 1227 // Can be omitted if not needed. 1228 static void TearDownTestSuite() { 1229 delete shared_resource_; 1230 shared_resource_ = nullptr; 1231 } 1232 1233 // You can define per-test set-up logic as usual. 1234 void SetUp() override { ... } 1235 1236 // You can define per-test tear-down logic as usual. 1237 void TearDown() override { ... } 1238 1239 // Some expensive resource shared by all tests. 1240 static T* shared_resource_; 1241}; 1242 1243T* FooTest::shared_resource_ = nullptr; 1244 1245TEST_F(FooTest, Test1) { 1246 ... you can refer to shared_resource_ here ... 1247} 1248 1249TEST_F(FooTest, Test2) { 1250 ... you can refer to shared_resource_ here ... 1251} 1252``` 1253 1254{: .callout .note} 1255NOTE: Though the above code declares `SetUpTestSuite()` protected, it may 1256sometimes be necessary to declare it public, such as when using it with 1257`TEST_P`. 1258 1259## Global Set-Up and Tear-Down 1260 1261Just as you can do set-up and tear-down at the test level and the test suite 1262level, you can also do it at the test program level. Here's how. 1263 1264First, you subclass the `::testing::Environment` class to define a test 1265environment, which knows how to set-up and tear-down: 1266 1267```c++ 1268class Environment : public ::testing::Environment { 1269 public: 1270 ~Environment() override {} 1271 1272 // Override this to define how to set up the environment. 1273 void SetUp() override {} 1274 1275 // Override this to define how to tear down the environment. 1276 void TearDown() override {} 1277}; 1278``` 1279 1280Then, you register an instance of your environment class with googletest by 1281calling the `::testing::AddGlobalTestEnvironment()` function: 1282 1283```c++ 1284Environment* AddGlobalTestEnvironment(Environment* env); 1285``` 1286 1287Now, when `RUN_ALL_TESTS()` is called, it first calls the `SetUp()` method of 1288each environment object, then runs the tests if none of the environments 1289reported fatal failures and `GTEST_SKIP()` was not called. `RUN_ALL_TESTS()` 1290always calls `TearDown()` with each environment object, regardless of whether or 1291not the tests were run. 1292 1293It's OK to register multiple environment objects. In this suite, their `SetUp()` 1294will be called in the order they are registered, and their `TearDown()` will be 1295called in the reverse order. 1296 1297Note that googletest takes ownership of the registered environment objects. 1298Therefore **do not delete them** by yourself. 1299 1300You should call `AddGlobalTestEnvironment()` before `RUN_ALL_TESTS()` is called, 1301probably in `main()`. If you use `gtest_main`, you need to call this before 1302`main()` starts for it to take effect. One way to do this is to define a global 1303variable like this: 1304 1305```c++ 1306testing::Environment* const foo_env = 1307 testing::AddGlobalTestEnvironment(new FooEnvironment); 1308``` 1309 1310However, we strongly recommend you to write your own `main()` and call 1311`AddGlobalTestEnvironment()` there, as relying on initialization of global 1312variables makes the code harder to read and may cause problems when you register 1313multiple environments from different translation units and the environments have 1314dependencies among them (remember that the compiler doesn't guarantee the order 1315in which global variables from different translation units are initialized). 1316 1317## Value-Parameterized Tests 1318 1319*Value-parameterized tests* allow you to test your code with different 1320parameters without writing multiple copies of the same test. This is useful in a 1321number of situations, for example: 1322 1323* You have a piece of code whose behavior is affected by one or more 1324 command-line flags. You want to make sure your code performs correctly for 1325 various values of those flags. 1326* You want to test different implementations of an OO interface. 1327* You want to test your code over various inputs (a.k.a. data-driven testing). 1328 This feature is easy to abuse, so please exercise your good sense when doing 1329 it! 1330 1331### How to Write Value-Parameterized Tests 1332 1333To write value-parameterized tests, first you should define a fixture class. It 1334must be derived from both `testing::Test` and `testing::WithParamInterface<T>` 1335(the latter is a pure interface), where `T` is the type of your parameter 1336values. For convenience, you can just derive the fixture class from 1337`testing::TestWithParam<T>`, which itself is derived from both `testing::Test` 1338and `testing::WithParamInterface<T>`. `T` can be any copyable type. If it's a 1339raw pointer, you are responsible for managing the lifespan of the pointed 1340values. 1341 1342{: .callout .note} 1343NOTE: If your test fixture defines `SetUpTestSuite()` or `TearDownTestSuite()` 1344they must be declared **public** rather than **protected** in order to use 1345`TEST_P`. 1346 1347```c++ 1348class FooTest : 1349 public testing::TestWithParam<const char*> { 1350 // You can implement all the usual fixture class members here. 1351 // To access the test parameter, call GetParam() from class 1352 // TestWithParam<T>. 1353}; 1354 1355// Or, when you want to add parameters to a pre-existing fixture class: 1356class BaseTest : public testing::Test { 1357 ... 1358}; 1359class BarTest : public BaseTest, 1360 public testing::WithParamInterface<const char*> { 1361 ... 1362}; 1363``` 1364 1365Then, use the `TEST_P` macro to define as many test patterns using this fixture 1366as you want. The `_P` suffix is for "parameterized" or "pattern", whichever you 1367prefer to think. 1368 1369```c++ 1370TEST_P(FooTest, DoesBlah) { 1371 // Inside a test, access the test parameter with the GetParam() method 1372 // of the TestWithParam<T> class: 1373 EXPECT_TRUE(foo.Blah(GetParam())); 1374 ... 1375} 1376 1377TEST_P(FooTest, HasBlahBlah) { 1378 ... 1379} 1380``` 1381 1382Finally, you can use `INSTANTIATE_TEST_SUITE_P` to instantiate the test suite 1383with any set of parameters you want. googletest defines a number of functions 1384for generating test parameters. They return what we call (surprise!) *parameter 1385generators*. Here is a summary of them, which are all in the `testing` 1386namespace: 1387 1388 1389| Parameter Generator | Behavior | 1390| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | 1391| `Range(begin, end [, step])` | Yields values `{begin, begin+step, begin+step+step, ...}`. The values do not include `end`. `step` defaults to 1. | 1392| `Values(v1, v2, ..., vN)` | Yields values `{v1, v2, ..., vN}`. | 1393| `ValuesIn(container)` and `ValuesIn(begin,end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)` | 1394| `Bool()` | Yields sequence `{false, true}`. | 1395| `Combine(g1, g2, ..., gN)` | Yields all combinations (Cartesian product) as std\:\:tuples of the values generated by the `N` generators. | 1396 1397 1398For more details, see the comments at the definitions of these functions. 1399 1400The following statement will instantiate tests from the `FooTest` test suite 1401each with parameter values `"meeny"`, `"miny"`, and `"moe"`. 1402 1403```c++ 1404INSTANTIATE_TEST_SUITE_P(MeenyMinyMoe, 1405 FooTest, 1406 testing::Values("meeny", "miny", "moe")); 1407``` 1408 1409{: .callout .note} 1410NOTE: The code above must be placed at global or namespace scope, not at 1411function scope. 1412 1413The first argument to `INSTANTIATE_TEST_SUITE_P` is a unique name for the 1414instantiation of the test suite. The next argument is the name of the test 1415pattern, and the last is the parameter generator. 1416 1417You can instantiate a test pattern more than once, so to distinguish different 1418instances of the pattern, the instantiation name is added as a prefix to the 1419actual test suite name. Remember to pick unique prefixes for different 1420instantiations. The tests from the instantiation above will have these names: 1421 1422* `MeenyMinyMoe/FooTest.DoesBlah/0` for `"meeny"` 1423* `MeenyMinyMoe/FooTest.DoesBlah/1` for `"miny"` 1424* `MeenyMinyMoe/FooTest.DoesBlah/2` for `"moe"` 1425* `MeenyMinyMoe/FooTest.HasBlahBlah/0` for `"meeny"` 1426* `MeenyMinyMoe/FooTest.HasBlahBlah/1` for `"miny"` 1427* `MeenyMinyMoe/FooTest.HasBlahBlah/2` for `"moe"` 1428 1429You can use these names in [`--gtest_filter`](#running-a-subset-of-the-tests). 1430 1431The following statement will instantiate all tests from `FooTest` again, each 1432with parameter values `"cat"` and `"dog"`: 1433 1434```c++ 1435const char* pets[] = {"cat", "dog"}; 1436INSTANTIATE_TEST_SUITE_P(Pets, FooTest, testing::ValuesIn(pets)); 1437``` 1438 1439The tests from the instantiation above will have these names: 1440 1441* `Pets/FooTest.DoesBlah/0` for `"cat"` 1442* `Pets/FooTest.DoesBlah/1` for `"dog"` 1443* `Pets/FooTest.HasBlahBlah/0` for `"cat"` 1444* `Pets/FooTest.HasBlahBlah/1` for `"dog"` 1445 1446Please note that `INSTANTIATE_TEST_SUITE_P` will instantiate *all* tests in the 1447given test suite, whether their definitions come before or *after* the 1448`INSTANTIATE_TEST_SUITE_P` statement. 1449 1450Additionally, by default, every `TEST_P` without a corresponding 1451`INSTANTIATE_TEST_SUITE_P` causes a failing test in test suite 1452`GoogleTestVerification`. If you have a test suite where that omission is not an 1453error, for example it is in a library that may be linked in for other reasons or 1454where the list of test cases is dynamic and may be empty, then this check can be 1455suppressed by tagging the test suite: 1456 1457```c++ 1458GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST(FooTest); 1459``` 1460 1461You can see [sample7_unittest.cc] and [sample8_unittest.cc] for more examples. 1462 1463[sample7_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample7_unittest.cc "Parameterized Test example" 1464[sample8_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample8_unittest.cc "Parameterized Test example with multiple parameters" 1465 1466### Creating Value-Parameterized Abstract Tests 1467 1468In the above, we define and instantiate `FooTest` in the *same* source file. 1469Sometimes you may want to define value-parameterized tests in a library and let 1470other people instantiate them later. This pattern is known as *abstract tests*. 1471As an example of its application, when you are designing an interface you can 1472write a standard suite of abstract tests (perhaps using a factory function as 1473the test parameter) that all implementations of the interface are expected to 1474pass. When someone implements the interface, they can instantiate your suite to 1475get all the interface-conformance tests for free. 1476 1477To define abstract tests, you should organize your code like this: 1478 14791. Put the definition of the parameterized test fixture class (e.g. `FooTest`) 1480 in a header file, say `foo_param_test.h`. Think of this as *declaring* your 1481 abstract tests. 14822. Put the `TEST_P` definitions in `foo_param_test.cc`, which includes 1483 `foo_param_test.h`. Think of this as *implementing* your abstract tests. 1484 1485Once they are defined, you can instantiate them by including `foo_param_test.h`, 1486invoking `INSTANTIATE_TEST_SUITE_P()`, and depending on the library target that 1487contains `foo_param_test.cc`. You can instantiate the same abstract test suite 1488multiple times, possibly in different source files. 1489 1490### Specifying Names for Value-Parameterized Test Parameters 1491 1492The optional last argument to `INSTANTIATE_TEST_SUITE_P()` allows the user to 1493specify a function or functor that generates custom test name suffixes based on 1494the test parameters. The function should accept one argument of type 1495`testing::TestParamInfo<class ParamType>`, and return `std::string`. 1496 1497`testing::PrintToStringParamName` is a builtin test suffix generator that 1498returns the value of `testing::PrintToString(GetParam())`. It does not work for 1499`std::string` or C strings. 1500 1501{: .callout .note} 1502NOTE: test names must be non-empty, unique, and may only contain ASCII 1503alphanumeric characters. In particular, they 1504[should not contain underscores](faq.md#why-should-test-suite-names-and-test-names-not-contain-underscore) 1505 1506```c++ 1507class MyTestSuite : public testing::TestWithParam<int> {}; 1508 1509TEST_P(MyTestSuite, MyTest) 1510{ 1511 std::cout << "Example Test Param: " << GetParam() << std::endl; 1512} 1513 1514INSTANTIATE_TEST_SUITE_P(MyGroup, MyTestSuite, testing::Range(0, 10), 1515 testing::PrintToStringParamName()); 1516``` 1517 1518Providing a custom functor allows for more control over test parameter name 1519generation, especially for types where the automatic conversion does not 1520generate helpful parameter names (e.g. strings as demonstrated above). The 1521following example illustrates this for multiple parameters, an enumeration type 1522and a string, and also demonstrates how to combine generators. It uses a lambda 1523for conciseness: 1524 1525```c++ 1526enum class MyType { MY_FOO = 0, MY_BAR = 1 }; 1527 1528class MyTestSuite : public testing::TestWithParam<std::tuple<MyType, std::string>> { 1529}; 1530 1531INSTANTIATE_TEST_SUITE_P( 1532 MyGroup, MyTestSuite, 1533 testing::Combine( 1534 testing::Values(MyType::MY_FOO, MyType::MY_BAR), 1535 testing::Values("A", "B")), 1536 [](const testing::TestParamInfo<MyTestSuite::ParamType>& info) { 1537 std::string name = absl::StrCat( 1538 std::get<0>(info.param) == MyType::MY_FOO ? "Foo" : "Bar", 1539 std::get<1>(info.param)); 1540 absl::c_replace_if(name, [](char c) { return !std::isalnum(c); }, ''); 1541 return name; 1542 }); 1543``` 1544 1545## Typed Tests 1546 1547Suppose you have multiple implementations of the same interface and want to make 1548sure that all of them satisfy some common requirements. Or, you may have defined 1549several types that are supposed to conform to the same "concept" and you want to 1550verify it. In both cases, you want the same test logic repeated for different 1551types. 1552 1553While you can write one `TEST` or `TEST_F` for each type you want to test (and 1554you may even factor the test logic into a function template that you invoke from 1555the `TEST`), it's tedious and doesn't scale: if you want `m` tests over `n` 1556types, you'll end up writing `m*n` `TEST`s. 1557 1558*Typed tests* allow you to repeat the same test logic over a list of types. You 1559only need to write the test logic once, although you must know the type list 1560when writing typed tests. Here's how you do it: 1561 1562First, define a fixture class template. It should be parameterized by a type. 1563Remember to derive it from `::testing::Test`: 1564 1565```c++ 1566template <typename T> 1567class FooTest : public testing::Test { 1568 public: 1569 ... 1570 using List = std::list<T>; 1571 static T shared_; 1572 T value_; 1573}; 1574``` 1575 1576Next, associate a list of types with the test suite, which will be repeated for 1577each type in the list: 1578 1579```c++ 1580using MyTypes = ::testing::Types<char, int, unsigned int>; 1581TYPED_TEST_SUITE(FooTest, MyTypes); 1582``` 1583 1584The type alias (`using` or `typedef`) is necessary for the `TYPED_TEST_SUITE` 1585macro to parse correctly. Otherwise the compiler will think that each comma in 1586the type list introduces a new macro argument. 1587 1588Then, use `TYPED_TEST()` instead of `TEST_F()` to define a typed test for this 1589test suite. You can repeat this as many times as you want: 1590 1591```c++ 1592TYPED_TEST(FooTest, DoesBlah) { 1593 // Inside a test, refer to the special name TypeParam to get the type 1594 // parameter. Since we are inside a derived class template, C++ requires 1595 // us to visit the members of FooTest via 'this'. 1596 TypeParam n = this->value_; 1597 1598 // To visit static members of the fixture, add the 'TestFixture::' 1599 // prefix. 1600 n += TestFixture::shared_; 1601 1602 // To refer to typedefs in the fixture, add the 'typename TestFixture::' 1603 // prefix. The 'typename' is required to satisfy the compiler. 1604 typename TestFixture::List values; 1605 1606 values.push_back(n); 1607 ... 1608} 1609 1610TYPED_TEST(FooTest, HasPropertyA) { ... } 1611``` 1612 1613You can see [sample6_unittest.cc] for a complete example. 1614 1615[sample6_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample6_unittest.cc "Typed Test example" 1616 1617## Type-Parameterized Tests 1618 1619*Type-parameterized tests* are like typed tests, except that they don't require 1620you to know the list of types ahead of time. Instead, you can define the test 1621logic first and instantiate it with different type lists later. You can even 1622instantiate it more than once in the same program. 1623 1624If you are designing an interface or concept, you can define a suite of 1625type-parameterized tests to verify properties that any valid implementation of 1626the interface/concept should have. Then, the author of each implementation can 1627just instantiate the test suite with their type to verify that it conforms to 1628the requirements, without having to write similar tests repeatedly. Here's an 1629example: 1630 1631First, define a fixture class template, as we did with typed tests: 1632 1633```c++ 1634template <typename T> 1635class FooTest : public testing::Test { 1636 ... 1637}; 1638``` 1639 1640Next, declare that you will define a type-parameterized test suite: 1641 1642```c++ 1643TYPED_TEST_SUITE_P(FooTest); 1644``` 1645 1646Then, use `TYPED_TEST_P()` to define a type-parameterized test. You can repeat 1647this as many times as you want: 1648 1649```c++ 1650TYPED_TEST_P(FooTest, DoesBlah) { 1651 // Inside a test, refer to TypeParam to get the type parameter. 1652 TypeParam n = 0; 1653 ... 1654} 1655 1656TYPED_TEST_P(FooTest, HasPropertyA) { ... } 1657``` 1658 1659Now the tricky part: you need to register all test patterns using the 1660`REGISTER_TYPED_TEST_SUITE_P` macro before you can instantiate them. The first 1661argument of the macro is the test suite name; the rest are the names of the 1662tests in this test suite: 1663 1664```c++ 1665REGISTER_TYPED_TEST_SUITE_P(FooTest, 1666 DoesBlah, HasPropertyA); 1667``` 1668 1669Finally, you are free to instantiate the pattern with the types you want. If you 1670put the above code in a header file, you can `#include` it in multiple C++ 1671source files and instantiate it multiple times. 1672 1673```c++ 1674using MyTypes = ::testing::Types<char, int, unsigned int>; 1675INSTANTIATE_TYPED_TEST_SUITE_P(My, FooTest, MyTypes); 1676``` 1677 1678To distinguish different instances of the pattern, the first argument to the 1679`INSTANTIATE_TYPED_TEST_SUITE_P` macro is a prefix that will be added to the 1680actual test suite name. Remember to pick unique prefixes for different 1681instances. 1682 1683In the special case where the type list contains only one type, you can write 1684that type directly without `::testing::Types<...>`, like this: 1685 1686```c++ 1687INSTANTIATE_TYPED_TEST_SUITE_P(My, FooTest, int); 1688``` 1689 1690You can see [sample6_unittest.cc] for a complete example. 1691 1692## Testing Private Code 1693 1694If you change your software's internal implementation, your tests should not 1695break as long as the change is not observable by users. Therefore, **per the 1696black-box testing principle, most of the time you should test your code through 1697its public interfaces.** 1698 1699**If you still find yourself needing to test internal implementation code, 1700consider if there's a better design.** The desire to test internal 1701implementation is often a sign that the class is doing too much. Consider 1702extracting an implementation class, and testing it. Then use that implementation 1703class in the original class. 1704 1705If you absolutely have to test non-public interface code though, you can. There 1706are two cases to consider: 1707 1708* Static functions ( *not* the same as static member functions!) or unnamed 1709 namespaces, and 1710* Private or protected class members 1711 1712To test them, we use the following special techniques: 1713 1714* Both static functions and definitions/declarations in an unnamed namespace 1715 are only visible within the same translation unit. To test them, you can 1716 `#include` the entire `.cc` file being tested in your `*_test.cc` file. 1717 (#including `.cc` files is not a good way to reuse code - you should not do 1718 this in production code!) 1719 1720 However, a better approach is to move the private code into the 1721 `foo::internal` namespace, where `foo` is the namespace your project 1722 normally uses, and put the private declarations in a `*-internal.h` file. 1723 Your production `.cc` files and your tests are allowed to include this 1724 internal header, but your clients are not. This way, you can fully test your 1725 internal implementation without leaking it to your clients. 1726 1727* Private class members are only accessible from within the class or by 1728 friends. To access a class' private members, you can declare your test 1729 fixture as a friend to the class and define accessors in your fixture. Tests 1730 using the fixture can then access the private members of your production 1731 class via the accessors in the fixture. Note that even though your fixture 1732 is a friend to your production class, your tests are not automatically 1733 friends to it, as they are technically defined in sub-classes of the 1734 fixture. 1735 1736 Another way to test private members is to refactor them into an 1737 implementation class, which is then declared in a `*-internal.h` file. Your 1738 clients aren't allowed to include this header but your tests can. Such is 1739 called the 1740 [Pimpl](https://www.gamedev.net/articles/programming/general-and-gameplay-programming/the-c-pimpl-r1794/) 1741 (Private Implementation) idiom. 1742 1743 Or, you can declare an individual test as a friend of your class by adding 1744 this line in the class body: 1745 1746 ```c++ 1747 FRIEND_TEST(TestSuiteName, TestName); 1748 ``` 1749 1750 For example, 1751 1752 ```c++ 1753 // foo.h 1754 class Foo { 1755 ... 1756 private: 1757 FRIEND_TEST(FooTest, BarReturnsZeroOnNull); 1758 1759 int Bar(void* x); 1760 }; 1761 1762 // foo_test.cc 1763 ... 1764 TEST(FooTest, BarReturnsZeroOnNull) { 1765 Foo foo; 1766 EXPECT_EQ(foo.Bar(NULL), 0); // Uses Foo's private member Bar(). 1767 } 1768 ``` 1769 1770 Pay special attention when your class is defined in a namespace. If you want 1771 your test fixtures and tests to be friends of your class, then they must be 1772 defined in the exact same namespace (no anonymous or inline namespaces). 1773 1774 For example, if the code to be tested looks like: 1775 1776 ```c++ 1777 namespace my_namespace { 1778 1779 class Foo { 1780 friend class FooTest; 1781 FRIEND_TEST(FooTest, Bar); 1782 FRIEND_TEST(FooTest, Baz); 1783 ... definition of the class Foo ... 1784 }; 1785 1786 } // namespace my_namespace 1787 ``` 1788 1789 Your test code should be something like: 1790 1791 ```c++ 1792 namespace my_namespace { 1793 1794 class FooTest : public testing::Test { 1795 protected: 1796 ... 1797 }; 1798 1799 TEST_F(FooTest, Bar) { ... } 1800 TEST_F(FooTest, Baz) { ... } 1801 1802 } // namespace my_namespace 1803 ``` 1804 1805## "Catching" Failures 1806 1807If you are building a testing utility on top of googletest, you'll want to test 1808your utility. What framework would you use to test it? googletest, of course. 1809 1810The challenge is to verify that your testing utility reports failures correctly. 1811In frameworks that report a failure by throwing an exception, you could catch 1812the exception and assert on it. But googletest doesn't use exceptions, so how do 1813we test that a piece of code generates an expected failure? 1814 1815`"gtest/gtest-spi.h"` contains some constructs to do this. After #including this header, 1816you can use 1817 1818```c++ 1819 EXPECT_FATAL_FAILURE(statement, substring); 1820``` 1821 1822to assert that `statement` generates a fatal (e.g. `ASSERT_*`) failure in the 1823current thread whose message contains the given `substring`, or use 1824 1825```c++ 1826 EXPECT_NONFATAL_FAILURE(statement, substring); 1827``` 1828 1829if you are expecting a non-fatal (e.g. `EXPECT_*`) failure. 1830 1831Only failures in the current thread are checked to determine the result of this 1832type of expectations. If `statement` creates new threads, failures in these 1833threads are also ignored. If you want to catch failures in other threads as 1834well, use one of the following macros instead: 1835 1836```c++ 1837 EXPECT_FATAL_FAILURE_ON_ALL_THREADS(statement, substring); 1838 EXPECT_NONFATAL_FAILURE_ON_ALL_THREADS(statement, substring); 1839``` 1840 1841{: .callout .note} 1842NOTE: Assertions from multiple threads are currently not supported on Windows. 1843 1844For technical reasons, there are some caveats: 1845 18461. You cannot stream a failure message to either macro. 1847 18482. `statement` in `EXPECT_FATAL_FAILURE{_ON_ALL_THREADS}()` cannot reference 1849 local non-static variables or non-static members of `this` object. 1850 18513. `statement` in `EXPECT_FATAL_FAILURE{_ON_ALL_THREADS}()` cannot return a 1852 value. 1853 1854## Registering tests programmatically 1855 1856The `TEST` macros handle the vast majority of all use cases, but there are few 1857where runtime registration logic is required. For those cases, the framework 1858provides the `::testing::RegisterTest` that allows callers to register arbitrary 1859tests dynamically. 1860 1861This is an advanced API only to be used when the `TEST` macros are insufficient. 1862The macros should be preferred when possible, as they avoid most of the 1863complexity of calling this function. 1864 1865It provides the following signature: 1866 1867```c++ 1868template <typename Factory> 1869TestInfo* RegisterTest(const char* test_suite_name, const char* test_name, 1870 const char* type_param, const char* value_param, 1871 const char* file, int line, Factory factory); 1872``` 1873 1874The `factory` argument is a factory callable (move-constructible) object or 1875function pointer that creates a new instance of the Test object. It handles 1876ownership to the caller. The signature of the callable is `Fixture*()`, where 1877`Fixture` is the test fixture class for the test. All tests registered with the 1878same `test_suite_name` must return the same fixture type. This is checked at 1879runtime. 1880 1881The framework will infer the fixture class from the factory and will call the 1882`SetUpTestSuite` and `TearDownTestSuite` for it. 1883 1884Must be called before `RUN_ALL_TESTS()` is invoked, otherwise behavior is 1885undefined. 1886 1887Use case example: 1888 1889```c++ 1890class MyFixture : public testing::Test { 1891 public: 1892 // All of these optional, just like in regular macro usage. 1893 static void SetUpTestSuite() { ... } 1894 static void TearDownTestSuite() { ... } 1895 void SetUp() override { ... } 1896 void TearDown() override { ... } 1897}; 1898 1899class MyTest : public MyFixture { 1900 public: 1901 explicit MyTest(int data) : data_(data) {} 1902 void TestBody() override { ... } 1903 1904 private: 1905 int data_; 1906}; 1907 1908void RegisterMyTests(const std::vector<int>& values) { 1909 for (int v : values) { 1910 testing::RegisterTest( 1911 "MyFixture", ("Test" + std::to_string(v)).c_str(), nullptr, 1912 std::to_string(v).c_str(), 1913 __FILE__, __LINE__, 1914 // Important to use the fixture type as the return type here. 1915 [=]() -> MyFixture* { return new MyTest(v); }); 1916 } 1917} 1918... 1919int main(int argc, char** argv) { 1920 std::vector<int> values_to_test = LoadValuesFromConfig(); 1921 RegisterMyTests(values_to_test); 1922 ... 1923 return RUN_ALL_TESTS(); 1924} 1925``` 1926## Getting the Current Test's Name 1927 1928Sometimes a function may need to know the name of the currently running test. 1929For example, you may be using the `SetUp()` method of your test fixture to set 1930the golden file name based on which test is running. The `::testing::TestInfo` 1931class has this information: 1932 1933```c++ 1934namespace testing { 1935 1936class TestInfo { 1937 public: 1938 // Returns the test suite name and the test name, respectively. 1939 // 1940 // Do NOT delete or free the return value - it's managed by the 1941 // TestInfo class. 1942 const char* test_suite_name() const; 1943 const char* name() const; 1944}; 1945 1946} 1947``` 1948 1949To obtain a `TestInfo` object for the currently running test, call 1950`current_test_info()` on the `UnitTest` singleton object: 1951 1952```c++ 1953 // Gets information about the currently running test. 1954 // Do NOT delete the returned object - it's managed by the UnitTest class. 1955 const testing::TestInfo* const test_info = 1956 testing::UnitTest::GetInstance()->current_test_info(); 1957 1958 printf("We are in test %s of test suite %s.\n", 1959 test_info->name(), 1960 test_info->test_suite_name()); 1961``` 1962 1963`current_test_info()` returns a null pointer if no test is running. In 1964particular, you cannot find the test suite name in `SetUpTestSuite()`, 1965`TearDownTestSuite()` (where you know the test suite name implicitly), or 1966functions called from them. 1967 1968## Extending googletest by Handling Test Events 1969 1970googletest provides an **event listener API** to let you receive notifications 1971about the progress of a test program and test failures. The events you can 1972listen to include the start and end of the test program, a test suite, or a test 1973method, among others. You may use this API to augment or replace the standard 1974console output, replace the XML output, or provide a completely different form 1975of output, such as a GUI or a database. You can also use test events as 1976checkpoints to implement a resource leak checker, for example. 1977 1978### Defining Event Listeners 1979 1980To define a event listener, you subclass either testing::TestEventListener or 1981testing::EmptyTestEventListener The former is an (abstract) interface, where 1982*each pure virtual method can be overridden to handle a test event* (For 1983example, when a test starts, the `OnTestStart()` method will be called.). The 1984latter provides an empty implementation of all methods in the interface, such 1985that a subclass only needs to override the methods it cares about. 1986 1987When an event is fired, its context is passed to the handler function as an 1988argument. The following argument types are used: 1989 1990* UnitTest reflects the state of the entire test program, 1991* TestSuite has information about a test suite, which can contain one or more 1992 tests, 1993* TestInfo contains the state of a test, and 1994* TestPartResult represents the result of a test assertion. 1995 1996An event handler function can examine the argument it receives to find out 1997interesting information about the event and the test program's state. 1998 1999Here's an example: 2000 2001```c++ 2002 class MinimalistPrinter : public testing::EmptyTestEventListener { 2003 // Called before a test starts. 2004 void OnTestStart(const testing::TestInfo& test_info) override { 2005 printf("*** Test %s.%s starting.\n", 2006 test_info.test_suite_name(), test_info.name()); 2007 } 2008 2009 // Called after a failed assertion or a SUCCESS(). 2010 void OnTestPartResult(const testing::TestPartResult& test_part_result) override { 2011 printf("%s in %s:%d\n%s\n", 2012 test_part_result.failed() ? "*** Failure" : "Success", 2013 test_part_result.file_name(), 2014 test_part_result.line_number(), 2015 test_part_result.summary()); 2016 } 2017 2018 // Called after a test ends. 2019 void OnTestEnd(const testing::TestInfo& test_info) override { 2020 printf("*** Test %s.%s ending.\n", 2021 test_info.test_suite_name(), test_info.name()); 2022 } 2023 }; 2024``` 2025 2026### Using Event Listeners 2027 2028To use the event listener you have defined, add an instance of it to the 2029googletest event listener list (represented by class TestEventListeners - note 2030the "s" at the end of the name) in your `main()` function, before calling 2031`RUN_ALL_TESTS()`: 2032 2033```c++ 2034int main(int argc, char** argv) { 2035 testing::InitGoogleTest(&argc, argv); 2036 // Gets hold of the event listener list. 2037 testing::TestEventListeners& listeners = 2038 testing::UnitTest::GetInstance()->listeners(); 2039 // Adds a listener to the end. googletest takes the ownership. 2040 listeners.Append(new MinimalistPrinter); 2041 return RUN_ALL_TESTS(); 2042} 2043``` 2044 2045There's only one problem: the default test result printer is still in effect, so 2046its output will mingle with the output from your minimalist printer. To suppress 2047the default printer, just release it from the event listener list and delete it. 2048You can do so by adding one line: 2049 2050```c++ 2051 ... 2052 delete listeners.Release(listeners.default_result_printer()); 2053 listeners.Append(new MinimalistPrinter); 2054 return RUN_ALL_TESTS(); 2055``` 2056 2057Now, sit back and enjoy a completely different output from your tests. For more 2058details, see [sample9_unittest.cc]. 2059 2060[sample9_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample9_unittest.cc "Event listener example" 2061 2062You may append more than one listener to the list. When an `On*Start()` or 2063`OnTestPartResult()` event is fired, the listeners will receive it in the order 2064they appear in the list (since new listeners are added to the end of the list, 2065the default text printer and the default XML generator will receive the event 2066first). An `On*End()` event will be received by the listeners in the *reverse* 2067order. This allows output by listeners added later to be framed by output from 2068listeners added earlier. 2069 2070### Generating Failures in Listeners 2071 2072You may use failure-raising macros (`EXPECT_*()`, `ASSERT_*()`, `FAIL()`, etc) 2073when processing an event. There are some restrictions: 2074 20751. You cannot generate any failure in `OnTestPartResult()` (otherwise it will 2076 cause `OnTestPartResult()` to be called recursively). 20772. A listener that handles `OnTestPartResult()` is not allowed to generate any 2078 failure. 2079 2080When you add listeners to the listener list, you should put listeners that 2081handle `OnTestPartResult()` *before* listeners that can generate failures. This 2082ensures that failures generated by the latter are attributed to the right test 2083by the former. 2084 2085See [sample10_unittest.cc] for an example of a failure-raising listener. 2086 2087[sample10_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample10_unittest.cc "Failure-raising listener example" 2088 2089## Running Test Programs: Advanced Options 2090 2091googletest test programs are ordinary executables. Once built, you can run them 2092directly and affect their behavior via the following environment variables 2093and/or command line flags. For the flags to work, your programs must call 2094`::testing::InitGoogleTest()` before calling `RUN_ALL_TESTS()`. 2095 2096To see a list of supported flags and their usage, please run your test program 2097with the `--help` flag. You can also use `-h`, `-?`, or `/?` for short. 2098 2099If an option is specified both by an environment variable and by a flag, the 2100latter takes precedence. 2101 2102### Selecting Tests 2103 2104#### Listing Test Names 2105 2106Sometimes it is necessary to list the available tests in a program before 2107running them so that a filter may be applied if needed. Including the flag 2108`--gtest_list_tests` overrides all other flags and lists tests in the following 2109format: 2110 2111```none 2112TestSuite1. 2113 TestName1 2114 TestName2 2115TestSuite2. 2116 TestName 2117``` 2118 2119None of the tests listed are actually run if the flag is provided. There is no 2120corresponding environment variable for this flag. 2121 2122#### Running a Subset of the Tests 2123 2124By default, a googletest program runs all tests the user has defined. Sometimes, 2125you want to run only a subset of the tests (e.g. for debugging or quickly 2126verifying a change). If you set the `GTEST_FILTER` environment variable or the 2127`--gtest_filter` flag to a filter string, googletest will only run the tests 2128whose full names (in the form of `TestSuiteName.TestName`) match the filter. 2129 2130The format of a filter is a '`:`'-separated list of wildcard patterns (called 2131the *positive patterns*) optionally followed by a '`-`' and another 2132'`:`'-separated pattern list (called the *negative patterns*). A test matches 2133the filter if and only if it matches any of the positive patterns but does not 2134match any of the negative patterns. 2135 2136A pattern may contain `'*'` (matches any string) or `'?'` (matches any single 2137character). For convenience, the filter `'*-NegativePatterns'` can be also 2138written as `'-NegativePatterns'`. 2139 2140For example: 2141 2142* `./foo_test` Has no flag, and thus runs all its tests. 2143* `./foo_test --gtest_filter=*` Also runs everything, due to the single 2144 match-everything `*` value. 2145* `./foo_test --gtest_filter=FooTest.*` Runs everything in test suite 2146 `FooTest` . 2147* `./foo_test --gtest_filter=*Null*:*Constructor*` Runs any test whose full 2148 name contains either `"Null"` or `"Constructor"` . 2149* `./foo_test --gtest_filter=-*DeathTest.*` Runs all non-death tests. 2150* `./foo_test --gtest_filter=FooTest.*-FooTest.Bar` Runs everything in test 2151 suite `FooTest` except `FooTest.Bar`. 2152* `./foo_test --gtest_filter=FooTest.*:BarTest.*-FooTest.Bar:BarTest.Foo` Runs 2153 everything in test suite `FooTest` except `FooTest.Bar` and everything in 2154 test suite `BarTest` except `BarTest.Foo`. 2155 2156#### Stop test execution upon first failure 2157 2158By default, a googletest program runs all tests the user has defined. In some 2159cases (e.g. iterative test development & execution) it may be desirable stop 2160test execution upon first failure (trading improved latency for completeness). 2161If `GTEST_FAIL_FAST` environment variable or `--gtest_fail_fast` flag is set, 2162the test runner will stop execution as soon as the first test failure is 2163found. 2164 2165#### Temporarily Disabling Tests 2166 2167If you have a broken test that you cannot fix right away, you can add the 2168`DISABLED_` prefix to its name. This will exclude it from execution. This is 2169better than commenting out the code or using `#if 0`, as disabled tests are 2170still compiled (and thus won't rot). 2171 2172If you need to disable all tests in a test suite, you can either add `DISABLED_` 2173to the front of the name of each test, or alternatively add it to the front of 2174the test suite name. 2175 2176For example, the following tests won't be run by googletest, even though they 2177will still be compiled: 2178 2179```c++ 2180// Tests that Foo does Abc. 2181TEST(FooTest, DISABLED_DoesAbc) { ... } 2182 2183class DISABLED_BarTest : public testing::Test { ... }; 2184 2185// Tests that Bar does Xyz. 2186TEST_F(DISABLED_BarTest, DoesXyz) { ... } 2187``` 2188 2189{: .callout .note} 2190NOTE: This feature should only be used for temporary pain-relief. You still have 2191to fix the disabled tests at a later date. As a reminder, googletest will print 2192a banner warning you if a test program contains any disabled tests. 2193 2194{: .callout .tip} 2195TIP: You can easily count the number of disabled tests you have using 2196`grep`. This number can be used as a metric for 2197improving your test quality. 2198 2199#### Temporarily Enabling Disabled Tests 2200 2201To include disabled tests in test execution, just invoke the test program with 2202the `--gtest_also_run_disabled_tests` flag or set the 2203`GTEST_ALSO_RUN_DISABLED_TESTS` environment variable to a value other than `0`. 2204You can combine this with the `--gtest_filter` flag to further select which 2205disabled tests to run. 2206 2207### Repeating the Tests 2208 2209Once in a while you'll run into a test whose result is hit-or-miss. Perhaps it 2210will fail only 1% of the time, making it rather hard to reproduce the bug under 2211a debugger. This can be a major source of frustration. 2212 2213The `--gtest_repeat` flag allows you to repeat all (or selected) test methods in 2214a program many times. Hopefully, a flaky test will eventually fail and give you 2215a chance to debug. Here's how to use it: 2216 2217```none 2218$ foo_test --gtest_repeat=1000 2219Repeat foo_test 1000 times and don't stop at failures. 2220 2221$ foo_test --gtest_repeat=-1 2222A negative count means repeating forever. 2223 2224$ foo_test --gtest_repeat=1000 --gtest_break_on_failure 2225Repeat foo_test 1000 times, stopping at the first failure. This 2226is especially useful when running under a debugger: when the test 2227fails, it will drop into the debugger and you can then inspect 2228variables and stacks. 2229 2230$ foo_test --gtest_repeat=1000 --gtest_filter=FooBar.* 2231Repeat the tests whose name matches the filter 1000 times. 2232``` 2233 2234If your test program contains 2235[global set-up/tear-down](#global-set-up-and-tear-down) code, it will be 2236repeated in each iteration as well, as the flakiness may be in it. You can also 2237specify the repeat count by setting the `GTEST_REPEAT` environment variable. 2238 2239### Shuffling the Tests 2240 2241You can specify the `--gtest_shuffle` flag (or set the `GTEST_SHUFFLE` 2242environment variable to `1`) to run the tests in a program in a random order. 2243This helps to reveal bad dependencies between tests. 2244 2245By default, googletest uses a random seed calculated from the current time. 2246Therefore you'll get a different order every time. The console output includes 2247the random seed value, such that you can reproduce an order-related test failure 2248later. To specify the random seed explicitly, use the `--gtest_random_seed=SEED` 2249flag (or set the `GTEST_RANDOM_SEED` environment variable), where `SEED` is an 2250integer in the range [0, 99999]. The seed value 0 is special: it tells 2251googletest to do the default behavior of calculating the seed from the current 2252time. 2253 2254If you combine this with `--gtest_repeat=N`, googletest will pick a different 2255random seed and re-shuffle the tests in each iteration. 2256 2257### Controlling Test Output 2258 2259#### Colored Terminal Output 2260 2261googletest can use colors in its terminal output to make it easier to spot the 2262important information: 2263 2264<pre>... 2265<font color="green">[----------]</font> 1 test from FooTest 2266<font color="green">[ RUN ]</font> FooTest.DoesAbc 2267<font color="green">[ OK ]</font> FooTest.DoesAbc 2268<font color="green">[----------]</font> 2 tests from BarTest 2269<font color="green">[ RUN ]</font> BarTest.HasXyzProperty 2270<font color="green">[ OK ]</font> BarTest.HasXyzProperty 2271<font color="green">[ RUN ]</font> BarTest.ReturnsTrueOnSuccess 2272... some error messages ... 2273<font color="red">[ FAILED ]</font> BarTest.ReturnsTrueOnSuccess 2274... 2275<font color="green">[==========]</font> 30 tests from 14 test suites ran. 2276<font color="green">[ PASSED ]</font> 28 tests. 2277<font color="red">[ FAILED ]</font> 2 tests, listed below: 2278<font color="red">[ FAILED ]</font> BarTest.ReturnsTrueOnSuccess 2279<font color="red">[ FAILED ]</font> AnotherTest.DoesXyz 2280 2281 2 FAILED TESTS 2282</pre> 2283 2284You can set the `GTEST_COLOR` environment variable or the `--gtest_color` 2285command line flag to `yes`, `no`, or `auto` (the default) to enable colors, 2286disable colors, or let googletest decide. When the value is `auto`, googletest 2287will use colors if and only if the output goes to a terminal and (on non-Windows 2288platforms) the `TERM` environment variable is set to `xterm` or `xterm-color`. 2289 2290#### Suppressing test passes 2291 2292By default, googletest prints 1 line of output for each test, indicating if it 2293passed or failed. To show only test failures, run the test program with 2294`--gtest_brief=1`, or set the GTEST_BRIEF environment variable to `1`. 2295 2296#### Suppressing the Elapsed Time 2297 2298By default, googletest prints the time it takes to run each test. To disable 2299that, run the test program with the `--gtest_print_time=0` command line flag, or 2300set the GTEST_PRINT_TIME environment variable to `0`. 2301 2302#### Suppressing UTF-8 Text Output 2303 2304In case of assertion failures, googletest prints expected and actual values of 2305type `string` both as hex-encoded strings as well as in readable UTF-8 text if 2306they contain valid non-ASCII UTF-8 characters. If you want to suppress the UTF-8 2307text because, for example, you don't have an UTF-8 compatible output medium, run 2308the test program with `--gtest_print_utf8=0` or set the `GTEST_PRINT_UTF8` 2309environment variable to `0`. 2310 2311 2312 2313#### Generating an XML Report 2314 2315googletest can emit a detailed XML report to a file in addition to its normal 2316textual output. The report contains the duration of each test, and thus can help 2317you identify slow tests. 2318 2319To generate the XML report, set the `GTEST_OUTPUT` environment variable or the 2320`--gtest_output` flag to the string `"xml:path_to_output_file"`, which will 2321create the file at the given location. You can also just use the string `"xml"`, 2322in which case the output can be found in the `test_detail.xml` file in the 2323current directory. 2324 2325If you specify a directory (for example, `"xml:output/directory/"` on Linux or 2326`"xml:output\directory\"` on Windows), googletest will create the XML file in 2327that directory, named after the test executable (e.g. `foo_test.xml` for test 2328program `foo_test` or `foo_test.exe`). If the file already exists (perhaps left 2329over from a previous run), googletest will pick a different name (e.g. 2330`foo_test_1.xml`) to avoid overwriting it. 2331 2332The report is based on the `junitreport` Ant task. Since that format was 2333originally intended for Java, a little interpretation is required to make it 2334apply to googletest tests, as shown here: 2335 2336```xml 2337<testsuites name="AllTests" ...> 2338 <testsuite name="test_case_name" ...> 2339 <testcase name="test_name" ...> 2340 <failure message="..."/> 2341 <failure message="..."/> 2342 <failure message="..."/> 2343 </testcase> 2344 </testsuite> 2345</testsuites> 2346``` 2347 2348* The root `<testsuites>` element corresponds to the entire test program. 2349* `<testsuite>` elements correspond to googletest test suites. 2350* `<testcase>` elements correspond to googletest test functions. 2351 2352For instance, the following program 2353 2354```c++ 2355TEST(MathTest, Addition) { ... } 2356TEST(MathTest, Subtraction) { ... } 2357TEST(LogicTest, NonContradiction) { ... } 2358``` 2359 2360could generate this report: 2361 2362```xml 2363<?xml version="1.0" encoding="UTF-8"?> 2364<testsuites tests="3" failures="1" errors="0" time="0.035" timestamp="2011-10-31T18:52:42" name="AllTests"> 2365 <testsuite name="MathTest" tests="2" failures="1" errors="0" time="0.015"> 2366 <testcase name="Addition" status="run" time="0.007" classname=""> 2367 <failure message="Value of: add(1, 1)
 Actual: 3
Expected: 2" type="">...</failure> 2368 <failure message="Value of: add(1, -1)
 Actual: 1
Expected: 0" type="">...</failure> 2369 </testcase> 2370 <testcase name="Subtraction" status="run" time="0.005" classname=""> 2371 </testcase> 2372 </testsuite> 2373 <testsuite name="LogicTest" tests="1" failures="0" errors="0" time="0.005"> 2374 <testcase name="NonContradiction" status="run" time="0.005" classname=""> 2375 </testcase> 2376 </testsuite> 2377</testsuites> 2378``` 2379 2380Things to note: 2381 2382* The `tests` attribute of a `<testsuites>` or `<testsuite>` element tells how 2383 many test functions the googletest program or test suite contains, while the 2384 `failures` attribute tells how many of them failed. 2385 2386* The `time` attribute expresses the duration of the test, test suite, or 2387 entire test program in seconds. 2388 2389* The `timestamp` attribute records the local date and time of the test 2390 execution. 2391 2392* Each `<failure>` element corresponds to a single failed googletest 2393 assertion. 2394 2395#### Generating a JSON Report 2396 2397googletest can also emit a JSON report as an alternative format to XML. To 2398generate the JSON report, set the `GTEST_OUTPUT` environment variable or the 2399`--gtest_output` flag to the string `"json:path_to_output_file"`, which will 2400create the file at the given location. You can also just use the string 2401`"json"`, in which case the output can be found in the `test_detail.json` file 2402in the current directory. 2403 2404The report format conforms to the following JSON Schema: 2405 2406```json 2407{ 2408 "$schema": "http://json-schema.org/schema#", 2409 "type": "object", 2410 "definitions": { 2411 "TestCase": { 2412 "type": "object", 2413 "properties": { 2414 "name": { "type": "string" }, 2415 "tests": { "type": "integer" }, 2416 "failures": { "type": "integer" }, 2417 "disabled": { "type": "integer" }, 2418 "time": { "type": "string" }, 2419 "testsuite": { 2420 "type": "array", 2421 "items": { 2422 "$ref": "#/definitions/TestInfo" 2423 } 2424 } 2425 } 2426 }, 2427 "TestInfo": { 2428 "type": "object", 2429 "properties": { 2430 "name": { "type": "string" }, 2431 "status": { 2432 "type": "string", 2433 "enum": ["RUN", "NOTRUN"] 2434 }, 2435 "time": { "type": "string" }, 2436 "classname": { "type": "string" }, 2437 "failures": { 2438 "type": "array", 2439 "items": { 2440 "$ref": "#/definitions/Failure" 2441 } 2442 } 2443 } 2444 }, 2445 "Failure": { 2446 "type": "object", 2447 "properties": { 2448 "failures": { "type": "string" }, 2449 "type": { "type": "string" } 2450 } 2451 } 2452 }, 2453 "properties": { 2454 "tests": { "type": "integer" }, 2455 "failures": { "type": "integer" }, 2456 "disabled": { "type": "integer" }, 2457 "errors": { "type": "integer" }, 2458 "timestamp": { 2459 "type": "string", 2460 "format": "date-time" 2461 }, 2462 "time": { "type": "string" }, 2463 "name": { "type": "string" }, 2464 "testsuites": { 2465 "type": "array", 2466 "items": { 2467 "$ref": "#/definitions/TestCase" 2468 } 2469 } 2470 } 2471} 2472``` 2473 2474The report uses the format that conforms to the following Proto3 using the 2475[JSON encoding](https://developers.google.com/protocol-buffers/docs/proto3#json): 2476 2477```proto 2478syntax = "proto3"; 2479 2480package googletest; 2481 2482import "google/protobuf/timestamp.proto"; 2483import "google/protobuf/duration.proto"; 2484 2485message UnitTest { 2486 int32 tests = 1; 2487 int32 failures = 2; 2488 int32 disabled = 3; 2489 int32 errors = 4; 2490 google.protobuf.Timestamp timestamp = 5; 2491 google.protobuf.Duration time = 6; 2492 string name = 7; 2493 repeated TestCase testsuites = 8; 2494} 2495 2496message TestCase { 2497 string name = 1; 2498 int32 tests = 2; 2499 int32 failures = 3; 2500 int32 disabled = 4; 2501 int32 errors = 5; 2502 google.protobuf.Duration time = 6; 2503 repeated TestInfo testsuite = 7; 2504} 2505 2506message TestInfo { 2507 string name = 1; 2508 enum Status { 2509 RUN = 0; 2510 NOTRUN = 1; 2511 } 2512 Status status = 2; 2513 google.protobuf.Duration time = 3; 2514 string classname = 4; 2515 message Failure { 2516 string failures = 1; 2517 string type = 2; 2518 } 2519 repeated Failure failures = 5; 2520} 2521``` 2522 2523For instance, the following program 2524 2525```c++ 2526TEST(MathTest, Addition) { ... } 2527TEST(MathTest, Subtraction) { ... } 2528TEST(LogicTest, NonContradiction) { ... } 2529``` 2530 2531could generate this report: 2532 2533```json 2534{ 2535 "tests": 3, 2536 "failures": 1, 2537 "errors": 0, 2538 "time": "0.035s", 2539 "timestamp": "2011-10-31T18:52:42Z", 2540 "name": "AllTests", 2541 "testsuites": [ 2542 { 2543 "name": "MathTest", 2544 "tests": 2, 2545 "failures": 1, 2546 "errors": 0, 2547 "time": "0.015s", 2548 "testsuite": [ 2549 { 2550 "name": "Addition", 2551 "status": "RUN", 2552 "time": "0.007s", 2553 "classname": "", 2554 "failures": [ 2555 { 2556 "message": "Value of: add(1, 1)\n Actual: 3\nExpected: 2", 2557 "type": "" 2558 }, 2559 { 2560 "message": "Value of: add(1, -1)\n Actual: 1\nExpected: 0", 2561 "type": "" 2562 } 2563 ] 2564 }, 2565 { 2566 "name": "Subtraction", 2567 "status": "RUN", 2568 "time": "0.005s", 2569 "classname": "" 2570 } 2571 ] 2572 }, 2573 { 2574 "name": "LogicTest", 2575 "tests": 1, 2576 "failures": 0, 2577 "errors": 0, 2578 "time": "0.005s", 2579 "testsuite": [ 2580 { 2581 "name": "NonContradiction", 2582 "status": "RUN", 2583 "time": "0.005s", 2584 "classname": "" 2585 } 2586 ] 2587 } 2588 ] 2589} 2590``` 2591 2592{: .callout .important} 2593IMPORTANT: The exact format of the JSON document is subject to change. 2594 2595### Controlling How Failures Are Reported 2596 2597#### Detecting Test Premature Exit 2598 2599Google Test implements the _premature-exit-file_ protocol for test runners 2600to catch any kind of unexpected exits of test programs. Upon start, 2601Google Test creates the file which will be automatically deleted after 2602all work has been finished. Then, the test runner can check if this file 2603exists. In case the file remains undeleted, the inspected test has exited 2604prematurely. 2605 2606This feature is enabled only if the `TEST_PREMATURE_EXIT_FILE` environment 2607variable has been set. 2608 2609#### Turning Assertion Failures into Break-Points 2610 2611When running test programs under a debugger, it's very convenient if the 2612debugger can catch an assertion failure and automatically drop into interactive 2613mode. googletest's *break-on-failure* mode supports this behavior. 2614 2615To enable it, set the `GTEST_BREAK_ON_FAILURE` environment variable to a value 2616other than `0`. Alternatively, you can use the `--gtest_break_on_failure` 2617command line flag. 2618 2619#### Disabling Catching Test-Thrown Exceptions 2620 2621googletest can be used either with or without exceptions enabled. If a test 2622throws a C++ exception or (on Windows) a structured exception (SEH), by default 2623googletest catches it, reports it as a test failure, and continues with the next 2624test method. This maximizes the coverage of a test run. Also, on Windows an 2625uncaught exception will cause a pop-up window, so catching the exceptions allows 2626you to run the tests automatically. 2627 2628When debugging the test failures, however, you may instead want the exceptions 2629to be handled by the debugger, such that you can examine the call stack when an 2630exception is thrown. To achieve that, set the `GTEST_CATCH_EXCEPTIONS` 2631environment variable to `0`, or use the `--gtest_catch_exceptions=0` flag when 2632running the tests. 2633 2634### Sanitizer Integration 2635 2636The 2637[Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html), 2638[Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer), 2639and 2640[Thread Sanitizer](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual) 2641all provide weak functions that you can override to trigger explicit failures 2642when they detect sanitizer errors, such as creating a reference from `nullptr`. 2643To override these functions, place definitions for them in a source file that 2644you compile as part of your main binary: 2645 2646``` 2647extern "C" { 2648void __ubsan_on_report() { 2649 FAIL() << "Encountered an undefined behavior sanitizer error"; 2650} 2651void __asan_on_error() { 2652 FAIL() << "Encountered an address sanitizer error"; 2653} 2654void __tsan_on_report() { 2655 FAIL() << "Encountered a thread sanitizer error"; 2656} 2657} // extern "C" 2658``` 2659 2660After compiling your project with one of the sanitizers enabled, if a particular 2661test triggers a sanitizer error, googletest will report that it failed. 2662