3 Now that you have read [Primer](V1_6_Primer.md) and learned how to write tests
4 using Google Test, it's time to learn some new tricks. This document
5 will show you more assertions as well as how to construct complex
6 failure messages, propagate fatal failures, reuse and speed up your
7 test fixtures, and use various flags with your tests.
11 This section covers some less frequently used, but still significant,
14 ## Explicit Success and Failure ##
16 These three assertions do not actually test a value or expression. Instead,
17 they generate a success or failure directly. Like the macros that actually
18 perform a test, you may stream a custom failure message into the them.
23 Generates a success. This does NOT make the overall test succeed. A test is
24 considered successful only if none of its assertions fail during its execution.
26 Note: `SUCCEED()` is purely documentary and currently doesn't generate any
27 user-visible output. However, we may add `SUCCEED()` messages to Google Test's
30 | `FAIL();` | `ADD_FAILURE();` | `ADD_FAILURE_AT("`_file\_path_`", `_line\_number_`);` |
31 |:-----------|:-----------------|:------------------------------------------------------|
33 `FAIL()` generates a fatal failure, while `ADD_FAILURE()` and `ADD_FAILURE_AT()` generate a nonfatal
34 failure. These are useful when control flow, rather than a Boolean expression,
35 deteremines the test's success or failure. For example, you might want to write
40 case 1: ... some checks ...
41 case 2: ... some other checks
43 default: FAIL() << "We shouldn't get here.";
47 _Availability_: Linux, Windows, Mac.
49 ## Exception Assertions ##
51 These are for verifying that a piece of code throws (or does not
52 throw) an exception of the given type:
54 | **Fatal assertion** | **Nonfatal assertion** | **Verifies** |
55 |:--------------------|:-----------------------|:-------------|
56 | `ASSERT_THROW(`_statement_, _exception\_type_`);` | `EXPECT_THROW(`_statement_, _exception\_type_`);` | _statement_ throws an exception of the given type |
57 | `ASSERT_ANY_THROW(`_statement_`);` | `EXPECT_ANY_THROW(`_statement_`);` | _statement_ throws an exception of any type |
58 | `ASSERT_NO_THROW(`_statement_`);` | `EXPECT_NO_THROW(`_statement_`);` | _statement_ doesn't throw any exception |
63 ASSERT_THROW(Foo(5), bar_exception);
71 _Availability_: Linux, Windows, Mac; since version 1.1.0.
73 ## Predicate Assertions for Better Error Messages ##
75 Even though Google Test has a rich set of assertions, they can never be
76 complete, as it's impossible (nor a good idea) to anticipate all the scenarios
77 a user might run into. Therefore, sometimes a user has to use `EXPECT_TRUE()`
78 to check a complex expression, for lack of a better macro. This has the problem
79 of not showing you the values of the parts of the expression, making it hard to
80 understand what went wrong. As a workaround, some users choose to construct the
81 failure message by themselves, streaming it into `EXPECT_TRUE()`. However, this
82 is awkward especially when the expression has side-effects or is expensive to
85 Google Test gives you three different options to solve this problem:
87 ### Using an Existing Boolean Function ###
89 If you already have a function or a functor that returns `bool` (or a type
90 that can be implicitly converted to `bool`), you can use it in a _predicate
91 assertion_ to get the function arguments printed for free:
93 | **Fatal assertion** | **Nonfatal assertion** | **Verifies** |
94 |:--------------------|:-----------------------|:-------------|
95 | `ASSERT_PRED1(`_pred1, val1_`);` | `EXPECT_PRED1(`_pred1, val1_`);` | _pred1(val1)_ returns true |
96 | `ASSERT_PRED2(`_pred2, val1, val2_`);` | `EXPECT_PRED2(`_pred2, val1, val2_`);` | _pred2(val1, val2)_ returns true |
99 In the above, _predn_ is an _n_-ary predicate function or functor, where
100 _val1_, _val2_, ..., and _valn_ are its arguments. The assertion succeeds
101 if the predicate returns `true` when applied to the given arguments, and fails
102 otherwise. When the assertion fails, it prints the value of each argument. In
103 either case, the arguments are evaluated exactly once.
105 Here's an example. Given
108 // Returns true iff m and n have no common divisors except 1.
109 bool MutuallyPrime(int m, int n) { ... }
115 the assertion `EXPECT_PRED2(MutuallyPrime, a, b);` will succeed, while the
116 assertion `EXPECT_PRED2(MutuallyPrime, b, c);` will fail with the message
119 !MutuallyPrime(b, c) is false, where<br>
126 1. If you see a compiler error "no matching function to call" when using `ASSERT_PRED*` or `EXPECT_PRED*`, please see [this](v1_6_FAQ.md#ithe-compiler-complains-about-undefined-references-to-some-static-const-member-variables-but-i-did-define-them-in-the-class-body-whats-wrong) for how to resolve it.
127 1. Currently we only provide predicate assertions of arity <= 5. If you need a higher-arity assertion, let us know.
129 _Availability_: Linux, Windows, Mac
131 ### Using a Function That Returns an AssertionResult ###
133 While `EXPECT_PRED*()` and friends are handy for a quick job, the
134 syntax is not satisfactory: you have to use different macros for
135 different arities, and it feels more like Lisp than C++. The
136 `::testing::AssertionResult` class solves this problem.
138 An `AssertionResult` object represents the result of an assertion
139 (whether it's a success or a failure, and an associated message). You
140 can create an `AssertionResult` using one of these factory
146 // Returns an AssertionResult object to indicate that an assertion has
148 AssertionResult AssertionSuccess();
150 // Returns an AssertionResult object to indicate that an assertion has
152 AssertionResult AssertionFailure();
157 You can then use the `<<` operator to stream messages to the
158 `AssertionResult` object.
160 To provide more readable messages in Boolean assertions
161 (e.g. `EXPECT_TRUE()`), write a predicate function that returns
162 `AssertionResult` instead of `bool`. For example, if you define
166 ::testing::AssertionResult IsEven(int n) {
168 return ::testing::AssertionSuccess();
170 return ::testing::AssertionFailure() << n << " is odd";
182 the failed assertion `EXPECT_TRUE(IsEven(Fib(4)))` will print:
185 Value of: !IsEven(Fib(4))<br>
186 Actual: false (*3 is odd*)<br>
190 instead of a more opaque
193 Value of: !IsEven(Fib(4))<br>
198 If you want informative messages in `EXPECT_FALSE` and `ASSERT_FALSE`
199 as well, and are fine with making the predicate slower in the success
200 case, you can supply a success message:
203 ::testing::AssertionResult IsEven(int n) {
205 return ::testing::AssertionSuccess() << n << " is even";
207 return ::testing::AssertionFailure() << n << " is odd";
211 Then the statement `EXPECT_FALSE(IsEven(Fib(6)))` will print
214 Value of: !IsEven(Fib(6))<br>
215 Actual: true (8 is even)<br>
219 _Availability_: Linux, Windows, Mac; since version 1.4.1.
221 ### Using a Predicate-Formatter ###
223 If you find the default message generated by `(ASSERT|EXPECT)_PRED*` and
224 `(ASSERT|EXPECT)_(TRUE|FALSE)` unsatisfactory, or some arguments to your
225 predicate do not support streaming to `ostream`, you can instead use the
226 following _predicate-formatter assertions_ to _fully_ customize how the
227 message is formatted:
229 | **Fatal assertion** | **Nonfatal assertion** | **Verifies** |
230 |:--------------------|:-----------------------|:-------------|
231 | `ASSERT_PRED_FORMAT1(`_pred\_format1, val1_`);` | `EXPECT_PRED_FORMAT1(`_pred\_format1, val1_`); | _pred\_format1(val1)_ is successful |
232 | `ASSERT_PRED_FORMAT2(`_pred\_format2, val1, val2_`);` | `EXPECT_PRED_FORMAT2(`_pred\_format2, val1, val2_`);` | _pred\_format2(val1, val2)_ is successful |
233 | `...` | `...` | `...` |
235 The difference between this and the previous two groups of macros is that instead of
236 a predicate, `(ASSERT|EXPECT)_PRED_FORMAT*` take a _predicate-formatter_
237 (_pred\_formatn_), which is a function or functor with the signature:
239 `::testing::AssertionResult PredicateFormattern(const char* `_expr1_`, const char* `_expr2_`, ... const char* `_exprn_`, T1 `_val1_`, T2 `_val2_`, ... Tn `_valn_`);`
241 where _val1_, _val2_, ..., and _valn_ are the values of the predicate
242 arguments, and _expr1_, _expr2_, ..., and _exprn_ are the corresponding
243 expressions as they appear in the source code. The types `T1`, `T2`, ..., and
244 `Tn` can be either value types or reference types. For example, if an
245 argument has type `Foo`, you can declare it as either `Foo` or `const Foo&`,
246 whichever is appropriate.
248 A predicate-formatter returns a `::testing::AssertionResult` object to indicate
249 whether the assertion has succeeded or not. The only way to create such an
250 object is to call one of these factory functions:
252 As an example, let's improve the failure message in the previous example, which uses `EXPECT_PRED2()`:
255 // Returns the smallest prime common divisor of m and n,
256 // or 1 when m and n are mutually prime.
257 int SmallestPrimeCommonDivisor(int m, int n) { ... }
259 // A predicate-formatter for asserting that two integers are mutually prime.
260 ::testing::AssertionResult AssertMutuallyPrime(const char* m_expr,
264 if (MutuallyPrime(m, n))
265 return ::testing::AssertionSuccess();
267 return ::testing::AssertionFailure()
268 << m_expr << " and " << n_expr << " (" << m << " and " << n
269 << ") are not mutually prime, " << "as they have a common divisor "
270 << SmallestPrimeCommonDivisor(m, n);
274 With this predicate-formatter, we can use
277 EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c);
280 to generate the message
283 b and c (4 and 10) are not mutually prime, as they have a common divisor 2.<br>
286 As you may have realized, many of the assertions we introduced earlier are
287 special cases of `(EXPECT|ASSERT)_PRED_FORMAT*`. In fact, most of them are
288 indeed defined using `(EXPECT|ASSERT)_PRED_FORMAT*`.
290 _Availability_: Linux, Windows, Mac.
293 ## Floating-Point Comparison ##
295 Comparing floating-point numbers is tricky. Due to round-off errors, it is
296 very unlikely that two floating-points will match exactly. Therefore,
297 `ASSERT_EQ` 's naive comparison usually doesn't work. And since floating-points
298 can have a wide value range, no single fixed error bound works. It's better to
299 compare by a fixed relative error bound, except for values close to 0 due to
300 the loss of precision there.
302 In general, for floating-point comparison to make sense, the user needs to
303 carefully choose the error bound. If they don't want or care to, comparing in
304 terms of Units in the Last Place (ULPs) is a good default, and Google Test
305 provides assertions to do this. Full details about ULPs are quite long; if you
306 want to learn more, see
307 [this article on float comparison](http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm).
309 ### Floating-Point Macros ###
311 | **Fatal assertion** | **Nonfatal assertion** | **Verifies** |
312 |:--------------------|:-----------------------|:-------------|
313 | `ASSERT_FLOAT_EQ(`_expected, actual_`);` | `EXPECT_FLOAT_EQ(`_expected, actual_`);` | the two `float` values are almost equal |
314 | `ASSERT_DOUBLE_EQ(`_expected, actual_`);` | `EXPECT_DOUBLE_EQ(`_expected, actual_`);` | the two `double` values are almost equal |
316 By "almost equal", we mean the two values are within 4 ULP's from each
319 The following assertions allow you to choose the acceptable error bound:
321 | **Fatal assertion** | **Nonfatal assertion** | **Verifies** |
322 |:--------------------|:-----------------------|:-------------|
323 | `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 |
325 _Availability_: Linux, Windows, Mac.
327 ### Floating-Point Predicate-Format Functions ###
329 Some floating-point operations are useful, but not that often used. In order
330 to avoid an explosion of new macros, we provide them as predicate-format
331 functions that can be used in predicate assertion macros (e.g.
332 `EXPECT_PRED_FORMAT2`, etc).
335 EXPECT_PRED_FORMAT2(::testing::FloatLE, val1, val2);
336 EXPECT_PRED_FORMAT2(::testing::DoubleLE, val1, val2);
339 Verifies that _val1_ is less than, or almost equal to, _val2_. You can
340 replace `EXPECT_PRED_FORMAT2` in the above table with `ASSERT_PRED_FORMAT2`.
342 _Availability_: Linux, Windows, Mac.
344 ## Windows HRESULT assertions ##
346 These assertions test for `HRESULT` success or failure.
348 | **Fatal assertion** | **Nonfatal assertion** | **Verifies** |
349 |:--------------------|:-----------------------|:-------------|
350 | `ASSERT_HRESULT_SUCCEEDED(`_expression_`);` | `EXPECT_HRESULT_SUCCEEDED(`_expression_`);` | _expression_ is a success `HRESULT` |
351 | `ASSERT_HRESULT_FAILED(`_expression_`);` | `EXPECT_HRESULT_FAILED(`_expression_`);` | _expression_ is a failure `HRESULT` |
353 The generated output contains the human-readable error message
354 associated with the `HRESULT` code returned by _expression_.
356 You might use them like this:
360 ASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application"));
362 ASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty));
365 _Availability_: Windows.
367 ## Type Assertions ##
369 You can call the function
371 ::testing::StaticAssertTypeEq<T1, T2>();
373 to assert that types `T1` and `T2` are the same. The function does
374 nothing if the assertion is satisfied. If the types are different,
375 the function call will fail to compile, and the compiler error message
376 will likely (depending on the compiler) show you the actual values of
377 `T1` and `T2`. This is mainly useful inside template code.
379 _Caveat:_ When used inside a member function of a class template or a
380 function template, `StaticAssertTypeEq<T1, T2>()` is effective _only if_
381 the function is instantiated. For example, given:
383 template <typename T> class Foo {
385 void Bar() { ::testing::StaticAssertTypeEq<int, T>(); }
390 void Test1() { Foo<bool> foo; }
392 will _not_ generate a compiler error, as `Foo<bool>::Bar()` is never
393 actually instantiated. Instead, you need:
395 void Test2() { Foo<bool> foo; foo.Bar(); }
397 to cause a compiler error.
399 _Availability:_ Linux, Windows, Mac; since version 1.3.0.
401 ## Assertion Placement ##
403 You can use assertions in any C++ function. In particular, it doesn't
404 have to be a method of the test fixture class. The one constraint is
405 that assertions that generate a fatal failure (`FAIL*` and `ASSERT_*`)
406 can only be used in void-returning functions. This is a consequence of
407 Google Test not using exceptions. By placing it in a non-void function
408 you'll get a confusing compile error like
409 `"error: void value not ignored as it ought to be"`.
411 If you need to use assertions in a function that returns non-void, one option
412 is to make the function return the value in an out parameter instead. For
413 example, you can rewrite `T2 Foo(T1 x)` to `void Foo(T1 x, T2* result)`. You
414 need to make sure that `*result` contains some sensible value even when the
415 function returns prematurely. As the function now returns `void`, you can use
416 any assertion inside of it.
418 If changing the function's type is not an option, you should just use
419 assertions that generate non-fatal failures, such as `ADD_FAILURE*` and
422 _Note_: Constructors and destructors are not considered void-returning
423 functions, according to the C++ language specification, and so you may not use
424 fatal assertions in them. You'll get a compilation error if you try. A simple
425 workaround is to transfer the entire body of the constructor or destructor to a
426 private void-returning method. However, you should be aware that a fatal
427 assertion failure in a constructor does not terminate the current test, as your
428 intuition might suggest; it merely returns from the constructor early, possibly
429 leaving your object in a partially-constructed state. Likewise, a fatal
430 assertion failure in a destructor may leave your object in a
431 partially-destructed state. Use assertions carefully in these situations!
433 # Teaching Google Test How to Print Your Values #
435 When a test assertion such as `EXPECT_EQ` fails, Google Test prints the
436 argument values to help you debug. It does this using a
437 user-extensible value printer.
439 This printer knows how to print built-in C++ types, native arrays, STL
440 containers, and any type that supports the `<<` operator. For other
441 types, it prints the raw bytes in the value and hopes that you the
442 user can figure it out.
444 As mentioned earlier, the printer is _extensible_. That means
445 you can teach it to do a better job at printing your particular type
446 than to dump the bytes. To do that, define `<<` for your type:
453 class Bar { ... }; // We want Google Test to be able to print instances of this.
455 // It's important that the << operator is defined in the SAME
456 // namespace that defines Bar. C++'s look-up rules rely on that.
457 ::std::ostream& operator<<(::std::ostream& os, const Bar& bar) {
458 return os << bar.DebugString(); // whatever needed to print bar to os
464 Sometimes, this might not be an option: your team may consider it bad
465 style to have a `<<` operator for `Bar`, or `Bar` may already have a
466 `<<` operator that doesn't do what you want (and you cannot change
467 it). If so, you can instead define a `PrintTo()` function like this:
476 // It's important that PrintTo() is defined in the SAME
477 // namespace that defines Bar. C++'s look-up rules rely on that.
478 void PrintTo(const Bar& bar, ::std::ostream* os) {
479 *os << bar.DebugString(); // whatever needed to print bar to os
485 If you have defined both `<<` and `PrintTo()`, the latter will be used
486 when Google Test is concerned. This allows you to customize how the value
487 appears in Google Test's output without affecting code that relies on the
488 behavior of its `<<` operator.
490 If you want to print a value `x` using Google Test's value printer
491 yourself, just call `::testing::PrintToString(`_x_`)`, which
492 returns an `std::string`:
495 vector<pair<Bar, int> > bar_ints = GetBarIntVector();
497 EXPECT_TRUE(IsCorrectBarIntVector(bar_ints))
498 << "bar_ints = " << ::testing::PrintToString(bar_ints);
503 In many applications, there are assertions that can cause application failure
504 if a condition is not met. These sanity checks, which ensure that the program
505 is in a known good state, are there to fail at the earliest possible time after
506 some program state is corrupted. If the assertion checks the wrong condition,
507 then the program may proceed in an erroneous state, which could lead to memory
508 corruption, security holes, or worse. Hence it is vitally important to test
509 that such assertion statements work as expected.
511 Since these precondition checks cause the processes to die, we call such tests
512 _death tests_. More generally, any test that checks that a program terminates
513 (except by throwing an exception) in an expected fashion is also a death test.
515 Note that if a piece of code throws an exception, we don't consider it "death"
516 for the purpose of death tests, as the caller of the code could catch the exception
517 and avoid the crash. If you want to verify exceptions thrown by your code,
518 see [Exception Assertions](#exception-assertions).
520 If you want to test `EXPECT_*()/ASSERT_*()` failures in your test code, see [Catching Failures](#catching-failures).
522 ## How to Write a Death Test ##
524 Google Test has the following macros to support death tests:
526 | **Fatal assertion** | **Nonfatal assertion** | **Verifies** |
527 |:--------------------|:-----------------------|:-------------|
528 | `ASSERT_DEATH(`_statement, regex_`); | `EXPECT_DEATH(`_statement, regex_`); | _statement_ crashes with the given error |
529 | `ASSERT_DEATH_IF_SUPPORTED(`_statement, regex_`); | `EXPECT_DEATH_IF_SUPPORTED(`_statement, regex_`); | if death tests are supported, verifies that _statement_ crashes with the given error; otherwise verifies nothing |
530 | `ASSERT_EXIT(`_statement, predicate, regex_`); | `EXPECT_EXIT(`_statement, predicate, regex_`); |_statement_ exits with the given error and its exit code matches _predicate_ |
532 where _statement_ is a statement that is expected to cause the process to
533 die, _predicate_ is a function or function object that evaluates an integer
534 exit status, and _regex_ is a regular expression that the stderr output of
535 _statement_ is expected to match. Note that _statement_ can be _any valid
536 statement_ (including _compound statement_) and doesn't have to be an
539 As usual, the `ASSERT` variants abort the current test function, while the
540 `EXPECT` variants do not.
542 **Note:** We use the word "crash" here to mean that the process
543 terminates with a _non-zero_ exit status code. There are two
544 possibilities: either the process has called `exit()` or `_exit()`
545 with a non-zero value, or it may be killed by a signal.
547 This means that if _statement_ terminates the process with a 0 exit
548 code, it is _not_ considered a crash by `EXPECT_DEATH`. Use
549 `EXPECT_EXIT` instead if this is the case, or if you want to restrict
550 the exit code more precisely.
552 A predicate here must accept an `int` and return a `bool`. The death test
553 succeeds only if the predicate returns `true`. Google Test defines a few
554 predicates that handle the most common cases:
557 ::testing::ExitedWithCode(exit_code)
560 This expression is `true` if the program exited normally with the given exit
564 ::testing::KilledBySignal(signal_number) // Not available on Windows.
567 This expression is `true` if the program was killed by the given signal.
569 The `*_DEATH` macros are convenient wrappers for `*_EXIT` that use a predicate
570 that verifies the process' exit code is non-zero.
572 Note that a death test only cares about three things:
574 1. does _statement_ abort or exit the process?
575 1. (in the case of `ASSERT_EXIT` and `EXPECT_EXIT`) does the exit status satisfy _predicate_? Or (in the case of `ASSERT_DEATH` and `EXPECT_DEATH`) is the exit status non-zero? And
576 1. does the stderr output match _regex_?
578 In particular, if _statement_ generates an `ASSERT_*` or `EXPECT_*` failure, it will **not** cause the death test to fail, as Google Test assertions don't abort the process.
580 To write a death test, simply use one of the above macros inside your test
581 function. For example,
584 TEST(My*DeathTest*, Foo) {
585 // This death test uses a compound statement.
586 ASSERT_DEATH({ int n = 5; Foo(&n); }, "Error on line .* of Foo()");
588 TEST(MyDeathTest, NormalExit) {
589 EXPECT_EXIT(NormalExit(), ::testing::ExitedWithCode(0), "Success");
591 TEST(MyDeathTest, KillMyself) {
592 EXPECT_EXIT(KillMyself(), ::testing::KilledBySignal(SIGKILL), "Sending myself unblockable signal");
598 * calling `Foo(5)` causes the process to die with the given error message,
599 * calling `NormalExit()` causes the process to print `"Success"` to stderr and exit with exit code 0, and
600 * calling `KillMyself()` kills the process with signal `SIGKILL`.
602 The test function body may contain other assertions and statements as well, if
605 _Important:_ We strongly recommend you to follow the convention of naming your
606 test case (not test) `*DeathTest` when it contains a death test, as
607 demonstrated in the above example. The `Death Tests And Threads` section below
610 If a test fixture class is shared by normal tests and death tests, you
611 can use typedef to introduce an alias for the fixture class and avoid
612 duplicating its code:
614 class FooTest : public ::testing::Test { ... };
616 typedef FooTest FooDeathTest;
618 TEST_F(FooTest, DoesThis) {
622 TEST_F(FooDeathTest, DoesThat) {
627 _Availability:_ Linux, Windows (requires MSVC 8.0 or above), Cygwin, and Mac (the latter three are supported since v1.3.0). `(ASSERT|EXPECT)_DEATH_IF_SUPPORTED` are new in v1.4.0.
629 ## Regular Expression Syntax ##
631 On POSIX systems (e.g. Linux, Cygwin, and Mac), Google Test uses the
632 [POSIX extended regular expression](http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04)
633 syntax in death tests. To learn about this syntax, you may want to read this [Wikipedia entry](http://en.wikipedia.org/wiki/Regular_expression#POSIX_Extended_Regular_Expressions).
635 On Windows, Google Test uses its own simple regular expression
636 implementation. It lacks many features you can find in POSIX extended
637 regular expressions. For example, we don't support union (`"x|y"`),
638 grouping (`"(xy)"`), brackets (`"[xy]"`), and repetition count
639 (`"x{5,7}"`), among others. Below is what we do support (`A` denotes a
640 literal character, period (`.`), or a single `\\` escape sequence; `x`
641 and `y` denote regular expressions.):
643 | `c` | matches any literal character `c` |
644 |:----|:----------------------------------|
645 | `\\d` | matches any decimal digit |
646 | `\\D` | matches any character that's not a decimal digit |
647 | `\\f` | matches `\f` |
648 | `\\n` | matches `\n` |
649 | `\\r` | matches `\r` |
650 | `\\s` | matches any ASCII whitespace, including `\n` |
651 | `\\S` | matches any character that's not a whitespace |
652 | `\\t` | matches `\t` |
653 | `\\v` | matches `\v` |
654 | `\\w` | matches any letter, `_`, or decimal digit |
655 | `\\W` | matches any character that `\\w` doesn't match |
656 | `\\c` | matches any literal character `c`, which must be a punctuation |
657 | `.` | matches any single character except `\n` |
658 | `A?` | matches 0 or 1 occurrences of `A` |
659 | `A*` | matches 0 or many occurrences of `A` |
660 | `A+` | matches 1 or many occurrences of `A` |
661 | `^` | matches the beginning of a string (not that of each line) |
662 | `$` | matches the end of a string (not that of each line) |
663 | `xy` | matches `x` followed by `y` |
665 To help you determine which capability is available on your system,
666 Google Test defines macro `GTEST_USES_POSIX_RE=1` when it uses POSIX
667 extended regular expressions, or `GTEST_USES_SIMPLE_RE=1` when it uses
668 the simple version. If you want your death tests to work in both
669 cases, you can either `#if` on these macros or use the more limited
674 Under the hood, `ASSERT_EXIT()` spawns a new process and executes the
675 death test statement in that process. The details of of how precisely
676 that happens depend on the platform and the variable
677 `::testing::GTEST_FLAG(death_test_style)` (which is initialized from the
678 command-line flag `--gtest_death_test_style`).
680 * On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the child, after which:
681 * If the variable's value is `"fast"`, the death test statement is immediately executed.
682 * If the variable's value is `"threadsafe"`, the child process re-executes the unit test binary just as it was originally invoked, but with some extra flags to cause just the single death test under consideration to be run.
683 * On Windows, the child is spawned using the `CreateProcess()` API, and re-executes the binary to cause just the single death test under consideration to be run - much like the `threadsafe` mode on POSIX.
685 Other values for the variable are illegal and will cause the death test to
686 fail. Currently, the flag's default value is `"fast"`. However, we reserve the
687 right to change it in the future. Therefore, your tests should not depend on
690 In either case, the parent process waits for the child process to complete, and checks that
692 1. the child's exit status satisfies the predicate, and
693 1. the child's stderr matches the regular expression.
695 If the death test statement runs to completion without dying, the child
696 process will nonetheless terminate, and the assertion fails.
698 ## Death Tests And Threads ##
700 The reason for the two death test styles has to do with thread safety. Due to
701 well-known problems with forking in the presence of threads, death tests should
702 be run in a single-threaded context. Sometimes, however, it isn't feasible to
703 arrange that kind of environment. For example, statically-initialized modules
704 may start threads before main is ever reached. Once threads have been created,
705 it may be difficult or impossible to clean them up.
707 Google Test has three features intended to raise awareness of threading issues.
709 1. A warning is emitted if multiple threads are running when a death test is encountered.
710 1. Test cases with a name ending in "DeathTest" are run before all other tests.
711 1. It uses `clone()` instead of `fork()` to spawn the child process on Linux (`clone()` is not available on Cygwin and Mac), as `fork()` is more likely to cause the child to hang when the parent process has multiple threads.
713 It's perfectly fine to create threads inside a death test statement; they are
714 executed in a separate process and cannot affect the parent.
716 ## Death Test Styles ##
718 The "threadsafe" death test style was introduced in order to help mitigate the
719 risks of testing in a possibly multithreaded environment. It trades increased
720 test execution time (potentially dramatically so) for improved thread safety.
721 We suggest using the faster, default "fast" style unless your test has specific
724 You can choose a particular style of death tests by setting the flag
728 ::testing::FLAGS_gtest_death_test_style = "threadsafe";
731 You can do this in `main()` to set the style for all death tests in the
732 binary, or in individual tests. Recall that flags are saved before running each
733 test and restored afterwards, so you need not do that yourself. For example:
736 TEST(MyDeathTest, TestOne) {
737 ::testing::FLAGS_gtest_death_test_style = "threadsafe";
738 // This test is run in the "threadsafe" style:
739 ASSERT_DEATH(ThisShouldDie(), "");
742 TEST(MyDeathTest, TestTwo) {
743 // This test is run in the "fast" style:
744 ASSERT_DEATH(ThisShouldDie(), "");
747 int main(int argc, char** argv) {
748 ::testing::InitGoogleTest(&argc, argv);
749 ::testing::FLAGS_gtest_death_test_style = "fast";
750 return RUN_ALL_TESTS();
756 The _statement_ argument of `ASSERT_EXIT()` can be any valid C++ statement.
757 If it leaves the current function via a `return` statement or by throwing an exception,
758 the death test is considered to have failed. Some Google Test macros may return
759 from the current function (e.g. `ASSERT_TRUE()`), so be sure to avoid them in _statement_.
761 Since _statement_ runs in the child process, any in-memory side effect (e.g.
762 modifying a variable, releasing memory, etc) it causes will _not_ be observable
763 in the parent process. In particular, if you release memory in a death test,
764 your program will fail the heap check as the parent process will never see the
765 memory reclaimed. To solve this problem, you can
767 1. try not to free memory in a death test;
768 1. free the memory again in the parent process; or
769 1. do not use the heap checker in your program.
771 Due to an implementation detail, you cannot place multiple death test
772 assertions on the same line; otherwise, compilation will fail with an unobvious
775 Despite the improved thread safety afforded by the "threadsafe" style of death
776 test, thread problems such as deadlock are still possible in the presence of
777 handlers registered with `pthread_atfork(3)`.
779 # Using Assertions in Sub-routines #
781 ## Adding Traces to Assertions ##
783 If a test sub-routine is called from several places, when an assertion
784 inside it fails, it can be hard to tell which invocation of the
785 sub-routine the failure is from. You can alleviate this problem using
786 extra logging or custom failure messages, but that usually clutters up
787 your tests. A better solution is to use the `SCOPED_TRACE` macro:
789 | `SCOPED_TRACE(`_message_`);` |
790 |:-----------------------------|
792 where _message_ can be anything streamable to `std::ostream`. This
793 macro will cause the current file name, line number, and the given
794 message to be added in every failure message. The effect will be
795 undone when the control leaves the current lexical scope.
800 10: void Sub1(int n) {
801 11: EXPECT_EQ(1, Bar(n));
802 12: EXPECT_EQ(2, Bar(n + 1));
805 15: TEST(FooTest, Bar) {
807 17: SCOPED_TRACE("A"); // This trace point will be included in
808 18: // every failure in this scope.
816 could result in messages like these:
819 path/to/foo_test.cc:11: Failure
824 path/to/foo_test.cc:17: A
826 path/to/foo_test.cc:12: Failure
832 Without the trace, it would've been difficult to know which invocation
833 of `Sub1()` the two failures come from respectively. (You could add an
834 extra message to each assertion in `Sub1()` to indicate the value of
835 `n`, but that's tedious.)
837 Some tips on using `SCOPED_TRACE`:
839 1. With a suitable message, it's often enough to use `SCOPED_TRACE` at the beginning of a sub-routine, instead of at each call site.
840 1. When calling sub-routines inside a loop, make the loop iterator part of the message in `SCOPED_TRACE` such that you can know which iteration the failure is from.
841 1. Sometimes the line number of the trace point is enough for identifying the particular invocation of a sub-routine. In this case, you don't have to choose a unique message for `SCOPED_TRACE`. You can simply use `""`.
842 1. You can use `SCOPED_TRACE` in an inner scope when there is one in the outer scope. In this case, all active trace points will be included in the failure messages, in reverse order they are encountered.
843 1. The trace dump is clickable in Emacs' compilation buffer - hit return on a line number and you'll be taken to that line in the source file!
845 _Availability:_ Linux, Windows, Mac.
847 ## Propagating Fatal Failures ##
849 A common pitfall when using `ASSERT_*` and `FAIL*` is not understanding that
850 when they fail they only abort the _current function_, not the entire test. For
851 example, the following test will segfault:
854 // Generates a fatal failure and aborts the current function.
856 // The following won't be executed.
862 // The intended behavior is for the fatal failure
863 // in Subroutine() to abort the entire test.
864 // The actual behavior: the function goes on after Subroutine() returns.
870 Since we don't use exceptions, it is technically impossible to
871 implement the intended behavior here. To alleviate this, Google Test
872 provides two solutions. You could use either the
873 `(ASSERT|EXPECT)_NO_FATAL_FAILURE` assertions or the
874 `HasFatalFailure()` function. They are described in the following two
877 ### Asserting on Subroutines ###
879 As shown above, if your test calls a subroutine that has an `ASSERT_*`
880 failure in it, the test will continue after the subroutine
881 returns. This may not be what you want.
883 Often people want fatal failures to propagate like exceptions. For
884 that Google Test offers the following macros:
886 | **Fatal assertion** | **Nonfatal assertion** | **Verifies** |
887 |:--------------------|:-----------------------|:-------------|
888 | `ASSERT_NO_FATAL_FAILURE(`_statement_`);` | `EXPECT_NO_FATAL_FAILURE(`_statement_`);` | _statement_ doesn't generate any new fatal failures in the current thread. |
890 Only failures in the thread that executes the assertion are checked to
891 determine the result of this type of assertions. If _statement_
892 creates new threads, failures in these threads are ignored.
897 ASSERT_NO_FATAL_FAILURE(Foo());
900 EXPECT_NO_FATAL_FAILURE({
905 _Availability:_ Linux, Windows, Mac. Assertions from multiple threads
906 are currently not supported.
908 ### Checking for Failures in the Current Test ###
910 `HasFatalFailure()` in the `::testing::Test` class returns `true` if an
911 assertion in the current test has suffered a fatal failure. This
912 allows functions to catch fatal failures in a sub-routine and return
919 static bool HasFatalFailure();
923 The typical usage, which basically simulates the behavior of a thrown
929 // Aborts if Subroutine() had a fatal failure.
930 if (HasFatalFailure())
932 // The following won't be executed.
937 If `HasFatalFailure()` is used outside of `TEST()` , `TEST_F()` , or a test
938 fixture, you must add the `::testing::Test::` prefix, as in:
941 if (::testing::Test::HasFatalFailure())
945 Similarly, `HasNonfatalFailure()` returns `true` if the current test
946 has at least one non-fatal failure, and `HasFailure()` returns `true`
947 if the current test has at least one failure of either kind.
949 _Availability:_ Linux, Windows, Mac. `HasNonfatalFailure()` and
950 `HasFailure()` are available since version 1.4.0.
952 # Logging Additional Information #
954 In your test code, you can call `RecordProperty("key", value)` to log
955 additional information, where `value` can be either a C string or a 32-bit
956 integer. The _last_ value recorded for a key will be emitted to the XML output
957 if you specify one. For example, the test
960 TEST_F(WidgetUsageTest, MinAndMaxWidgets) {
961 RecordProperty("MaximumWidgets", ComputeMaxUsage());
962 RecordProperty("MinimumWidgets", ComputeMinUsage());
966 will output XML like this:
970 <testcase name="MinAndMaxWidgets" status="run" time="6" classname="WidgetUsageTest"
972 MinimumWidgets="9" />
977 * `RecordProperty()` is a static member of the `Test` class. Therefore it needs to be prefixed with `::testing::Test::` if used outside of the `TEST` body and the test fixture class.
978 * `key` must be a valid XML attribute name, and cannot conflict with the ones already used by Google Test (`name`, `status`, `time`, and `classname`).
980 _Availability_: Linux, Windows, Mac.
982 # Sharing Resources Between Tests in the Same Test Case #
986 Google Test creates a new test fixture object for each test in order to make
987 tests independent and easier to debug. However, sometimes tests use resources
988 that are expensive to set up, making the one-copy-per-test model prohibitively
991 If the tests don't change the resource, there's no harm in them sharing a
992 single resource copy. So, in addition to per-test set-up/tear-down, Google Test
993 also supports per-test-case set-up/tear-down. To use it:
995 1. In your test fixture class (say `FooTest` ), define as `static` some member variables to hold the shared resources.
996 1. In the same test fixture class, define a `static void SetUpTestCase()` function (remember not to spell it as **`SetupTestCase`** with a small `u`!) to set up the shared resources and a `static void TearDownTestCase()` function to tear them down.
998 That's it! Google Test automatically calls `SetUpTestCase()` before running the
999 _first test_ in the `FooTest` test case (i.e. before creating the first
1000 `FooTest` object), and calls `TearDownTestCase()` after running the _last test_
1001 in it (i.e. after deleting the last `FooTest` object). In between, the tests
1002 can use the shared resources.
1004 Remember that the test order is undefined, so your code can't depend on a test
1005 preceding or following another. Also, the tests must either not modify the
1006 state of any shared resource, or, if they do modify the state, they must
1007 restore the state to its original value before passing control to the next
1010 Here's an example of per-test-case set-up and tear-down:
1012 class FooTest : public ::testing::Test {
1014 // Per-test-case set-up.
1015 // Called before the first test in this test case.
1016 // Can be omitted if not needed.
1017 static void SetUpTestCase() {
1018 shared_resource_ = new ...;
1021 // Per-test-case tear-down.
1022 // Called after the last test in this test case.
1023 // Can be omitted if not needed.
1024 static void TearDownTestCase() {
1025 delete shared_resource_;
1026 shared_resource_ = NULL;
1029 // You can define per-test set-up and tear-down logic as usual.
1030 virtual void SetUp() { ... }
1031 virtual void TearDown() { ... }
1033 // Some expensive resource shared by all tests.
1034 static T* shared_resource_;
1037 T* FooTest::shared_resource_ = NULL;
1039 TEST_F(FooTest, Test1) {
1040 ... you can refer to shared_resource here ...
1042 TEST_F(FooTest, Test2) {
1043 ... you can refer to shared_resource here ...
1047 _Availability:_ Linux, Windows, Mac.
1049 # Global Set-Up and Tear-Down #
1051 Just as you can do set-up and tear-down at the test level and the test case
1052 level, you can also do it at the test program level. Here's how.
1054 First, you subclass the `::testing::Environment` class to define a test
1055 environment, which knows how to set-up and tear-down:
1060 virtual ~Environment() {}
1061 // Override this to define how to set up the environment.
1062 virtual void SetUp() {}
1063 // Override this to define how to tear down the environment.
1064 virtual void TearDown() {}
1068 Then, you register an instance of your environment class with Google Test by
1069 calling the `::testing::AddGlobalTestEnvironment()` function:
1072 Environment* AddGlobalTestEnvironment(Environment* env);
1075 Now, when `RUN_ALL_TESTS()` is called, it first calls the `SetUp()` method of
1076 the environment object, then runs the tests if there was no fatal failures, and
1077 finally calls `TearDown()` of the environment object.
1079 It's OK to register multiple environment objects. In this case, their `SetUp()`
1080 will be called in the order they are registered, and their `TearDown()` will be
1081 called in the reverse order.
1083 Note that Google Test takes ownership of the registered environment objects.
1084 Therefore **do not delete them** by yourself.
1086 You should call `AddGlobalTestEnvironment()` before `RUN_ALL_TESTS()` is
1087 called, probably in `main()`. If you use `gtest_main`, you need to call
1088 this before `main()` starts for it to take effect. One way to do this is to
1089 define a global variable like this:
1092 ::testing::Environment* const foo_env = ::testing::AddGlobalTestEnvironment(new FooEnvironment);
1095 However, we strongly recommend you to write your own `main()` and call
1096 `AddGlobalTestEnvironment()` there, as relying on initialization of global
1097 variables makes the code harder to read and may cause problems when you
1098 register multiple environments from different translation units and the
1099 environments have dependencies among them (remember that the compiler doesn't
1100 guarantee the order in which global variables from different translation units
1103 _Availability:_ Linux, Windows, Mac.
1106 # Value Parameterized Tests #
1108 _Value-parameterized tests_ allow you to test your code with different
1109 parameters without writing multiple copies of the same test.
1111 Suppose you write a test for your code and then realize that your code is affected by a presence of a Boolean command line flag.
1114 TEST(MyCodeTest, TestFoo) {
1115 // A code to test foo().
1119 Usually people factor their test code into a function with a Boolean parameter in such situations. The function sets the flag, then executes the testing code.
1122 void TestFooHelper(bool flag_value) {
1124 // A code to test foo().
1127 TEST(MyCodeTest, TestFooo) {
1128 TestFooHelper(false);
1129 TestFooHelper(true);
1133 But this setup has serious drawbacks. First, when a test assertion fails in your tests, it becomes unclear what value of the parameter caused it to fail. You can stream a clarifying message into your `EXPECT`/`ASSERT` statements, but it you'll have to do it with all of them. Second, you have to add one such helper function per test. What if you have ten tests? Twenty? A hundred?
1135 Value-parameterized tests will let you write your test only once and then easily instantiate and run it with an arbitrary number of parameter values.
1137 Here are some other situations when value-parameterized tests come handy:
1139 * You want to test different implementations of an OO interface.
1140 * You want to test your code over various inputs (a.k.a. data-driven testing). This feature is easy to abuse, so please exercise your good sense when doing it!
1142 ## How to Write Value-Parameterized Tests ##
1144 To write value-parameterized tests, first you should define a fixture
1145 class. It must be derived from both `::testing::Test` and
1146 `::testing::WithParamInterface<T>` (the latter is a pure interface),
1147 where `T` is the type of your parameter values. For convenience, you
1148 can just derive the fixture class from `::testing::TestWithParam<T>`,
1149 which itself is derived from both `::testing::Test` and
1150 `::testing::WithParamInterface<T>`. `T` can be any copyable type. If
1151 it's a raw pointer, you are responsible for managing the lifespan of
1155 class FooTest : public ::testing::TestWithParam<const char*> {
1156 // You can implement all the usual fixture class members here.
1157 // To access the test parameter, call GetParam() from class
1158 // TestWithParam<T>.
1161 // Or, when you want to add parameters to a pre-existing fixture class:
1162 class BaseTest : public ::testing::Test {
1165 class BarTest : public BaseTest,
1166 public ::testing::WithParamInterface<const char*> {
1171 Then, use the `TEST_P` macro to define as many test patterns using
1172 this fixture as you want. The `_P` suffix is for "parameterized" or
1173 "pattern", whichever you prefer to think.
1176 TEST_P(FooTest, DoesBlah) {
1177 // Inside a test, access the test parameter with the GetParam() method
1178 // of the TestWithParam<T> class:
1179 EXPECT_TRUE(foo.Blah(GetParam()));
1183 TEST_P(FooTest, HasBlahBlah) {
1188 Finally, you can use `INSTANTIATE_TEST_CASE_P` to instantiate the test
1189 case with any set of parameters you want. Google Test defines a number of
1190 functions for generating test parameters. They return what we call
1191 (surprise!) _parameter generators_. Here is a summary of them,
1192 which are all in the `testing` namespace:
1194 | `Range(begin, end[, step])` | Yields values `{begin, begin+step, begin+step+step, ...}`. The values do not include `end`. `step` defaults to 1. |
1195 |:----------------------------|:------------------------------------------------------------------------------------------------------------------|
1196 | `Values(v1, v2, ..., vN)` | Yields values `{v1, v2, ..., vN}`. |
1197 | `ValuesIn(container)` and `ValuesIn(begin, end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)`. `container`, `begin`, and `end` can be expressions whose values are determined at run time. |
1198 | `Bool()` | Yields sequence `{false, true}`. |
1199 | `Combine(g1, g2, ..., gN)` | Yields all combinations (the Cartesian product for the math savvy) of the values generated by the `N` generators. This is only available if your system provides the `<tr1/tuple>` header. If you are sure your system does, and Google Test disagrees, you can override it by defining `GTEST_HAS_TR1_TUPLE=1`. See comments in [include/gtest/internal/gtest-port.h](../include/gtest/internal/gtest-port.h) for more information. |
1201 For more details, see the comments at the definitions of these functions in the [source code](../include/gtest/gtest-param-test.h).
1203 The following statement will instantiate tests from the `FooTest` test case
1204 each with parameter values `"meeny"`, `"miny"`, and `"moe"`.
1207 INSTANTIATE_TEST_CASE_P(InstantiationName,
1209 ::testing::Values("meeny", "miny", "moe"));
1212 To distinguish different instances of the pattern (yes, you can
1213 instantiate it more than once), the first argument to
1214 `INSTANTIATE_TEST_CASE_P` is a prefix that will be added to the actual
1215 test case name. Remember to pick unique prefixes for different
1216 instantiations. The tests from the instantiation above will have these
1219 * `InstantiationName/FooTest.DoesBlah/0` for `"meeny"`
1220 * `InstantiationName/FooTest.DoesBlah/1` for `"miny"`
1221 * `InstantiationName/FooTest.DoesBlah/2` for `"moe"`
1222 * `InstantiationName/FooTest.HasBlahBlah/0` for `"meeny"`
1223 * `InstantiationName/FooTest.HasBlahBlah/1` for `"miny"`
1224 * `InstantiationName/FooTest.HasBlahBlah/2` for `"moe"`
1226 You can use these names in [--gtest\-filter](#running-a-subset-of-the-tests).
1228 This statement will instantiate all tests from `FooTest` again, each
1229 with parameter values `"cat"` and `"dog"`:
1232 const char* pets[] = {"cat", "dog"};
1233 INSTANTIATE_TEST_CASE_P(AnotherInstantiationName, FooTest,
1234 ::testing::ValuesIn(pets));
1237 The tests from the instantiation above will have these names:
1239 * `AnotherInstantiationName/FooTest.DoesBlah/0` for `"cat"`
1240 * `AnotherInstantiationName/FooTest.DoesBlah/1` for `"dog"`
1241 * `AnotherInstantiationName/FooTest.HasBlahBlah/0` for `"cat"`
1242 * `AnotherInstantiationName/FooTest.HasBlahBlah/1` for `"dog"`
1244 Please note that `INSTANTIATE_TEST_CASE_P` will instantiate _all_
1245 tests in the given test case, whether their definitions come before or
1246 _after_ the `INSTANTIATE_TEST_CASE_P` statement.
1249 [these](../samples/sample7_unittest.cc)
1250 [files](../samples/sample8_unittest.cc) for more examples.
1252 _Availability_: Linux, Windows (requires MSVC 8.0 or above), Mac; since version 1.2.0.
1254 ## Creating Value-Parameterized Abstract Tests ##
1256 In the above, we define and instantiate `FooTest` in the same source
1257 file. Sometimes you may want to define value-parameterized tests in a
1258 library and let other people instantiate them later. This pattern is
1259 known as <i>abstract tests</i>. As an example of its application, when you
1260 are designing an interface you can write a standard suite of abstract
1261 tests (perhaps using a factory function as the test parameter) that
1262 all implementations of the interface are expected to pass. When
1263 someone implements the interface, he can instantiate your suite to get
1264 all the interface-conformance tests for free.
1266 To define abstract tests, you should organize your code like this:
1268 1. Put the definition of the parameterized test fixture class (e.g. `FooTest`) in a header file, say `foo_param_test.h`. Think of this as _declaring_ your abstract tests.
1269 1. Put the `TEST_P` definitions in `foo_param_test.cc`, which includes `foo_param_test.h`. Think of this as _implementing_ your abstract tests.
1271 Once they are defined, you can instantiate them by including
1272 `foo_param_test.h`, invoking `INSTANTIATE_TEST_CASE_P()`, and linking
1273 with `foo_param_test.cc`. You can instantiate the same abstract test
1274 case multiple times, possibly in different source files.
1278 Suppose you have multiple implementations of the same interface and
1279 want to make sure that all of them satisfy some common requirements.
1280 Or, you may have defined several types that are supposed to conform to
1281 the same "concept" and you want to verify it. In both cases, you want
1282 the same test logic repeated for different types.
1284 While you can write one `TEST` or `TEST_F` for each type you want to
1285 test (and you may even factor the test logic into a function template
1286 that you invoke from the `TEST`), it's tedious and doesn't scale:
1287 if you want _m_ tests over _n_ types, you'll end up writing _m\*n_
1290 _Typed tests_ allow you to repeat the same test logic over a list of
1291 types. You only need to write the test logic once, although you must
1292 know the type list when writing typed tests. Here's how you do it:
1294 First, define a fixture class template. It should be parameterized
1295 by a type. Remember to derive it from `::testing::Test`:
1298 template <typename T>
1299 class FooTest : public ::testing::Test {
1302 typedef std::list<T> List;
1308 Next, associate a list of types with the test case, which will be
1309 repeated for each type in the list:
1312 typedef ::testing::Types<char, int, unsigned int> MyTypes;
1313 TYPED_TEST_CASE(FooTest, MyTypes);
1316 The `typedef` is necessary for the `TYPED_TEST_CASE` macro to parse
1317 correctly. Otherwise the compiler will think that each comma in the
1318 type list introduces a new macro argument.
1320 Then, use `TYPED_TEST()` instead of `TEST_F()` to define a typed test
1321 for this test case. You can repeat this as many times as you want:
1324 TYPED_TEST(FooTest, DoesBlah) {
1325 // Inside a test, refer to the special name TypeParam to get the type
1326 // parameter. Since we are inside a derived class template, C++ requires
1327 // us to visit the members of FooTest via 'this'.
1328 TypeParam n = this->value_;
1330 // To visit static members of the fixture, add the 'TestFixture::'
1332 n += TestFixture::shared_;
1334 // To refer to typedefs in the fixture, add the 'typename TestFixture::'
1335 // prefix. The 'typename' is required to satisfy the compiler.
1336 typename TestFixture::List values;
1337 values.push_back(n);
1341 TYPED_TEST(FooTest, HasPropertyA) { ... }
1344 You can see `samples/sample6_unittest.cc` for a complete example.
1346 _Availability:_ Linux, Windows (requires MSVC 8.0 or above), Mac;
1347 since version 1.1.0.
1349 # Type-Parameterized Tests #
1351 _Type-parameterized tests_ are like typed tests, except that they
1352 don't require you to know the list of types ahead of time. Instead,
1353 you can define the test logic first and instantiate it with different
1354 type lists later. You can even instantiate it more than once in the
1357 If you are designing an interface or concept, you can define a suite
1358 of type-parameterized tests to verify properties that any valid
1359 implementation of the interface/concept should have. Then, the author
1360 of each implementation can just instantiate the test suite with his
1361 type to verify that it conforms to the requirements, without having to
1362 write similar tests repeatedly. Here's an example:
1364 First, define a fixture class template, as we did with typed tests:
1367 template <typename T>
1368 class FooTest : public ::testing::Test {
1373 Next, declare that you will define a type-parameterized test case:
1376 TYPED_TEST_CASE_P(FooTest);
1379 The `_P` suffix is for "parameterized" or "pattern", whichever you
1382 Then, use `TYPED_TEST_P()` to define a type-parameterized test. You
1383 can repeat this as many times as you want:
1386 TYPED_TEST_P(FooTest, DoesBlah) {
1387 // Inside a test, refer to TypeParam to get the type parameter.
1392 TYPED_TEST_P(FooTest, HasPropertyA) { ... }
1395 Now the tricky part: you need to register all test patterns using the
1396 `REGISTER_TYPED_TEST_CASE_P` macro before you can instantiate them.
1397 The first argument of the macro is the test case name; the rest are
1398 the names of the tests in this test case:
1401 REGISTER_TYPED_TEST_CASE_P(FooTest,
1402 DoesBlah, HasPropertyA);
1405 Finally, you are free to instantiate the pattern with the types you
1406 want. If you put the above code in a header file, you can `#include`
1407 it in multiple C++ source files and instantiate it multiple times.
1410 typedef ::testing::Types<char, int, unsigned int> MyTypes;
1411 INSTANTIATE_TYPED_TEST_CASE_P(My, FooTest, MyTypes);
1414 To distinguish different instances of the pattern, the first argument
1415 to the `INSTANTIATE_TYPED_TEST_CASE_P` macro is a prefix that will be
1416 added to the actual test case name. Remember to pick unique prefixes
1417 for different instances.
1419 In the special case where the type list contains only one type, you
1420 can write that type directly without `::testing::Types<...>`, like this:
1423 INSTANTIATE_TYPED_TEST_CASE_P(My, FooTest, int);
1426 You can see `samples/sample6_unittest.cc` for a complete example.
1428 _Availability:_ Linux, Windows (requires MSVC 8.0 or above), Mac;
1429 since version 1.1.0.
1431 # Testing Private Code #
1433 If you change your software's internal implementation, your tests should not
1434 break as long as the change is not observable by users. Therefore, per the
1435 _black-box testing principle_, most of the time you should test your code
1436 through its public interfaces.
1438 If you still find yourself needing to test internal implementation code,
1439 consider if there's a better design that wouldn't require you to do so. If you
1440 absolutely have to test non-public interface code though, you can. There are
1441 two cases to consider:
1443 * Static functions (_not_ the same as static member functions!) or unnamed namespaces, and
1444 * Private or protected class members
1446 ## Static Functions ##
1448 Both static functions and definitions/declarations in an unnamed namespace are
1449 only visible within the same translation unit. To test them, you can `#include`
1450 the entire `.cc` file being tested in your `*_test.cc` file. (`#include`ing `.cc`
1451 files is not a good way to reuse code - you should not do this in production
1454 However, a better approach is to move the private code into the
1455 `foo::internal` namespace, where `foo` is the namespace your project normally
1456 uses, and put the private declarations in a `*-internal.h` file. Your
1457 production `.cc` files and your tests are allowed to include this internal
1458 header, but your clients are not. This way, you can fully test your internal
1459 implementation without leaking it to your clients.
1461 ## Private Class Members ##
1463 Private class members are only accessible from within the class or by friends.
1464 To access a class' private members, you can declare your test fixture as a
1465 friend to the class and define accessors in your fixture. Tests using the
1466 fixture can then access the private members of your production class via the
1467 accessors in the fixture. Note that even though your fixture is a friend to
1468 your production class, your tests are not automatically friends to it, as they
1469 are technically defined in sub-classes of the fixture.
1471 Another way to test private members is to refactor them into an implementation
1472 class, which is then declared in a `*-internal.h` file. Your clients aren't
1473 allowed to include this header but your tests can. Such is called the Pimpl
1474 (Private Implementation) idiom.
1476 Or, you can declare an individual test as a friend of your class by adding this
1477 line in the class body:
1480 FRIEND_TEST(TestCaseName, TestName);
1486 #include "gtest/gtest_prod.h"
1488 // Defines FRIEND_TEST.
1492 FRIEND_TEST(FooTest, BarReturnsZeroOnNull);
1498 TEST(FooTest, BarReturnsZeroOnNull) {
1500 EXPECT_EQ(0, foo.Bar(NULL));
1501 // Uses Foo's private member Bar().
1505 Pay special attention when your class is defined in a namespace, as you should
1506 define your test fixtures and tests in the same namespace if you want them to
1507 be friends of your class. For example, if the code to be tested looks like:
1510 namespace my_namespace {
1513 friend class FooTest;
1514 FRIEND_TEST(FooTest, Bar);
1515 FRIEND_TEST(FooTest, Baz);
1517 definition of the class Foo
1521 } // namespace my_namespace
1524 Your test code should be something like:
1527 namespace my_namespace {
1528 class FooTest : public ::testing::Test {
1533 TEST_F(FooTest, Bar) { ... }
1534 TEST_F(FooTest, Baz) { ... }
1536 } // namespace my_namespace
1539 # Catching Failures #
1541 If you are building a testing utility on top of Google Test, you'll
1542 want to test your utility. What framework would you use to test it?
1543 Google Test, of course.
1545 The challenge is to verify that your testing utility reports failures
1546 correctly. In frameworks that report a failure by throwing an
1547 exception, you could catch the exception and assert on it. But Google
1548 Test doesn't use exceptions, so how do we test that a piece of code
1549 generates an expected failure?
1551 `"gtest/gtest-spi.h"` contains some constructs to do this. After
1552 `#include`ing this header, you can use
1554 | `EXPECT_FATAL_FAILURE(`_statement, substring_`);` |
1555 |:--------------------------------------------------|
1557 to assert that _statement_ generates a fatal (e.g. `ASSERT_*`) failure
1558 whose message contains the given _substring_, or use
1560 | `EXPECT_NONFATAL_FAILURE(`_statement, substring_`);` |
1561 |:-----------------------------------------------------|
1563 if you are expecting a non-fatal (e.g. `EXPECT_*`) failure.
1565 For technical reasons, there are some caveats:
1567 1. You cannot stream a failure message to either macro.
1568 1. _statement_ in `EXPECT_FATAL_FAILURE()` cannot reference local non-static variables or non-static members of `this` object.
1569 1. _statement_ in `EXPECT_FATAL_FAILURE()` cannot return a value.
1571 _Note:_ Google Test is designed with threads in mind. Once the
1572 synchronization primitives in `"gtest/internal/gtest-port.h"` have
1573 been implemented, Google Test will become thread-safe, meaning that
1574 you can then use assertions in multiple threads concurrently. Before
1576 that, however, Google Test only supports single-threaded usage. Once
1577 thread-safe, `EXPECT_FATAL_FAILURE()` and `EXPECT_NONFATAL_FAILURE()`
1578 will capture failures in the current thread only. If _statement_
1579 creates new threads, failures in these threads will be ignored. If
1580 you want to capture failures from all threads instead, you should use
1581 the following macros:
1583 | `EXPECT_FATAL_FAILURE_ON_ALL_THREADS(`_statement, substring_`);` |
1584 |:-----------------------------------------------------------------|
1585 | `EXPECT_NONFATAL_FAILURE_ON_ALL_THREADS(`_statement, substring_`);` |
1587 # Getting the Current Test's Name #
1589 Sometimes a function may need to know the name of the currently running test.
1590 For example, you may be using the `SetUp()` method of your test fixture to set
1591 the golden file name based on which test is running. The `::testing::TestInfo`
1592 class has this information:
1599 // Returns the test case name and the test name, respectively.
1601 // Do NOT delete or free the return value - it's managed by the
1603 const char* test_case_name() const;
1604 const char* name() const;
1607 } // namespace testing
1611 > To obtain a `TestInfo` object for the currently running test, call
1612 `current_test_info()` on the `UnitTest` singleton object:
1615 // Gets information about the currently running test.
1616 // Do NOT delete the returned object - it's managed by the UnitTest class.
1617 const ::testing::TestInfo* const test_info =
1618 ::testing::UnitTest::GetInstance()->current_test_info();
1619 printf("We are in test %s of test case %s.\n",
1620 test_info->name(), test_info->test_case_name());
1623 `current_test_info()` returns a null pointer if no test is running. In
1624 particular, you cannot find the test case name in `TestCaseSetUp()`,
1625 `TestCaseTearDown()` (where you know the test case name implicitly), or
1626 functions called from them.
1628 _Availability:_ Linux, Windows, Mac.
1630 # Extending Google Test by Handling Test Events #
1632 Google Test provides an <b>event listener API</b> to let you receive
1633 notifications about the progress of a test program and test
1634 failures. The events you can listen to include the start and end of
1635 the test program, a test case, or a test method, among others. You may
1636 use this API to augment or replace the standard console output,
1637 replace the XML output, or provide a completely different form of
1638 output, such as a GUI or a database. You can also use test events as
1639 checkpoints to implement a resource leak checker, for example.
1641 _Availability:_ Linux, Windows, Mac; since v1.4.0.
1643 ## Defining Event Listeners ##
1645 To define a event listener, you subclass either
1646 [testing::TestEventListener](../include/gtest/gtest.h#L855)
1647 or [testing::EmptyTestEventListener](../include/gtest/gtest.h#L905).
1648 The former is an (abstract) interface, where <i>each pure virtual method<br>
1649 can be overridden to handle a test event</i> (For example, when a test
1650 starts, the `OnTestStart()` method will be called.). The latter provides
1651 an empty implementation of all methods in the interface, such that a
1652 subclass only needs to override the methods it cares about.
1654 When an event is fired, its context is passed to the handler function
1655 as an argument. The following argument types are used:
1656 * [UnitTest](../include/gtest/gtest.h#L1007) reflects the state of the entire test program,
1657 * [TestCase](../include/gtest/gtest.h#L689) has information about a test case, which can contain one or more tests,
1658 * [TestInfo](../include/gtest/gtest.h#L599) contains the state of a test, and
1659 * [TestPartResult](../include/gtest/gtest-test-part.h#L42) represents the result of a test assertion.
1661 An event handler function can examine the argument it receives to find
1662 out interesting information about the event and the test program's
1663 state. Here's an example:
1666 class MinimalistPrinter : public ::testing::EmptyTestEventListener {
1667 // Called before a test starts.
1668 virtual void OnTestStart(const ::testing::TestInfo& test_info) {
1669 printf("*** Test %s.%s starting.\n",
1670 test_info.test_case_name(), test_info.name());
1673 // Called after a failed assertion or a SUCCEED() invocation.
1674 virtual void OnTestPartResult(
1675 const ::testing::TestPartResult& test_part_result) {
1676 printf("%s in %s:%d\n%s\n",
1677 test_part_result.failed() ? "*** Failure" : "Success",
1678 test_part_result.file_name(),
1679 test_part_result.line_number(),
1680 test_part_result.summary());
1683 // Called after a test ends.
1684 virtual void OnTestEnd(const ::testing::TestInfo& test_info) {
1685 printf("*** Test %s.%s ending.\n",
1686 test_info.test_case_name(), test_info.name());
1691 ## Using Event Listeners ##
1693 To use the event listener you have defined, add an instance of it to
1694 the Google Test event listener list (represented by class
1695 [TestEventListeners](../include/gtest/gtest.h#L929)
1696 - note the "s" at the end of the name) in your
1697 `main()` function, before calling `RUN_ALL_TESTS()`:
1699 int main(int argc, char** argv) {
1700 ::testing::InitGoogleTest(&argc, argv);
1701 // Gets hold of the event listener list.
1702 ::testing::TestEventListeners& listeners =
1703 ::testing::UnitTest::GetInstance()->listeners();
1704 // Adds a listener to the end. Google Test takes the ownership.
1705 listeners.Append(new MinimalistPrinter);
1706 return RUN_ALL_TESTS();
1710 There's only one problem: the default test result printer is still in
1711 effect, so its output will mingle with the output from your minimalist
1712 printer. To suppress the default printer, just release it from the
1713 event listener list and delete it. You can do so by adding one line:
1716 delete listeners.Release(listeners.default_result_printer());
1717 listeners.Append(new MinimalistPrinter);
1718 return RUN_ALL_TESTS();
1721 Now, sit back and enjoy a completely different output from your
1722 tests. For more details, you can read this
1723 [sample](../samples/sample9_unittest.cc).
1725 You may append more than one listener to the list. When an `On*Start()`
1726 or `OnTestPartResult()` event is fired, the listeners will receive it in
1727 the order they appear in the list (since new listeners are added to
1728 the end of the list, the default text printer and the default XML
1729 generator will receive the event first). An `On*End()` event will be
1730 received by the listeners in the _reverse_ order. This allows output by
1731 listeners added later to be framed by output from listeners added
1734 ## Generating Failures in Listeners ##
1736 You may use failure-raising macros (`EXPECT_*()`, `ASSERT_*()`,
1737 `FAIL()`, etc) when processing an event. There are some restrictions:
1739 1. You cannot generate any failure in `OnTestPartResult()` (otherwise it will cause `OnTestPartResult()` to be called recursively).
1740 1. A listener that handles `OnTestPartResult()` is not allowed to generate any failure.
1742 When you add listeners to the listener list, you should put listeners
1743 that handle `OnTestPartResult()` _before_ listeners that can generate
1744 failures. This ensures that failures generated by the latter are
1745 attributed to the right test by the former.
1747 We have a sample of failure-raising listener
1748 [here](../samples/sample10_unittest.cc).
1750 # Running Test Programs: Advanced Options #
1752 Google Test test programs are ordinary executables. Once built, you can run
1753 them directly and affect their behavior via the following environment variables
1754 and/or command line flags. For the flags to work, your programs must call
1755 `::testing::InitGoogleTest()` before calling `RUN_ALL_TESTS()`.
1757 To see a list of supported flags and their usage, please run your test
1758 program with the `--help` flag. You can also use `-h`, `-?`, or `/?`
1759 for short. This feature is added in version 1.3.0.
1761 If an option is specified both by an environment variable and by a
1762 flag, the latter takes precedence. Most of the options can also be
1763 set/read in code: to access the value of command line flag
1764 `--gtest_foo`, write `::testing::GTEST_FLAG(foo)`. A common pattern is
1765 to set the value of a flag before calling `::testing::InitGoogleTest()`
1766 to change the default value of the flag:
1768 int main(int argc, char** argv) {
1769 // Disables elapsed time by default.
1770 ::testing::GTEST_FLAG(print_time) = false;
1772 // This allows the user to override the flag on the command line.
1773 ::testing::InitGoogleTest(&argc, argv);
1775 return RUN_ALL_TESTS();
1779 ## Selecting Tests ##
1781 This section shows various options for choosing which tests to run.
1783 ### Listing Test Names ###
1785 Sometimes it is necessary to list the available tests in a program before
1786 running them so that a filter may be applied if needed. Including the flag
1787 `--gtest_list_tests` overrides all other flags and lists tests in the following
1797 None of the tests listed are actually run if the flag is provided. There is no
1798 corresponding environment variable for this flag.
1800 _Availability:_ Linux, Windows, Mac.
1802 ### Running a Subset of the Tests ###
1804 By default, a Google Test program runs all tests the user has defined.
1805 Sometimes, you want to run only a subset of the tests (e.g. for debugging or
1806 quickly verifying a change). If you set the `GTEST_FILTER` environment variable
1807 or the `--gtest_filter` flag to a filter string, Google Test will only run the
1808 tests whose full names (in the form of `TestCaseName.TestName`) match the
1811 The format of a filter is a '`:`'-separated list of wildcard patterns (called
1812 the positive patterns) optionally followed by a '`-`' and another
1813 '`:`'-separated pattern list (called the negative patterns). A test matches the
1814 filter if and only if it matches any of the positive patterns but does not
1815 match any of the negative patterns.
1817 A pattern may contain `'*'` (matches any string) or `'?'` (matches any single
1818 character). For convenience, the filter `'*-NegativePatterns'` can be also
1819 written as `'-NegativePatterns'`.
1823 * `./foo_test` Has no flag, and thus runs all its tests.
1824 * `./foo_test --gtest_filter=*` Also runs everything, due to the single match-everything `*` value.
1825 * `./foo_test --gtest_filter=FooTest.*` Runs everything in test case `FooTest`.
1826 * `./foo_test --gtest_filter=*Null*:*Constructor*` Runs any test whose full name contains either `"Null"` or `"Constructor"`.
1827 * `./foo_test --gtest_filter=-*DeathTest.*` Runs all non-death tests.
1828 * `./foo_test --gtest_filter=FooTest.*-FooTest.Bar` Runs everything in test case `FooTest` except `FooTest.Bar`.
1830 _Availability:_ Linux, Windows, Mac.
1832 ### Temporarily Disabling Tests ###
1834 If you have a broken test that you cannot fix right away, you can add the
1835 `DISABLED_` prefix to its name. This will exclude it from execution. This is
1836 better than commenting out the code or using `#if 0`, as disabled tests are
1837 still compiled (and thus won't rot).
1839 If you need to disable all tests in a test case, you can either add `DISABLED_`
1840 to the front of the name of each test, or alternatively add it to the front of
1843 For example, the following tests won't be run by Google Test, even though they
1844 will still be compiled:
1847 // Tests that Foo does Abc.
1848 TEST(FooTest, DISABLED_DoesAbc) { ... }
1850 class DISABLED_BarTest : public ::testing::Test { ... };
1852 // Tests that Bar does Xyz.
1853 TEST_F(DISABLED_BarTest, DoesXyz) { ... }
1856 _Note:_ This feature should only be used for temporary pain-relief. You still
1857 have to fix the disabled tests at a later date. As a reminder, Google Test will
1858 print a banner warning you if a test program contains any disabled tests.
1860 _Tip:_ You can easily count the number of disabled tests you have
1861 using `grep`. This number can be used as a metric for improving your
1864 _Availability:_ Linux, Windows, Mac.
1866 ### Temporarily Enabling Disabled Tests ###
1868 To include [disabled tests](#temporarily-disabling-tests) in test
1869 execution, just invoke the test program with the
1870 `--gtest_also_run_disabled_tests` flag or set the
1871 `GTEST_ALSO_RUN_DISABLED_TESTS` environment variable to a value other
1872 than `0`. You can combine this with the
1873 [--gtest\-filter](#running-a-subset-of-the_tests) flag to further select
1874 which disabled tests to run.
1876 _Availability:_ Linux, Windows, Mac; since version 1.3.0.
1878 ## Repeating the Tests ##
1880 Once in a while you'll run into a test whose result is hit-or-miss. Perhaps it
1881 will fail only 1% of the time, making it rather hard to reproduce the bug under
1882 a debugger. This can be a major source of frustration.
1884 The `--gtest_repeat` flag allows you to repeat all (or selected) test methods
1885 in a program many times. Hopefully, a flaky test will eventually fail and give
1886 you a chance to debug. Here's how to use it:
1888 | `$ foo_test --gtest_repeat=1000` | Repeat foo\_test 1000 times and don't stop at failures. |
1889 |:---------------------------------|:--------------------------------------------------------|
1890 | `$ foo_test --gtest_repeat=-1` | A negative count means repeating forever. |
1891 | `$ foo_test --gtest_repeat=1000 --gtest_break_on_failure` | Repeat foo\_test 1000 times, stopping at the first failure. This is especially useful when running under a debugger: when the testfails, it will drop into the debugger and you can then inspect variables and stacks. |
1892 | `$ foo_test --gtest_repeat=1000 --gtest_filter=FooBar` | Repeat the tests whose name matches the filter 1000 times. |
1894 If your test program contains global set-up/tear-down code registered
1895 using `AddGlobalTestEnvironment()`, it will be repeated in each
1896 iteration as well, as the flakiness may be in it. You can also specify
1897 the repeat count by setting the `GTEST_REPEAT` environment variable.
1899 _Availability:_ Linux, Windows, Mac.
1901 ## Shuffling the Tests ##
1903 You can specify the `--gtest_shuffle` flag (or set the `GTEST_SHUFFLE`
1904 environment variable to `1`) to run the tests in a program in a random
1905 order. This helps to reveal bad dependencies between tests.
1907 By default, Google Test uses a random seed calculated from the current
1908 time. Therefore you'll get a different order every time. The console
1909 output includes the random seed value, such that you can reproduce an
1910 order-related test failure later. To specify the random seed
1911 explicitly, use the `--gtest_random_seed=SEED` flag (or set the
1912 `GTEST_RANDOM_SEED` environment variable), where `SEED` is an integer
1913 between 0 and 99999. The seed value 0 is special: it tells Google Test
1914 to do the default behavior of calculating the seed from the current
1917 If you combine this with `--gtest_repeat=N`, Google Test will pick a
1918 different random seed and re-shuffle the tests in each iteration.
1920 _Availability:_ Linux, Windows, Mac; since v1.4.0.
1922 ## Controlling Test Output ##
1924 This section teaches how to tweak the way test results are reported.
1926 ### Colored Terminal Output ###
1928 Google Test can use colors in its terminal output to make it easier to spot
1929 the separation between tests, and whether tests passed.
1931 You can set the GTEST\_COLOR environment variable or set the `--gtest_color`
1932 command line flag to `yes`, `no`, or `auto` (the default) to enable colors,
1933 disable colors, or let Google Test decide. When the value is `auto`, Google
1934 Test will use colors if and only if the output goes to a terminal and (on
1935 non-Windows platforms) the `TERM` environment variable is set to `xterm` or
1938 _Availability:_ Linux, Windows, Mac.
1940 ### Suppressing the Elapsed Time ###
1942 By default, Google Test prints the time it takes to run each test. To
1943 suppress that, run the test program with the `--gtest_print_time=0`
1944 command line flag. Setting the `GTEST_PRINT_TIME` environment
1945 variable to `0` has the same effect.
1947 _Availability:_ Linux, Windows, Mac. (In Google Test 1.3.0 and lower,
1948 the default behavior is that the elapsed time is **not** printed.)
1950 ### Generating an XML Report ###
1952 Google Test can emit a detailed XML report to a file in addition to its normal
1953 textual output. The report contains the duration of each test, and thus can
1954 help you identify slow tests.
1956 To generate the XML report, set the `GTEST_OUTPUT` environment variable or the
1957 `--gtest_output` flag to the string `"xml:_path_to_output_file_"`, which will
1958 create the file at the given location. You can also just use the string
1959 `"xml"`, in which case the output can be found in the `test_detail.xml` file in
1960 the current directory.
1962 If you specify a directory (for example, `"xml:output/directory/"` on Linux or
1963 `"xml:output\directory\"` on Windows), Google Test will create the XML file in
1964 that directory, named after the test executable (e.g. `foo_test.xml` for test
1965 program `foo_test` or `foo_test.exe`). If the file already exists (perhaps left
1966 over from a previous run), Google Test will pick a different name (e.g.
1967 `foo_test_1.xml`) to avoid overwriting it.
1969 The report uses the format described here. It is based on the
1970 `junitreport` Ant task and can be parsed by popular continuous build
1971 systems like [Hudson](https://hudson.dev.java.net/). Since that format
1972 was originally intended for Java, a little interpretation is required
1973 to make it apply to Google Test tests, as shown here:
1976 <testsuites name="AllTests" ...>
1977 <testsuite name="test_case_name" ...>
1978 <testcase name="test_name" ...>
1979 <failure message="..."/>
1980 <failure message="..."/>
1981 <failure message="..."/>
1987 * The root `<testsuites>` element corresponds to the entire test program.
1988 * `<testsuite>` elements correspond to Google Test test cases.
1989 * `<testcase>` elements correspond to Google Test test functions.
1991 For instance, the following program
1994 TEST(MathTest, Addition) { ... }
1995 TEST(MathTest, Subtraction) { ... }
1996 TEST(LogicTest, NonContradiction) { ... }
1999 could generate this report:
2002 <?xml version="1.0" encoding="UTF-8"?>
2003 <testsuites tests="3" failures="1" errors="0" time="35" name="AllTests">
2004 <testsuite name="MathTest" tests="2" failures="1" errors="0" time="15">
2005 <testcase name="Addition" status="run" time="7" classname="">
2006 <failure message="Value of: add(1, 1)
 Actual: 3
Expected: 2" type=""/>
2007 <failure message="Value of: add(1, -1)
 Actual: 1
Expected: 0" type=""/>
2009 <testcase name="Subtraction" status="run" time="5" classname="">
2012 <testsuite name="LogicTest" tests="1" failures="0" errors="0" time="5">
2013 <testcase name="NonContradiction" status="run" time="5" classname="">
2021 * The `tests` attribute of a `<testsuites>` or `<testsuite>` element tells how many test functions the Google Test program or test case contains, while the `failures` attribute tells how many of them failed.
2022 * The `time` attribute expresses the duration of the test, test case, or entire test program in milliseconds.
2023 * Each `<failure>` element corresponds to a single failed Google Test assertion.
2024 * Some JUnit concepts don't apply to Google Test, yet we have to conform to the DTD. Therefore you'll see some dummy elements and attributes in the report. You can safely ignore these parts.
2026 _Availability:_ Linux, Windows, Mac.
2028 ## Controlling How Failures Are Reported ##
2030 ### Turning Assertion Failures into Break-Points ###
2032 When running test programs under a debugger, it's very convenient if the
2033 debugger can catch an assertion failure and automatically drop into interactive
2034 mode. Google Test's _break-on-failure_ mode supports this behavior.
2036 To enable it, set the `GTEST_BREAK_ON_FAILURE` environment variable to a value
2037 other than `0` . Alternatively, you can use the `--gtest_break_on_failure`
2040 _Availability:_ Linux, Windows, Mac.
2042 ### Disabling Catching Test-Thrown Exceptions ###
2044 Google Test can be used either with or without exceptions enabled. If
2045 a test throws a C++ exception or (on Windows) a structured exception
2046 (SEH), by default Google Test catches it, reports it as a test
2047 failure, and continues with the next test method. This maximizes the
2048 coverage of a test run. Also, on Windows an uncaught exception will
2049 cause a pop-up window, so catching the exceptions allows you to run
2050 the tests automatically.
2052 When debugging the test failures, however, you may instead want the
2053 exceptions to be handled by the debugger, such that you can examine
2054 the call stack when an exception is thrown. To achieve that, set the
2055 `GTEST_CATCH_EXCEPTIONS` environment variable to `0`, or use the
2056 `--gtest_catch_exceptions=0` flag when running the tests.
2058 **Availability**: Linux, Windows, Mac.
2060 ### Letting Another Testing Framework Drive ###
2062 If you work on a project that has already been using another testing
2063 framework and is not ready to completely switch to Google Test yet,
2064 you can get much of Google Test's benefit by using its assertions in
2065 your existing tests. Just change your `main()` function to look
2069 #include "gtest/gtest.h"
2071 int main(int argc, char** argv) {
2072 ::testing::GTEST_FLAG(throw_on_failure) = true;
2073 // Important: Google Test must be initialized.
2074 ::testing::InitGoogleTest(&argc, argv);
2076 ... whatever your existing testing framework requires ...
2080 With that, you can use Google Test assertions in addition to the
2081 native assertions your testing framework provides, for example:
2084 void TestFooDoesBar() {
2086 EXPECT_LE(foo.Bar(1), 100); // A Google Test assertion.
2087 CPPUNIT_ASSERT(foo.IsEmpty()); // A native assertion.
2091 If a Google Test assertion fails, it will print an error message and
2092 throw an exception, which will be treated as a failure by your host
2093 testing framework. If you compile your code with exceptions disabled,
2094 a failed Google Test assertion will instead exit your program with a
2095 non-zero code, which will also signal a test failure to your test
2098 If you don't write `::testing::GTEST_FLAG(throw_on_failure) = true;` in
2099 your `main()`, you can alternatively enable this feature by specifying
2100 the `--gtest_throw_on_failure` flag on the command-line or setting the
2101 `GTEST_THROW_ON_FAILURE` environment variable to a non-zero value.
2103 _Availability:_ Linux, Windows, Mac; since v1.3.0.
2105 ## Distributing Test Functions to Multiple Machines ##
2107 If you have more than one machine you can use to run a test program,
2108 you might want to run the test functions in parallel and get the
2109 result faster. We call this technique _sharding_, where each machine
2110 is called a _shard_.
2112 Google Test is compatible with test sharding. To take advantage of
2113 this feature, your test runner (not part of Google Test) needs to do
2116 1. Allocate a number of machines (shards) to run the tests.
2117 1. On each shard, set the `GTEST_TOTAL_SHARDS` environment variable to the total number of shards. It must be the same for all shards.
2118 1. On each shard, set the `GTEST_SHARD_INDEX` environment variable to the index of the shard. Different shards must be assigned different indices, which must be in the range `[0, GTEST_TOTAL_SHARDS - 1]`.
2119 1. Run the same test program on all shards. When Google Test sees the above two environment variables, it will select a subset of the test functions to run. Across all shards, each test function in the program will be run exactly once.
2120 1. Wait for all shards to finish, then collect and report the results.
2122 Your project may have tests that were written without Google Test and
2123 thus don't understand this protocol. In order for your test runner to
2124 figure out which test supports sharding, it can set the environment
2125 variable `GTEST_SHARD_STATUS_FILE` to a non-existent file path. If a
2126 test program supports sharding, it will create this file to
2127 acknowledge the fact (the actual contents of the file are not
2128 important at this time; although we may stick some useful information
2129 in it in the future.); otherwise it will not create it.
2131 Here's an example to make it clear. Suppose you have a test program
2132 `foo_test` that contains the following 5 test functions:
2140 and you have 3 machines at your disposal. To run the test functions in
2141 parallel, you would set `GTEST_TOTAL_SHARDS` to 3 on all machines, and
2142 set `GTEST_SHARD_INDEX` to 0, 1, and 2 on the machines respectively.
2143 Then you would run the same `foo_test` on each machine.
2145 Google Test reserves the right to change how the work is distributed
2146 across the shards, but here's one possible scenario:
2148 * Machine #0 runs `A.V` and `B.X`.
2149 * Machine #1 runs `A.W` and `B.Y`.
2150 * Machine #2 runs `B.Z`.
2152 _Availability:_ Linux, Windows, Mac; since version 1.3.0.
2154 # Fusing Google Test Source Files #
2156 Google Test's implementation consists of ~30 files (excluding its own
2157 tests). Sometimes you may want them to be packaged up in two files (a
2158 `.h` and a `.cc`) instead, such that you can easily copy them to a new
2159 machine and start hacking there. For this we provide an experimental
2160 Python script `fuse_gtest_files.py` in the `scripts/` directory (since release 1.3.0).
2161 Assuming you have Python 2.4 or above installed on your machine, just
2162 go to that directory and run
2164 python fuse_gtest_files.py OUTPUT_DIR
2167 and you should see an `OUTPUT_DIR` directory being created with files
2168 `gtest/gtest.h` and `gtest/gtest-all.cc` in it. These files contain
2169 everything you need to use Google Test. Just copy them to anywhere
2170 you want and you are ready to write tests. You can use the
2171 [scripts/test/Makefile](../scripts/test/Makefile)
2172 file as an example on how to compile your tests against them.
2174 # Where to Go from Here #
2176 Congratulations! You've now learned more advanced Google Test tools and are
2177 ready to tackle more complex testing tasks. If you want to dive even deeper, you
2178 can read the [Frequently-Asked Questions](V1_6_FAQ.md).