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