From 489283524e3726b7adb9692763c2fb61b235d41a Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Tue, 5 Jan 2021 16:46:37 -0500 Subject: Googletest export Move all docs into top-level docs/ directory PiperOrigin-RevId: 350211277 --- docs/advanced.md | 2640 ++++++++++++ docs/community_created_documentation.md | 9 + docs/faq.md | 771 ++++ docs/gmock_cheat_sheet.md | 786 ++++ docs/gmock_cook_book.md | 4267 ++++++++++++++++++++ docs/gmock_faq.md | 398 ++ docs/gmock_for_dummies.md | 702 ++++ docs/pkgconfig.md | 150 + docs/primer.md | 583 +++ docs/pump_manual.md | 190 + docs/samples.md | 22 + googlemock/docs/README.md | 4 + googlemock/docs/cheat_sheet.md | 786 ---- googlemock/docs/community_created_documentation.md | 9 - googlemock/docs/contribute.md | 5 - googlemock/docs/cook_book.md | 4266 ------------------- googlemock/docs/design.md | 1600 -------- googlemock/docs/for_dummies.md | 702 ---- googlemock/docs/gmock_faq.md | 398 -- googlemock/docs/guide.md | 49 - googlemock/docs/index.md | 127 - googlemock/docs/overview.md | 111 - googlemock/docs/pump_manual.md | 189 - googlemock/docs/sitemap.md | 11 - googlemock/docs/under-construction-banner.md | 4 - googlemock/g3doc/includes/g3_BUILD_rule.md | 17 - .../g3doc/includes/g3_absl_status_matcher.md | 54 - googlemock/g3doc/includes/g3_callback_snippet.md | 3 - .../g3doc/includes/g3_callbacks_as_matchers.md | 22 - googlemock/g3doc/includes/g3_content.md | 134 - .../g3_matching_proto_buffers_cookbook_recipe.md | 36 - .../g3doc/includes/g3_mock_a_stubby_server.md | 37 - googlemock/g3doc/includes/g3_mock_callbacks.md | 95 - googlemock/g3doc/includes/g3_mock_multithreaded.md | 9 - googlemock/g3doc/includes/g3_proto_matchers.md | 148 - googlemock/g3doc/includes/g3_stubby_actions.md | 31 - googlemock/g3doc/includes/g3_testing_LOGs.md | 185 - .../includes/g3_testing_code_stubby_server.md | 77 - .../includes/g3_useful_matchers_outsidegmock.md | 109 - .../g3doc/includes/g3_wrap_external_api_snippet.md | 3 - googletest/docs/README.md | 4 + googletest/docs/advanced.md | 2640 ------------ googletest/docs/faq.md | 771 ---- googletest/docs/pkgconfig.md | 150 - googletest/docs/primer.md | 583 --- googletest/docs/samples.md | 22 - 46 files changed, 10526 insertions(+), 13383 deletions(-) create mode 100644 docs/advanced.md create mode 100644 docs/community_created_documentation.md create mode 100644 docs/faq.md create mode 100644 docs/gmock_cheat_sheet.md create mode 100644 docs/gmock_cook_book.md create mode 100644 docs/gmock_faq.md create mode 100644 docs/gmock_for_dummies.md create mode 100644 docs/pkgconfig.md create mode 100644 docs/primer.md create mode 100644 docs/pump_manual.md create mode 100644 docs/samples.md create mode 100644 googlemock/docs/README.md delete mode 100644 googlemock/docs/cheat_sheet.md delete mode 100644 googlemock/docs/community_created_documentation.md delete mode 100644 googlemock/docs/contribute.md delete mode 100644 googlemock/docs/cook_book.md delete mode 100644 googlemock/docs/design.md delete mode 100644 googlemock/docs/for_dummies.md delete mode 100644 googlemock/docs/gmock_faq.md delete mode 100644 googlemock/docs/guide.md delete mode 100644 googlemock/docs/index.md delete mode 100644 googlemock/docs/overview.md delete mode 100644 googlemock/docs/pump_manual.md delete mode 100644 googlemock/docs/sitemap.md delete mode 100644 googlemock/docs/under-construction-banner.md delete mode 100644 googlemock/g3doc/includes/g3_BUILD_rule.md delete mode 100644 googlemock/g3doc/includes/g3_absl_status_matcher.md delete mode 100644 googlemock/g3doc/includes/g3_callback_snippet.md delete mode 100644 googlemock/g3doc/includes/g3_callbacks_as_matchers.md delete mode 100644 googlemock/g3doc/includes/g3_content.md delete mode 100644 googlemock/g3doc/includes/g3_matching_proto_buffers_cookbook_recipe.md delete mode 100644 googlemock/g3doc/includes/g3_mock_a_stubby_server.md delete mode 100644 googlemock/g3doc/includes/g3_mock_callbacks.md delete mode 100644 googlemock/g3doc/includes/g3_mock_multithreaded.md delete mode 100644 googlemock/g3doc/includes/g3_proto_matchers.md delete mode 100644 googlemock/g3doc/includes/g3_stubby_actions.md delete mode 100644 googlemock/g3doc/includes/g3_testing_LOGs.md delete mode 100644 googlemock/g3doc/includes/g3_testing_code_stubby_server.md delete mode 100644 googlemock/g3doc/includes/g3_useful_matchers_outsidegmock.md delete mode 100644 googlemock/g3doc/includes/g3_wrap_external_api_snippet.md create mode 100644 googletest/docs/README.md delete mode 100644 googletest/docs/advanced.md delete mode 100644 googletest/docs/faq.md delete mode 100644 googletest/docs/pkgconfig.md delete mode 100644 googletest/docs/primer.md delete mode 100644 googletest/docs/samples.md diff --git a/docs/advanced.md b/docs/advanced.md new file mode 100644 index 0000000..3db96d3 --- /dev/null +++ b/docs/advanced.md @@ -0,0 +1,2640 @@ +# Advanced googletest Topics + + + + + +## Introduction + +Now that you have read the [googletest Primer](primer.md) and learned how to +write tests using googletest, it's time to learn some new tricks. This document +will show you more assertions as well as how to construct complex failure +messages, propagate fatal failures, reuse and speed up your test fixtures, and +use various flags with your tests. + +## More Assertions + +This section covers some less frequently used, but still significant, +assertions. + +### Explicit Success and Failure + +These three assertions do not actually test a value or expression. Instead, they +generate a success or failure directly. Like the macros that actually perform a +test, you may stream a custom failure message into them. + +```c++ +SUCCEED(); +``` + +Generates a success. This does **NOT** make the overall test succeed. A test is +considered successful only if none of its assertions fail during its execution. + +NOTE: `SUCCEED()` is purely documentary and currently doesn't generate any +user-visible output. However, we may add `SUCCEED()` messages to googletest's +output in the future. + +```c++ +FAIL(); +ADD_FAILURE(); +ADD_FAILURE_AT("file_path", line_number); +``` + +`FAIL()` generates a fatal failure, while `ADD_FAILURE()` and `ADD_FAILURE_AT()` +generate a nonfatal failure. These are useful when control flow, rather than a +Boolean expression, determines the test's success or failure. For example, you +might want to write something like: + +```c++ +switch(expression) { + case 1: + ... some checks ... + case 2: + ... some other checks ... + default: + FAIL() << "We shouldn't get here."; +} +``` + +NOTE: you can only use `FAIL()` in functions that return `void`. See the +[Assertion Placement section](#assertion-placement) for more information. + +### Exception Assertions + +These are for verifying that a piece of code throws (or does not throw) an +exception of the given type: + +Fatal assertion | Nonfatal assertion | Verifies +------------------------------------------ | ------------------------------------------ | -------- +`ASSERT_THROW(statement, exception_type);` | `EXPECT_THROW(statement, exception_type);` | `statement` throws an exception of the given type +`ASSERT_ANY_THROW(statement);` | `EXPECT_ANY_THROW(statement);` | `statement` throws an exception of any type +`ASSERT_NO_THROW(statement);` | `EXPECT_NO_THROW(statement);` | `statement` doesn't throw any exception + +Examples: + +```c++ +ASSERT_THROW(Foo(5), bar_exception); + +EXPECT_NO_THROW({ + int n = 5; + Bar(&n); +}); +``` + +**Availability**: requires exceptions to be enabled in the build environment + +### Predicate Assertions for Better Error Messages + +Even though googletest has a rich set of assertions, they can never be complete, +as it's impossible (nor a good idea) to anticipate all scenarios a user might +run into. Therefore, sometimes a user has to use `EXPECT_TRUE()` to check a +complex expression, for lack of a better macro. This has the problem of not +showing you the values of the parts of the expression, making it hard to +understand what went wrong. As a workaround, some users choose to construct the +failure message by themselves, streaming it into `EXPECT_TRUE()`. However, this +is awkward especially when the expression has side-effects or is expensive to +evaluate. + +googletest gives you three different options to solve this problem: + +#### Using an Existing Boolean Function + +If you already have a function or functor that returns `bool` (or a type that +can be implicitly converted to `bool`), you can use it in a *predicate +assertion* to get the function arguments printed for free: + + + +| Fatal assertion | Nonfatal assertion | Verifies | +| --------------------------------- | --------------------------------- | --------------------------- | +| `ASSERT_PRED1(pred1, val1)` | `EXPECT_PRED1(pred1, val1)` | `pred1(val1)` is true | +| `ASSERT_PRED2(pred2, val1, val2)` | `EXPECT_PRED2(pred2, val1, val2)` | `pred2(val1, val2)` is true | +| `...` | `...` | `...` | + + +In the above, `predn` is an `n`-ary predicate function or functor, where `val1`, +`val2`, ..., and `valn` are its arguments. The assertion succeeds if the +predicate returns `true` when applied to the given arguments, and fails +otherwise. When the assertion fails, it prints the value of each argument. In +either case, the arguments are evaluated exactly once. + +Here's an example. Given + +```c++ +// Returns true if m and n have no common divisors except 1. +bool MutuallyPrime(int m, int n) { ... } + +const int a = 3; +const int b = 4; +const int c = 10; +``` + +the assertion + +```c++ + EXPECT_PRED2(MutuallyPrime, a, b); +``` + +will succeed, while the assertion + +```c++ + EXPECT_PRED2(MutuallyPrime, b, c); +``` + +will fail with the message + +```none +MutuallyPrime(b, c) is false, where +b is 4 +c is 10 +``` + +> NOTE: +> +> 1. If you see a compiler error "no matching function to call" when using +> `ASSERT_PRED*` or `EXPECT_PRED*`, please see +> [this](faq.md#the-compiler-complains-no-matching-function-to-call-when-i-use-assert-pred-how-do-i-fix-it) +> for how to resolve it. + +#### Using a Function That Returns an AssertionResult + +While `EXPECT_PRED*()` and friends are handy for a quick job, the syntax is not +satisfactory: you have to use different macros for different arities, and it +feels more like Lisp than C++. The `::testing::AssertionResult` class solves +this problem. + +An `AssertionResult` object represents the result of an assertion (whether it's +a success or a failure, and an associated message). You can create an +`AssertionResult` using one of these factory functions: + +```c++ +namespace testing { + +// Returns an AssertionResult object to indicate that an assertion has +// succeeded. +AssertionResult AssertionSuccess(); + +// Returns an AssertionResult object to indicate that an assertion has +// failed. +AssertionResult AssertionFailure(); + +} +``` + +You can then use the `<<` operator to stream messages to the `AssertionResult` +object. + +To provide more readable messages in Boolean assertions (e.g. `EXPECT_TRUE()`), +write a predicate function that returns `AssertionResult` instead of `bool`. For +example, if you define `IsEven()` as: + +```c++ +testing::AssertionResult IsEven(int n) { + if ((n % 2) == 0) + return testing::AssertionSuccess(); + else + return testing::AssertionFailure() << n << " is odd"; +} +``` + +instead of: + +```c++ +bool IsEven(int n) { + return (n % 2) == 0; +} +``` + +the failed assertion `EXPECT_TRUE(IsEven(Fib(4)))` will print: + +```none +Value of: IsEven(Fib(4)) + Actual: false (3 is odd) +Expected: true +``` + +instead of a more opaque + +```none +Value of: IsEven(Fib(4)) + Actual: false +Expected: true +``` + +If you want informative messages in `EXPECT_FALSE` and `ASSERT_FALSE` as well +(one third of Boolean assertions in the Google code base are negative ones), and +are fine with making the predicate slower in the success case, you can supply a +success message: + +```c++ +testing::AssertionResult IsEven(int n) { + if ((n % 2) == 0) + return testing::AssertionSuccess() << n << " is even"; + else + return testing::AssertionFailure() << n << " is odd"; +} +``` + +Then the statement `EXPECT_FALSE(IsEven(Fib(6)))` will print + +```none + Value of: IsEven(Fib(6)) + Actual: true (8 is even) + Expected: false +``` + +#### Using a Predicate-Formatter + +If you find the default message generated by `(ASSERT|EXPECT)_PRED*` and +`(ASSERT|EXPECT)_(TRUE|FALSE)` unsatisfactory, or some arguments to your +predicate do not support streaming to `ostream`, you can instead use the +following *predicate-formatter assertions* to *fully* customize how the message +is formatted: + +Fatal assertion | Nonfatal assertion | Verifies +------------------------------------------------ | ------------------------------------------------ | -------- +`ASSERT_PRED_FORMAT1(pred_format1, val1);` | `EXPECT_PRED_FORMAT1(pred_format1, val1);` | `pred_format1(val1)` is successful +`ASSERT_PRED_FORMAT2(pred_format2, val1, val2);` | `EXPECT_PRED_FORMAT2(pred_format2, val1, val2);` | `pred_format2(val1, val2)` is successful +`...` | `...` | ... + +The difference between this and the previous group of macros is that instead of +a predicate, `(ASSERT|EXPECT)_PRED_FORMAT*` take a *predicate-formatter* +(`pred_formatn`), which is a function or functor with the signature: + +```c++ +testing::AssertionResult PredicateFormattern(const char* expr1, + const char* expr2, + ... + const char* exprn, + T1 val1, + T2 val2, + ... + Tn valn); +``` + +where `val1`, `val2`, ..., and `valn` are the values of the predicate arguments, +and `expr1`, `expr2`, ..., and `exprn` are the corresponding expressions as they +appear in the source code. The types `T1`, `T2`, ..., and `Tn` can be either +value types or reference types. For example, if an argument has type `Foo`, you +can declare it as either `Foo` or `const Foo&`, whichever is appropriate. + +As an example, let's improve the failure message in `MutuallyPrime()`, which was +used with `EXPECT_PRED2()`: + +```c++ +// Returns the smallest prime common divisor of m and n, +// or 1 when m and n are mutually prime. +int SmallestPrimeCommonDivisor(int m, int n) { ... } + +// A predicate-formatter for asserting that two integers are mutually prime. +testing::AssertionResult AssertMutuallyPrime(const char* m_expr, + const char* n_expr, + int m, + int n) { + if (MutuallyPrime(m, n)) return testing::AssertionSuccess(); + + return testing::AssertionFailure() << m_expr << " and " << n_expr + << " (" << m << " and " << n << ") are not mutually prime, " + << "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n); +} +``` + +With this predicate-formatter, we can use + +```c++ + EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c); +``` + +to generate the message + +```none +b and c (4 and 10) are not mutually prime, as they have a common divisor 2. +``` + +As you may have realized, many of the built-in assertions we introduced earlier +are special cases of `(EXPECT|ASSERT)_PRED_FORMAT*`. In fact, most of them are +indeed defined using `(EXPECT|ASSERT)_PRED_FORMAT*`. + +### Floating-Point Comparison + +Comparing floating-point numbers is tricky. Due to round-off errors, it is very +unlikely that two floating-points will match exactly. Therefore, `ASSERT_EQ` 's +naive comparison usually doesn't work. And since floating-points can have a wide +value range, no single fixed error bound works. It's better to compare by a +fixed relative error bound, except for values close to 0 due to the loss of +precision there. + +In general, for floating-point comparison to make sense, the user needs to +carefully choose the error bound. If they don't want or care to, comparing in +terms of Units in the Last Place (ULPs) is a good default, and googletest +provides assertions to do this. Full details about ULPs are quite long; if you +want to learn more, see +[here](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/). + +#### Floating-Point Macros + + + +| Fatal assertion | Nonfatal assertion | Verifies | +| ------------------------------- | ------------------------------- | ---------------------------------------- | +| `ASSERT_FLOAT_EQ(val1, val2);` | `EXPECT_FLOAT_EQ(val1, val2);` | the two `float` values are almost equal | +| `ASSERT_DOUBLE_EQ(val1, val2);` | `EXPECT_DOUBLE_EQ(val1, val2);` | the two `double` values are almost equal | + + + +By "almost equal" we mean the values are within 4 ULP's from each other. + +The following assertions allow you to choose the acceptable error bound: + + + +| Fatal assertion | Nonfatal assertion | Verifies | +| ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- | +| `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 | + + + +#### Floating-Point Predicate-Format Functions + +Some floating-point operations are useful, but not that often used. In order to +avoid an explosion of new macros, we provide them as predicate-format functions +that can be used in predicate assertion macros (e.g. `EXPECT_PRED_FORMAT2`, +etc). + +```c++ +EXPECT_PRED_FORMAT2(testing::FloatLE, val1, val2); +EXPECT_PRED_FORMAT2(testing::DoubleLE, val1, val2); +``` + +Verifies that `val1` is less than, or almost equal to, `val2`. You can replace +`EXPECT_PRED_FORMAT2` in the above table with `ASSERT_PRED_FORMAT2`. + +### Asserting Using gMock Matchers + +[gMock](gmock_index.md) comes with +[a library of matchers](gmock_cheat_sheet.md#MatcherList) for +validating arguments passed to mock objects. A gMock *matcher* is basically a +predicate that knows how to describe itself. It can be used in these assertion +macros: + + + +| Fatal assertion | Nonfatal assertion | Verifies | +| ------------------------------ | ------------------------------ | --------------------- | +| `ASSERT_THAT(value, matcher);` | `EXPECT_THAT(value, matcher);` | value matches matcher | + + + +For example, `StartsWith(prefix)` is a matcher that matches a string starting +with `prefix`, and you can write: + +```c++ +using ::testing::StartsWith; +... + // Verifies that Foo() returns a string starting with "Hello". + EXPECT_THAT(Foo(), StartsWith("Hello")); +``` + +Read this +[recipe](gmock_cook_book.md#using-matchers-in-googletest-assertions) +in the gMock Cookbook for more details. + +gMock has a rich set of matchers. You can do many things googletest cannot do +alone with them. For a list of matchers gMock provides, read +[this](gmock_cook_book.md##using-matchers). It's easy to write +your [own matchers](gmock_cook_book.md#NewMatchers) too. + +gMock is bundled with googletest, so you don't need to add any build dependency +in order to take advantage of this. Just include `"gmock/gmock.h"` +and you're ready to go. + +### More String Assertions + +(Please read the [previous](#asserting-using-gmock-matchers) section first if +you haven't.) + +You can use the gMock +[string matchers](gmock_cheat_sheet.md#string-matchers) with +`EXPECT_THAT()` or `ASSERT_THAT()` to do more string comparison tricks +(sub-string, prefix, suffix, regular expression, and etc). For example, + +```c++ +using ::testing::HasSubstr; +using ::testing::MatchesRegex; +... + ASSERT_THAT(foo_string, HasSubstr("needle")); + EXPECT_THAT(bar_string, MatchesRegex("\\w*\\d+")); +``` + +If the string contains a well-formed HTML or XML document, you can check whether +its DOM tree matches an +[XPath expression](http://www.w3.org/TR/xpath/#contents): + +```c++ +// Currently still in //template/prototemplate/testing:xpath_matcher +#include "template/prototemplate/testing/xpath_matcher.h" +using ::prototemplate::testing::MatchesXPath; +EXPECT_THAT(html_string, MatchesXPath("//a[text()='click here']")); +``` + +### Windows HRESULT assertions + +These assertions test for `HRESULT` success or failure. + +Fatal assertion | Nonfatal assertion | Verifies +-------------------------------------- | -------------------------------------- | -------- +`ASSERT_HRESULT_SUCCEEDED(expression)` | `EXPECT_HRESULT_SUCCEEDED(expression)` | `expression` is a success `HRESULT` +`ASSERT_HRESULT_FAILED(expression)` | `EXPECT_HRESULT_FAILED(expression)` | `expression` is a failure `HRESULT` + +The generated output contains the human-readable error message associated with +the `HRESULT` code returned by `expression`. + +You might use them like this: + +```c++ +CComPtr shell; +ASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application")); +CComVariant empty; +ASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty)); +``` + +### Type Assertions + +You can call the function + +```c++ +::testing::StaticAssertTypeEq(); +``` + +to assert that types `T1` and `T2` are the same. The function does nothing if +the assertion is satisfied. If the types are different, the function call will +fail to compile, the compiler error message will say that +`T1 and T2 are not the same type` and most likely (depending on the compiler) +show you the actual values of `T1` and `T2`. This is mainly useful inside +template code. + +**Caveat**: When used inside a member function of a class template or a function +template, `StaticAssertTypeEq()` is effective only if the function is +instantiated. For example, given: + +```c++ +template class Foo { + public: + void Bar() { testing::StaticAssertTypeEq(); } +}; +``` + +the code: + +```c++ +void Test1() { Foo foo; } +``` + +will not generate a compiler error, as `Foo::Bar()` is never actually +instantiated. Instead, you need: + +```c++ +void Test2() { Foo foo; foo.Bar(); } +``` + +to cause a compiler error. + +### Assertion Placement + +You can use assertions in any C++ function. In particular, it doesn't have to be +a method of the test fixture class. The one constraint is that assertions that +generate a fatal failure (`FAIL*` and `ASSERT_*`) can only be used in +void-returning functions. This is a consequence of Google's not using +exceptions. By placing it in a non-void function you'll get a confusing compile +error like `"error: void value not ignored as it ought to be"` or `"cannot +initialize return object of type 'bool' with an rvalue of type 'void'"` or +`"error: no viable conversion from 'void' to 'string'"`. + +If you need to use fatal assertions in a function that returns non-void, one +option is to make the function return the value in an out parameter instead. For +example, you can rewrite `T2 Foo(T1 x)` to `void Foo(T1 x, T2* result)`. You +need to make sure that `*result` contains some sensible value even when the +function returns prematurely. As the function now returns `void`, you can use +any assertion inside of it. + +If changing the function's type is not an option, you should just use assertions +that generate non-fatal failures, such as `ADD_FAILURE*` and `EXPECT_*`. + +NOTE: Constructors and destructors are not considered void-returning functions, +according to the C++ language specification, and so you may not use fatal +assertions in them; you'll get a compilation error if you try. Instead, either +call `abort` and crash the entire test executable, or put the fatal assertion in +a `SetUp`/`TearDown` function; see +[constructor/destructor vs. `SetUp`/`TearDown`](faq.md#CtorVsSetUp) + +WARNING: A fatal assertion in a helper function (private void-returning method) +called from a constructor or destructor does not terminate the current test, as +your intuition might suggest: it merely returns from the constructor or +destructor early, possibly leaving your object in a partially-constructed or +partially-destructed state! You almost certainly want to `abort` or use +`SetUp`/`TearDown` instead. + +## Teaching googletest How to Print Your Values + +When a test assertion such as `EXPECT_EQ` fails, googletest prints the argument +values to help you debug. It does this using a user-extensible value printer. + +This printer knows how to print built-in C++ types, native arrays, STL +containers, and any type that supports the `<<` operator. For other types, it +prints the raw bytes in the value and hopes that you the user can figure it out. + +As mentioned earlier, the printer is *extensible*. That means you can teach it +to do a better job at printing your particular type than to dump the bytes. To +do that, define `<<` for your type: + +```c++ +#include + +namespace foo { + +class Bar { // We want googletest to be able to print instances of this. +... + // Create a free inline friend function. + friend std::ostream& operator<<(std::ostream& os, const Bar& bar) { + return os << bar.DebugString(); // whatever needed to print bar to os + } +}; + +// If you can't declare the function in the class it's important that the +// << operator is defined in the SAME namespace that defines Bar. C++'s look-up +// rules rely on that. +std::ostream& operator<<(std::ostream& os, const Bar& bar) { + return os << bar.DebugString(); // whatever needed to print bar to os +} + +} // namespace foo +``` + +Sometimes, this might not be an option: your team may consider it bad style to +have a `<<` operator for `Bar`, or `Bar` may already have a `<<` operator that +doesn't do what you want (and you cannot change it). If so, you can instead +define a `PrintTo()` function like this: + +```c++ +#include + +namespace foo { + +class Bar { + ... + friend void PrintTo(const Bar& bar, std::ostream* os) { + *os << bar.DebugString(); // whatever needed to print bar to os + } +}; + +// If you can't declare the function in the class it's important that PrintTo() +// is defined in the SAME namespace that defines Bar. C++'s look-up rules rely +// on that. +void PrintTo(const Bar& bar, std::ostream* os) { + *os << bar.DebugString(); // whatever needed to print bar to os +} + +} // namespace foo +``` + +If you have defined both `<<` and `PrintTo()`, the latter will be used when +googletest is concerned. This allows you to customize how the value appears in +googletest's output without affecting code that relies on the behavior of its +`<<` operator. + +If you want to print a value `x` using googletest's value printer yourself, just +call `::testing::PrintToString(x)`, which returns an `std::string`: + +```c++ +vector > bar_ints = GetBarIntVector(); + +EXPECT_TRUE(IsCorrectBarIntVector(bar_ints)) + << "bar_ints = " << testing::PrintToString(bar_ints); +``` + +## Death Tests + +In many applications, there are assertions that can cause application failure if +a condition is not met. These sanity checks, which ensure that the program is in +a known good state, are there to fail at the earliest possible time after some +program state is corrupted. If the assertion checks the wrong condition, then +the program may proceed in an erroneous state, which could lead to memory +corruption, security holes, or worse. Hence it is vitally important to test that +such assertion statements work as expected. + +Since these precondition checks cause the processes to die, we call such tests +_death tests_. More generally, any test that checks that a program terminates +(except by throwing an exception) in an expected fashion is also a death test. + +Note that if a piece of code throws an exception, we don't consider it "death" +for the purpose of death tests, as the caller of the code could catch the +exception and avoid the crash. If you want to verify exceptions thrown by your +code, see [Exception Assertions](#ExceptionAssertions). + +If you want to test `EXPECT_*()/ASSERT_*()` failures in your test code, see +Catching Failures + +### How to Write a Death Test + +googletest has the following macros to support death tests: + +Fatal assertion | Nonfatal assertion | Verifies +------------------------------------------------ | ------------------------------------------------ | -------- +`ASSERT_DEATH(statement, matcher);` | `EXPECT_DEATH(statement, matcher);` | `statement` crashes with the given error +`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 +`ASSERT_DEBUG_DEATH(statement, matcher);` | `EXPECT_DEBUG_DEATH(statement, matcher);` | `statement` crashes with the given error **in debug mode**. When not in debug (i.e. `NDEBUG` is defined), this just executes `statement` +`ASSERT_EXIT(statement, predicate, matcher);` | `EXPECT_EXIT(statement, predicate, matcher);` | `statement` exits with the given error, and its exit code matches `predicate` + +where `statement` is a statement that is expected to cause the process to die, +`predicate` is a function or function object that evaluates an integer exit +status, and `matcher` is either a gMock matcher matching a `const std::string&` +or a (Perl) regular expression - either of which is matched against the stderr +output of `statement`. For legacy reasons, a bare string (i.e. with no matcher) +is interpreted as `ContainsRegex(str)`, **not** `Eq(str)`. Note that `statement` +can be *any valid statement* (including *compound statement*) and doesn't have +to be an expression. + +As usual, the `ASSERT` variants abort the current test function, while the +`EXPECT` variants do not. + +> NOTE: We use the word "crash" here to mean that the process terminates with a +> *non-zero* exit status code. There are two possibilities: either the process +> has called `exit()` or `_exit()` with a non-zero value, or it may be killed by +> a signal. +> +> This means that if *`statement`* terminates the process with a 0 exit code, it +> is *not* considered a crash by `EXPECT_DEATH`. Use `EXPECT_EXIT` instead if +> this is the case, or if you want to restrict the exit code more precisely. + +A predicate here must accept an `int` and return a `bool`. The death test +succeeds only if the predicate returns `true`. googletest defines a few +predicates that handle the most common cases: + +```c++ +::testing::ExitedWithCode(exit_code) +``` + +This expression is `true` if the program exited normally with the given exit +code. + +```c++ +testing::KilledBySignal(signal_number) // Not available on Windows. +``` + +This expression is `true` if the program was killed by the given signal. + +The `*_DEATH` macros are convenient wrappers for `*_EXIT` that use a predicate +that verifies the process' exit code is non-zero. + +Note that a death test only cares about three things: + +1. does `statement` abort or exit the process? +2. (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 +3. does the stderr output match `matcher`? + +In particular, if `statement` generates an `ASSERT_*` or `EXPECT_*` failure, it +will **not** cause the death test to fail, as googletest assertions don't abort +the process. + +To write a death test, simply use one of the above macros inside your test +function. For example, + +```c++ +TEST(MyDeathTest, Foo) { + // This death test uses a compound statement. + ASSERT_DEATH({ + int n = 5; + Foo(&n); + }, "Error on line .* of Foo()"); +} + +TEST(MyDeathTest, NormalExit) { + EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success"); +} + +TEST(MyDeathTest, KillMyself) { + EXPECT_EXIT(KillMyself(), testing::KilledBySignal(SIGKILL), + "Sending myself unblockable signal"); +} +``` + +verifies that: + +* calling `Foo(5)` causes the process to die with the given error message, +* calling `NormalExit()` causes the process to print `"Success"` to stderr and + exit with exit code 0, and +* calling `KillMyself()` kills the process with signal `SIGKILL`. + +The test function body may contain other assertions and statements as well, if +necessary. + +### Death Test Naming + +IMPORTANT: We strongly recommend you to follow the convention of naming your +**test suite** (not test) `*DeathTest` when it contains a death test, as +demonstrated in the above example. The +[Death Tests And Threads](#death-tests-and-threads) section below explains why. + +If a test fixture class is shared by normal tests and death tests, you can use +`using` or `typedef` to introduce an alias for the fixture class and avoid +duplicating its code: + +```c++ +class FooTest : public testing::Test { ... }; + +using FooDeathTest = FooTest; + +TEST_F(FooTest, DoesThis) { + // normal test +} + +TEST_F(FooDeathTest, DoesThat) { + // death test +} +``` + +### Regular Expression Syntax + +On POSIX systems (e.g. Linux, Cygwin, and Mac), googletest uses the +[POSIX extended regular expression](http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04) +syntax. To learn about this syntax, you may want to read this +[Wikipedia entry](http://en.wikipedia.org/wiki/Regular_expression#POSIX_Extended_Regular_Expressions). + +On Windows, googletest uses its own simple regular expression implementation. It +lacks many features. For example, we don't support union (`"x|y"`), grouping +(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among +others. Below is what we do support (`A` denotes a literal character, period +(`.`), or a single `\\ ` escape sequence; `x` and `y` denote regular +expressions.): + +Expression | Meaning +---------- | -------------------------------------------------------------- +`c` | matches any literal character `c` +`\\d` | matches any decimal digit +`\\D` | matches any character that's not a decimal digit +`\\f` | matches `\f` +`\\n` | matches `\n` +`\\r` | matches `\r` +`\\s` | matches any ASCII whitespace, including `\n` +`\\S` | matches any character that's not a whitespace +`\\t` | matches `\t` +`\\v` | matches `\v` +`\\w` | matches any letter, `_`, or decimal digit +`\\W` | matches any character that `\\w` doesn't match +`\\c` | matches any literal character `c`, which must be a punctuation +`.` | matches any single character except `\n` +`A?` | matches 0 or 1 occurrences of `A` +`A*` | matches 0 or many occurrences of `A` +`A+` | matches 1 or many occurrences of `A` +`^` | matches the beginning of a string (not that of each line) +`$` | matches the end of a string (not that of each line) +`xy` | matches `x` followed by `y` + +To help you determine which capability is available on your system, googletest +defines macros to govern which regular expression it is using. The macros are: +`GTEST_USES_SIMPLE_RE=1` or `GTEST_USES_POSIX_RE=1`. If you want your death +tests to work in all cases, you can either `#if` on these macros or use the more +limited syntax only. + +### How It Works + +Under the hood, `ASSERT_EXIT()` spawns a new process and executes the death test +statement in that process. The details of how precisely that happens depend on +the platform and the variable `::testing::GTEST_FLAG(death_test_style)` (which is +initialized from the command-line flag `--gtest_death_test_style`). + +* On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the + child, after which: + * If the variable's value is `"fast"`, the death test statement is + immediately executed. + * 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. +* 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. + +Other values for the variable are illegal and will cause the death test to fail. +Currently, the flag's default value is **"fast"** + +1. the child's exit status satisfies the predicate, and +2. the child's stderr matches the regular expression. + +If the death test statement runs to completion without dying, the child process +will nonetheless terminate, and the assertion fails. + +### Death Tests And Threads + +The reason for the two death test styles has to do with thread safety. Due to +well-known problems with forking in the presence of threads, death tests should +be run in a single-threaded context. Sometimes, however, it isn't feasible to +arrange that kind of environment. For example, statically-initialized modules +may start threads before main is ever reached. Once threads have been created, +it may be difficult or impossible to clean them up. + +googletest has three features intended to raise awareness of threading issues. + +1. A warning is emitted if multiple threads are running when a death test is + encountered. +2. Test suites with a name ending in "DeathTest" are run before all other + tests. +3. 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. + +It's perfectly fine to create threads inside a death test statement; they are +executed in a separate process and cannot affect the parent. + +### Death Test Styles + +The "threadsafe" death test style was introduced in order to help mitigate the +risks of testing in a possibly multithreaded environment. It trades increased +test execution time (potentially dramatically so) for improved thread safety. + +The automated testing framework does not set the style flag. You can choose a +particular style of death tests by setting the flag programmatically: + +```c++ +testing::FLAGS_gtest_death_test_style="threadsafe" +``` + +You can do this in `main()` to set the style for all death tests in the binary, +or in individual tests. Recall that flags are saved before running each test and +restored afterwards, so you need not do that yourself. For example: + +```c++ +int main(int argc, char** argv) { + testing::InitGoogleTest(&argc, argv); + testing::FLAGS_gtest_death_test_style = "fast"; + return RUN_ALL_TESTS(); +} + +TEST(MyDeathTest, TestOne) { + testing::FLAGS_gtest_death_test_style = "threadsafe"; + // This test is run in the "threadsafe" style: + ASSERT_DEATH(ThisShouldDie(), ""); +} + +TEST(MyDeathTest, TestTwo) { + // This test is run in the "fast" style: + ASSERT_DEATH(ThisShouldDie(), ""); +} +``` + +### Caveats + +The `statement` argument of `ASSERT_EXIT()` can be any valid C++ statement. If +it leaves the current function via a `return` statement or by throwing an +exception, the death test is considered to have failed. Some googletest macros +may return from the current function (e.g. `ASSERT_TRUE()`), so be sure to avoid +them in `statement`. + +Since `statement` runs in the child process, any in-memory side effect (e.g. +modifying a variable, releasing memory, etc) it causes will *not* be observable +in the parent process. In particular, if you release memory in a death test, +your program will fail the heap check as the parent process will never see the +memory reclaimed. To solve this problem, you can + +1. try not to free memory in a death test; +2. free the memory again in the parent process; or +3. do not use the heap checker in your program. + +Due to an implementation detail, you cannot place multiple death test assertions +on the same line; otherwise, compilation will fail with an unobvious error +message. + +Despite the improved thread safety afforded by the "threadsafe" style of death +test, thread problems such as deadlock are still possible in the presence of +handlers registered with `pthread_atfork(3)`. + + +## Using Assertions in Sub-routines + +Note: If you want to put a series of test assertions in a subroutine to check +for a complex condition, consider using +[a custom GMock matcher](gmock_cook_book.md#NewMatchers) +instead. This lets you provide a more readable error message in case of failure +and avoid all of the issues described below. + +### Adding Traces to Assertions + +If a test sub-routine is called from several places, when an assertion inside it +fails, it can be hard to tell which invocation of the sub-routine the failure is +from. You can alleviate this problem using extra logging or custom failure +messages, but that usually clutters up your tests. A better solution is to use +the `SCOPED_TRACE` macro or the `ScopedTrace` utility: + +```c++ +SCOPED_TRACE(message); +``` +```c++ +ScopedTrace trace("file_path", line_number, message); +``` + +where `message` can be anything streamable to `std::ostream`. `SCOPED_TRACE` +macro will cause the current file name, line number, and the given message to be +added in every failure message. `ScopedTrace` accepts explicit file name and +line number in arguments, which is useful for writing test helpers. The effect +will be undone when the control leaves the current lexical scope. + +For example, + +```c++ +10: void Sub1(int n) { +11: EXPECT_EQ(Bar(n), 1); +12: EXPECT_EQ(Bar(n + 1), 2); +13: } +14: +15: TEST(FooTest, Bar) { +16: { +17: SCOPED_TRACE("A"); // This trace point will be included in +18: // every failure in this scope. +19: Sub1(1); +20: } +21: // Now it won't. +22: Sub1(9); +23: } +``` + +could result in messages like these: + +```none +path/to/foo_test.cc:11: Failure +Value of: Bar(n) +Expected: 1 + Actual: 2 +Google Test trace: +path/to/foo_test.cc:17: A + +path/to/foo_test.cc:12: Failure +Value of: Bar(n + 1) +Expected: 2 + Actual: 3 +``` + +Without the trace, it would've been difficult to know which invocation of +`Sub1()` the two failures come from respectively. (You could add an extra +message to each assertion in `Sub1()` to indicate the value of `n`, but that's +tedious.) + +Some tips on using `SCOPED_TRACE`: + +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. +2. 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. +3. 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 `""`. +4. 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. +5. The trace dump is clickable in Emacs - hit `return` on a line number and + you'll be taken to that line in the source file! + +### Propagating Fatal Failures + +A common pitfall when using `ASSERT_*` and `FAIL*` is not understanding that +when they fail they only abort the _current function_, not the entire test. For +example, the following test will segfault: + +```c++ +void Subroutine() { + // Generates a fatal failure and aborts the current function. + ASSERT_EQ(1, 2); + + // The following won't be executed. + ... +} + +TEST(FooTest, Bar) { + Subroutine(); // The intended behavior is for the fatal failure + // in Subroutine() to abort the entire test. + + // The actual behavior: the function goes on after Subroutine() returns. + int* p = nullptr; + *p = 3; // Segfault! +} +``` + +To alleviate this, googletest provides three different solutions. You could use +either exceptions, the `(ASSERT|EXPECT)_NO_FATAL_FAILURE` assertions or the +`HasFatalFailure()` function. They are described in the following two +subsections. + +#### Asserting on Subroutines with an exception + +The following code can turn ASSERT-failure into an exception: + +```c++ +class ThrowListener : public testing::EmptyTestEventListener { + void OnTestPartResult(const testing::TestPartResult& result) override { + if (result.type() == testing::TestPartResult::kFatalFailure) { + throw testing::AssertionException(result); + } + } +}; +int main(int argc, char** argv) { + ... + testing::UnitTest::GetInstance()->listeners().Append(new ThrowListener); + return RUN_ALL_TESTS(); +} +``` + +This listener should be added after other listeners if you have any, otherwise +they won't see failed `OnTestPartResult`. + +#### Asserting on Subroutines + +As shown above, if your test calls a subroutine that has an `ASSERT_*` failure +in it, the test will continue after the subroutine returns. This may not be what +you want. + +Often people want fatal failures to propagate like exceptions. For that +googletest offers the following macros: + +Fatal assertion | Nonfatal assertion | Verifies +------------------------------------- | ------------------------------------- | -------- +`ASSERT_NO_FATAL_FAILURE(statement);` | `EXPECT_NO_FATAL_FAILURE(statement);` | `statement` doesn't generate any new fatal failures in the current thread. + +Only failures in the thread that executes the assertion are checked to determine +the result of this type of assertions. If `statement` creates new threads, +failures in these threads are ignored. + +Examples: + +```c++ +ASSERT_NO_FATAL_FAILURE(Foo()); + +int i; +EXPECT_NO_FATAL_FAILURE({ + i = Bar(); +}); +``` + +Assertions from multiple threads are currently not supported on Windows. + +#### Checking for Failures in the Current Test + +`HasFatalFailure()` in the `::testing::Test` class returns `true` if an +assertion in the current test has suffered a fatal failure. This allows +functions to catch fatal failures in a sub-routine and return early. + +```c++ +class Test { + public: + ... + static bool HasFatalFailure(); +}; +``` + +The typical usage, which basically simulates the behavior of a thrown exception, +is: + +```c++ +TEST(FooTest, Bar) { + Subroutine(); + // Aborts if Subroutine() had a fatal failure. + if (HasFatalFailure()) return; + + // The following won't be executed. + ... +} +``` + +If `HasFatalFailure()` is used outside of `TEST()` , `TEST_F()` , or a test +fixture, you must add the `::testing::Test::` prefix, as in: + +```c++ +if (testing::Test::HasFatalFailure()) return; +``` + +Similarly, `HasNonfatalFailure()` returns `true` if the current test has at +least one non-fatal failure, and `HasFailure()` returns `true` if the current +test has at least one failure of either kind. + +## Logging Additional Information + +In your test code, you can call `RecordProperty("key", value)` to log additional +information, where `value` can be either a string or an `int`. The *last* value +recorded for a key will be emitted to the +[XML output](#generating-an-xml-report) if you specify one. For example, the +test + +```c++ +TEST_F(WidgetUsageTest, MinAndMaxWidgets) { + RecordProperty("MaximumWidgets", ComputeMaxUsage()); + RecordProperty("MinimumWidgets", ComputeMinUsage()); +} +``` + +will output XML like this: + +```xml + ... + + ... +``` + +> NOTE: +> +> * `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. +> * *`key`* must be a valid XML attribute name, and cannot conflict with the +> ones already used by googletest (`name`, `status`, `time`, `classname`, +> `type_param`, and `value_param`). +> * Calling `RecordProperty()` outside of the lifespan of a test is allowed. +> If it's called outside of a test but between a test suite's +> `SetUpTestSuite()` and `TearDownTestSuite()` methods, it will be +> attributed to the XML element for the test suite. If it's called outside +> of all test suites (e.g. in a test environment), it will be attributed to +> the top-level XML element. + +## Sharing Resources Between Tests in the Same Test Suite + +googletest creates a new test fixture object for each test in order to make +tests independent and easier to debug. However, sometimes tests use resources +that are expensive to set up, making the one-copy-per-test model prohibitively +expensive. + +If the tests don't change the resource, there's no harm in their sharing a +single resource copy. So, in addition to per-test set-up/tear-down, googletest +also supports per-test-suite set-up/tear-down. To use it: + +1. In your test fixture class (say `FooTest` ), declare as `static` some member + variables to hold the shared resources. +2. Outside your test fixture class (typically just below it), define those + member variables, optionally giving them initial values. +3. In the same test fixture class, define a `static void SetUpTestSuite()` + function (remember not to spell it as **`SetupTestSuite`** with a small + `u`!) to set up the shared resources and a `static void TearDownTestSuite()` + function to tear them down. + +That's it! googletest automatically calls `SetUpTestSuite()` before running the +*first test* in the `FooTest` test suite (i.e. before creating the first +`FooTest` object), and calls `TearDownTestSuite()` after running the *last test* +in it (i.e. after deleting the last `FooTest` object). In between, the tests can +use the shared resources. + +Remember that the test order is undefined, so your code can't depend on a test +preceding or following another. Also, the tests must either not modify the state +of any shared resource, or, if they do modify the state, they must restore the +state to its original value before passing control to the next test. + +Here's an example of per-test-suite set-up and tear-down: + +```c++ +class FooTest : public testing::Test { + protected: + // Per-test-suite set-up. + // Called before the first test in this test suite. + // Can be omitted if not needed. + static void SetUpTestSuite() { + shared_resource_ = new ...; + } + + // Per-test-suite tear-down. + // Called after the last test in this test suite. + // Can be omitted if not needed. + static void TearDownTestSuite() { + delete shared_resource_; + shared_resource_ = nullptr; + } + + // You can define per-test set-up logic as usual. + virtual void SetUp() { ... } + + // You can define per-test tear-down logic as usual. + virtual void TearDown() { ... } + + // Some expensive resource shared by all tests. + static T* shared_resource_; +}; + +T* FooTest::shared_resource_ = nullptr; + +TEST_F(FooTest, Test1) { + ... you can refer to shared_resource_ here ... +} + +TEST_F(FooTest, Test2) { + ... you can refer to shared_resource_ here ... +} +``` + +NOTE: Though the above code declares `SetUpTestSuite()` protected, it may +sometimes be necessary to declare it public, such as when using it with +`TEST_P`. + +## Global Set-Up and Tear-Down + +Just as you can do set-up and tear-down at the test level and the test suite +level, you can also do it at the test program level. Here's how. + +First, you subclass the `::testing::Environment` class to define a test +environment, which knows how to set-up and tear-down: + +```c++ +class Environment : public testing::Environment { + public: + ~Environment() override {} + + // Override this to define how to set up the environment. + void SetUp() override {} + + // Override this to define how to tear down the environment. + void TearDown() override {} +}; +``` + +Then, you register an instance of your environment class with googletest by +calling the `::testing::AddGlobalTestEnvironment()` function: + +```c++ +Environment* AddGlobalTestEnvironment(Environment* env); +``` + +Now, when `RUN_ALL_TESTS()` is called, it first calls the `SetUp()` method of +each environment object, then runs the tests if none of the environments +reported fatal failures and `GTEST_SKIP()` was not called. `RUN_ALL_TESTS()` +always calls `TearDown()` with each environment object, regardless of whether or +not the tests were run. + +It's OK to register multiple environment objects. In this suite, their `SetUp()` +will be called in the order they are registered, and their `TearDown()` will be +called in the reverse order. + +Note that googletest takes ownership of the registered environment objects. +Therefore **do not delete them** by yourself. + +You should call `AddGlobalTestEnvironment()` before `RUN_ALL_TESTS()` is called, +probably in `main()`. If you use `gtest_main`, you need to call this before +`main()` starts for it to take effect. One way to do this is to define a global +variable like this: + +```c++ +testing::Environment* const foo_env = + testing::AddGlobalTestEnvironment(new FooEnvironment); +``` + +However, we strongly recommend you to write your own `main()` and call +`AddGlobalTestEnvironment()` there, as relying on initialization of global +variables makes the code harder to read and may cause problems when you register +multiple environments from different translation units and the environments have +dependencies among them (remember that the compiler doesn't guarantee the order +in which global variables from different translation units are initialized). + +## Value-Parameterized Tests + +*Value-parameterized tests* allow you to test your code with different +parameters without writing multiple copies of the same test. This is useful in a +number of situations, for example: + +* You have a piece of code whose behavior is affected by one or more + command-line flags. You want to make sure your code performs correctly for + various values of those flags. +* You want to test different implementations of an OO interface. +* 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! + +### How to Write Value-Parameterized Tests + +To write value-parameterized tests, first you should define a fixture class. It +must be derived from both `testing::Test` and `testing::WithParamInterface` +(the latter is a pure interface), where `T` is the type of your parameter +values. For convenience, you can just derive the fixture class from +`testing::TestWithParam`, which itself is derived from both `testing::Test` +and `testing::WithParamInterface`. `T` can be any copyable type. If it's a +raw pointer, you are responsible for managing the lifespan of the pointed +values. + +NOTE: If your test fixture defines `SetUpTestSuite()` or `TearDownTestSuite()` +they must be declared **public** rather than **protected** in order to use +`TEST_P`. + +```c++ +class FooTest : + public testing::TestWithParam { + // You can implement all the usual fixture class members here. + // To access the test parameter, call GetParam() from class + // TestWithParam. +}; + +// Or, when you want to add parameters to a pre-existing fixture class: +class BaseTest : public testing::Test { + ... +}; +class BarTest : public BaseTest, + public testing::WithParamInterface { + ... +}; +``` + +Then, use the `TEST_P` macro to define as many test patterns using this fixture +as you want. The `_P` suffix is for "parameterized" or "pattern", whichever you +prefer to think. + +```c++ +TEST_P(FooTest, DoesBlah) { + // Inside a test, access the test parameter with the GetParam() method + // of the TestWithParam class: + EXPECT_TRUE(foo.Blah(GetParam())); + ... +} + +TEST_P(FooTest, HasBlahBlah) { + ... +} +``` + +Finally, you can use `INSTANTIATE_TEST_SUITE_P` to instantiate the test suite +with any set of parameters you want. googletest defines a number of functions +for generating test parameters. They return what we call (surprise!) *parameter +generators*. Here is a summary of them, which are all in the `testing` +namespace: + + + +| Parameter Generator | Behavior | +| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `Range(begin, end [, step])` | Yields values `{begin, begin+step, begin+step+step, ...}`. The values do not include `end`. `step` defaults to 1. | +| `Values(v1, v2, ..., vN)` | Yields values `{v1, v2, ..., vN}`. | +| `ValuesIn(container)` and `ValuesIn(begin,end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)` | +| `Bool()` | Yields sequence `{false, true}`. | +| `Combine(g1, g2, ..., gN)` | Yields all combinations (Cartesian product) as std\:\:tuples of the values generated by the `N` generators. | + + + +For more details, see the comments at the definitions of these functions. + +The following statement will instantiate tests from the `FooTest` test suite +each with parameter values `"meeny"`, `"miny"`, and `"moe"`. + +```c++ +INSTANTIATE_TEST_SUITE_P(InstantiationName, + FooTest, + testing::Values("meeny", "miny", "moe")); +``` + +NOTE: The code above must be placed at global or namespace scope, not at +function scope. + +Per default, every `TEST_P` without a corresponding `INSTANTIATE_TEST_SUITE_P` +causes a failing test in test suite `GoogleTestVerification`. If you have a test +suite where that omission is not an error, for example it is in a library that +may be linked in for other reason or where the list of test cases is dynamic and +may be empty, then this check can be suppressed by tagging the test suite: + +```c++ +GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST(FooTest); +``` + +To distinguish different instances of the pattern (yes, you can instantiate it +more than once), the first argument to `INSTANTIATE_TEST_SUITE_P` is a prefix +that will be added to the actual test suite name. Remember to pick unique +prefixes for different instantiations. The tests from the instantiation above +will have these names: + +* `InstantiationName/FooTest.DoesBlah/0` for `"meeny"` +* `InstantiationName/FooTest.DoesBlah/1` for `"miny"` +* `InstantiationName/FooTest.DoesBlah/2` for `"moe"` +* `InstantiationName/FooTest.HasBlahBlah/0` for `"meeny"` +* `InstantiationName/FooTest.HasBlahBlah/1` for `"miny"` +* `InstantiationName/FooTest.HasBlahBlah/2` for `"moe"` + +You can use these names in [`--gtest_filter`](#running-a-subset-of-the-tests). + +This statement will instantiate all tests from `FooTest` again, each with +parameter values `"cat"` and `"dog"`: + +```c++ +const char* pets[] = {"cat", "dog"}; +INSTANTIATE_TEST_SUITE_P(AnotherInstantiationName, FooTest, + testing::ValuesIn(pets)); +``` + +The tests from the instantiation above will have these names: + +* `AnotherInstantiationName/FooTest.DoesBlah/0` for `"cat"` +* `AnotherInstantiationName/FooTest.DoesBlah/1` for `"dog"` +* `AnotherInstantiationName/FooTest.HasBlahBlah/0` for `"cat"` +* `AnotherInstantiationName/FooTest.HasBlahBlah/1` for `"dog"` + +Please note that `INSTANTIATE_TEST_SUITE_P` will instantiate *all* tests in the +given test suite, whether their definitions come before or *after* the +`INSTANTIATE_TEST_SUITE_P` statement. + +You can see [sample7_unittest.cc] and [sample8_unittest.cc] for more examples. + +[sample7_unittest.cc]: ../googletest/samples/sample7_unittest.cc "Parameterized Test example" +[sample8_unittest.cc]: ../googletest/samples/sample8_unittest.cc "Parameterized Test example with multiple parameters" + +### Creating Value-Parameterized Abstract Tests + +In the above, we define and instantiate `FooTest` in the *same* source file. +Sometimes you may want to define value-parameterized tests in a library and let +other people instantiate them later. This pattern is known as *abstract tests*. +As an example of its application, when you are designing an interface you can +write a standard suite of abstract tests (perhaps using a factory function as +the test parameter) that all implementations of the interface are expected to +pass. When someone implements the interface, they can instantiate your suite to +get all the interface-conformance tests for free. + +To define abstract tests, you should organize your code like this: + +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. +2. Put the `TEST_P` definitions in `foo_param_test.cc`, which includes + `foo_param_test.h`. Think of this as *implementing* your abstract tests. + +Once they are defined, you can instantiate them by including `foo_param_test.h`, +invoking `INSTANTIATE_TEST_SUITE_P()`, and depending on the library target that +contains `foo_param_test.cc`. You can instantiate the same abstract test suite +multiple times, possibly in different source files. + +### Specifying Names for Value-Parameterized Test Parameters + +The optional last argument to `INSTANTIATE_TEST_SUITE_P()` allows the user to +specify a function or functor that generates custom test name suffixes based on +the test parameters. The function should accept one argument of type +`testing::TestParamInfo`, and return `std::string`. + +`testing::PrintToStringParamName` is a builtin test suffix generator that +returns the value of `testing::PrintToString(GetParam())`. It does not work for +`std::string` or C strings. + +NOTE: test names must be non-empty, unique, and may only contain ASCII +alphanumeric characters. In particular, they +[should not contain underscores](faq.md#why-should-test-suite-names-and-test-names-not-contain-underscore) + +```c++ +class MyTestSuite : public testing::TestWithParam {}; + +TEST_P(MyTestSuite, MyTest) +{ + std::cout << "Example Test Param: " << GetParam() << std::endl; +} + +INSTANTIATE_TEST_SUITE_P(MyGroup, MyTestSuite, testing::Range(0, 10), + testing::PrintToStringParamName()); +``` + +Providing a custom functor allows for more control over test parameter name +generation, especially for types where the automatic conversion does not +generate helpful parameter names (e.g. strings as demonstrated above). The +following example illustrates this for multiple parameters, an enumeration type +and a string, and also demonstrates how to combine generators. It uses a lambda +for conciseness: + +```c++ +enum class MyType { MY_FOO = 0, MY_BAR = 1 }; + +class MyTestSuite : public testing::TestWithParam> { +}; + +INSTANTIATE_TEST_SUITE_P( + MyGroup, MyTestSuite, + testing::Combine( + testing::Values(MyType::VALUE_0, MyType::VALUE_1), + testing::ValuesIn("", "")), + [](const testing::TestParamInfo& info) { + std::string name = absl::StrCat( + std::get<0>(info.param) == MY_FOO ? "Foo" : "Bar", "_", + std::get<1>(info.param)); + absl::c_replace_if(name, [](char c) { return !std::isalnum(c); }, '_'); + return name; + }); +``` + +## Typed Tests + +Suppose you have multiple implementations of the same interface and want to make +sure that all of them satisfy some common requirements. Or, you may have defined +several types that are supposed to conform to the same "concept" and you want to +verify it. In both cases, you want the same test logic repeated for different +types. + +While you can write one `TEST` or `TEST_F` for each type you want to test (and +you may even factor the test logic into a function template that you invoke from +the `TEST`), it's tedious and doesn't scale: if you want `m` tests over `n` +types, you'll end up writing `m*n` `TEST`s. + +*Typed tests* allow you to repeat the same test logic over a list of types. You +only need to write the test logic once, although you must know the type list +when writing typed tests. Here's how you do it: + +First, define a fixture class template. It should be parameterized by a type. +Remember to derive it from `::testing::Test`: + +```c++ +template +class FooTest : public testing::Test { + public: + ... + using List = std::list; + static T shared_; + T value_; +}; +``` + +Next, associate a list of types with the test suite, which will be repeated for +each type in the list: + +```c++ +using MyTypes = ::testing::Types; +TYPED_TEST_SUITE(FooTest, MyTypes); +``` + +The type alias (`using` or `typedef`) is necessary for the `TYPED_TEST_SUITE` +macro to parse correctly. Otherwise the compiler will think that each comma in +the type list introduces a new macro argument. + +Then, use `TYPED_TEST()` instead of `TEST_F()` to define a typed test for this +test suite. You can repeat this as many times as you want: + +```c++ +TYPED_TEST(FooTest, DoesBlah) { + // Inside a test, refer to the special name TypeParam to get the type + // parameter. Since we are inside a derived class template, C++ requires + // us to visit the members of FooTest via 'this'. + TypeParam n = this->value_; + + // To visit static members of the fixture, add the 'TestFixture::' + // prefix. + n += TestFixture::shared_; + + // To refer to typedefs in the fixture, add the 'typename TestFixture::' + // prefix. The 'typename' is required to satisfy the compiler. + typename TestFixture::List values; + + values.push_back(n); + ... +} + +TYPED_TEST(FooTest, HasPropertyA) { ... } +``` + +You can see [sample6_unittest.cc] for a complete example. + +[sample6_unittest.cc]: ../googletest/samples/sample6_unittest.cc "Typed Test example" + +## Type-Parameterized Tests + +*Type-parameterized tests* are like typed tests, except that they don't require +you to know the list of types ahead of time. Instead, you can define the test +logic first and instantiate it with different type lists later. You can even +instantiate it more than once in the same program. + +If you are designing an interface or concept, you can define a suite of +type-parameterized tests to verify properties that any valid implementation of +the interface/concept should have. Then, the author of each implementation can +just instantiate the test suite with their type to verify that it conforms to +the requirements, without having to write similar tests repeatedly. Here's an +example: + +First, define a fixture class template, as we did with typed tests: + +```c++ +template +class FooTest : public testing::Test { + ... +}; +``` + +Next, declare that you will define a type-parameterized test suite: + +```c++ +TYPED_TEST_SUITE_P(FooTest); +``` + +Then, use `TYPED_TEST_P()` to define a type-parameterized test. You can repeat +this as many times as you want: + +```c++ +TYPED_TEST_P(FooTest, DoesBlah) { + // Inside a test, refer to TypeParam to get the type parameter. + TypeParam n = 0; + ... +} + +TYPED_TEST_P(FooTest, HasPropertyA) { ... } +``` + +Now the tricky part: you need to register all test patterns using the +`REGISTER_TYPED_TEST_SUITE_P` macro before you can instantiate them. The first +argument of the macro is the test suite name; the rest are the names of the +tests in this test suite: + +```c++ +REGISTER_TYPED_TEST_SUITE_P(FooTest, + DoesBlah, HasPropertyA); +``` + +Finally, you are free to instantiate the pattern with the types you want. If you +put the above code in a header file, you can `#include` it in multiple C++ +source files and instantiate it multiple times. + +```c++ +using MyTypes = ::testing::Types; +INSTANTIATE_TYPED_TEST_SUITE_P(My, FooTest, MyTypes); +``` + +To distinguish different instances of the pattern, the first argument to the +`INSTANTIATE_TYPED_TEST_SUITE_P` macro is a prefix that will be added to the +actual test suite name. Remember to pick unique prefixes for different +instances. + +In the special case where the type list contains only one type, you can write +that type directly without `::testing::Types<...>`, like this: + +```c++ +INSTANTIATE_TYPED_TEST_SUITE_P(My, FooTest, int); +``` + +You can see [sample6_unittest.cc] for a complete example. + +## Testing Private Code + +If you change your software's internal implementation, your tests should not +break as long as the change is not observable by users. Therefore, **per the +black-box testing principle, most of the time you should test your code through +its public interfaces.** + +**If you still find yourself needing to test internal implementation code, +consider if there's a better design.** The desire to test internal +implementation is often a sign that the class is doing too much. Consider +extracting an implementation class, and testing it. Then use that implementation +class in the original class. + +If you absolutely have to test non-public interface code though, you can. There +are two cases to consider: + +* Static functions ( *not* the same as static member functions!) or unnamed + namespaces, and +* Private or protected class members + +To test them, we use the following special techniques: + +* Both static functions and definitions/declarations in an unnamed namespace + are only visible within the same translation unit. To test them, you can + `#include` the entire `.cc` file being tested in your `*_test.cc` file. + (#including `.cc` files is not a good way to reuse code - you should not do + this in production code!) + + However, a better approach is to move the private code into the + `foo::internal` namespace, where `foo` is the namespace your project + normally uses, and put the private declarations in a `*-internal.h` file. + Your production `.cc` files and your tests are allowed to include this + internal header, but your clients are not. This way, you can fully test your + internal implementation without leaking it to your clients. + +* Private class members are only accessible from within the class or by + friends. To access a class' private members, you can declare your test + fixture as a friend to the class and define accessors in your fixture. Tests + using the fixture can then access the private members of your production + class via the accessors in the fixture. Note that even though your fixture + is a friend to your production class, your tests are not automatically + friends to it, as they are technically defined in sub-classes of the + fixture. + + Another way to test private members is to refactor them into an + implementation class, which is then declared in a `*-internal.h` file. Your + clients aren't allowed to include this header but your tests can. Such is + called the + [Pimpl](https://www.gamedev.net/articles/programming/general-and-gameplay-programming/the-c-pimpl-r1794/) + (Private Implementation) idiom. + + Or, you can declare an individual test as a friend of your class by adding + this line in the class body: + + ```c++ + FRIEND_TEST(TestSuiteName, TestName); + ``` + + For example, + + ```c++ + // foo.h + class Foo { + ... + private: + FRIEND_TEST(FooTest, BarReturnsZeroOnNull); + + int Bar(void* x); + }; + + // foo_test.cc + ... + TEST(FooTest, BarReturnsZeroOnNull) { + Foo foo; + EXPECT_EQ(foo.Bar(NULL), 0); // Uses Foo's private member Bar(). + } + ``` + + Pay special attention when your class is defined in a namespace, as you + should define your test fixtures and tests in the same namespace if you want + them to be friends of your class. For example, if the code to be tested + looks like: + + ```c++ + namespace my_namespace { + + class Foo { + friend class FooTest; + FRIEND_TEST(FooTest, Bar); + FRIEND_TEST(FooTest, Baz); + ... definition of the class Foo ... + }; + + } // namespace my_namespace + ``` + + Your test code should be something like: + + ```c++ + namespace my_namespace { + + class FooTest : public testing::Test { + protected: + ... + }; + + TEST_F(FooTest, Bar) { ... } + TEST_F(FooTest, Baz) { ... } + + } // namespace my_namespace + ``` + +## "Catching" Failures + +If you are building a testing utility on top of googletest, you'll want to test +your utility. What framework would you use to test it? googletest, of course. + +The challenge is to verify that your testing utility reports failures correctly. +In frameworks that report a failure by throwing an exception, you could catch +the exception and assert on it. But googletest doesn't use exceptions, so how do +we test that a piece of code generates an expected failure? + +`"gtest/gtest-spi.h"` contains some constructs to do this. After #including this header, +you can use + +```c++ + EXPECT_FATAL_FAILURE(statement, substring); +``` + +to assert that `statement` generates a fatal (e.g. `ASSERT_*`) failure in the +current thread whose message contains the given `substring`, or use + +```c++ + EXPECT_NONFATAL_FAILURE(statement, substring); +``` + +if you are expecting a non-fatal (e.g. `EXPECT_*`) failure. + +Only failures in the current thread are checked to determine the result of this +type of expectations. If `statement` creates new threads, failures in these +threads are also ignored. If you want to catch failures in other threads as +well, use one of the following macros instead: + +```c++ + EXPECT_FATAL_FAILURE_ON_ALL_THREADS(statement, substring); + EXPECT_NONFATAL_FAILURE_ON_ALL_THREADS(statement, substring); +``` + +NOTE: Assertions from multiple threads are currently not supported on Windows. + +For technical reasons, there are some caveats: + +1. You cannot stream a failure message to either macro. + +2. `statement` in `EXPECT_FATAL_FAILURE{_ON_ALL_THREADS}()` cannot reference + local non-static variables or non-static members of `this` object. + +3. `statement` in `EXPECT_FATAL_FAILURE{_ON_ALL_THREADS}()` cannot return a + value. + +## Registering tests programmatically + +The `TEST` macros handle the vast majority of all use cases, but there are few +where runtime registration logic is required. For those cases, the framework +provides the `::testing::RegisterTest` that allows callers to register arbitrary +tests dynamically. + +This is an advanced API only to be used when the `TEST` macros are insufficient. +The macros should be preferred when possible, as they avoid most of the +complexity of calling this function. + +It provides the following signature: + +```c++ +template +TestInfo* RegisterTest(const char* test_suite_name, const char* test_name, + const char* type_param, const char* value_param, + const char* file, int line, Factory factory); +``` + +The `factory` argument is a factory callable (move-constructible) object or +function pointer that creates a new instance of the Test object. It handles +ownership to the caller. The signature of the callable is `Fixture*()`, where +`Fixture` is the test fixture class for the test. All tests registered with the +same `test_suite_name` must return the same fixture type. This is checked at +runtime. + +The framework will infer the fixture class from the factory and will call the +`SetUpTestSuite` and `TearDownTestSuite` for it. + +Must be called before `RUN_ALL_TESTS()` is invoked, otherwise behavior is +undefined. + +Use case example: + +```c++ +class MyFixture : public testing::Test { + public: + // All of these optional, just like in regular macro usage. + static void SetUpTestSuite() { ... } + static void TearDownTestSuite() { ... } + void SetUp() override { ... } + void TearDown() override { ... } +}; + +class MyTest : public MyFixture { + public: + explicit MyTest(int data) : data_(data) {} + void TestBody() override { ... } + + private: + int data_; +}; + +void RegisterMyTests(const std::vector& values) { + for (int v : values) { + testing::RegisterTest( + "MyFixture", ("Test" + std::to_string(v)).c_str(), nullptr, + std::to_string(v).c_str(), + __FILE__, __LINE__, + // Important to use the fixture type as the return type here. + [=]() -> MyFixture* { return new MyTest(v); }); + } +} +... +int main(int argc, char** argv) { + std::vector values_to_test = LoadValuesFromConfig(); + RegisterMyTests(values_to_test); + ... + return RUN_ALL_TESTS(); +} +``` +## Getting the Current Test's Name + +Sometimes a function may need to know the name of the currently running test. +For example, you may be using the `SetUp()` method of your test fixture to set +the golden file name based on which test is running. The `::testing::TestInfo` +class has this information: + +```c++ +namespace testing { + +class TestInfo { + public: + // Returns the test suite name and the test name, respectively. + // + // Do NOT delete or free the return value - it's managed by the + // TestInfo class. + const char* test_suite_name() const; + const char* name() const; +}; + +} +``` + +To obtain a `TestInfo` object for the currently running test, call +`current_test_info()` on the `UnitTest` singleton object: + +```c++ + // Gets information about the currently running test. + // Do NOT delete the returned object - it's managed by the UnitTest class. + const testing::TestInfo* const test_info = + testing::UnitTest::GetInstance()->current_test_info(); + + printf("We are in test %s of test suite %s.\n", + test_info->name(), + test_info->test_suite_name()); +``` + +`current_test_info()` returns a null pointer if no test is running. In +particular, you cannot find the test suite name in `SetUpTestSuite()`, +`TearDownTestSuite()` (where you know the test suite name implicitly), or +functions called from them. + +## Extending googletest by Handling Test Events + +googletest provides an **event listener API** to let you receive notifications +about the progress of a test program and test failures. The events you can +listen to include the start and end of the test program, a test suite, or a test +method, among others. You may use this API to augment or replace the standard +console output, replace the XML output, or provide a completely different form +of output, such as a GUI or a database. You can also use test events as +checkpoints to implement a resource leak checker, for example. + +### Defining Event Listeners + +To define a event listener, you subclass either testing::TestEventListener or +testing::EmptyTestEventListener The former is an (abstract) interface, where +*each pure virtual method can be overridden to handle a test event* (For +example, when a test starts, the `OnTestStart()` method will be called.). The +latter provides an empty implementation of all methods in the interface, such +that a subclass only needs to override the methods it cares about. + +When an event is fired, its context is passed to the handler function as an +argument. The following argument types are used: + +* UnitTest reflects the state of the entire test program, +* TestSuite has information about a test suite, which can contain one or more + tests, +* TestInfo contains the state of a test, and +* TestPartResult represents the result of a test assertion. + +An event handler function can examine the argument it receives to find out +interesting information about the event and the test program's state. + +Here's an example: + +```c++ + class MinimalistPrinter : public testing::EmptyTestEventListener { + // Called before a test starts. + virtual void OnTestStart(const testing::TestInfo& test_info) { + printf("*** Test %s.%s starting.\n", + test_info.test_suite_name(), test_info.name()); + } + + // Called after a failed assertion or a SUCCESS(). + virtual void OnTestPartResult(const testing::TestPartResult& test_part_result) { + printf("%s in %s:%d\n%s\n", + test_part_result.failed() ? "*** Failure" : "Success", + test_part_result.file_name(), + test_part_result.line_number(), + test_part_result.summary()); + } + + // Called after a test ends. + virtual void OnTestEnd(const testing::TestInfo& test_info) { + printf("*** Test %s.%s ending.\n", + test_info.test_suite_name(), test_info.name()); + } + }; +``` + +### Using Event Listeners + +To use the event listener you have defined, add an instance of it to the +googletest event listener list (represented by class TestEventListeners - note +the "s" at the end of the name) in your `main()` function, before calling +`RUN_ALL_TESTS()`: + +```c++ +int main(int argc, char** argv) { + testing::InitGoogleTest(&argc, argv); + // Gets hold of the event listener list. + testing::TestEventListeners& listeners = + testing::UnitTest::GetInstance()->listeners(); + // Adds a listener to the end. googletest takes the ownership. + listeners.Append(new MinimalistPrinter); + return RUN_ALL_TESTS(); +} +``` + +There's only one problem: the default test result printer is still in effect, so +its output will mingle with the output from your minimalist printer. To suppress +the default printer, just release it from the event listener list and delete it. +You can do so by adding one line: + +```c++ + ... + delete listeners.Release(listeners.default_result_printer()); + listeners.Append(new MinimalistPrinter); + return RUN_ALL_TESTS(); +``` + +Now, sit back and enjoy a completely different output from your tests. For more +details, see [sample9_unittest.cc]. + +[sample9_unittest.cc]: ../googletest/samples/sample9_unittest.cc "Event listener example" + +You may append more than one listener to the list. When an `On*Start()` or +`OnTestPartResult()` event is fired, the listeners will receive it in the order +they appear in the list (since new listeners are added to the end of the list, +the default text printer and the default XML generator will receive the event +first). An `On*End()` event will be received by the listeners in the *reverse* +order. This allows output by listeners added later to be framed by output from +listeners added earlier. + +### Generating Failures in Listeners + +You may use failure-raising macros (`EXPECT_*()`, `ASSERT_*()`, `FAIL()`, etc) +when processing an event. There are some restrictions: + +1. You cannot generate any failure in `OnTestPartResult()` (otherwise it will + cause `OnTestPartResult()` to be called recursively). +2. A listener that handles `OnTestPartResult()` is not allowed to generate any + failure. + +When you add listeners to the listener list, you should put listeners that +handle `OnTestPartResult()` *before* listeners that can generate failures. This +ensures that failures generated by the latter are attributed to the right test +by the former. + +See [sample10_unittest.cc] for an example of a failure-raising listener. + +[sample10_unittest.cc]: ../googletest/samples/sample10_unittest.cc "Failure-raising listener example" + +## Running Test Programs: Advanced Options + +googletest test programs are ordinary executables. Once built, you can run them +directly and affect their behavior via the following environment variables +and/or command line flags. For the flags to work, your programs must call +`::testing::InitGoogleTest()` before calling `RUN_ALL_TESTS()`. + +To see a list of supported flags and their usage, please run your test program +with the `--help` flag. You can also use `-h`, `-?`, or `/?` for short. + +If an option is specified both by an environment variable and by a flag, the +latter takes precedence. + +### Selecting Tests + +#### Listing Test Names + +Sometimes it is necessary to list the available tests in a program before +running them so that a filter may be applied if needed. Including the flag +`--gtest_list_tests` overrides all other flags and lists tests in the following +format: + +```none +TestSuite1. + TestName1 + TestName2 +TestSuite2. + TestName +``` + +None of the tests listed are actually run if the flag is provided. There is no +corresponding environment variable for this flag. + +#### Running a Subset of the Tests + +By default, a googletest program runs all tests the user has defined. Sometimes, +you want to run only a subset of the tests (e.g. for debugging or quickly +verifying a change). If you set the `GTEST_FILTER` environment variable or the +`--gtest_filter` flag to a filter string, googletest will only run the tests +whose full names (in the form of `TestSuiteName.TestName`) match the filter. + +The format of a filter is a '`:`'-separated list of wildcard patterns (called +the *positive patterns*) optionally followed by a '`-`' and another +'`:`'-separated pattern list (called the *negative patterns*). A test matches +the filter if and only if it matches any of the positive patterns but does not +match any of the negative patterns. + +A pattern may contain `'*'` (matches any string) or `'?'` (matches any single +character). For convenience, the filter `'*-NegativePatterns'` can be also +written as `'-NegativePatterns'`. + +For example: + +* `./foo_test` Has no flag, and thus runs all its tests. +* `./foo_test --gtest_filter=*` Also runs everything, due to the single + match-everything `*` value. +* `./foo_test --gtest_filter=FooTest.*` Runs everything in test suite + `FooTest` . +* `./foo_test --gtest_filter=*Null*:*Constructor*` Runs any test whose full + name contains either `"Null"` or `"Constructor"` . +* `./foo_test --gtest_filter=-*DeathTest.*` Runs all non-death tests. +* `./foo_test --gtest_filter=FooTest.*-FooTest.Bar` Runs everything in test + suite `FooTest` except `FooTest.Bar`. +* `./foo_test --gtest_filter=FooTest.*:BarTest.*-FooTest.Bar:BarTest.Foo` Runs + everything in test suite `FooTest` except `FooTest.Bar` and everything in + test suite `BarTest` except `BarTest.Foo`. + +#### Stop test execution upon first failure + +By default, a googletest program runs all tests the user has defined. In some +cases (e.g. iterative test development & execution) it may be desirable stop +test execution upon first failure (trading improved latency for completeness). +If `GTEST_FAIL_FAST` environment variable or `--gtest_fail_fast` flag is set, +the test runner will stop execution as soon as the first test failure is +found. + +#### Temporarily Disabling Tests + +If you have a broken test that you cannot fix right away, you can add the +`DISABLED_` prefix to its name. This will exclude it from execution. This is +better than commenting out the code or using `#if 0`, as disabled tests are +still compiled (and thus won't rot). + +If you need to disable all tests in a test suite, you can either add `DISABLED_` +to the front of the name of each test, or alternatively add it to the front of +the test suite name. + +For example, the following tests won't be run by googletest, even though they +will still be compiled: + +```c++ +// Tests that Foo does Abc. +TEST(FooTest, DISABLED_DoesAbc) { ... } + +class DISABLED_BarTest : public testing::Test { ... }; + +// Tests that Bar does Xyz. +TEST_F(DISABLED_BarTest, DoesXyz) { ... } +``` + +NOTE: This feature should only be used for temporary pain-relief. You still have +to fix the disabled tests at a later date. As a reminder, googletest will print +a banner warning you if a test program contains any disabled tests. + +TIP: You can easily count the number of disabled tests you have using `gsearch` +and/or `grep`. This number can be used as a metric for improving your test +quality. + +#### Temporarily Enabling Disabled Tests + +To include disabled tests in test execution, just invoke the test program with +the `--gtest_also_run_disabled_tests` flag or set the +`GTEST_ALSO_RUN_DISABLED_TESTS` environment variable to a value other than `0`. +You can combine this with the `--gtest_filter` flag to further select which +disabled tests to run. + +### Repeating the Tests + +Once in a while you'll run into a test whose result is hit-or-miss. Perhaps it +will fail only 1% of the time, making it rather hard to reproduce the bug under +a debugger. This can be a major source of frustration. + +The `--gtest_repeat` flag allows you to repeat all (or selected) test methods in +a program many times. Hopefully, a flaky test will eventually fail and give you +a chance to debug. Here's how to use it: + +```none +$ foo_test --gtest_repeat=1000 +Repeat foo_test 1000 times and don't stop at failures. + +$ foo_test --gtest_repeat=-1 +A negative count means repeating forever. + +$ 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 test +fails, it will drop into the debugger and you can then inspect +variables and stacks. + +$ foo_test --gtest_repeat=1000 --gtest_filter=FooBar.* +Repeat the tests whose name matches the filter 1000 times. +``` + +If your test program contains +[global set-up/tear-down](#global-set-up-and-tear-down) code, it will be +repeated in each iteration as well, as the flakiness may be in it. You can also +specify the repeat count by setting the `GTEST_REPEAT` environment variable. + +### Shuffling the Tests + +You can specify the `--gtest_shuffle` flag (or set the `GTEST_SHUFFLE` +environment variable to `1`) to run the tests in a program in a random order. +This helps to reveal bad dependencies between tests. + +By default, googletest uses a random seed calculated from the current time. +Therefore you'll get a different order every time. The console output includes +the random seed value, such that you can reproduce an order-related test failure +later. To specify the random seed explicitly, use the `--gtest_random_seed=SEED` +flag (or set the `GTEST_RANDOM_SEED` environment variable), where `SEED` is an +integer in the range [0, 99999]. The seed value 0 is special: it tells +googletest to do the default behavior of calculating the seed from the current +time. + +If you combine this with `--gtest_repeat=N`, googletest will pick a different +random seed and re-shuffle the tests in each iteration. + +### Controlling Test Output + +#### Colored Terminal Output + +googletest can use colors in its terminal output to make it easier to spot the +important information: + + +...
+ [----------] 1 test from + FooTest
+ [ RUN      ] + FooTest.DoesAbc
+ [       OK ] + FooTest.DoesAbc
+ [----------] + 2 tests from BarTest
+ [ RUN      ] + BarTest.HasXyzProperty
+ [       OK ] + BarTest.HasXyzProperty
+ [ RUN      ] + BarTest.ReturnsTrueOnSuccess ... some error messages ...
+ [   FAILED ] + BarTest.ReturnsTrueOnSuccess ...
+ [==========] + 30 tests from 14 test suites ran.
+ [   PASSED ] + 28 tests.
+ [   FAILED ] + 2 tests, listed below:
+ [   FAILED ] + BarTest.ReturnsTrueOnSuccess
+ [   FAILED ] + AnotherTest.DoesXyz
+
+ 2 FAILED TESTS + + + +You can set the `GTEST_COLOR` environment variable or the `--gtest_color` +command line flag to `yes`, `no`, or `auto` (the default) to enable colors, +disable colors, or let googletest decide. When the value is `auto`, googletest +will use colors if and only if the output goes to a terminal and (on non-Windows +platforms) the `TERM` environment variable is set to `xterm` or `xterm-color`. + +#### Suppressing test passes + +By default, googletest prints 1 line of output for each test, indicating if it +passed or failed. To show only test failures, run the test program with +`--gtest_brief=1`, or set the GTEST_BRIEF environment variable to `1`. + +#### Suppressing the Elapsed Time + +By default, googletest prints the time it takes to run each test. To disable +that, run the test program with the `--gtest_print_time=0` command line flag, or +set the GTEST_PRINT_TIME environment variable to `0`. + +#### Suppressing UTF-8 Text Output + +In case of assertion failures, googletest prints expected and actual values of +type `string` both as hex-encoded strings as well as in readable UTF-8 text if +they contain valid non-ASCII UTF-8 characters. If you want to suppress the UTF-8 +text because, for example, you don't have an UTF-8 compatible output medium, run +the test program with `--gtest_print_utf8=0` or set the `GTEST_PRINT_UTF8` +environment variable to `0`. + + + +#### Generating an XML Report + +googletest can emit a detailed XML report to a file in addition to its normal +textual output. The report contains the duration of each test, and thus can help +you identify slow tests. + +To generate the XML report, set the `GTEST_OUTPUT` environment variable or the +`--gtest_output` flag to the string `"xml:path_to_output_file"`, which will +create the file at the given location. You can also just use the string `"xml"`, +in which case the output can be found in the `test_detail.xml` file in the +current directory. + +If you specify a directory (for example, `"xml:output/directory/"` on Linux or +`"xml:output\directory\"` on Windows), googletest will create the XML file in +that directory, named after the test executable (e.g. `foo_test.xml` for test +program `foo_test` or `foo_test.exe`). If the file already exists (perhaps left +over from a previous run), googletest will pick a different name (e.g. +`foo_test_1.xml`) to avoid overwriting it. + +The report is based on the `junitreport` Ant task. Since that format was +originally intended for Java, a little interpretation is required to make it +apply to googletest tests, as shown here: + +```xml + + + + + + + + + +``` + +* The root `` element corresponds to the entire test program. +* `` elements correspond to googletest test suites. +* `` elements correspond to googletest test functions. + +For instance, the following program + +```c++ +TEST(MathTest, Addition) { ... } +TEST(MathTest, Subtraction) { ... } +TEST(LogicTest, NonContradiction) { ... } +``` + +could generate this report: + +```xml + + + + + ... + ... + + + + + + + + + +``` + +Things to note: + +* The `tests` attribute of a `` or `` element tells how + many test functions the googletest program or test suite contains, while the + `failures` attribute tells how many of them failed. + +* The `time` attribute expresses the duration of the test, test suite, or + entire test program in seconds. + +* The `timestamp` attribute records the local date and time of the test + execution. + +* Each `` element corresponds to a single failed googletest + assertion. + +#### Generating a JSON Report + +googletest can also emit a JSON report as an alternative format to XML. To +generate the JSON report, set the `GTEST_OUTPUT` environment variable or the +`--gtest_output` flag to the string `"json:path_to_output_file"`, which will +create the file at the given location. You can also just use the string +`"json"`, in which case the output can be found in the `test_detail.json` file +in the current directory. + +The report format conforms to the following JSON Schema: + +```json +{ + "$schema": "http://json-schema.org/schema#", + "type": "object", + "definitions": { + "TestCase": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "tests": { "type": "integer" }, + "failures": { "type": "integer" }, + "disabled": { "type": "integer" }, + "time": { "type": "string" }, + "testsuite": { + "type": "array", + "items": { + "$ref": "#/definitions/TestInfo" + } + } + } + }, + "TestInfo": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "status": { + "type": "string", + "enum": ["RUN", "NOTRUN"] + }, + "time": { "type": "string" }, + "classname": { "type": "string" }, + "failures": { + "type": "array", + "items": { + "$ref": "#/definitions/Failure" + } + } + } + }, + "Failure": { + "type": "object", + "properties": { + "failures": { "type": "string" }, + "type": { "type": "string" } + } + } + }, + "properties": { + "tests": { "type": "integer" }, + "failures": { "type": "integer" }, + "disabled": { "type": "integer" }, + "errors": { "type": "integer" }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "time": { "type": "string" }, + "name": { "type": "string" }, + "testsuites": { + "type": "array", + "items": { + "$ref": "#/definitions/TestCase" + } + } + } +} +``` + +The report uses the format that conforms to the following Proto3 using the +[JSON encoding](https://developers.google.com/protocol-buffers/docs/proto3#json): + +```proto +syntax = "proto3"; + +package googletest; + +import "google/protobuf/timestamp.proto"; +import "google/protobuf/duration.proto"; + +message UnitTest { + int32 tests = 1; + int32 failures = 2; + int32 disabled = 3; + int32 errors = 4; + google.protobuf.Timestamp timestamp = 5; + google.protobuf.Duration time = 6; + string name = 7; + repeated TestCase testsuites = 8; +} + +message TestCase { + string name = 1; + int32 tests = 2; + int32 failures = 3; + int32 disabled = 4; + int32 errors = 5; + google.protobuf.Duration time = 6; + repeated TestInfo testsuite = 7; +} + +message TestInfo { + string name = 1; + enum Status { + RUN = 0; + NOTRUN = 1; + } + Status status = 2; + google.protobuf.Duration time = 3; + string classname = 4; + message Failure { + string failures = 1; + string type = 2; + } + repeated Failure failures = 5; +} +``` + +For instance, the following program + +```c++ +TEST(MathTest, Addition) { ... } +TEST(MathTest, Subtraction) { ... } +TEST(LogicTest, NonContradiction) { ... } +``` + +could generate this report: + +```json +{ + "tests": 3, + "failures": 1, + "errors": 0, + "time": "0.035s", + "timestamp": "2011-10-31T18:52:42Z", + "name": "AllTests", + "testsuites": [ + { + "name": "MathTest", + "tests": 2, + "failures": 1, + "errors": 0, + "time": "0.015s", + "testsuite": [ + { + "name": "Addition", + "status": "RUN", + "time": "0.007s", + "classname": "", + "failures": [ + { + "message": "Value of: add(1, 1)\n Actual: 3\nExpected: 2", + "type": "" + }, + { + "message": "Value of: add(1, -1)\n Actual: 1\nExpected: 0", + "type": "" + } + ] + }, + { + "name": "Subtraction", + "status": "RUN", + "time": "0.005s", + "classname": "" + } + ] + }, + { + "name": "LogicTest", + "tests": 1, + "failures": 0, + "errors": 0, + "time": "0.005s", + "testsuite": [ + { + "name": "NonContradiction", + "status": "RUN", + "time": "0.005s", + "classname": "" + } + ] + } + ] +} +``` + +IMPORTANT: The exact format of the JSON document is subject to change. + +### Controlling How Failures Are Reported + +#### Detecting Test Premature Exit + +Google Test implements the _premature-exit-file_ protocol for test runners +to catch any kind of unexpected exits of test programs. Upon start, +Google Test creates the file which will be automatically deleted after +all work has been finished. Then, the test runner can check if this file +exists. In case the file remains undeleted, the inspected test has exited +prematurely. + +This feature is enabled only if the `TEST_PREMATURE_EXIT_FILE` environment +variable has been set. + +#### Turning Assertion Failures into Break-Points + +When running test programs under a debugger, it's very convenient if the +debugger can catch an assertion failure and automatically drop into interactive +mode. googletest's *break-on-failure* mode supports this behavior. + +To enable it, set the `GTEST_BREAK_ON_FAILURE` environment variable to a value +other than `0`. Alternatively, you can use the `--gtest_break_on_failure` +command line flag. + +#### Disabling Catching Test-Thrown Exceptions + +googletest can be used either with or without exceptions enabled. If a test +throws a C++ exception or (on Windows) a structured exception (SEH), by default +googletest catches it, reports it as a test failure, and continues with the next +test method. This maximizes the coverage of a test run. Also, on Windows an +uncaught exception will cause a pop-up window, so catching the exceptions allows +you to run the tests automatically. + +When debugging the test failures, however, you may instead want the exceptions +to be handled by the debugger, such that you can examine the call stack when an +exception is thrown. To achieve that, set the `GTEST_CATCH_EXCEPTIONS` +environment variable to `0`, or use the `--gtest_catch_exceptions=0` flag when +running the tests. + +### Sanitizer Integration + +The +[Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html), +[Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer), +and +[Thread Sanitizer](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual) +all provide weak functions that you can override to trigger explicit failures +when they detect sanitizer errors, such as creating a reference from `nullptr`. +To override these functions, place definitions for them in a source file that +you compile as part of your main binary: + +``` +extern "C" { +void __ubsan_on_report() { + FAIL() << "Encountered an undefined behavior sanitizer error"; +} +void __asan_on_error() { + FAIL() << "Encountered an address sanitizer error"; +} +void __tsan_on_report() { + FAIL() << "Encountered a thread sanitizer error"; +} +} // extern "C" +``` + +After compiling your project with one of the sanitizers enabled, if a particular +test triggers a sanitizer error, googletest will report that it failed. diff --git a/docs/community_created_documentation.md b/docs/community_created_documentation.md new file mode 100644 index 0000000..dfd87f7 --- /dev/null +++ b/docs/community_created_documentation.md @@ -0,0 +1,9 @@ +# Community-Created Documentation + +go/gunit-community-created-docs + +The following is a list, in no particular order, of links to documentation +created by the Googletest community. + +* [Googlemock Insights](https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles/blob/master/googletest/insights.md), + by [ElectricRCAircraftGuy](https://github.com/ElectricRCAircraftGuy) diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..d91bd4d --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,771 @@ +# Googletest FAQ + + + + + +## Why should test suite names and test names not contain underscore? + +Note: Googletest reserves underscore (`_`) for special purpose keywords, such as +[the `DISABLED_` prefix](advanced.md#temporarily-disabling-tests), in addition +to the following rationale. + +Underscore (`_`) is special, as C++ reserves the following to be used by the +compiler and the standard library: + +1. any identifier that starts with an `_` followed by an upper-case letter, and +2. any identifier that contains two consecutive underscores (i.e. `__`) + *anywhere* in its name. + +User code is *prohibited* from using such identifiers. + +Now let's look at what this means for `TEST` and `TEST_F`. + +Currently `TEST(TestSuiteName, TestName)` generates a class named +`TestSuiteName_TestName_Test`. What happens if `TestSuiteName` or `TestName` +contains `_`? + +1. If `TestSuiteName` starts with an `_` followed by an upper-case letter (say, + `_Foo`), we end up with `_Foo_TestName_Test`, which is reserved and thus + invalid. +2. If `TestSuiteName` ends with an `_` (say, `Foo_`), we get + `Foo__TestName_Test`, which is invalid. +3. If `TestName` starts with an `_` (say, `_Bar`), we get + `TestSuiteName__Bar_Test`, which is invalid. +4. If `TestName` ends with an `_` (say, `Bar_`), we get + `TestSuiteName_Bar__Test`, which is invalid. + +So clearly `TestSuiteName` and `TestName` cannot start or end with `_` +(Actually, `TestSuiteName` can start with `_` -- as long as the `_` isn't +followed by an upper-case letter. But that's getting complicated. So for +simplicity we just say that it cannot start with `_`.). + +It may seem fine for `TestSuiteName` and `TestName` to contain `_` in the +middle. However, consider this: + +```c++ +TEST(Time, Flies_Like_An_Arrow) { ... } +TEST(Time_Flies, Like_An_Arrow) { ... } +``` + +Now, the two `TEST`s will both generate the same class +(`Time_Flies_Like_An_Arrow_Test`). That's not good. + +So for simplicity, we just ask the users to avoid `_` in `TestSuiteName` and +`TestName`. The rule is more constraining than necessary, but it's simple and +easy to remember. It also gives googletest some wiggle room in case its +implementation needs to change in the future. + +If you violate the rule, there may not be immediate consequences, but your test +may (just may) break with a new compiler (or a new version of the compiler you +are using) or with a new version of googletest. Therefore it's best to follow +the rule. + +## Why does googletest support `EXPECT_EQ(NULL, ptr)` and `ASSERT_EQ(NULL, ptr)` but not `EXPECT_NE(NULL, ptr)` and `ASSERT_NE(NULL, ptr)`? + +First of all you can use `EXPECT_NE(nullptr, ptr)` and `ASSERT_NE(nullptr, +ptr)`. This is the preferred syntax in the style guide because nullptr does not +have the type problems that NULL does. Which is why NULL does not work. + +Due to some peculiarity of C++, it requires some non-trivial template meta +programming tricks to support using `NULL` as an argument of the `EXPECT_XX()` +and `ASSERT_XX()` macros. Therefore we only do it where it's most needed +(otherwise we make the implementation of googletest harder to maintain and more +error-prone than necessary). + +The `EXPECT_EQ()` macro takes the *expected* value as its first argument and the +*actual* value as the second. It's reasonable that someone wants to write +`EXPECT_EQ(NULL, some_expression)`, and this indeed was requested several times. +Therefore we implemented it. + +The need for `EXPECT_NE(NULL, ptr)` isn't nearly as strong. When the assertion +fails, you already know that `ptr` must be `NULL`, so it doesn't add any +information to print `ptr` in this case. That means `EXPECT_TRUE(ptr != NULL)` +works just as well. + +If we were to support `EXPECT_NE(NULL, ptr)`, for consistency we'll have to +support `EXPECT_NE(ptr, NULL)` as well, as unlike `EXPECT_EQ`, we don't have a +convention on the order of the two arguments for `EXPECT_NE`. This means using +the template meta programming tricks twice in the implementation, making it even +harder to understand and maintain. We believe the benefit doesn't justify the +cost. + +Finally, with the growth of the gMock matcher library, we are encouraging people +to use the unified `EXPECT_THAT(value, matcher)` syntax more often in tests. One +significant advantage of the matcher approach is that matchers can be easily +combined to form new matchers, while the `EXPECT_NE`, etc, macros cannot be +easily combined. Therefore we want to invest more in the matchers than in the +`EXPECT_XX()` macros. + +## I need to test that different implementations of an interface satisfy some common requirements. Should I use typed tests or value-parameterized tests? + +For testing various implementations of the same interface, either typed tests or +value-parameterized tests can get it done. It's really up to you the user to +decide which is more convenient for you, depending on your particular case. Some +rough guidelines: + +* Typed tests can be easier to write if instances of the different + implementations can be created the same way, modulo the type. For example, + if all these implementations have a public default constructor (such that + you can write `new TypeParam`), or if their factory functions have the same + form (e.g. `CreateInstance()`). +* Value-parameterized tests can be easier to write if you need different code + patterns to create different implementations' instances, e.g. `new Foo` vs + `new Bar(5)`. To accommodate for the differences, you can write factory + function wrappers and pass these function pointers to the tests as their + parameters. +* When a typed test fails, the default output includes the name of the type, + which can help you quickly identify which implementation is wrong. + Value-parameterized tests only show the number of the failed iteration by + default. You will need to define a function that returns the iteration name + and pass it as the third parameter to INSTANTIATE_TEST_SUITE_P to have more + useful output. +* When using typed tests, you need to make sure you are testing against the + interface type, not the concrete types (in other words, you want to make + sure `implicit_cast(my_concrete_impl)` works, not just that + `my_concrete_impl` works). It's less likely to make mistakes in this area + when using value-parameterized tests. + +I hope I didn't confuse you more. :-) If you don't mind, I'd suggest you to give +both approaches a try. Practice is a much better way to grasp the subtle +differences between the two tools. Once you have some concrete experience, you +can much more easily decide which one to use the next time. + +## I got some run-time errors about invalid proto descriptors when using `ProtocolMessageEquals`. Help! + +**Note:** `ProtocolMessageEquals` and `ProtocolMessageEquiv` are *deprecated* +now. Please use `EqualsProto`, etc instead. + +`ProtocolMessageEquals` and `ProtocolMessageEquiv` were redefined recently and +are now less tolerant of invalid protocol buffer definitions. In particular, if +you have a `foo.proto` that doesn't fully qualify the type of a protocol message +it references (e.g. `message` where it should be `message`), you +will now get run-time errors like: + +``` +... descriptor.cc:...] Invalid proto descriptor for file "path/to/foo.proto": +... descriptor.cc:...] blah.MyMessage.my_field: ".Bar" is not defined. +``` + +If you see this, your `.proto` file is broken and needs to be fixed by making +the types fully qualified. The new definition of `ProtocolMessageEquals` and +`ProtocolMessageEquiv` just happen to reveal your bug. + +## My death test modifies some state, but the change seems lost after the death test finishes. Why? + +Death tests (`EXPECT_DEATH`, etc) are executed in a sub-process s.t. the +expected crash won't kill the test program (i.e. the parent process). As a +result, any in-memory side effects they incur are observable in their respective +sub-processes, but not in the parent process. You can think of them as running +in a parallel universe, more or less. + +In particular, if you use mocking and the death test statement invokes some mock +methods, the parent process will think the calls have never occurred. Therefore, +you may want to move your `EXPECT_CALL` statements inside the `EXPECT_DEATH` +macro. + +## EXPECT_EQ(htonl(blah), blah_blah) generates weird compiler errors in opt mode. Is this a googletest bug? + +Actually, the bug is in `htonl()`. + +According to `'man htonl'`, `htonl()` is a *function*, which means it's valid to +use `htonl` as a function pointer. However, in opt mode `htonl()` is defined as +a *macro*, which breaks this usage. + +Worse, the macro definition of `htonl()` uses a `gcc` extension and is *not* +standard C++. That hacky implementation has some ad hoc limitations. In +particular, it prevents you from writing `Foo()`, where `Foo` +is a template that has an integral argument. + +The implementation of `EXPECT_EQ(a, b)` uses `sizeof(... a ...)` inside a +template argument, and thus doesn't compile in opt mode when `a` contains a call +to `htonl()`. It is difficult to make `EXPECT_EQ` bypass the `htonl()` bug, as +the solution must work with different compilers on various platforms. + +`htonl()` has some other problems as described in `//util/endian/endian.h`, +which defines `ghtonl()` to replace it. `ghtonl()` does the same thing `htonl()` +does, only without its problems. We suggest you to use `ghtonl()` instead of +`htonl()`, both in your tests and production code. + +`//util/endian/endian.h` also defines `ghtons()`, which solves similar problems +in `htons()`. + +Don't forget to add `//util/endian` to the list of dependencies in the `BUILD` +file wherever `ghtonl()` and `ghtons()` are used. The library consists of a +single header file and will not bloat your binary. + +## The compiler complains about "undefined references" to some static const member variables, but I did define them in the class body. What's wrong? + +If your class has a static data member: + +```c++ +// foo.h +class Foo { + ... + static const int kBar = 100; +}; +``` + +You also need to define it *outside* of the class body in `foo.cc`: + +```c++ +const int Foo::kBar; // No initializer here. +``` + +Otherwise your code is **invalid C++**, and may break in unexpected ways. In +particular, using it in googletest comparison assertions (`EXPECT_EQ`, etc) will +generate an "undefined reference" linker error. The fact that "it used to work" +doesn't mean it's valid. It just means that you were lucky. :-) + +If the declaration of the static data member is `constexpr` then it is +implicitly an `inline` definition, and a separate definition in `foo.cc` is not +needed: + +```c++ +// foo.h +class Foo { + ... + static constexpr int kBar = 100; // Defines kBar, no need to do it in foo.cc. +}; +``` + +## Can I derive a test fixture from another? + +Yes. + +Each test fixture has a corresponding and same named test suite. This means only +one test suite can use a particular fixture. Sometimes, however, multiple test +cases may want to use the same or slightly different fixtures. For example, you +may want to make sure that all of a GUI library's test suites don't leak +important system resources like fonts and brushes. + +In googletest, you share a fixture among test suites by putting the shared logic +in a base test fixture, then deriving from that base a separate fixture for each +test suite that wants to use this common logic. You then use `TEST_F()` to write +tests using each derived fixture. + +Typically, your code looks like this: + +```c++ +// Defines a base test fixture. +class BaseTest : public ::testing::Test { + protected: + ... +}; + +// Derives a fixture FooTest from BaseTest. +class FooTest : public BaseTest { + protected: + void SetUp() override { + BaseTest::SetUp(); // Sets up the base fixture first. + ... additional set-up work ... + } + + void TearDown() override { + ... clean-up work for FooTest ... + BaseTest::TearDown(); // Remember to tear down the base fixture + // after cleaning up FooTest! + } + + ... functions and variables for FooTest ... +}; + +// Tests that use the fixture FooTest. +TEST_F(FooTest, Bar) { ... } +TEST_F(FooTest, Baz) { ... } + +... additional fixtures derived from BaseTest ... +``` + +If necessary, you can continue to derive test fixtures from a derived fixture. +googletest has no limit on how deep the hierarchy can be. + +For a complete example using derived test fixtures, see +[sample5_unittest.cc](../googletest/samples/sample5_unittest.cc). + +## My compiler complains "void value not ignored as it ought to be." What does this mean? + +You're probably using an `ASSERT_*()` in a function that doesn't return `void`. +`ASSERT_*()` can only be used in `void` functions, due to exceptions being +disabled by our build system. Please see more details +[here](advanced.md#assertion-placement). + +## My death test hangs (or seg-faults). How do I fix it? + +In googletest, death tests are run in a child process and the way they work is +delicate. To write death tests you really need to understand how they work. +Please make sure you have read [this](advanced.md#how-it-works). + +In particular, death tests don't like having multiple threads in the parent +process. So the first thing you can try is to eliminate creating threads outside +of `EXPECT_DEATH()`. For example, you may want to use mocks or fake objects +instead of real ones in your tests. + +Sometimes this is impossible as some library you must use may be creating +threads before `main()` is even reached. In this case, you can try to minimize +the chance of conflicts by either moving as many activities as possible inside +`EXPECT_DEATH()` (in the extreme case, you want to move everything inside), or +leaving as few things as possible in it. Also, you can try to set the death test +style to `"threadsafe"`, which is safer but slower, and see if it helps. + +If you go with thread-safe death tests, remember that they rerun the test +program from the beginning in the child process. Therefore make sure your +program can run side-by-side with itself and is deterministic. + +In the end, this boils down to good concurrent programming. You have to make +sure that there are no race conditions or deadlocks in your program. No silver +bullet - sorry! + +## Should I use the constructor/destructor of the test fixture or SetUp()/TearDown()? {#CtorVsSetUp} + +The first thing to remember is that googletest does **not** reuse the same test +fixture object across multiple tests. For each `TEST_F`, googletest will create +a **fresh** test fixture object, immediately call `SetUp()`, run the test body, +call `TearDown()`, and then delete the test fixture object. + +When you need to write per-test set-up and tear-down logic, you have the choice +between using the test fixture constructor/destructor or `SetUp()/TearDown()`. +The former is usually preferred, as it has the following benefits: + +* By initializing a member variable in the constructor, we have the option to + make it `const`, which helps prevent accidental changes to its value and + makes the tests more obviously correct. +* In case we need to subclass the test fixture class, the subclass' + constructor is guaranteed to call the base class' constructor *first*, and + the subclass' destructor is guaranteed to call the base class' destructor + *afterward*. With `SetUp()/TearDown()`, a subclass may make the mistake of + forgetting to call the base class' `SetUp()/TearDown()` or call them at the + wrong time. + +You may still want to use `SetUp()/TearDown()` in the following cases: + +* C++ does not allow virtual function calls in constructors and destructors. + You can call a method declared as virtual, but it will not use dynamic + dispatch, it will use the definition from the class the constructor of which + is currently executing. This is because calling a virtual method before the + derived class constructor has a chance to run is very dangerous - the + virtual method might operate on uninitialized data. Therefore, if you need + to call a method that will be overridden in a derived class, you have to use + `SetUp()/TearDown()`. +* In the body of a constructor (or destructor), it's not possible to use the + `ASSERT_xx` macros. Therefore, if the set-up operation could cause a fatal + test failure that should prevent the test from running, it's necessary to + use `abort` and abort the whole test executable, + or to use `SetUp()` instead of a constructor. +* If the tear-down operation could throw an exception, you must use + `TearDown()` as opposed to the destructor, as throwing in a destructor leads + to undefined behavior and usually will kill your program right away. Note + that many standard libraries (like STL) may throw when exceptions are + enabled in the compiler. Therefore you should prefer `TearDown()` if you + want to write portable tests that work with or without exceptions. +* The googletest team is considering making the assertion macros throw on + platforms where exceptions are enabled (e.g. Windows, Mac OS, and Linux + client-side), which will eliminate the need for the user to propagate + failures from a subroutine to its caller. Therefore, you shouldn't use + googletest assertions in a destructor if your code could run on such a + platform. + +## The compiler complains "no matching function to call" when I use ASSERT_PRED*. How do I fix it? + +If the predicate function you use in `ASSERT_PRED*` or `EXPECT_PRED*` is +overloaded or a template, the compiler will have trouble figuring out which +overloaded version it should use. `ASSERT_PRED_FORMAT*` and +`EXPECT_PRED_FORMAT*` don't have this problem. + +If you see this error, you might want to switch to +`(ASSERT|EXPECT)_PRED_FORMAT*`, which will also give you a better failure +message. If, however, that is not an option, you can resolve the problem by +explicitly telling the compiler which version to pick. + +For example, suppose you have + +```c++ +bool IsPositive(int n) { + return n > 0; +} + +bool IsPositive(double x) { + return x > 0; +} +``` + +you will get a compiler error if you write + +```c++ +EXPECT_PRED1(IsPositive, 5); +``` + +However, this will work: + +```c++ +EXPECT_PRED1(static_cast(IsPositive), 5); +``` + +(The stuff inside the angled brackets for the `static_cast` operator is the type +of the function pointer for the `int`-version of `IsPositive()`.) + +As another example, when you have a template function + +```c++ +template +bool IsNegative(T x) { + return x < 0; +} +``` + +you can use it in a predicate assertion like this: + +```c++ +ASSERT_PRED1(IsNegative, -5); +``` + +Things are more interesting if your template has more than one parameter. The +following won't compile: + +```c++ +ASSERT_PRED2(GreaterThan, 5, 0); +``` + +as the C++ pre-processor thinks you are giving `ASSERT_PRED2` 4 arguments, which +is one more than expected. The workaround is to wrap the predicate function in +parentheses: + +```c++ +ASSERT_PRED2((GreaterThan), 5, 0); +``` + +## My compiler complains about "ignoring return value" when I call RUN_ALL_TESTS(). Why? + +Some people had been ignoring the return value of `RUN_ALL_TESTS()`. That is, +instead of + +```c++ + return RUN_ALL_TESTS(); +``` + +they write + +```c++ + RUN_ALL_TESTS(); +``` + +This is **wrong and dangerous**. The testing services needs to see the return +value of `RUN_ALL_TESTS()` in order to determine if a test has passed. If your +`main()` function ignores it, your test will be considered successful even if it +has a googletest assertion failure. Very bad. + +We have decided to fix this (thanks to Michael Chastain for the idea). Now, your +code will no longer be able to ignore `RUN_ALL_TESTS()` when compiled with +`gcc`. If you do so, you'll get a compiler error. + +If you see the compiler complaining about you ignoring the return value of +`RUN_ALL_TESTS()`, the fix is simple: just make sure its value is used as the +return value of `main()`. + +But how could we introduce a change that breaks existing tests? Well, in this +case, the code was already broken in the first place, so we didn't break it. :-) + +## My compiler complains that a constructor (or destructor) cannot return a value. What's going on? + +Due to a peculiarity of C++, in order to support the syntax for streaming +messages to an `ASSERT_*`, e.g. + +```c++ + ASSERT_EQ(1, Foo()) << "blah blah" << foo; +``` + +we had to give up using `ASSERT*` and `FAIL*` (but not `EXPECT*` and +`ADD_FAILURE*`) in constructors and destructors. The workaround is to move the +content of your constructor/destructor to a private void member function, or +switch to `EXPECT_*()` if that works. This +[section](advanced.md#assertion-placement) in the user's guide explains it. + +## My SetUp() function is not called. Why? + +C++ is case-sensitive. Did you spell it as `Setup()`? + +Similarly, sometimes people spell `SetUpTestSuite()` as `SetupTestSuite()` and +wonder why it's never called. + + +## I have several test suites which share the same test fixture logic, do I have to define a new test fixture class for each of them? This seems pretty tedious. + +You don't have to. Instead of + +```c++ +class FooTest : public BaseTest {}; + +TEST_F(FooTest, Abc) { ... } +TEST_F(FooTest, Def) { ... } + +class BarTest : public BaseTest {}; + +TEST_F(BarTest, Abc) { ... } +TEST_F(BarTest, Def) { ... } +``` + +you can simply `typedef` the test fixtures: + +```c++ +typedef BaseTest FooTest; + +TEST_F(FooTest, Abc) { ... } +TEST_F(FooTest, Def) { ... } + +typedef BaseTest BarTest; + +TEST_F(BarTest, Abc) { ... } +TEST_F(BarTest, Def) { ... } +``` + +## googletest output is buried in a whole bunch of LOG messages. What do I do? + +The googletest output is meant to be a concise and human-friendly report. If +your test generates textual output itself, it will mix with the googletest +output, making it hard to read. However, there is an easy solution to this +problem. + +Since `LOG` messages go to stderr, we decided to let googletest output go to +stdout. This way, you can easily separate the two using redirection. For +example: + +```shell +$ ./my_test > gtest_output.txt +``` + +## Why should I prefer test fixtures over global variables? + +There are several good reasons: + +1. It's likely your test needs to change the states of its global variables. + This makes it difficult to keep side effects from escaping one test and + contaminating others, making debugging difficult. By using fixtures, each + test has a fresh set of variables that's different (but with the same + names). Thus, tests are kept independent of each other. +2. Global variables pollute the global namespace. +3. Test fixtures can be reused via subclassing, which cannot be done easily + with global variables. This is useful if many test suites have something in + common. + +## What can the statement argument in ASSERT_DEATH() be? + +`ASSERT_DEATH(statement, matcher)` (or any death assertion macro) can be used +wherever *`statement`* is valid. So basically *`statement`* can be any C++ +statement that makes sense in the current context. In particular, it can +reference global and/or local variables, and can be: + +* a simple function call (often the case), +* a complex expression, or +* a compound statement. + +Some examples are shown here: + +```c++ +// A death test can be a simple function call. +TEST(MyDeathTest, FunctionCall) { + ASSERT_DEATH(Xyz(5), "Xyz failed"); +} + +// Or a complex expression that references variables and functions. +TEST(MyDeathTest, ComplexExpression) { + const bool c = Condition(); + ASSERT_DEATH((c ? Func1(0) : object2.Method("test")), + "(Func1|Method) failed"); +} + +// Death assertions can be used anywhere in a function. In +// particular, they can be inside a loop. +TEST(MyDeathTest, InsideLoop) { + // Verifies that Foo(0), Foo(1), ..., and Foo(4) all die. + for (int i = 0; i < 5; i++) { + EXPECT_DEATH_M(Foo(i), "Foo has \\d+ errors", + ::testing::Message() << "where i is " << i); + } +} + +// A death assertion can contain a compound statement. +TEST(MyDeathTest, CompoundStatement) { + // Verifies that at lease one of Bar(0), Bar(1), ..., and + // Bar(4) dies. + ASSERT_DEATH({ + for (int i = 0; i < 5; i++) { + Bar(i); + } + }, + "Bar has \\d+ errors"); +} +``` + +gtest-death-test_test.cc contains more examples if you are interested. + +## I have a fixture class `FooTest`, but `TEST_F(FooTest, Bar)` gives me error ``"no matching function for call to `FooTest::FooTest()'"``. Why? + +Googletest needs to be able to create objects of your test fixture class, so it +must have a default constructor. Normally the compiler will define one for you. +However, there are cases where you have to define your own: + +* If you explicitly declare a non-default constructor for class `FooTest` + (`DISALLOW_EVIL_CONSTRUCTORS()` does this), then you need to define a + default constructor, even if it would be empty. +* If `FooTest` has a const non-static data member, then you have to define the + default constructor *and* initialize the const member in the initializer + list of the constructor. (Early versions of `gcc` doesn't force you to + initialize the const member. It's a bug that has been fixed in `gcc 4`.) + +## Why does ASSERT_DEATH complain about previous threads that were already joined? + +With the Linux pthread library, there is no turning back once you cross the line +from a single thread to multiple threads. The first time you create a thread, a +manager thread is created in addition, so you get 3, not 2, threads. Later when +the thread you create joins the main thread, the thread count decrements by 1, +but the manager thread will never be killed, so you still have 2 threads, which +means you cannot safely run a death test. + +The new NPTL thread library doesn't suffer from this problem, as it doesn't +create a manager thread. However, if you don't control which machine your test +runs on, you shouldn't depend on this. + +## Why does googletest require the entire test suite, instead of individual tests, to be named *DeathTest when it uses ASSERT_DEATH? + +googletest does not interleave tests from different test suites. That is, it +runs all tests in one test suite first, and then runs all tests in the next test +suite, and so on. googletest does this because it needs to set up a test suite +before the first test in it is run, and tear it down afterwards. Splitting up +the test case would require multiple set-up and tear-down processes, which is +inefficient and makes the semantics unclean. + +If we were to determine the order of tests based on test name instead of test +case name, then we would have a problem with the following situation: + +```c++ +TEST_F(FooTest, AbcDeathTest) { ... } +TEST_F(FooTest, Uvw) { ... } + +TEST_F(BarTest, DefDeathTest) { ... } +TEST_F(BarTest, Xyz) { ... } +``` + +Since `FooTest.AbcDeathTest` needs to run before `BarTest.Xyz`, and we don't +interleave tests from different test suites, we need to run all tests in the +`FooTest` case before running any test in the `BarTest` case. This contradicts +with the requirement to run `BarTest.DefDeathTest` before `FooTest.Uvw`. + +## But I don't like calling my entire test suite \*DeathTest when it contains both death tests and non-death tests. What do I do? + +You don't have to, but if you like, you may split up the test suite into +`FooTest` and `FooDeathTest`, where the names make it clear that they are +related: + +```c++ +class FooTest : public ::testing::Test { ... }; + +TEST_F(FooTest, Abc) { ... } +TEST_F(FooTest, Def) { ... } + +using FooDeathTest = FooTest; + +TEST_F(FooDeathTest, Uvw) { ... EXPECT_DEATH(...) ... } +TEST_F(FooDeathTest, Xyz) { ... ASSERT_DEATH(...) ... } +``` + +## googletest prints the LOG messages in a death test's child process only when the test fails. How can I see the LOG messages when the death test succeeds? + +Printing the LOG messages generated by the statement inside `EXPECT_DEATH()` +makes it harder to search for real problems in the parent's log. Therefore, +googletest only prints them when the death test has failed. + +If you really need to see such LOG messages, a workaround is to temporarily +break the death test (e.g. by changing the regex pattern it is expected to +match). Admittedly, this is a hack. We'll consider a more permanent solution +after the fork-and-exec-style death tests are implemented. + +## The compiler complains about "no match for 'operator<<'" when I use an assertion. What gives? + +If you use a user-defined type `FooType` in an assertion, you must make sure +there is an `std::ostream& operator<<(std::ostream&, const FooType&)` function +defined such that we can print a value of `FooType`. + +In addition, if `FooType` is declared in a name space, the `<<` operator also +needs to be defined in the *same* name space. See https://abseil.io/tips/49 for details. + +## How do I suppress the memory leak messages on Windows? + +Since the statically initialized googletest singleton requires allocations on +the heap, the Visual C++ memory leak detector will report memory leaks at the +end of the program run. The easiest way to avoid this is to use the +`_CrtMemCheckpoint` and `_CrtMemDumpAllObjectsSince` calls to not report any +statically initialized heap objects. See MSDN for more details and additional +heap check/debug routines. + +## How can my code detect if it is running in a test? + +If you write code that sniffs whether it's running in a test and does different +things accordingly, you are leaking test-only logic into production code and +there is no easy way to ensure that the test-only code paths aren't run by +mistake in production. Such cleverness also leads to +[Heisenbugs](https://en.wikipedia.org/wiki/Heisenbug). Therefore we strongly +advise against the practice, and googletest doesn't provide a way to do it. + +In general, the recommended way to cause the code to behave differently under +test is [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection). You can inject +different functionality from the test and from the production code. Since your +production code doesn't link in the for-test logic at all (the +[`testonly`](https://docs.bazel.build/versions/master/be/common-definitions.html#common.testonly) attribute for BUILD targets helps to ensure +that), there is no danger in accidentally running it. + +However, if you *really*, *really*, *really* have no choice, and if you follow +the rule of ending your test program names with `_test`, you can use the +*horrible* hack of sniffing your executable name (`argv[0]` in `main()`) to know +whether the code is under test. + +## How do I temporarily disable a test? + +If you have a broken test that you cannot fix right away, you can add the +DISABLED_ prefix to its name. This will exclude it from execution. This is +better than commenting out the code or using #if 0, as disabled tests are still +compiled (and thus won't rot). + +To include disabled tests in test execution, just invoke the test program with +the --gtest_also_run_disabled_tests flag. + +## Is it OK if I have two separate `TEST(Foo, Bar)` test methods defined in different namespaces? + +Yes. + +The rule is **all test methods in the same test suite must use the same fixture +class.** This means that the following is **allowed** because both tests use the +same fixture class (`::testing::Test`). + +```c++ +namespace foo { +TEST(CoolTest, DoSomething) { + SUCCEED(); +} +} // namespace foo + +namespace bar { +TEST(CoolTest, DoSomething) { + SUCCEED(); +} +} // namespace bar +``` + +However, the following code is **not allowed** and will produce a runtime error +from googletest because the test methods are using different test fixture +classes with the same test suite name. + +```c++ +namespace foo { +class CoolTest : public ::testing::Test {}; // Fixture foo::CoolTest +TEST_F(CoolTest, DoSomething) { + SUCCEED(); +} +} // namespace foo + +namespace bar { +class CoolTest : public ::testing::Test {}; // Fixture: bar::CoolTest +TEST_F(CoolTest, DoSomething) { + SUCCEED(); +} +} // namespace bar +``` diff --git a/docs/gmock_cheat_sheet.md b/docs/gmock_cheat_sheet.md new file mode 100644 index 0000000..c13d85d --- /dev/null +++ b/docs/gmock_cheat_sheet.md @@ -0,0 +1,786 @@ +# gMock Cheat Sheet + + + + + + + +## Defining a Mock Class + +### Mocking a Normal Class {#MockClass} + +Given + +```cpp +class Foo { + ... + virtual ~Foo(); + virtual int GetSize() const = 0; + virtual string Describe(const char* name) = 0; + virtual string Describe(int type) = 0; + virtual bool Process(Bar elem, int count) = 0; +}; +``` + +(note that `~Foo()` **must** be virtual) we can define its mock as + +```cpp +#include "gmock/gmock.h" + +class MockFoo : public Foo { + ... + MOCK_METHOD(int, GetSize, (), (const, override)); + MOCK_METHOD(string, Describe, (const char* name), (override)); + MOCK_METHOD(string, Describe, (int type), (override)); + MOCK_METHOD(bool, Process, (Bar elem, int count), (override)); +}; +``` + +To create a "nice" mock, which ignores all uninteresting calls, a "naggy" mock, +which warns on all uninteresting calls, or a "strict" mock, which treats them as +failures: + +```cpp +using ::testing::NiceMock; +using ::testing::NaggyMock; +using ::testing::StrictMock; + +NiceMock nice_foo; // The type is a subclass of MockFoo. +NaggyMock naggy_foo; // The type is a subclass of MockFoo. +StrictMock strict_foo; // The type is a subclass of MockFoo. +``` + +**Note:** A mock object is currently naggy by default. We may make it nice by +default in the future. + +### Mocking a Class Template {#MockTemplate} + +Class templates can be mocked just like any class. + +To mock + +```cpp +template +class StackInterface { + ... + virtual ~StackInterface(); + virtual int GetSize() const = 0; + virtual void Push(const Elem& x) = 0; +}; +``` + +(note that all member functions that are mocked, including `~StackInterface()` +**must** be virtual). + +```cpp +template +class MockStack : public StackInterface { + ... + MOCK_METHOD(int, GetSize, (), (const, override)); + MOCK_METHOD(void, Push, (const Elem& x), (override)); +}; +``` + +### Specifying Calling Conventions for Mock Functions + +If your mock function doesn't use the default calling convention, you can +specify it by adding `Calltype(convention)` to `MOCK_METHOD`'s 4th parameter. +For example, + +```cpp + MOCK_METHOD(bool, Foo, (int n), (Calltype(STDMETHODCALLTYPE))); + MOCK_METHOD(int, Bar, (double x, double y), + (const, Calltype(STDMETHODCALLTYPE))); +``` + +where `STDMETHODCALLTYPE` is defined by `` on Windows. + +## Using Mocks in Tests {#UsingMocks} + +The typical work flow is: + +1. Import the gMock names you need to use. All gMock symbols are in the + `testing` namespace unless they are macros or otherwise noted. +2. Create the mock objects. +3. Optionally, set the default actions of the mock objects. +4. Set your expectations on the mock objects (How will they be called? What + will they do?). +5. Exercise code that uses the mock objects; if necessary, check the result + using googletest assertions. +6. When a mock object is destructed, gMock automatically verifies that all + expectations on it have been satisfied. + +Here's an example: + +```cpp +using ::testing::Return; // #1 + +TEST(BarTest, DoesThis) { + MockFoo foo; // #2 + + ON_CALL(foo, GetSize()) // #3 + .WillByDefault(Return(1)); + // ... other default actions ... + + EXPECT_CALL(foo, Describe(5)) // #4 + .Times(3) + .WillRepeatedly(Return("Category 5")); + // ... other expectations ... + + EXPECT_EQ("good", MyProductionFunction(&foo)); // #5 +} // #6 +``` + +## Setting Default Actions {#OnCall} + +gMock has a **built-in default action** for any function that returns `void`, +`bool`, a numeric value, or a pointer. In C++11, it will additionally returns +the default-constructed value, if one exists for the given type. + +To customize the default action for functions with return type *`T`*: + +```cpp +using ::testing::DefaultValue; + +// Sets the default value to be returned. T must be CopyConstructible. +DefaultValue::Set(value); +// Sets a factory. Will be invoked on demand. T must be MoveConstructible. +// T MakeT(); +DefaultValue::SetFactory(&MakeT); +// ... use the mocks ... +// Resets the default value. +DefaultValue::Clear(); +``` + +Example usage: + +```cpp + // Sets the default action for return type std::unique_ptr to + // creating a new Buzz every time. + DefaultValue>::SetFactory( + [] { return MakeUnique(AccessLevel::kInternal); }); + + // When this fires, the default action of MakeBuzz() will run, which + // will return a new Buzz object. + EXPECT_CALL(mock_buzzer_, MakeBuzz("hello")).Times(AnyNumber()); + + auto buzz1 = mock_buzzer_.MakeBuzz("hello"); + auto buzz2 = mock_buzzer_.MakeBuzz("hello"); + EXPECT_NE(nullptr, buzz1); + EXPECT_NE(nullptr, buzz2); + EXPECT_NE(buzz1, buzz2); + + // Resets the default action for return type std::unique_ptr, + // to avoid interfere with other tests. + DefaultValue>::Clear(); +``` + +To customize the default action for a particular method of a specific mock +object, use `ON_CALL()`. `ON_CALL()` has a similar syntax to `EXPECT_CALL()`, +but it is used for setting default behaviors (when you do not require that the +mock method is called). See [here](gmock_cook_book.md#UseOnCall) for a more detailed +discussion. + +```cpp +ON_CALL(mock-object, method(matchers)) + .With(multi-argument-matcher) ? + .WillByDefault(action); +``` + +## Setting Expectations {#ExpectCall} + +`EXPECT_CALL()` sets **expectations** on a mock method (How will it be called? +What will it do?): + +```cpp +EXPECT_CALL(mock-object, method (matchers)?) + .With(multi-argument-matcher) ? + .Times(cardinality) ? + .InSequence(sequences) * + .After(expectations) * + .WillOnce(action) * + .WillRepeatedly(action) ? + .RetiresOnSaturation(); ? +``` + +For each item above, `?` means it can be used at most once, while `*` means it +can be used any number of times. + +In order to pass, `EXPECT_CALL` must be used before the calls are actually made. + +The `(matchers)` is a comma-separated list of matchers that correspond to each +of the arguments of `method`, and sets the expectation only for calls of +`method` that matches all of the matchers. + +If `(matchers)` is omitted, the expectation is the same as if the matchers were +set to anything matchers (for example, `(_, _, _, _)` for a four-arg method). + +If `Times()` is omitted, the cardinality is assumed to be: + +* `Times(1)` when there is neither `WillOnce()` nor `WillRepeatedly()`; +* `Times(n)` when there are `n` `WillOnce()`s but no `WillRepeatedly()`, where + `n` >= 1; or +* `Times(AtLeast(n))` when there are `n` `WillOnce()`s and a + `WillRepeatedly()`, where `n` >= 0. + +A method with no `EXPECT_CALL()` is free to be invoked *any number of times*, +and the default action will be taken each time. + +## Matchers {#MatcherList} + + + +A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or +`EXPECT_CALL()`, or use it to validate a value directly using two macros: + + +| Macro | Description | +| :----------------------------------- | :------------------------------------ | +| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. | +| `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. | + + +**Note:** Although equality matching via `EXPECT_THAT(actual_value, +expected_value)` is supported, prefer to make the comparison explicit via +`EXPECT_THAT(actual_value, Eq(expected_value))` or `EXPECT_EQ(actual_value, +expected_value)`. + +Built-in matchers (where `argument` is the function argument, e.g. +`actual_value` in the example above, or when used in the context of +`EXPECT_CALL(mock_object, method(matchers))`, the arguments of `method`) are +divided into several categories: + +### Wildcard + +Matcher | Description +:-------------------------- | :----------------------------------------------- +`_` | `argument` can be any value of the correct type. +`A()` or `An()` | `argument` can be any value of type `type`. + +### Generic Comparison + + +| Matcher | Description | +| :--------------------- | :-------------------------------------------------- | +| `Eq(value)` or `value` | `argument == value` | +| `Ge(value)` | `argument >= value` | +| `Gt(value)` | `argument > value` | +| `Le(value)` | `argument <= value` | +| `Lt(value)` | `argument < value` | +| `Ne(value)` | `argument != value` | +| `IsFalse()` | `argument` evaluates to `false` in a Boolean context. | +| `IsTrue()` | `argument` evaluates to `true` in a Boolean context. | +| `IsNull()` | `argument` is a `NULL` pointer (raw or smart). | +| `NotNull()` | `argument` is a non-null pointer (raw or smart). | +| `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. (For testing whether an `optional<>` is set, check for equality with `nullopt`. You may need to use `Eq(nullopt)` if the inner type doesn't have `==`.)| +| `VariantWith(m)` | `argument` is `variant<>` that holds the alternative of type T with a value matching `m`. | +| `Ref(variable)` | `argument` is a reference to `variable`. | +| `TypedEq(value)` | `argument` has type `type` and is equal to `value`. You may need to use this instead of `Eq(value)` when the mock function is overloaded. | + + +Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or +destructed later. If the compiler complains that `value` doesn't have a public +copy constructor, try wrap it in `std::ref()`, e.g. +`Eq(std::ref(non_copyable_value))`. If you do that, make sure +`non_copyable_value` is not changed afterwards, or the meaning of your matcher +will be changed. + +`IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types +that can be explicitly converted to Boolean, but are not implicitly converted to +Boolean. In other cases, you can use the basic +[`EXPECT_TRUE` and `EXPECT_FALSE`](../../googletest/docs/primer#basic-assertions) +assertions. + +### Floating-Point Matchers {#FpMatchers} + + +| Matcher | Description | +| :------------------------------- | :--------------------------------- | +| `DoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. | +| `FloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. | +| `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. | +| `NanSensitiveFloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. | +| `IsNan()` | `argument` is any floating-point type with a NaN value. | + + +The above matchers use ULP-based comparison (the same as used in googletest). +They automatically pick a reasonable error bound based on the absolute value of +the expected value. `DoubleEq()` and `FloatEq()` conform to the IEEE standard, +which requires comparing two NaNs for equality to return false. The +`NanSensitive*` version instead treats two NaNs as equal, which is often what a +user wants. + + +| Matcher | Description | +| :------------------------------------------------ | :----------------------- | +| `DoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as unequal. | +| `FloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as unequal. | +| `NanSensitiveDoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as equal. | +| `NanSensitiveFloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as equal. | + + +### String Matchers + +The `argument` can be either a C string or a C++ string object: + + +| Matcher | Description | +| :---------------------- | :------------------------------------------------- | +| `ContainsRegex(string)` | `argument` matches the given regular expression. | +| `EndsWith(suffix)` | `argument` ends with string `suffix`. | +| `HasSubstr(string)` | `argument` contains `string` as a sub-string. | +| `MatchesRegex(string)` | `argument` matches the given regular expression with the match starting at the first character and ending at the last character. | +| `StartsWith(prefix)` | `argument` starts with string `prefix`. | +| `StrCaseEq(string)` | `argument` is equal to `string`, ignoring case. | +| `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring case. | +| `StrEq(string)` | `argument` is equal to `string`. | +| `StrNe(string)` | `argument` is not equal to `string`. | + + +`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They +use the regular expression syntax defined +[here](../../googletest/docs/advanced.md#regular-expression-syntax). All of +these matchers, except `ContainsRegex()` and `MatchesRegex()` work for wide +strings as well. + +### Container Matchers + +Most STL-style containers support `==`, so you can use `Eq(expected_container)` +or simply `expected_container` to match a container exactly. If you want to +write the elements in-line, match them more flexibly, or get more informative +messages, you can use: + + +| Matcher | Description | +| :---------------------------------------- | :------------------------------- | +| `BeginEndDistanceIs(m)` | `argument` is a container whose `begin()` and `end()` iterators are separated by a number of increments matching `m`. E.g. `BeginEndDistanceIs(2)` or `BeginEndDistanceIs(Lt(2))`. For containers that define a `size()` method, `SizeIs(m)` may be more efficient. | +| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. | +| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. | +| `Each(e)` | `argument` is a container where *every* element matches `e`, which can be either a value or a matcher. | +| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. | +| `ElementsAreArray({e0, e1, ..., en})`, `ElementsAreArray(a_container)`, `ElementsAreArray(begin, end)`, `ElementsAreArray(array)`, or `ElementsAreArray(array, count)` | The same as `ElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. | +| `IsEmpty()` | `argument` is an empty container (`container.empty()`). | +| `IsSubsetOf({e0, e1, ..., en})`, `IsSubsetOf(a_container)`, `IsSubsetOf(begin, end)`, `IsSubsetOf(array)`, or `IsSubsetOf(array, count)` | `argument` matches `UnorderedElementsAre(x0, x1, ..., xk)` for some subset `{x0, x1, ..., xk}` of the expected matchers. | +| `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. | +| `Pointwise(m, container)`, `Pointwise(m, {e0, e1, ..., en})` | `argument` contains the same number of elements as in `container`, and for all i, (the i-th element in `argument`, the i-th element in `container`) match `m`, which is a matcher on 2-tuples. E.g. `Pointwise(Le(), upper_bounds)` verifies that each element in `argument` doesn't exceed the corresponding element in `upper_bounds`. See more detail below. | +| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. | +| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, and under *some* permutation of the elements, each element matches an `ei` (for a different `i`), which can be a value or a matcher. | +| `UnorderedElementsAreArray({e0, e1, ..., en})`, `UnorderedElementsAreArray(a_container)`, `UnorderedElementsAreArray(begin, end)`, `UnorderedElementsAreArray(array)`, or `UnorderedElementsAreArray(array, count)` | The same as `UnorderedElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. | +| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. | +| `WhenSorted(m)` | When `argument` is sorted using the `<` operator, it matches container matcher `m`. E.g. `WhenSorted(ElementsAre(1, 2, 3))` verifies that `argument` contains elements 1, 2, and 3, ignoring order. | +| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, except that the given comparator instead of `<` is used to sort `argument`. E.g. `WhenSortedBy(std::greater(), ElementsAre(3, 2, 1))`. | + + +**Notes:** + +* These matchers can also match: + 1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`), + and + 2. an array passed as a pointer and a count (e.g. in `Bar(const T* buffer, + int len)` -- see [Multi-argument Matchers](#MultiArgMatchers)). +* The array being matched may be multi-dimensional (i.e. its elements can be + arrays). +* `m` in `Pointwise(m, ...)` should be a matcher for `::std::tuple` + where `T` and `U` are the element type of the actual container and the + expected container, respectively. For example, to compare two `Foo` + containers where `Foo` doesn't support `operator==`, one might write: + + ```cpp + using ::std::get; + MATCHER(FooEq, "") { + return std::get<0>(arg).Equals(std::get<1>(arg)); + } + ... + EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos)); + ``` + +### Member Matchers + + +| Matcher | Description | +| :------------------------------ | :----------------------------------------- | +| `Field(&class::field, m)` | `argument.field` (or `argument->field` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. | +| `Key(e)` | `argument.first` matches `e`, which can be either a value or a matcher. E.g. `Contains(Key(Le(5)))` can verify that a `map` contains a key `<= 5`. | +| `Pair(m1, m2)` | `argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. | +| `FieldsAre(m...)` | `argument` is a compatible object where each field matches piecewise with `m...`. A compatible object is any that supports the `std::tuple_size`+`get(obj)` protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates. | +| `Property(&class::property, m)` | `argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. | + + +### Matching the Result of a Function, Functor, or Callback + + +| Matcher | Description | +| :--------------- | :------------------------------------------------ | +| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. | + + +### Pointer Matchers + + +| Matcher | Description | +| :------------------------ | :---------------------------------------------- | +| `Address(m)` | the result of `std::addressof(argument)` matches `m`. | +| `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. | +| `Pointer(m)` | `argument` (either a smart pointer or a raw pointer) contains a pointer that matches `m`. `m` will match against the raw pointer regardless of the type of `argument`. | +| `WhenDynamicCastTo(m)` | when `argument` is passed through `dynamic_cast()`, it matches matcher `m`. | + + + + + + +### Multi-argument Matchers {#MultiArgMatchers} + +Technically, all matchers match a *single* value. A "multi-argument" matcher is +just one that matches a *tuple*. The following matchers can be used to match a +tuple `(x, y)`: + +Matcher | Description +:------ | :---------- +`Eq()` | `x == y` +`Ge()` | `x >= y` +`Gt()` | `x > y` +`Le()` | `x <= y` +`Lt()` | `x < y` +`Ne()` | `x != y` + +You can use the following selectors to pick a subset of the arguments (or +reorder them) to participate in the matching: + + +| Matcher | Description | +| :------------------------- | :---------------------------------------------- | +| `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`. | +| `Args(m)` | The tuple of the `k` selected (using 0-based indices) arguments matches `m`, e.g. `Args<1, 2>(Eq())`. | + + +### Composite Matchers + +You can make a matcher from one or more other matchers: + + +| Matcher | Description | +| :------------------------------- | :-------------------------------------- | +| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. | +| `AllOfArray({m0, m1, ..., mn})`, `AllOfArray(a_container)`, `AllOfArray(begin, end)`, `AllOfArray(array)`, or `AllOfArray(array, count)` | The same as `AllOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. | +| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. | +| `AnyOfArray({m0, m1, ..., mn})`, `AnyOfArray(a_container)`, `AnyOfArray(begin, end)`, `AnyOfArray(array)`, or `AnyOfArray(array, count)` | The same as `AnyOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. | +| `Not(m)` | `argument` doesn't match matcher `m`. | + + + + +### Adapters for Matchers + + +| Matcher | Description | +| :---------------------- | :------------------------------------ | +| `MatcherCast(m)` | casts matcher `m` to type `Matcher`. | +| `SafeMatcherCast(m)` | [safely casts](gmock_cook_book.md#casting-matchers) matcher `m` to type `Matcher`. | +| `Truly(predicate)` | `predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor. | + + +`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`, +which must be a permanent callback. + +### Using Matchers as Predicates {#MatchersAsPredicatesCheat} + + +| Matcher | Description | +| :---------------------------- | :------------------------------------------ | +| `Matches(m)(value)` | evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor. | +| `ExplainMatchResult(m, value, result_listener)` | evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. | +| `Value(value, m)` | evaluates to `true` if `value` matches `m`. | + + +### Defining Matchers + + +| Matcher | Description | +| :----------------------------------- | :------------------------------------ | +| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. | +| `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a matcher `IsDivisibleBy(n)` to match a number divisible by `n`. | +| `MATCHER_P2(IsBetween, a, b, absl::StrCat(negation ? "isn't" : "is", " between ", PrintToString(a), " and ", PrintToString(b))) { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. | + + +**Notes:** + +1. The `MATCHER*` macros cannot be used inside a function or class. +2. The matcher body must be *purely functional* (i.e. it cannot have any side + effect, and the result must not depend on anything other than the value + being matched and the matcher parameters). +3. You can use `PrintToString(x)` to convert a value `x` of any type to a + string. + +## Actions {#ActionList} + +**Actions** specify what a mock function should do when invoked. + +### Returning a Value + + +| | | +| :-------------------------------- | :-------------------------------------------- | +| `Return()` | Return from a `void` mock function. | +| `Return(value)` | Return `value`. If the type of `value` is different to the mock function's return type, `value` is converted to the latter type at the time the expectation is set, not when the action is executed. | +| `ReturnArg()` | Return the `N`-th (0-based) argument. | +| `ReturnNew(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different object is created each time. | +| `ReturnNull()` | Return a null pointer. | +| `ReturnPointee(ptr)` | Return the value pointed to by `ptr`. | +| `ReturnRef(variable)` | Return a reference to `variable`. | +| `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. | +| `ReturnRoundRobin({a1, ..., ak})` | Each call will return the next `ai` in the list, starting at the beginning when the end of the list is reached. | + + +### Side Effects + + +| | | +| :--------------------------------- | :-------------------------------------- | +| `Assign(&variable, value)` | Assign `value` to variable. | +| `DeleteArg()` | Delete the `N`-th (0-based) argument, which must be a pointer. | +| `SaveArg(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. | +| `SaveArgPointee(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. | +| `SetArgReferee(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. | +| `SetArgPointee(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. | +| `SetArgumentPointee(value)` | Same as `SetArgPointee(value)`. Deprecated. Will be removed in v1.7.0. | +| `SetArrayArgument(first, last)` | Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range. | +| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. | +| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. | + + +### Using a Function, Functor, or Lambda as an Action + +In the following, by "callable" we mean a free function, `std::function`, +functor, or lambda. + + +| | | +| :---------------------------------- | :------------------------------------- | +| `f` | Invoke f with the arguments passed to the mock function, where f is a callable. | +| `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. | +| `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. | +| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. | +| `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. | +| `InvokeArgument(arg1, arg2, ..., argk)` | Invoke the mock function's `N`-th (0-based) argument, which must be a function or a functor, with the `k` arguments. | + + +The return value of the invoked function is used as the return value of the +action. + +When defining a callable to be used with `Invoke*()`, you can declare any unused +parameters as `Unused`: + +```cpp +using ::testing::Invoke; +double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); } +... +EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance)); +``` + +`Invoke(callback)` and `InvokeWithoutArgs(callback)` take ownership of +`callback`, which must be permanent. The type of `callback` must be a base +callback type instead of a derived one, e.g. + +```cpp + BlockingClosure* done = new BlockingClosure; + ... Invoke(done) ...; // This won't compile! + + Closure* done2 = new BlockingClosure; + ... Invoke(done2) ...; // This works. +``` + +In `InvokeArgument(...)`, if an argument needs to be passed by reference, +wrap it inside `std::ref()`. For example, + +```cpp +using ::testing::InvokeArgument; +... +InvokeArgument<2>(5, string("Hi"), std::ref(foo)) +``` + +calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by +value, and `foo` by reference. + +### Default Action + + +| Matcher | Description | +| :------------ | :----------------------------------------------------- | +| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). | + + +**Note:** due to technical reasons, `DoDefault()` cannot be used inside a +composite action - trying to do so will result in a run-time error. + + + +### Composite Actions + + +| | | +| :----------------------------- | :------------------------------------------ | +| `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the result of `an` in each invocation. The first `n - 1` sub-actions must return void and will receive a readonly view of the arguments. | +| `IgnoreResult(a)` | Perform action `a` and ignore its result. `a` must not return void. | +| `WithArg(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. | +| `WithArgs(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. | +| `WithoutArgs(a)` | Perform action `a` without any arguments. | + + +### Defining Actions + + +| | | +| :--------------------------------- | :-------------------------------------- | +| `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. | +| `ACTION_P(Plus, n) { return arg0 + n; }` | Defines an action `Plus(n)` to return the sum of the mock function's argument #0 and `n`. | +| `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. | + + +The `ACTION*` macros cannot be used inside a function or class. + +## Cardinalities {#CardinalityList} + +These are used in `Times()` to specify how many times a mock function will be +called: + + +| | | +| :---------------- | :----------------------------------------------------- | +| `AnyNumber()` | The function can be called any number of times. | +| `AtLeast(n)` | The call is expected at least `n` times. | +| `AtMost(n)` | The call is expected at most `n` times. | +| `Between(m, n)` | The call is expected between `m` and `n` (inclusive) times. | +| `Exactly(n) or n` | The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0. | + + +## Expectation Order + +By default, the expectations can be matched in *any* order. If some or all +expectations must be matched in a given order, there are two ways to specify it. +They can be used either independently or together. + +### The After Clause {#AfterClause} + +```cpp +using ::testing::Expectation; +... +Expectation init_x = EXPECT_CALL(foo, InitX()); +Expectation init_y = EXPECT_CALL(foo, InitY()); +EXPECT_CALL(foo, Bar()) + .After(init_x, init_y); +``` + +says that `Bar()` can be called only after both `InitX()` and `InitY()` have +been called. + +If you don't know how many pre-requisites an expectation has when you write it, +you can use an `ExpectationSet` to collect them: + +```cpp +using ::testing::ExpectationSet; +... +ExpectationSet all_inits; +for (int i = 0; i < element_count; i++) { + all_inits += EXPECT_CALL(foo, InitElement(i)); +} +EXPECT_CALL(foo, Bar()) + .After(all_inits); +``` + +says that `Bar()` can be called only after all elements have been initialized +(but we don't care about which elements get initialized before the others). + +Modifying an `ExpectationSet` after using it in an `.After()` doesn't affect the +meaning of the `.After()`. + +### Sequences {#UsingSequences} + +When you have a long chain of sequential expectations, it's easier to specify +the order using **sequences**, which don't require you to given each expectation +in the chain a different name. *All expected calls* in the same sequence must +occur in the order they are specified. + +```cpp +using ::testing::Return; +using ::testing::Sequence; +Sequence s1, s2; +... +EXPECT_CALL(foo, Reset()) + .InSequence(s1, s2) + .WillOnce(Return(true)); +EXPECT_CALL(foo, GetSize()) + .InSequence(s1) + .WillOnce(Return(1)); +EXPECT_CALL(foo, Describe(A())) + .InSequence(s2) + .WillOnce(Return("dummy")); +``` + +says that `Reset()` must be called before *both* `GetSize()` *and* `Describe()`, +and the latter two can occur in any order. + +To put many expectations in a sequence conveniently: + +```cpp +using ::testing::InSequence; +{ + InSequence seq; + + EXPECT_CALL(...)...; + EXPECT_CALL(...)...; + ... + EXPECT_CALL(...)...; +} +``` + +says that all expected calls in the scope of `seq` must occur in strict order. +The name `seq` is irrelevant. + +## Verifying and Resetting a Mock + +gMock will verify the expectations on a mock object when it is destructed, or +you can do it earlier: + +```cpp +using ::testing::Mock; +... +// Verifies and removes the expectations on mock_obj; +// returns true if and only if successful. +Mock::VerifyAndClearExpectations(&mock_obj); +... +// Verifies and removes the expectations on mock_obj; +// also removes the default actions set by ON_CALL(); +// returns true if and only if successful. +Mock::VerifyAndClear(&mock_obj); +``` + +You can also tell gMock that a mock object can be leaked and doesn't need to be +verified: + +```cpp +Mock::AllowLeak(&mock_obj); +``` + +## Mock Classes + +gMock defines a convenient mock class template + +```cpp +class MockFunction { + public: + MOCK_METHOD(R, Call, (A1, ..., An)); +}; +``` + +See this [recipe](gmock_cook_book.md#using-check-points) for one application of it. + +## Flags + + +| Flag | Description | +| :----------------------------- | :---------------------------------------- | +| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. | +| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. | + diff --git a/docs/gmock_cook_book.md b/docs/gmock_cook_book.md new file mode 100644 index 0000000..c88ded2 --- /dev/null +++ b/docs/gmock_cook_book.md @@ -0,0 +1,4267 @@ +# gMock Cookbook + + + +You can find recipes for using gMock here. If you haven't yet, please read +[the dummy guide](gmock_for_dummies.md) first to make sure you understand the +basics. + +**Note:** gMock lives in the `testing` name space. For readability, it is +recommended to write `using ::testing::Foo;` once in your file before using the +name `Foo` defined by gMock. We omit such `using` statements in this section for +brevity, but you should do it in your own code. + + + +## Creating Mock Classes + +Mock classes are defined as normal classes, using the `MOCK_METHOD` macro to +generate mocked methods. The macro gets 3 or 4 parameters: + +```cpp +class MyMock { + public: + MOCK_METHOD(ReturnType, MethodName, (Args...)); + MOCK_METHOD(ReturnType, MethodName, (Args...), (Specs...)); +}; +``` + +The first 3 parameters are simply the method declaration, split into 3 parts. +The 4th parameter accepts a closed list of qualifiers, which affect the +generated method: + +* **`const`** - Makes the mocked method a `const` method. Required if + overriding a `const` method. +* **`override`** - Marks the method with `override`. Recommended if overriding + a `virtual` method. +* **`noexcept`** - Marks the method with `noexcept`. Required if overriding a + `noexcept` method. +* **`Calltype(...)`** - Sets the call type for the method (e.g. to + `STDMETHODCALLTYPE`), useful in Windows. +* **`ref(...)`** - Marks the method with the reference qualification + specified. Required if overriding a method that has reference + qualifications. Eg `ref(&)` or `ref(&&)`. + +### Dealing with unprotected commas + +Unprotected commas, i.e. commas which are not surrounded by parentheses, prevent +`MOCK_METHOD` from parsing its arguments correctly: + +```cpp {.bad} +class MockFoo { + public: + MOCK_METHOD(std::pair, GetPair, ()); // Won't compile! + MOCK_METHOD(bool, CheckMap, (std::map, bool)); // Won't compile! +}; +``` + +Solution 1 - wrap with parentheses: + +```cpp {.good} +class MockFoo { + public: + MOCK_METHOD((std::pair), GetPair, ()); + MOCK_METHOD(bool, CheckMap, ((std::map), bool)); +}; +``` + +Note that wrapping a return or argument type with parentheses is, in general, +invalid C++. `MOCK_METHOD` removes the parentheses. + +Solution 2 - define an alias: + +```cpp {.good} +class MockFoo { + public: + using BoolAndInt = std::pair; + MOCK_METHOD(BoolAndInt, GetPair, ()); + using MapIntDouble = std::map; + MOCK_METHOD(bool, CheckMap, (MapIntDouble, bool)); +}; +``` + +### Mocking Private or Protected Methods + +You must always put a mock method definition (`MOCK_METHOD`) in a `public:` +section of the mock class, regardless of the method being mocked being `public`, +`protected`, or `private` in the base class. This allows `ON_CALL` and +`EXPECT_CALL` to reference the mock function from outside of the mock class. +(Yes, C++ allows a subclass to change the access level of a virtual function in +the base class.) Example: + +```cpp +class Foo { + public: + ... + virtual bool Transform(Gadget* g) = 0; + + protected: + virtual void Resume(); + + private: + virtual int GetTimeOut(); +}; + +class MockFoo : public Foo { + public: + ... + MOCK_METHOD(bool, Transform, (Gadget* g), (override)); + + // The following must be in the public section, even though the + // methods are protected or private in the base class. + MOCK_METHOD(void, Resume, (), (override)); + MOCK_METHOD(int, GetTimeOut, (), (override)); +}; +``` + +### Mocking Overloaded Methods + +You can mock overloaded functions as usual. No special attention is required: + +```cpp +class Foo { + ... + + // Must be virtual as we'll inherit from Foo. + virtual ~Foo(); + + // Overloaded on the types and/or numbers of arguments. + virtual int Add(Element x); + virtual int Add(int times, Element x); + + // Overloaded on the const-ness of this object. + virtual Bar& GetBar(); + virtual const Bar& GetBar() const; +}; + +class MockFoo : public Foo { + ... + MOCK_METHOD(int, Add, (Element x), (override)); + MOCK_METHOD(int, Add, (int times, Element x), (override)); + + MOCK_METHOD(Bar&, GetBar, (), (override)); + MOCK_METHOD(const Bar&, GetBar, (), (const, override)); +}; +``` + +**Note:** if you don't mock all versions of the overloaded method, the compiler +will give you a warning about some methods in the base class being hidden. To +fix that, use `using` to bring them in scope: + +```cpp +class MockFoo : public Foo { + ... + using Foo::Add; + MOCK_METHOD(int, Add, (Element x), (override)); + // We don't want to mock int Add(int times, Element x); + ... +}; +``` + +### Mocking Class Templates + +You can mock class templates just like any class. + +```cpp +template +class StackInterface { + ... + // Must be virtual as we'll inherit from StackInterface. + virtual ~StackInterface(); + + virtual int GetSize() const = 0; + virtual void Push(const Elem& x) = 0; +}; + +template +class MockStack : public StackInterface { + ... + MOCK_METHOD(int, GetSize, (), (override)); + MOCK_METHOD(void, Push, (const Elem& x), (override)); +}; +``` + +### Mocking Non-virtual Methods {#MockingNonVirtualMethods} + +gMock can mock non-virtual functions to be used in Hi-perf dependency +injection. + +In this case, instead of sharing a common base class with the real class, your +mock class will be *unrelated* to the real class, but contain methods with the +same signatures. The syntax for mocking non-virtual methods is the *same* as +mocking virtual methods (just don't add `override`): + +```cpp +// A simple packet stream class. None of its members is virtual. +class ConcretePacketStream { + public: + void AppendPacket(Packet* new_packet); + const Packet* GetPacket(size_t packet_number) const; + size_t NumberOfPackets() const; + ... +}; + +// A mock packet stream class. It inherits from no other, but defines +// GetPacket() and NumberOfPackets(). +class MockPacketStream { + public: + MOCK_METHOD(const Packet*, GetPacket, (size_t packet_number), (const)); + MOCK_METHOD(size_t, NumberOfPackets, (), (const)); + ... +}; +``` + +Note that the mock class doesn't define `AppendPacket()`, unlike the real class. +That's fine as long as the test doesn't need to call it. + +Next, you need a way to say that you want to use `ConcretePacketStream` in +production code, and use `MockPacketStream` in tests. Since the functions are +not virtual and the two classes are unrelated, you must specify your choice at +*compile time* (as opposed to run time). + +One way to do it is to templatize your code that needs to use a packet stream. +More specifically, you will give your code a template type argument for the type +of the packet stream. In production, you will instantiate your template with +`ConcretePacketStream` as the type argument. In tests, you will instantiate the +same template with `MockPacketStream`. For example, you may write: + +```cpp +template +void CreateConnection(PacketStream* stream) { ... } + +template +class PacketReader { + public: + void ReadPackets(PacketStream* stream, size_t packet_num); +}; +``` + +Then you can use `CreateConnection()` and +`PacketReader` in production code, and use +`CreateConnection()` and `PacketReader` in +tests. + +```cpp + MockPacketStream mock_stream; + EXPECT_CALL(mock_stream, ...)...; + .. set more expectations on mock_stream ... + PacketReader reader(&mock_stream); + ... exercise reader ... +``` + +### Mocking Free Functions + +It's possible to use gMock to mock a free function (i.e. a C-style function or a +static method). You just need to rewrite your code to use an interface (abstract +class). + +Instead of calling a free function (say, `OpenFile`) directly, introduce an +interface for it and have a concrete subclass that calls the free function: + +```cpp +class FileInterface { + public: + ... + virtual bool Open(const char* path, const char* mode) = 0; +}; + +class File : public FileInterface { + public: + ... + virtual bool Open(const char* path, const char* mode) { + return OpenFile(path, mode); + } +}; +``` + +Your code should talk to `FileInterface` to open a file. Now it's easy to mock +out the function. + +This may seem like a lot of hassle, but in practice you often have multiple +related functions that you can put in the same interface, so the per-function +syntactic overhead will be much lower. + +If you are concerned about the performance overhead incurred by virtual +functions, and profiling confirms your concern, you can combine this with the +recipe for [mocking non-virtual methods](#MockingNonVirtualMethods). + +### Old-Style `MOCK_METHODn` Macros + +Before the generic `MOCK_METHOD` macro +[was introduced in 2018](https://github.com/google/googletest/commit/c5f08bf91944ce1b19bcf414fa1760e69d20afc2), +mocks where created using a family of macros collectively called `MOCK_METHODn`. +These macros are still supported, though migration to the new `MOCK_METHOD` is +recommended. + +The macros in the `MOCK_METHODn` family differ from `MOCK_METHOD`: + +* The general structure is `MOCK_METHODn(MethodName, ReturnType(Args))`, + instead of `MOCK_METHOD(ReturnType, MethodName, (Args))`. +* The number `n` must equal the number of arguments. +* When mocking a const method, one must use `MOCK_CONST_METHODn`. +* When mocking a class template, the macro name must be suffixed with `_T`. +* In order to specify the call type, the macro name must be suffixed with + `_WITH_CALLTYPE`, and the call type is the first macro argument. + +Old macros and their new equivalents: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Simple
Old `MOCK_METHOD1(Foo, bool(int))`
New `MOCK_METHOD(bool, Foo, (int))`
Const Method
Old +`MOCK_CONST_METHOD1(Foo, bool(int))`
New +`MOCK_METHOD(bool, Foo, (int), (const))`
Method in a Class Template
Old `MOCK_METHOD1_T(Foo, bool(int))`
New +`MOCK_METHOD(bool, Foo, (int))`
Const Method in a Class Template
Old + `MOCK_CONST_METHOD1_T(Foo, bool(int))`
New + `MOCK_METHOD(bool, Foo, (int), (const))`
Method with Call Type
Old +`MOCK_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))`
New `MOCK_METHOD(bool, Foo, (int), +(Calltype(STDMETHODCALLTYPE)))`
Const Method with Call Type
Old `MOCK_CONST_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))`
New `MOCK_METHOD(bool, Foo, (int), (const, +Calltype(STDMETHODCALLTYPE)))`
Method with Call Type in a Class Template
Old `MOCK_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, +bool(int))`
New `MOCK_METHOD(bool, Foo, (int), +(Calltype(STDMETHODCALLTYPE)))`
Const Method with Call Type in a Class Template
Old `MOCK_CONST_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, +Foo, bool(int))`
New `MOCK_METHOD(bool, Foo, +(int), (const, Calltype(STDMETHODCALLTYPE)))`
+ +### The Nice, the Strict, and the Naggy {#NiceStrictNaggy} + +If a mock method has no `EXPECT_CALL` spec but is called, we say that it's an +"uninteresting call", and the default action (which can be specified using +`ON_CALL()`) of the method will be taken. Currently, an uninteresting call will +also by default cause gMock to print a warning. (In the future, we might remove +this warning by default.) + +However, sometimes you may want to ignore these uninteresting calls, and +sometimes you may want to treat them as errors. gMock lets you make the decision +on a per-mock-object basis. + +Suppose your test uses a mock class `MockFoo`: + +```cpp +TEST(...) { + MockFoo mock_foo; + EXPECT_CALL(mock_foo, DoThis()); + ... code that uses mock_foo ... +} +``` + +If a method of `mock_foo` other than `DoThis()` is called, you will get a +warning. However, if you rewrite your test to use `NiceMock` instead, +you can suppress the warning: + +```cpp +using ::testing::NiceMock; + +TEST(...) { + NiceMock mock_foo; + EXPECT_CALL(mock_foo, DoThis()); + ... code that uses mock_foo ... +} +``` + +`NiceMock` is a subclass of `MockFoo`, so it can be used wherever +`MockFoo` is accepted. + +It also works if `MockFoo`'s constructor takes some arguments, as +`NiceMock` "inherits" `MockFoo`'s constructors: + +```cpp +using ::testing::NiceMock; + +TEST(...) { + NiceMock mock_foo(5, "hi"); // Calls MockFoo(5, "hi"). + EXPECT_CALL(mock_foo, DoThis()); + ... code that uses mock_foo ... +} +``` + +The usage of `StrictMock` is similar, except that it makes all uninteresting +calls failures: + +```cpp +using ::testing::StrictMock; + +TEST(...) { + StrictMock mock_foo; + EXPECT_CALL(mock_foo, DoThis()); + ... code that uses mock_foo ... + + // The test will fail if a method of mock_foo other than DoThis() + // is called. +} +``` + +NOTE: `NiceMock` and `StrictMock` only affects *uninteresting* calls (calls of +*methods* with no expectations); they do not affect *unexpected* calls (calls of +methods with expectations, but they don't match). See +[Understanding Uninteresting vs Unexpected Calls](#uninteresting-vs-unexpected). + +There are some caveats though (sadly they are side effects of C++'s +limitations): + +1. `NiceMock` and `StrictMock` only work for mock methods + defined using the `MOCK_METHOD` macro **directly** in the `MockFoo` class. + If a mock method is defined in a **base class** of `MockFoo`, the "nice" or + "strict" modifier may not affect it, depending on the compiler. In + particular, nesting `NiceMock` and `StrictMock` (e.g. + `NiceMock >`) is **not** supported. +2. `NiceMock` and `StrictMock` may not work correctly if the + destructor of `MockFoo` is not virtual. We would like to fix this, but it + requires cleaning up existing tests. + +Finally, you should be **very cautious** about when to use naggy or strict +mocks, as they tend to make tests more brittle and harder to maintain. When you +refactor your code without changing its externally visible behavior, ideally you +shouldn't need to update any tests. If your code interacts with a naggy mock, +however, you may start to get spammed with warnings as the result of your +change. Worse, if your code interacts with a strict mock, your tests may start +to fail and you'll be forced to fix them. Our general recommendation is to use +nice mocks (not yet the default) most of the time, use naggy mocks (the current +default) when developing or debugging tests, and use strict mocks only as the +last resort. + +### Simplifying the Interface without Breaking Existing Code {#SimplerInterfaces} + +Sometimes a method has a long list of arguments that is mostly uninteresting. +For example: + +```cpp +class LogSink { + public: + ... + virtual void send(LogSeverity severity, const char* full_filename, + const char* base_filename, int line, + const struct tm* tm_time, + const char* message, size_t message_len) = 0; +}; +``` + +This method's argument list is lengthy and hard to work with (the `message` +argument is not even 0-terminated). If we mock it as is, using the mock will be +awkward. If, however, we try to simplify this interface, we'll need to fix all +clients depending on it, which is often infeasible. + +The trick is to redispatch the method in the mock class: + +```cpp +class ScopedMockLog : public LogSink { + public: + ... + virtual void send(LogSeverity severity, const char* full_filename, + const char* base_filename, int line, const tm* tm_time, + const char* message, size_t message_len) { + // We are only interested in the log severity, full file name, and + // log message. + Log(severity, full_filename, std::string(message, message_len)); + } + + // Implements the mock method: + // + // void Log(LogSeverity severity, + // const string& file_path, + // const string& message); + MOCK_METHOD(void, Log, + (LogSeverity severity, const string& file_path, + const string& message)); +}; +``` + +By defining a new mock method with a trimmed argument list, we make the mock +class more user-friendly. + +This technique may also be applied to make overloaded methods more amenable to +mocking. For example, when overloads have been used to implement default +arguments: + +```cpp +class MockTurtleFactory : public TurtleFactory { + public: + Turtle* MakeTurtle(int length, int weight) override { ... } + Turtle* MakeTurtle(int length, int weight, int speed) override { ... } + + // the above methods delegate to this one: + MOCK_METHOD(Turtle*, DoMakeTurtle, ()); +}; +``` + +This allows tests that don't care which overload was invoked to avoid specifying +argument matchers: + +```cpp +ON_CALL(factory, DoMakeTurtle) + .WillByDefault(Return(MakeMockTurtle())); +``` + +### Alternative to Mocking Concrete Classes + +Often you may find yourself using classes that don't implement interfaces. In +order to test your code that uses such a class (let's call it `Concrete`), you +may be tempted to make the methods of `Concrete` virtual and then mock it. + +Try not to do that. + +Making a non-virtual function virtual is a big decision. It creates an extension +point where subclasses can tweak your class' behavior. This weakens your control +on the class because now it's harder to maintain the class invariants. You +should make a function virtual only when there is a valid reason for a subclass +to override it. + +Mocking concrete classes directly is problematic as it creates a tight coupling +between the class and the tests - any small change in the class may invalidate +your tests and make test maintenance a pain. + +To avoid such problems, many programmers have been practicing "coding to +interfaces": instead of talking to the `Concrete` class, your code would define +an interface and talk to it. Then you implement that interface as an adaptor on +top of `Concrete`. In tests, you can easily mock that interface to observe how +your code is doing. + +This technique incurs some overhead: + +* You pay the cost of virtual function calls (usually not a problem). +* There is more abstraction for the programmers to learn. + +However, it can also bring significant benefits in addition to better +testability: + +* `Concrete`'s API may not fit your problem domain very well, as you may not + be the only client it tries to serve. By designing your own interface, you + have a chance to tailor it to your need - you may add higher-level + functionalities, rename stuff, etc instead of just trimming the class. This + allows you to write your code (user of the interface) in a more natural way, + which means it will be more readable, more maintainable, and you'll be more + productive. +* If `Concrete`'s implementation ever has to change, you don't have to rewrite + everywhere it is used. Instead, you can absorb the change in your + implementation of the interface, and your other code and tests will be + insulated from this change. + +Some people worry that if everyone is practicing this technique, they will end +up writing lots of redundant code. This concern is totally understandable. +However, there are two reasons why it may not be the case: + +* Different projects may need to use `Concrete` in different ways, so the best + interfaces for them will be different. Therefore, each of them will have its + own domain-specific interface on top of `Concrete`, and they will not be the + same code. +* If enough projects want to use the same interface, they can always share it, + just like they have been sharing `Concrete`. You can check in the interface + and the adaptor somewhere near `Concrete` (perhaps in a `contrib` + sub-directory) and let many projects use it. + +You need to weigh the pros and cons carefully for your particular problem, but +I'd like to assure you that the Java community has been practicing this for a +long time and it's a proven effective technique applicable in a wide variety of +situations. :-) + +### Delegating Calls to a Fake {#DelegatingToFake} + +Some times you have a non-trivial fake implementation of an interface. For +example: + +```cpp +class Foo { + public: + virtual ~Foo() {} + virtual char DoThis(int n) = 0; + virtual void DoThat(const char* s, int* p) = 0; +}; + +class FakeFoo : public Foo { + public: + char DoThis(int n) override { + return (n > 0) ? '+' : + (n < 0) ? '-' : '0'; + } + + void DoThat(const char* s, int* p) override { + *p = strlen(s); + } +}; +``` + +Now you want to mock this interface such that you can set expectations on it. +However, you also want to use `FakeFoo` for the default behavior, as duplicating +it in the mock object is, well, a lot of work. + +When you define the mock class using gMock, you can have it delegate its default +action to a fake class you already have, using this pattern: + +```cpp +class MockFoo : public Foo { + public: + // Normal mock method definitions using gMock. + MOCK_METHOD(char, DoThis, (int n), (override)); + MOCK_METHOD(void, DoThat, (const char* s, int* p), (override)); + + // Delegates the default actions of the methods to a FakeFoo object. + // This must be called *before* the custom ON_CALL() statements. + void DelegateToFake() { + ON_CALL(*this, DoThis).WillByDefault([this](int n) { + return fake_.DoThis(n); + }); + ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) { + fake_.DoThat(s, p); + }); + } + + private: + FakeFoo fake_; // Keeps an instance of the fake in the mock. +}; +``` + +With that, you can use `MockFoo` in your tests as usual. Just remember that if +you don't explicitly set an action in an `ON_CALL()` or `EXPECT_CALL()`, the +fake will be called upon to do it.: + +```cpp +using ::testing::_; + +TEST(AbcTest, Xyz) { + MockFoo foo; + + foo.DelegateToFake(); // Enables the fake for delegation. + + // Put your ON_CALL(foo, ...)s here, if any. + + // No action specified, meaning to use the default action. + EXPECT_CALL(foo, DoThis(5)); + EXPECT_CALL(foo, DoThat(_, _)); + + int n = 0; + EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked. + foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked. + EXPECT_EQ(2, n); +} +``` + +**Some tips:** + +* If you want, you can still override the default action by providing your own + `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`. +* In `DelegateToFake()`, you only need to delegate the methods whose fake + implementation you intend to use. + +* The general technique discussed here works for overloaded methods, but + you'll need to tell the compiler which version you mean. To disambiguate a + mock function (the one you specify inside the parentheses of `ON_CALL()`), + use [this technique](#SelectOverload); to disambiguate a fake function (the + one you place inside `Invoke()`), use a `static_cast` to specify the + function's type. For instance, if class `Foo` has methods `char DoThis(int + n)` and `bool DoThis(double x) const`, and you want to invoke the latter, + you need to write `Invoke(&fake_, static_cast(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)` + (The strange-looking thing inside the angled brackets of `static_cast` is + the type of a function pointer to the second `DoThis()` method.). + +* Having to mix a mock and a fake is often a sign of something gone wrong. + Perhaps you haven't got used to the interaction-based way of testing yet. Or + perhaps your interface is taking on too many roles and should be split up. + Therefore, **don't abuse this**. We would only recommend to do it as an + intermediate step when you are refactoring your code. + +Regarding the tip on mixing a mock and a fake, here's an example on why it may +be a bad sign: Suppose you have a class `System` for low-level system +operations. In particular, it does file and I/O operations. And suppose you want +to test how your code uses `System` to do I/O, and you just want the file +operations to work normally. If you mock out the entire `System` class, you'll +have to provide a fake implementation for the file operation part, which +suggests that `System` is taking on too many roles. + +Instead, you can define a `FileOps` interface and an `IOOps` interface and split +`System`'s functionalities into the two. Then you can mock `IOOps` without +mocking `FileOps`. + +### Delegating Calls to a Real Object + +When using testing doubles (mocks, fakes, stubs, and etc), sometimes their +behaviors will differ from those of the real objects. This difference could be +either intentional (as in simulating an error such that you can test the error +handling code) or unintentional. If your mocks have different behaviors than the +real objects by mistake, you could end up with code that passes the tests but +fails in production. + +You can use the *delegating-to-real* technique to ensure that your mock has the +same behavior as the real object while retaining the ability to validate calls. +This technique is very similar to the [delegating-to-fake](#DelegatingToFake) +technique, the difference being that we use a real object instead of a fake. +Here's an example: + +```cpp +using ::testing::AtLeast; + +class MockFoo : public Foo { + public: + MockFoo() { + // By default, all calls are delegated to the real object. + ON_CALL(*this, DoThis).WillByDefault([this](int n) { + return real_.DoThis(n); + }); + ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) { + real_.DoThat(s, p); + }); + ... + } + MOCK_METHOD(char, DoThis, ...); + MOCK_METHOD(void, DoThat, ...); + ... + private: + Foo real_; +}; + +... + MockFoo mock; + EXPECT_CALL(mock, DoThis()) + .Times(3); + EXPECT_CALL(mock, DoThat("Hi")) + .Times(AtLeast(1)); + ... use mock in test ... +``` + +With this, gMock will verify that your code made the right calls (with the right +arguments, in the right order, called the right number of times, etc), and a +real object will answer the calls (so the behavior will be the same as in +production). This gives you the best of both worlds. + +### Delegating Calls to a Parent Class + +Ideally, you should code to interfaces, whose methods are all pure virtual. In +reality, sometimes you do need to mock a virtual method that is not pure (i.e, +it already has an implementation). For example: + +```cpp +class Foo { + public: + virtual ~Foo(); + + virtual void Pure(int n) = 0; + virtual int Concrete(const char* str) { ... } +}; + +class MockFoo : public Foo { + public: + // Mocking a pure method. + MOCK_METHOD(void, Pure, (int n), (override)); + // Mocking a concrete method. Foo::Concrete() is shadowed. + MOCK_METHOD(int, Concrete, (const char* str), (override)); +}; +``` + +Sometimes you may want to call `Foo::Concrete()` instead of +`MockFoo::Concrete()`. Perhaps you want to do it as part of a stub action, or +perhaps your test doesn't need to mock `Concrete()` at all (but it would be +oh-so painful to have to define a new mock class whenever you don't need to mock +one of its methods). + +You can call `Foo::Concrete()` inside an action by: + +```cpp +... + EXPECT_CALL(foo, Concrete).WillOnce([&foo](const char* str) { + return foo.Foo::Concrete(str); + }); +``` + +or tell the mock object that you don't want to mock `Concrete()`: + +```cpp +... + ON_CALL(foo, Concrete).WillByDefault([&foo](const char* str) { + return foo.Foo::Concrete(str); + }); +``` + +(Why don't we just write `{ return foo.Concrete(str); }`? If you do that, +`MockFoo::Concrete()` will be called (and cause an infinite recursion) since +`Foo::Concrete()` is virtual. That's just how C++ works.) + +## Using Matchers + +### Matching Argument Values Exactly + +You can specify exactly which arguments a mock method is expecting: + +```cpp +using ::testing::Return; +... + EXPECT_CALL(foo, DoThis(5)) + .WillOnce(Return('a')); + EXPECT_CALL(foo, DoThat("Hello", bar)); +``` + +### Using Simple Matchers + +You can use matchers to match arguments that have a certain property: + +```cpp +using ::testing::NotNull; +using ::testing::Return; +... + EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5. + .WillOnce(Return('a')); + EXPECT_CALL(foo, DoThat("Hello", NotNull())); + // The second argument must not be NULL. +``` + +A frequently used matcher is `_`, which matches anything: + +```cpp + EXPECT_CALL(foo, DoThat(_, NotNull())); +``` + + +### Combining Matchers {#CombiningMatchers} + +You can build complex matchers from existing ones using `AllOf()`, +`AllOfArray()`, `AnyOf()`, `AnyOfArray()` and `Not()`: + +```cpp +using ::testing::AllOf; +using ::testing::Gt; +using ::testing::HasSubstr; +using ::testing::Ne; +using ::testing::Not; +... + // The argument must be > 5 and != 10. + EXPECT_CALL(foo, DoThis(AllOf(Gt(5), + Ne(10)))); + + // The first argument must not contain sub-string "blah". + EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")), + NULL)); +``` + +Matchers are function objects, and parametrized matchers can be composed just +like any other function. However because their types can be long and rarely +provide meaningful information, it can be easier to express them with C++14 +generic lambdas to avoid specifying types. For example, + +```cpp +using ::testing::Contains; +using ::testing::Property; + +inline constexpr auto HasFoo = [](const auto& f) { + return Property(&MyClass::foo, Contains(f)); +}; +... + EXPECT_THAT(x, HasFoo("blah")); +``` + +### Casting Matchers {#SafeMatcherCast} + +gMock matchers are statically typed, meaning that the compiler can catch your +mistake if you use a matcher of the wrong type (for example, if you use `Eq(5)` +to match a `string` argument). Good for you! + +Sometimes, however, you know what you're doing and want the compiler to give you +some slack. One example is that you have a matcher for `long` and the argument +you want to match is `int`. While the two types aren't exactly the same, there +is nothing really wrong with using a `Matcher` to match an `int` - after +all, we can first convert the `int` argument to a `long` losslessly before +giving it to the matcher. + +To support this need, gMock gives you the `SafeMatcherCast(m)` function. It +casts a matcher `m` to type `Matcher`. To ensure safety, gMock checks that +(let `U` be the type `m` accepts : + +1. Type `T` can be *implicitly* cast to type `U`; +2. When both `T` and `U` are built-in arithmetic types (`bool`, integers, and + floating-point numbers), the conversion from `T` to `U` is not lossy (in + other words, any value representable by `T` can also be represented by `U`); + and +3. When `U` is a reference, `T` must also be a reference (as the underlying + matcher may be interested in the address of the `U` value). + +The code won't compile if any of these conditions isn't met. + +Here's one example: + +```cpp +using ::testing::SafeMatcherCast; + +// A base class and a child class. +class Base { ... }; +class Derived : public Base { ... }; + +class MockFoo : public Foo { + public: + MOCK_METHOD(void, DoThis, (Derived* derived), (override)); +}; + +... + MockFoo foo; + // m is a Matcher we got from somewhere. + EXPECT_CALL(foo, DoThis(SafeMatcherCast(m))); +``` + +If you find `SafeMatcherCast(m)` too limiting, you can use a similar function +`MatcherCast(m)`. The difference is that `MatcherCast` works as long as you +can `static_cast` type `T` to type `U`. + +`MatcherCast` essentially lets you bypass C++'s type system (`static_cast` isn't +always safe as it could throw away information, for example), so be careful not +to misuse/abuse it. + +### Selecting Between Overloaded Functions {#SelectOverload} + +If you expect an overloaded function to be called, the compiler may need some +help on which overloaded version it is. + +To disambiguate functions overloaded on the const-ness of this object, use the +`Const()` argument wrapper. + +```cpp +using ::testing::ReturnRef; + +class MockFoo : public Foo { + ... + MOCK_METHOD(Bar&, GetBar, (), (override)); + MOCK_METHOD(const Bar&, GetBar, (), (const, override)); +}; + +... + MockFoo foo; + Bar bar1, bar2; + EXPECT_CALL(foo, GetBar()) // The non-const GetBar(). + .WillOnce(ReturnRef(bar1)); + EXPECT_CALL(Const(foo), GetBar()) // The const GetBar(). + .WillOnce(ReturnRef(bar2)); +``` + +(`Const()` is defined by gMock and returns a `const` reference to its argument.) + +To disambiguate overloaded functions with the same number of arguments but +different argument types, you may need to specify the exact type of a matcher, +either by wrapping your matcher in `Matcher()`, or using a matcher whose +type is fixed (`TypedEq`, `An()`, etc): + +```cpp +using ::testing::An; +using ::testing::Matcher; +using ::testing::TypedEq; + +class MockPrinter : public Printer { + public: + MOCK_METHOD(void, Print, (int n), (override)); + MOCK_METHOD(void, Print, (char c), (override)); +}; + +TEST(PrinterTest, Print) { + MockPrinter printer; + + EXPECT_CALL(printer, Print(An())); // void Print(int); + EXPECT_CALL(printer, Print(Matcher(Lt(5)))); // void Print(int); + EXPECT_CALL(printer, Print(TypedEq('a'))); // void Print(char); + + printer.Print(3); + printer.Print(6); + printer.Print('a'); +} +``` + +### Performing Different Actions Based on the Arguments + +When a mock method is called, the *last* matching expectation that's still +active will be selected (think "newer overrides older"). So, you can make a +method do different things depending on its argument values like this: + +```cpp +using ::testing::_; +using ::testing::Lt; +using ::testing::Return; +... + // The default case. + EXPECT_CALL(foo, DoThis(_)) + .WillRepeatedly(Return('b')); + // The more specific case. + EXPECT_CALL(foo, DoThis(Lt(5))) + .WillRepeatedly(Return('a')); +``` + +Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will be +returned; otherwise `'b'` will be returned. + +### Matching Multiple Arguments as a Whole + +Sometimes it's not enough to match the arguments individually. For example, we +may want to say that the first argument must be less than the second argument. +The `With()` clause allows us to match all arguments of a mock function as a +whole. For example, + +```cpp +using ::testing::_; +using ::testing::Ne; +using ::testing::Lt; +... + EXPECT_CALL(foo, InRange(Ne(0), _)) + .With(Lt()); +``` + +says that the first argument of `InRange()` must not be 0, and must be less than +the second argument. + +The expression inside `With()` must be a matcher of type `Matcher>`, where `A1`, ..., `An` are the types of the function arguments. + +You can also write `AllArgs(m)` instead of `m` inside `.With()`. The two forms +are equivalent, but `.With(AllArgs(Lt()))` is more readable than `.With(Lt())`. + +You can use `Args(m)` to match the `n` selected arguments (as a +tuple) against `m`. For example, + +```cpp +using ::testing::_; +using ::testing::AllOf; +using ::testing::Args; +using ::testing::Lt; +... + EXPECT_CALL(foo, Blah) + .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt()))); +``` + +says that `Blah` will be called with arguments `x`, `y`, and `z` where `x < y < +z`. Note that in this example, it wasn't necessary specify the positional +matchers. + +As a convenience and example, gMock provides some matchers for 2-tuples, +including the `Lt()` matcher above. See [here](#MultiArgMatchers) for the +complete list. + +Note that if you want to pass the arguments to a predicate of your own (e.g. +`.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be written to +take a `std::tuple` as its argument; gMock will pass the `n` selected arguments +as *one* single tuple to the predicate. + +### Using Matchers as Predicates + +Have you noticed that a matcher is just a fancy predicate that also knows how to +describe itself? Many existing algorithms take predicates as arguments (e.g. +those defined in STL's `` header), and it would be a shame if gMock +matchers were not allowed to participate. + +Luckily, you can use a matcher where a unary predicate functor is expected by +wrapping it inside the `Matches()` function. For example, + +```cpp +#include +#include + +using ::testing::Matches; +using ::testing::Ge; + +vector v; +... +// How many elements in v are >= 10? +const int count = count_if(v.begin(), v.end(), Matches(Ge(10))); +``` + +Since you can build complex matchers from simpler ones easily using gMock, this +gives you a way to conveniently construct composite predicates (doing the same +using STL's `` header is just painful). For example, here's a +predicate that's satisfied by any number that is >= 0, <= 100, and != 50: + +```cpp +using testing::AllOf; +using testing::Ge; +using testing::Le; +using testing::Matches; +using testing::Ne; +... +Matches(AllOf(Ge(0), Le(100), Ne(50))) +``` + +### Using Matchers in googletest Assertions + +Since matchers are basically predicates that also know how to describe +themselves, there is a way to take advantage of them in googletest assertions. +It's called `ASSERT_THAT` and `EXPECT_THAT`: + +```cpp + ASSERT_THAT(value, matcher); // Asserts that value matches matcher. + EXPECT_THAT(value, matcher); // The non-fatal version. +``` + +For example, in a googletest test you can write: + +```cpp +#include "gmock/gmock.h" + +using ::testing::AllOf; +using ::testing::Ge; +using ::testing::Le; +using ::testing::MatchesRegex; +using ::testing::StartsWith; + +... + EXPECT_THAT(Foo(), StartsWith("Hello")); + EXPECT_THAT(Bar(), MatchesRegex("Line \\d+")); + ASSERT_THAT(Baz(), AllOf(Ge(5), Le(10))); +``` + +which (as you can probably guess) executes `Foo()`, `Bar()`, and `Baz()`, and +verifies that: + +* `Foo()` returns a string that starts with `"Hello"`. +* `Bar()` returns a string that matches regular expression `"Line \\d+"`. +* `Baz()` returns a number in the range [5, 10]. + +The nice thing about these macros is that *they read like English*. They +generate informative messages too. For example, if the first `EXPECT_THAT()` +above fails, the message will be something like: + +```cpp +Value of: Foo() + Actual: "Hi, world!" +Expected: starts with "Hello" +``` + +**Credit:** The idea of `(ASSERT|EXPECT)_THAT` was borrowed from Joe Walnes' +Hamcrest project, which adds `assertThat()` to JUnit. + +### Using Predicates as Matchers + +gMock provides a [built-in set](gmock_cheat_sheet.md#MatcherList) of matchers. +In case you find them lacking, you can use an arbitrary unary predicate function +or functor as a matcher - as long as the predicate accepts a value of the type +you want. You do this by wrapping the predicate inside the `Truly()` function, +for example: + +```cpp +using ::testing::Truly; + +int IsEven(int n) { return (n % 2) == 0 ? 1 : 0; } +... + // Bar() must be called with an even number. + EXPECT_CALL(foo, Bar(Truly(IsEven))); +``` + +Note that the predicate function / functor doesn't have to return `bool`. It +works as long as the return value can be used as the condition in in statement +`if (condition) ...`. + + + +### Matching Arguments that Are Not Copyable + +When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of +`bar`. When `Foo()` is called later, gMock compares the argument to `Foo()` with +the saved copy of `bar`. This way, you don't need to worry about `bar` being +modified or destroyed after the `EXPECT_CALL()` is executed. The same is true +when you use matchers like `Eq(bar)`, `Le(bar)`, and so on. + +But what if `bar` cannot be copied (i.e. has no copy constructor)? You could +define your own matcher function or callback and use it with `Truly()`, as the +previous couple of recipes have shown. Or, you may be able to get away from it +if you can guarantee that `bar` won't be changed after the `EXPECT_CALL()` is +executed. Just tell gMock that it should save a reference to `bar`, instead of a +copy of it. Here's how: + +```cpp +using ::testing::Eq; +using ::testing::Lt; +... + // Expects that Foo()'s argument == bar. + EXPECT_CALL(mock_obj, Foo(Eq(std::ref(bar)))); + + // Expects that Foo()'s argument < bar. + EXPECT_CALL(mock_obj, Foo(Lt(std::ref(bar)))); +``` + +Remember: if you do this, don't change `bar` after the `EXPECT_CALL()`, or the +result is undefined. + +### Validating a Member of an Object + +Often a mock function takes a reference to object as an argument. When matching +the argument, you may not want to compare the entire object against a fixed +object, as that may be over-specification. Instead, you may need to validate a +certain member variable or the result of a certain getter method of the object. +You can do this with `Field()` and `Property()`. More specifically, + +```cpp +Field(&Foo::bar, m) +``` + +is a matcher that matches a `Foo` object whose `bar` member variable satisfies +matcher `m`. + +```cpp +Property(&Foo::baz, m) +``` + +is a matcher that matches a `Foo` object whose `baz()` method returns a value +that satisfies matcher `m`. + +For example: + + +| Expression | Description | +| :--------------------------- | :--------------------------------------- | +| `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. | +| `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. | + + +Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument +and be declared as `const`. + +BTW, `Field()` and `Property()` can also match plain pointers to objects. For +instance, + +```cpp +using ::testing::Field; +using ::testing::Ge; +... +Field(&Foo::number, Ge(3)) +``` + +matches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`, the match +will always fail regardless of the inner matcher. + +What if you want to validate more than one members at the same time? Remember +that there are [`AllOf()` and `AllOfArray()`](#CombiningMatchers). + +Finally `Field()` and `Property()` provide overloads that take the field or +property names as the first argument to include it in the error message. This +can be useful when creating combined matchers. + +```cpp +using ::testing::AllOf; +using ::testing::Field; +using ::testing::Matcher; +using ::testing::SafeMatcherCast; + +Matcher IsFoo(const Foo& foo) { + return AllOf(Field("some_field", &Foo::some_field, foo.some_field), + Field("other_field", &Foo::other_field, foo.other_field), + Field("last_field", &Foo::last_field, foo.last_field)); +} +``` + +### Validating the Value Pointed to by a Pointer Argument + +C++ functions often take pointers as arguments. You can use matchers like +`IsNull()`, `NotNull()`, and other comparison matchers to match a pointer, but +what if you want to make sure the value *pointed to* by the pointer, instead of +the pointer itself, has a certain property? Well, you can use the `Pointee(m)` +matcher. + +`Pointee(m)` matches a pointer if and only if `m` matches the value the pointer +points to. For example: + +```cpp +using ::testing::Ge; +using ::testing::Pointee; +... + EXPECT_CALL(foo, Bar(Pointee(Ge(3)))); +``` + +expects `foo.Bar()` to be called with a pointer that points to a value greater +than or equal to 3. + +One nice thing about `Pointee()` is that it treats a `NULL` pointer as a match +failure, so you can write `Pointee(m)` instead of + +```cpp +using ::testing::AllOf; +using ::testing::NotNull; +using ::testing::Pointee; +... + AllOf(NotNull(), Pointee(m)) +``` + +without worrying that a `NULL` pointer will crash your test. + +Also, did we tell you that `Pointee()` works with both raw pointers **and** +smart pointers (`std::unique_ptr`, `std::shared_ptr`, etc)? + +What if you have a pointer to pointer? You guessed it - you can use nested +`Pointee()` to probe deeper inside the value. For example, +`Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer that points +to a number less than 3 (what a mouthful...). + +### Testing a Certain Property of an Object + +Sometimes you want to specify that an object argument has a certain property, +but there is no existing matcher that does this. If you want good error +messages, you should [define a matcher](#NewMatchers). If you want to do it +quick and dirty, you could get away with writing an ordinary function. + +Let's say you have a mock function that takes an object of type `Foo`, which has +an `int bar()` method and an `int baz()` method, and you want to constrain that +the argument's `bar()` value plus its `baz()` value is a given number. Here's +how you can define a matcher to do it: + +```cpp +using ::testing::Matcher; +using ::testing::MatcherInterface; +using ::testing::MatchResultListener; + +class BarPlusBazEqMatcher : public MatcherInterface { + public: + explicit BarPlusBazEqMatcher(int expected_sum) + : expected_sum_(expected_sum) {} + + bool MatchAndExplain(const Foo& foo, + MatchResultListener* /* listener */) const override { + return (foo.bar() + foo.baz()) == expected_sum_; + } + + void DescribeTo(std::ostream* os) const override { + *os << "bar() + baz() equals " << expected_sum_; + } + + void DescribeNegationTo(std::ostream* os) const override { + *os << "bar() + baz() does not equal " << expected_sum_; + } + private: + const int expected_sum_; +}; + +Matcher BarPlusBazEq(int expected_sum) { + return MakeMatcher(new BarPlusBazEqMatcher(expected_sum)); +} + +... + EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...; +``` + +### Matching Containers + +Sometimes an STL container (e.g. list, vector, map, ...) is passed to a mock +function and you may want to validate it. Since most STL containers support the +`==` operator, you can write `Eq(expected_container)` or simply +`expected_container` to match a container exactly. + +Sometimes, though, you may want to be more flexible (for example, the first +element must be an exact match, but the second element can be any positive +number, and so on). Also, containers used in tests often have a small number of +elements, and having to define the expected container out-of-line is a bit of a +hassle. + +You can use the `ElementsAre()` or `UnorderedElementsAre()` matcher in such +cases: + +```cpp +using ::testing::_; +using ::testing::ElementsAre; +using ::testing::Gt; +... + MOCK_METHOD(void, Foo, (const vector& numbers), (override)); +... + EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5))); +``` + +The above matcher says that the container must have 4 elements, which must be 1, +greater than 0, anything, and 5 respectively. + +If you instead write: + +```cpp +using ::testing::_; +using ::testing::Gt; +using ::testing::UnorderedElementsAre; +... + MOCK_METHOD(void, Foo, (const vector& numbers), (override)); +... + EXPECT_CALL(mock, Foo(UnorderedElementsAre(1, Gt(0), _, 5))); +``` + +It means that the container must have 4 elements, which (under some permutation) +must be 1, greater than 0, anything, and 5 respectively. + +As an alternative you can place the arguments in a C-style array and use +`ElementsAreArray()` or `UnorderedElementsAreArray()` instead: + +```cpp +using ::testing::ElementsAreArray; +... + // ElementsAreArray accepts an array of element values. + const int expected_vector1[] = {1, 5, 2, 4, ...}; + EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1))); + + // Or, an array of element matchers. + Matcher expected_vector2[] = {1, Gt(2), _, 3, ...}; + EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2))); +``` + +In case the array needs to be dynamically created (and therefore the array size +cannot be inferred by the compiler), you can give `ElementsAreArray()` an +additional argument to specify the array size: + +```cpp +using ::testing::ElementsAreArray; +... + int* const expected_vector3 = new int[count]; + ... fill expected_vector3 with values ... + EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count))); +``` + +Use `Pair` when comparing maps or other associative containers. + +```cpp +using testing::ElementsAre; +using testing::Pair; +... + std::map m = {{"a", 1}, {"b", 2}, {"c", 3}}; + EXPECT_THAT(m, ElementsAre(Pair("a", 1), Pair("b", 2), Pair("c", 3))); +``` + +**Tips:** + +* `ElementsAre*()` can be used to match *any* container that implements the + STL iterator pattern (i.e. it has a `const_iterator` type and supports + `begin()/end()`), not just the ones defined in STL. It will even work with + container types yet to be written - as long as they follows the above + pattern. +* You can use nested `ElementsAre*()` to match nested (multi-dimensional) + containers. +* If the container is passed by pointer instead of by reference, just write + `Pointee(ElementsAre*(...))`. +* The order of elements *matters* for `ElementsAre*()`. If you are using it + with containers whose element order are undefined (e.g. `hash_map`) you + should use `WhenSorted` around `ElementsAre`. + +### Sharing Matchers + +Under the hood, a gMock matcher object consists of a pointer to a ref-counted +implementation object. Copying matchers is allowed and very efficient, as only +the pointer is copied. When the last matcher that references the implementation +object dies, the implementation object will be deleted. + +Therefore, if you have some complex matcher that you want to use again and +again, there is no need to build it everytime. Just assign it to a matcher +variable and use that variable repeatedly! For example, + +```cpp +using ::testing::AllOf; +using ::testing::Gt; +using ::testing::Le; +using ::testing::Matcher; +... + Matcher in_range = AllOf(Gt(5), Le(10)); + ... use in_range as a matcher in multiple EXPECT_CALLs ... +``` + +### Matchers must have no side-effects {#PureMatchers} + +WARNING: gMock does not guarantee when or how many times a matcher will be +invoked. Therefore, all matchers must be *purely functional*: they cannot have +any side effects, and the match result must not depend on anything other than +the matcher's parameters and the value being matched. + +This requirement must be satisfied no matter how a matcher is defined (e.g., if +it is one of the standard matchers, or a custom matcher). In particular, a +matcher can never call a mock function, as that will affect the state of the +mock object and gMock. + +## Setting Expectations + +### Knowing When to Expect {#UseOnCall} + + + +**`ON_CALL`** is likely the *single most under-utilized construct* in gMock. + +There are basically two constructs for defining the behavior of a mock object: +`ON_CALL` and `EXPECT_CALL`. The difference? `ON_CALL` defines what happens when +a mock method is called, but doesn't imply any expectation on the method +being called. `EXPECT_CALL` not only defines the behavior, but also sets an +expectation that the method will be called with the given arguments, for the +given number of times (and *in the given order* when you specify the order +too). + +Since `EXPECT_CALL` does more, isn't it better than `ON_CALL`? Not really. Every +`EXPECT_CALL` adds a constraint on the behavior of the code under test. Having +more constraints than necessary is *baaad* - even worse than not having enough +constraints. + +This may be counter-intuitive. How could tests that verify more be worse than +tests that verify less? Isn't verification the whole point of tests? + +The answer lies in *what* a test should verify. **A good test verifies the +contract of the code.** If a test over-specifies, it doesn't leave enough +freedom to the implementation. As a result, changing the implementation without +breaking the contract (e.g. refactoring and optimization), which should be +perfectly fine to do, can break such tests. Then you have to spend time fixing +them, only to see them broken again the next time the implementation is changed. + +Keep in mind that one doesn't have to verify more than one property in one test. +In fact, **it's a good style to verify only one thing in one test.** If you do +that, a bug will likely break only one or two tests instead of dozens (which +case would you rather debug?). If you are also in the habit of giving tests +descriptive names that tell what they verify, you can often easily guess what's +wrong just from the test log itself. + +So use `ON_CALL` by default, and only use `EXPECT_CALL` when you actually intend +to verify that the call is made. For example, you may have a bunch of `ON_CALL`s +in your test fixture to set the common mock behavior shared by all tests in the +same group, and write (scarcely) different `EXPECT_CALL`s in different `TEST_F`s +to verify different aspects of the code's behavior. Compared with the style +where each `TEST` has many `EXPECT_CALL`s, this leads to tests that are more +resilient to implementational changes (and thus less likely to require +maintenance) and makes the intent of the tests more obvious (so they are easier +to maintain when you do need to maintain them). + +If you are bothered by the "Uninteresting mock function call" message printed +when a mock method without an `EXPECT_CALL` is called, you may use a `NiceMock` +instead to suppress all such messages for the mock object, or suppress the +message for specific methods by adding `EXPECT_CALL(...).Times(AnyNumber())`. DO +NOT suppress it by blindly adding an `EXPECT_CALL(...)`, or you'll have a test +that's a pain to maintain. + +### Ignoring Uninteresting Calls + +If you are not interested in how a mock method is called, just don't say +anything about it. In this case, if the method is ever called, gMock will +perform its default action to allow the test program to continue. If you are not +happy with the default action taken by gMock, you can override it using +`DefaultValue::Set()` (described [here](#DefaultValue)) or `ON_CALL()`. + +Please note that once you expressed interest in a particular mock method (via +`EXPECT_CALL()`), all invocations to it must match some expectation. If this +function is called but the arguments don't match any `EXPECT_CALL()` statement, +it will be an error. + +### Disallowing Unexpected Calls + +If a mock method shouldn't be called at all, explicitly say so: + +```cpp +using ::testing::_; +... + EXPECT_CALL(foo, Bar(_)) + .Times(0); +``` + +If some calls to the method are allowed, but the rest are not, just list all the +expected calls: + +```cpp +using ::testing::AnyNumber; +using ::testing::Gt; +... + EXPECT_CALL(foo, Bar(5)); + EXPECT_CALL(foo, Bar(Gt(10))) + .Times(AnyNumber()); +``` + +A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` statements +will be an error. + +### Understanding Uninteresting vs Unexpected Calls {#uninteresting-vs-unexpected} + +*Uninteresting* calls and *unexpected* calls are different concepts in gMock. +*Very* different. + +A call `x.Y(...)` is **uninteresting** if there's *not even a single* +`EXPECT_CALL(x, Y(...))` set. In other words, the test isn't interested in the +`x.Y()` method at all, as evident in that the test doesn't care to say anything +about it. + +A call `x.Y(...)` is **unexpected** if there are *some* `EXPECT_CALL(x, +Y(...))`s set, but none of them matches the call. Put another way, the test is +interested in the `x.Y()` method (therefore it explicitly sets some +`EXPECT_CALL` to verify how it's called); however, the verification fails as the +test doesn't expect this particular call to happen. + +**An unexpected call is always an error,** as the code under test doesn't behave +the way the test expects it to behave. + +**By default, an uninteresting call is not an error,** as it violates no +constraint specified by the test. (gMock's philosophy is that saying nothing +means there is no constraint.) However, it leads to a warning, as it *might* +indicate a problem (e.g. the test author might have forgotten to specify a +constraint). + +In gMock, `NiceMock` and `StrictMock` can be used to make a mock class "nice" or +"strict". How does this affect uninteresting calls and unexpected calls? + +A **nice mock** suppresses uninteresting call *warnings*. It is less chatty than +the default mock, but otherwise is the same. If a test fails with a default +mock, it will also fail using a nice mock instead. And vice versa. Don't expect +making a mock nice to change the test's result. + +A **strict mock** turns uninteresting call warnings into errors. So making a +mock strict may change the test's result. + +Let's look at an example: + +```cpp +TEST(...) { + NiceMock mock_registry; + EXPECT_CALL(mock_registry, GetDomainOwner("google.com")) + .WillRepeatedly(Return("Larry Page")); + + // Use mock_registry in code under test. + ... &mock_registry ... +} +``` + +The sole `EXPECT_CALL` here says that all calls to `GetDomainOwner()` must have +`"google.com"` as the argument. If `GetDomainOwner("yahoo.com")` is called, it +will be an unexpected call, and thus an error. *Having a nice mock doesn't +change the severity of an unexpected call.* + +So how do we tell gMock that `GetDomainOwner()` can be called with some other +arguments as well? The standard technique is to add a "catch all" `EXPECT_CALL`: + +```cpp + EXPECT_CALL(mock_registry, GetDomainOwner(_)) + .Times(AnyNumber()); // catches all other calls to this method. + EXPECT_CALL(mock_registry, GetDomainOwner("google.com")) + .WillRepeatedly(Return("Larry Page")); +``` + +Remember that `_` is the wildcard matcher that matches anything. With this, if +`GetDomainOwner("google.com")` is called, it will do what the second +`EXPECT_CALL` says; if it is called with a different argument, it will do what +the first `EXPECT_CALL` says. + +Note that the order of the two `EXPECT_CALL`s is important, as a newer +`EXPECT_CALL` takes precedence over an older one. + +For more on uninteresting calls, nice mocks, and strict mocks, read +["The Nice, the Strict, and the Naggy"](#NiceStrictNaggy). + +### Ignoring Uninteresting Arguments {#ParameterlessExpectations} + +If your test doesn't care about the parameters (it only cares about the number +or order of calls), you can often simply omit the parameter list: + +```cpp + // Expect foo.Bar( ... ) twice with any arguments. + EXPECT_CALL(foo, Bar).Times(2); + + // Delegate to the given method whenever the factory is invoked. + ON_CALL(foo_factory, MakeFoo) + .WillByDefault(&BuildFooForTest); +``` + +This functionality is only available when a method is not overloaded; to prevent +unexpected behavior it is a compilation error to try to set an expectation on a +method where the specific overload is ambiguous. You can work around this by +supplying a [simpler mock interface](#SimplerInterfaces) than the mocked class +provides. + +This pattern is also useful when the arguments are interesting, but match logic +is substantially complex. You can leave the argument list unspecified and use +SaveArg actions to [save the values for later verification](#SaveArgVerify). If +you do that, you can easily differentiate calling the method the wrong number of +times from calling it with the wrong arguments. + +### Expecting Ordered Calls {#OrderedCalls} + +Although an `EXPECT_CALL()` statement defined later takes precedence when gMock +tries to match a function call with an expectation, by default calls don't have +to happen in the order `EXPECT_CALL()` statements are written. For example, if +the arguments match the matchers in the second `EXPECT_CALL()`, but not those in +the first and third, then the second expectation will be used. + +If you would rather have all calls occur in the order of the expectations, put +the `EXPECT_CALL()` statements in a block where you define a variable of type +`InSequence`: + +```cpp +using ::testing::_; +using ::testing::InSequence; + + { + InSequence s; + + EXPECT_CALL(foo, DoThis(5)); + EXPECT_CALL(bar, DoThat(_)) + .Times(2); + EXPECT_CALL(foo, DoThis(6)); + } +``` + +In this example, we expect a call to `foo.DoThis(5)`, followed by two calls to +`bar.DoThat()` where the argument can be anything, which are in turn followed by +a call to `foo.DoThis(6)`. If a call occurred out-of-order, gMock will report an +error. + +### Expecting Partially Ordered Calls {#PartialOrder} + +Sometimes requiring everything to occur in a predetermined order can lead to +brittle tests. For example, we may care about `A` occurring before both `B` and +`C`, but aren't interested in the relative order of `B` and `C`. In this case, +the test should reflect our real intent, instead of being overly constraining. + +gMock allows you to impose an arbitrary DAG (directed acyclic graph) on the +calls. One way to express the DAG is to use the +[After](gmock_cheat_sheet.md#AfterClause) clause of `EXPECT_CALL`. + +Another way is via the `InSequence()` clause (not the same as the `InSequence` +class), which we borrowed from jMock 2. It's less flexible than `After()`, but +more convenient when you have long chains of sequential calls, as it doesn't +require you to come up with different names for the expectations in the chains. +Here's how it works: + +If we view `EXPECT_CALL()` statements as nodes in a graph, and add an edge from +node A to node B wherever A must occur before B, we can get a DAG. We use the +term "sequence" to mean a directed path in this DAG. Now, if we decompose the +DAG into sequences, we just need to know which sequences each `EXPECT_CALL()` +belongs to in order to be able to reconstruct the original DAG. + +So, to specify the partial order on the expectations we need to do two things: +first to define some `Sequence` objects, and then for each `EXPECT_CALL()` say +which `Sequence` objects it is part of. + +Expectations in the same sequence must occur in the order they are written. For +example, + +```cpp +using ::testing::Sequence; +... + Sequence s1, s2; + + EXPECT_CALL(foo, A()) + .InSequence(s1, s2); + EXPECT_CALL(bar, B()) + .InSequence(s1); + EXPECT_CALL(bar, C()) + .InSequence(s2); + EXPECT_CALL(foo, D()) + .InSequence(s2); +``` + +specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> C -> D`): + +```text + +---> B + | + A ---| + | + +---> C ---> D +``` + +This means that A must occur before B and C, and C must occur before D. There's +no restriction about the order other than these. + +### Controlling When an Expectation Retires + +When a mock method is called, gMock only considers expectations that are still +active. An expectation is active when created, and becomes inactive (aka +*retires*) when a call that has to occur later has occurred. For example, in + +```cpp +using ::testing::_; +using ::testing::Sequence; +... + Sequence s1, s2; + + EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1 + .Times(AnyNumber()) + .InSequence(s1, s2); + EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2 + .InSequence(s1); + EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3 + .InSequence(s2); +``` + +as soon as either #2 or #3 is matched, #1 will retire. If a warning `"File too +large."` is logged after this, it will be an error. + +Note that an expectation doesn't retire automatically when it's saturated. For +example, + +```cpp +using ::testing::_; +... + EXPECT_CALL(log, Log(WARNING, _, _)); // #1 + EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2 +``` + +says that there will be exactly one warning with the message `"File too +large."`. If the second warning contains this message too, #2 will match again +and result in an upper-bound-violated error. + +If this is not what you want, you can ask an expectation to retire as soon as it +becomes saturated: + +```cpp +using ::testing::_; +... + EXPECT_CALL(log, Log(WARNING, _, _)); // #1 + EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2 + .RetiresOnSaturation(); +``` + +Here #2 can be used only once, so if you have two warnings with the message +`"File too large."`, the first will match #2 and the second will match #1 - +there will be no error. + +## Using Actions + +### Returning References from Mock Methods + +If a mock function's return type is a reference, you need to use `ReturnRef()` +instead of `Return()` to return a result: + +```cpp +using ::testing::ReturnRef; + +class MockFoo : public Foo { + public: + MOCK_METHOD(Bar&, GetBar, (), (override)); +}; +... + MockFoo foo; + Bar bar; + EXPECT_CALL(foo, GetBar()) + .WillOnce(ReturnRef(bar)); +... +``` + +### Returning Live Values from Mock Methods + +The `Return(x)` action saves a copy of `x` when the action is created, and +always returns the same value whenever it's executed. Sometimes you may want to +instead return the *live* value of `x` (i.e. its value at the time when the +action is *executed*.). Use either `ReturnRef()` or `ReturnPointee()` for this +purpose. + +If the mock function's return type is a reference, you can do it using +`ReturnRef(x)`, as shown in the previous recipe ("Returning References from Mock +Methods"). However, gMock doesn't let you use `ReturnRef()` in a mock function +whose return type is not a reference, as doing that usually indicates a user +error. So, what shall you do? + +Though you may be tempted, DO NOT use `std::ref()`: + +```cpp +using testing::Return; + +class MockFoo : public Foo { + public: + MOCK_METHOD(int, GetValue, (), (override)); +}; +... + int x = 0; + MockFoo foo; + EXPECT_CALL(foo, GetValue()) + .WillRepeatedly(Return(std::ref(x))); // Wrong! + x = 42; + EXPECT_EQ(42, foo.GetValue()); +``` + +Unfortunately, it doesn't work here. The above code will fail with error: + +```text +Value of: foo.GetValue() + Actual: 0 +Expected: 42 +``` + +The reason is that `Return(*value*)` converts `value` to the actual return type +of the mock function at the time when the action is *created*, not when it is +*executed*. (This behavior was chosen for the action to be safe when `value` is +a proxy object that references some temporary objects.) As a result, +`std::ref(x)` is converted to an `int` value (instead of a `const int&`) when +the expectation is set, and `Return(std::ref(x))` will always return 0. + +`ReturnPointee(pointer)` was provided to solve this problem specifically. It +returns the value pointed to by `pointer` at the time the action is *executed*: + +```cpp +using testing::ReturnPointee; +... + int x = 0; + MockFoo foo; + EXPECT_CALL(foo, GetValue()) + .WillRepeatedly(ReturnPointee(&x)); // Note the & here. + x = 42; + EXPECT_EQ(42, foo.GetValue()); // This will succeed now. +``` + +### Combining Actions + +Want to do more than one thing when a function is called? That's fine. `DoAll()` +allow you to do sequence of actions every time. Only the return value of the +last action in the sequence will be used. + +```cpp +using ::testing::_; +using ::testing::DoAll; + +class MockFoo : public Foo { + public: + MOCK_METHOD(bool, Bar, (int n), (override)); +}; +... + EXPECT_CALL(foo, Bar(_)) + .WillOnce(DoAll(action_1, + action_2, + ... + action_n)); +``` + +### Verifying Complex Arguments {#SaveArgVerify} + +If you want to verify that a method is called with a particular argument but the +match criteria is complex, it can be difficult to distinguish between +cardinality failures (calling the method the wrong number of times) and argument +match failures. Similarly, if you are matching multiple parameters, it may not +be easy to distinguishing which argument failed to match. For example: + +```cpp + // Not ideal: this could fail because of a problem with arg1 or arg2, or maybe + // just the method wasn't called. + EXPECT_CALL(foo, SendValues(_, ElementsAre(1, 4, 4, 7), EqualsProto( ... ))); +``` + +You can instead save the arguments and test them individually: + +```cpp + EXPECT_CALL(foo, SendValues) + .WillOnce(DoAll(SaveArg<1>(&actual_array), SaveArg<2>(&actual_proto))); + ... run the test + EXPECT_THAT(actual_array, ElementsAre(1, 4, 4, 7)); + EXPECT_THAT(actual_proto, EqualsProto( ... )); +``` + +### Mocking Side Effects {#MockingSideEffects} + +Sometimes a method exhibits its effect not via returning a value but via side +effects. For example, it may change some global state or modify an output +argument. To mock side effects, in general you can define your own action by +implementing `::testing::ActionInterface`. + +If all you need to do is to change an output argument, the built-in +`SetArgPointee()` action is convenient: + +```cpp +using ::testing::_; +using ::testing::SetArgPointee; + +class MockMutator : public Mutator { + public: + MOCK_METHOD(void, Mutate, (bool mutate, int* value), (override)); + ... +} +... + MockMutator mutator; + EXPECT_CALL(mutator, Mutate(true, _)) + .WillOnce(SetArgPointee<1>(5)); +``` + +In this example, when `mutator.Mutate()` is called, we will assign 5 to the +`int` variable pointed to by argument #1 (0-based). + +`SetArgPointee()` conveniently makes an internal copy of the value you pass to +it, removing the need to keep the value in scope and alive. The implication +however is that the value must have a copy constructor and assignment operator. + +If the mock method also needs to return a value as well, you can chain +`SetArgPointee()` with `Return()` using `DoAll()`, remembering to put the +`Return()` statement last: + +```cpp +using ::testing::_; +using ::testing::Return; +using ::testing::SetArgPointee; + +class MockMutator : public Mutator { + public: + ... + MOCK_METHOD(bool, MutateInt, (int* value), (override)); +} +... + MockMutator mutator; + EXPECT_CALL(mutator, MutateInt(_)) + .WillOnce(DoAll(SetArgPointee<0>(5), + Return(true))); +``` + +Note, however, that if you use the `ReturnOKWith()` method, it will override the +values provided by `SetArgPointee()` in the response parameters of your function +call. + +If the output argument is an array, use the `SetArrayArgument(first, last)` +action instead. It copies the elements in source range `[first, last)` to the +array pointed to by the `N`-th (0-based) argument: + +```cpp +using ::testing::NotNull; +using ::testing::SetArrayArgument; + +class MockArrayMutator : public ArrayMutator { + public: + MOCK_METHOD(void, Mutate, (int* values, int num_values), (override)); + ... +} +... + MockArrayMutator mutator; + int values[5] = {1, 2, 3, 4, 5}; + EXPECT_CALL(mutator, Mutate(NotNull(), 5)) + .WillOnce(SetArrayArgument<0>(values, values + 5)); +``` + +This also works when the argument is an output iterator: + +```cpp +using ::testing::_; +using ::testing::SetArrayArgument; + +class MockRolodex : public Rolodex { + public: + MOCK_METHOD(void, GetNames, (std::back_insert_iterator>), + (override)); + ... +} +... + MockRolodex rolodex; + vector names; + names.push_back("George"); + names.push_back("John"); + names.push_back("Thomas"); + EXPECT_CALL(rolodex, GetNames(_)) + .WillOnce(SetArrayArgument<0>(names.begin(), names.end())); +``` + +### Changing a Mock Object's Behavior Based on the State + +If you expect a call to change the behavior of a mock object, you can use +`::testing::InSequence` to specify different behaviors before and after the +call: + +```cpp +using ::testing::InSequence; +using ::testing::Return; + +... + { + InSequence seq; + EXPECT_CALL(my_mock, IsDirty()) + .WillRepeatedly(Return(true)); + EXPECT_CALL(my_mock, Flush()); + EXPECT_CALL(my_mock, IsDirty()) + .WillRepeatedly(Return(false)); + } + my_mock.FlushIfDirty(); +``` + +This makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called +and return `false` afterwards. + +If the behavior change is more complex, you can store the effects in a variable +and make a mock method get its return value from that variable: + +```cpp +using ::testing::_; +using ::testing::SaveArg; +using ::testing::Return; + +ACTION_P(ReturnPointee, p) { return *p; } +... + int previous_value = 0; + EXPECT_CALL(my_mock, GetPrevValue) + .WillRepeatedly(ReturnPointee(&previous_value)); + EXPECT_CALL(my_mock, UpdateValue) + .WillRepeatedly(SaveArg<0>(&previous_value)); + my_mock.DoSomethingToUpdateValue(); +``` + +Here `my_mock.GetPrevValue()` will always return the argument of the last +`UpdateValue()` call. + +### Setting the Default Value for a Return Type {#DefaultValue} + +If a mock method's return type is a built-in C++ type or pointer, by default it +will return 0 when invoked. Also, in C++ 11 and above, a mock method whose +return type has a default constructor will return a default-constructed value by +default. You only need to specify an action if this default value doesn't work +for you. + +Sometimes, you may want to change this default value, or you may want to specify +a default value for types gMock doesn't know about. You can do this using the +`::testing::DefaultValue` class template: + +```cpp +using ::testing::DefaultValue; + +class MockFoo : public Foo { + public: + MOCK_METHOD(Bar, CalculateBar, (), (override)); +}; + + +... + Bar default_bar; + // Sets the default return value for type Bar. + DefaultValue::Set(default_bar); + + MockFoo foo; + + // We don't need to specify an action here, as the default + // return value works for us. + EXPECT_CALL(foo, CalculateBar()); + + foo.CalculateBar(); // This should return default_bar. + + // Unsets the default return value. + DefaultValue::Clear(); +``` + +Please note that changing the default value for a type can make your tests hard +to understand. We recommend you to use this feature judiciously. For example, +you may want to make sure the `Set()` and `Clear()` calls are right next to the +code that uses your mock. + +### Setting the Default Actions for a Mock Method + +You've learned how to change the default value of a given type. However, this +may be too coarse for your purpose: perhaps you have two mock methods with the +same return type and you want them to have different behaviors. The `ON_CALL()` +macro allows you to customize your mock's behavior at the method level: + +```cpp +using ::testing::_; +using ::testing::AnyNumber; +using ::testing::Gt; +using ::testing::Return; +... + ON_CALL(foo, Sign(_)) + .WillByDefault(Return(-1)); + ON_CALL(foo, Sign(0)) + .WillByDefault(Return(0)); + ON_CALL(foo, Sign(Gt(0))) + .WillByDefault(Return(1)); + + EXPECT_CALL(foo, Sign(_)) + .Times(AnyNumber()); + + foo.Sign(5); // This should return 1. + foo.Sign(-9); // This should return -1. + foo.Sign(0); // This should return 0. +``` + +As you may have guessed, when there are more than one `ON_CALL()` statements, +the newer ones in the order take precedence over the older ones. In other words, +the **last** one that matches the function arguments will be used. This matching +order allows you to set up the common behavior in a mock object's constructor or +the test fixture's set-up phase and specialize the mock's behavior later. + +Note that both `ON_CALL` and `EXPECT_CALL` have the same "later statements take +precedence" rule, but they don't interact. That is, `EXPECT_CALL`s have their +own precedence order distinct from the `ON_CALL` precedence order. + +### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions} + +If the built-in actions don't suit you, you can use an existing callable +(function, `std::function`, method, functor, lambda) as an action. + + + +```cpp +using ::testing::_; using ::testing::Invoke; + +class MockFoo : public Foo { + public: + MOCK_METHOD(int, Sum, (int x, int y), (override)); + MOCK_METHOD(bool, ComplexJob, (int x), (override)); +}; + +int CalculateSum(int x, int y) { return x + y; } +int Sum3(int x, int y, int z) { return x + y + z; } + +class Helper { + public: + bool ComplexJob(int x); +}; + +... + MockFoo foo; + Helper helper; + EXPECT_CALL(foo, Sum(_, _)) + .WillOnce(&CalculateSum) + .WillRepeatedly(Invoke(NewPermanentCallback(Sum3, 1))); + EXPECT_CALL(foo, ComplexJob(_)) + .WillOnce(Invoke(&helper, &Helper::ComplexJob)) + .WillOnce([] { return true; }) + .WillRepeatedly([](int x) { return x > 0; }); + + foo.Sum(5, 6); // Invokes CalculateSum(5, 6). + foo.Sum(2, 3); // Invokes Sum3(1, 2, 3). + foo.ComplexJob(10); // Invokes helper.ComplexJob(10). + foo.ComplexJob(-1); // Invokes the inline lambda. +``` + +The only requirement is that the type of the function, etc must be *compatible* +with the signature of the mock function, meaning that the latter's arguments (if +it takes any) can be implicitly converted to the corresponding arguments of the +former, and the former's return type can be implicitly converted to that of the +latter. So, you can invoke something whose type is *not* exactly the same as the +mock function, as long as it's safe to do so - nice, huh? + +**`Note:`{.escaped}** + +* The action takes ownership of the callback and will delete it when the + action itself is destructed. +* If the type of a callback is derived from a base callback type `C`, you need + to implicitly cast it to `C` to resolve the overloading, e.g. + + ```cpp + using ::testing::Invoke; + ... + ResultCallback* is_ok = ...; + ... Invoke(is_ok) ...; // This works. + + BlockingClosure* done = new BlockingClosure; + ... Invoke(implicit_cast(done)) ...; // The cast is necessary. + ``` + +### Using Functions with Extra Info as Actions + +The function or functor you call using `Invoke()` must have the same number of +arguments as the mock function you use it for. Sometimes you may have a function +that takes more arguments, and you are willing to pass in the extra arguments +yourself to fill the gap. You can do this in gMock using callbacks with +pre-bound arguments. Here's an example: + +```cpp +using ::testing::Invoke; + +class MockFoo : public Foo { + public: + MOCK_METHOD(char, DoThis, (int n), (override)); +}; + +char SignOfSum(int x, int y) { + const int sum = x + y; + return (sum > 0) ? '+' : (sum < 0) ? '-' : '0'; +} + +TEST_F(FooTest, Test) { + MockFoo foo; + + EXPECT_CALL(foo, DoThis(2)) + .WillOnce(Invoke(NewPermanentCallback(SignOfSum, 5))); + EXPECT_EQ('+', foo.DoThis(2)); // Invokes SignOfSum(5, 2). +} +``` + +### Invoking a Function/Method/Functor/Lambda/Callback Without Arguments + +`Invoke()` passes the mock function's arguments to the function, etc being +invoked such that the callee has the full context of the call to work with. If +the invoked function is not interested in some or all of the arguments, it can +simply ignore them. + +Yet, a common pattern is that a test author wants to invoke a function without +the arguments of the mock function. She could do that using a wrapper function +that throws away the arguments before invoking an underlining nullary function. +Needless to say, this can be tedious and obscures the intent of the test. + +There are two solutions to this problem. First, you can pass any callable of +zero args as an action. Alternatively, use `InvokeWithoutArgs()`, which is like +`Invoke()` except that it doesn't pass the mock function's arguments to the +callee. Here's an example of each: + +```cpp +using ::testing::_; +using ::testing::InvokeWithoutArgs; + +class MockFoo : public Foo { + public: + MOCK_METHOD(bool, ComplexJob, (int n), (override)); +}; + +bool Job1() { ... } +bool Job2(int n, char c) { ... } + +... + MockFoo foo; + EXPECT_CALL(foo, ComplexJob(_)) + .WillOnce([] { Job1(); }); + .WillOnce(InvokeWithoutArgs(NewPermanentCallback(Job2, 5, 'a'))); + + foo.ComplexJob(10); // Invokes Job1(). + foo.ComplexJob(20); // Invokes Job2(5, 'a'). +``` + +**`Note:`{.escaped}** + +* The action takes ownership of the callback and will delete it when the + action itself is destructed. +* If the type of a callback is derived from a base callback type `C`, you need + to implicitly cast it to `C` to resolve the overloading, e.g. + + ```cpp + using ::testing::InvokeWithoutArgs; + ... + ResultCallback* is_ok = ...; + ... InvokeWithoutArgs(is_ok) ...; // This works. + + BlockingClosure* done = ...; + ... InvokeWithoutArgs(implicit_cast(done)) ...; + // The cast is necessary. + ``` + +### Invoking an Argument of the Mock Function + +Sometimes a mock function will receive a function pointer, a functor (in other +words, a "callable") as an argument, e.g. + +```cpp +class MockFoo : public Foo { + public: + MOCK_METHOD(bool, DoThis, (int n, (ResultCallback1* callback)), + (override)); +}; +``` + +and you may want to invoke this callable argument: + +```cpp +using ::testing::_; +... + MockFoo foo; + EXPECT_CALL(foo, DoThis(_, _)) + .WillOnce(...); + // Will execute callback->Run(5), where callback is the + // second argument DoThis() receives. +``` + +NOTE: The section below is legacy documentation from before C++ had lambdas: + +Arghh, you need to refer to a mock function argument but C++ has no lambda +(yet), so you have to define your own action. :-( Or do you really? + +Well, gMock has an action to solve *exactly* this problem: + +```cpp +InvokeArgument(arg_1, arg_2, ..., arg_m) +``` + +will invoke the `N`-th (0-based) argument the mock function receives, with +`arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is a function +pointer, a functor, or a callback. gMock handles them all. + +With that, you could write: + +```cpp +using ::testing::_; +using ::testing::InvokeArgument; +... + EXPECT_CALL(foo, DoThis(_, _)) + .WillOnce(InvokeArgument<1>(5)); + // Will execute callback->Run(5), where callback is the + // second argument DoThis() receives. +``` + +What if the callable takes an argument by reference? No problem - just wrap it +inside `std::ref()`: + +```cpp + ... + MOCK_METHOD(bool, Bar, + ((ResultCallback2* callback)), + (override)); + ... + using ::testing::_; + using ::testing::InvokeArgument; + ... + MockFoo foo; + Helper helper; + ... + EXPECT_CALL(foo, Bar(_)) + .WillOnce(InvokeArgument<0>(5, std::ref(helper))); + // std::ref(helper) guarantees that a reference to helper, not a copy of + // it, will be passed to the callback. +``` + +What if the callable takes an argument by reference and we do **not** wrap the +argument in `std::ref()`? Then `InvokeArgument()` will *make a copy* of the +argument, and pass a *reference to the copy*, instead of a reference to the +original value, to the callable. This is especially handy when the argument is a +temporary value: + +```cpp + ... + MOCK_METHOD(bool, DoThat, (bool (*f)(const double& x, const string& s)), + (override)); + ... + using ::testing::_; + using ::testing::InvokeArgument; + ... + MockFoo foo; + ... + EXPECT_CALL(foo, DoThat(_)) + .WillOnce(InvokeArgument<0>(5.0, string("Hi"))); + // Will execute (*f)(5.0, string("Hi")), where f is the function pointer + // DoThat() receives. Note that the values 5.0 and string("Hi") are + // temporary and dead once the EXPECT_CALL() statement finishes. Yet + // it's fine to perform this action later, since a copy of the values + // are kept inside the InvokeArgument action. +``` + +### Ignoring an Action's Result + +Sometimes you have an action that returns *something*, but you need an action +that returns `void` (perhaps you want to use it in a mock function that returns +`void`, or perhaps it needs to be used in `DoAll()` and it's not the last in the +list). `IgnoreResult()` lets you do that. For example: + +```cpp +using ::testing::_; +using ::testing::DoAll; +using ::testing::IgnoreResult; +using ::testing::Return; + +int Process(const MyData& data); +string DoSomething(); + +class MockFoo : public Foo { + public: + MOCK_METHOD(void, Abc, (const MyData& data), (override)); + MOCK_METHOD(bool, Xyz, (), (override)); +}; + + ... + MockFoo foo; + EXPECT_CALL(foo, Abc(_)) + // .WillOnce(Invoke(Process)); + // The above line won't compile as Process() returns int but Abc() needs + // to return void. + .WillOnce(IgnoreResult(Process)); + EXPECT_CALL(foo, Xyz()) + .WillOnce(DoAll(IgnoreResult(DoSomething), + // Ignores the string DoSomething() returns. + Return(true))); +``` + +Note that you **cannot** use `IgnoreResult()` on an action that already returns +`void`. Doing so will lead to ugly compiler errors. + +### Selecting an Action's Arguments {#SelectingArgs} + +Say you have a mock function `Foo()` that takes seven arguments, and you have a +custom action that you want to invoke when `Foo()` is called. Trouble is, the +custom action only wants three arguments: + +```cpp +using ::testing::_; +using ::testing::Invoke; +... + MOCK_METHOD(bool, Foo, + (bool visible, const string& name, int x, int y, + (const map>), double& weight, double min_weight, + double max_wight)); +... +bool IsVisibleInQuadrant1(bool visible, int x, int y) { + return visible && x >= 0 && y >= 0; +} +... + EXPECT_CALL(mock, Foo) + .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-( +``` + +To please the compiler God, you need to define an "adaptor" that has the same +signature as `Foo()` and calls the custom action with the right arguments: + +```cpp +using ::testing::_; +using ::testing::Invoke; +... +bool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y, + const map, double>& weight, + double min_weight, double max_wight) { + return IsVisibleInQuadrant1(visible, x, y); +} +... + EXPECT_CALL(mock, Foo) + .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works. +``` + +But isn't this awkward? + +gMock provides a generic *action adaptor*, so you can spend your time minding +more important business than writing your own adaptors. Here's the syntax: + +```cpp +WithArgs(action) +``` + +creates an action that passes the arguments of the mock function at the given +indices (0-based) to the inner `action` and performs it. Using `WithArgs`, our +original example can be written as: + +```cpp +using ::testing::_; +using ::testing::Invoke; +using ::testing::WithArgs; +... + EXPECT_CALL(mock, Foo) + .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1))); // No need to define your own adaptor. +``` + +For better readability, gMock also gives you: + +* `WithoutArgs(action)` when the inner `action` takes *no* argument, and +* `WithArg(action)` (no `s` after `Arg`) when the inner `action` takes + *one* argument. + +As you may have realized, `InvokeWithoutArgs(...)` is just syntactic sugar for +`WithoutArgs(Invoke(...))`. + +Here are more tips: + +* The inner action used in `WithArgs` and friends does not have to be + `Invoke()` -- it can be anything. +* You can repeat an argument in the argument list if necessary, e.g. + `WithArgs<2, 3, 3, 5>(...)`. +* You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`. +* The types of the selected arguments do *not* have to match the signature of + the inner action exactly. It works as long as they can be implicitly + converted to the corresponding arguments of the inner action. For example, + if the 4-th argument of the mock function is an `int` and `my_action` takes + a `double`, `WithArg<4>(my_action)` will work. + +### Ignoring Arguments in Action Functions + +The [selecting-an-action's-arguments](#SelectingArgs) recipe showed us one way +to make a mock function and an action with incompatible argument lists fit +together. The downside is that wrapping the action in `WithArgs<...>()` can get +tedious for people writing the tests. + +If you are defining a function (or method, functor, lambda, callback) to be used +with `Invoke*()`, and you are not interested in some of its arguments, an +alternative to `WithArgs` is to declare the uninteresting arguments as `Unused`. +This makes the definition less cluttered and less fragile in case the types of +the uninteresting arguments change. It could also increase the chance the action +function can be reused. For example, given + +```cpp + public: + MOCK_METHOD(double, Foo, double(const string& label, double x, double y), + (override)); + MOCK_METHOD(double, Bar, (int index, double x, double y), (override)); +``` + +instead of + +```cpp +using ::testing::_; +using ::testing::Invoke; + +double DistanceToOriginWithLabel(const string& label, double x, double y) { + return sqrt(x*x + y*y); +} +double DistanceToOriginWithIndex(int index, double x, double y) { + return sqrt(x*x + y*y); +} +... + EXPECT_CALL(mock, Foo("abc", _, _)) + .WillOnce(Invoke(DistanceToOriginWithLabel)); + EXPECT_CALL(mock, Bar(5, _, _)) + .WillOnce(Invoke(DistanceToOriginWithIndex)); +``` + +you could write + +```cpp +using ::testing::_; +using ::testing::Invoke; +using ::testing::Unused; + +double DistanceToOrigin(Unused, double x, double y) { + return sqrt(x*x + y*y); +} +... + EXPECT_CALL(mock, Foo("abc", _, _)) + .WillOnce(Invoke(DistanceToOrigin)); + EXPECT_CALL(mock, Bar(5, _, _)) + .WillOnce(Invoke(DistanceToOrigin)); +``` + +### Sharing Actions + +Just like matchers, a gMock action object consists of a pointer to a ref-counted +implementation object. Therefore copying actions is also allowed and very +efficient. When the last action that references the implementation object dies, +the implementation object will be deleted. + +If you have some complex action that you want to use again and again, you may +not have to build it from scratch everytime. If the action doesn't have an +internal state (i.e. if it always does the same thing no matter how many times +it has been called), you can assign it to an action variable and use that +variable repeatedly. For example: + +```cpp +using ::testing::Action; +using ::testing::DoAll; +using ::testing::Return; +using ::testing::SetArgPointee; +... + Action set_flag = DoAll(SetArgPointee<0>(5), + Return(true)); + ... use set_flag in .WillOnce() and .WillRepeatedly() ... +``` + +However, if the action has its own state, you may be surprised if you share the +action object. Suppose you have an action factory `IncrementCounter(init)` which +creates an action that increments and returns a counter whose initial value is +`init`, using two actions created from the same expression and using a shared +action will exhibit different behaviors. Example: + +```cpp + EXPECT_CALL(foo, DoThis()) + .WillRepeatedly(IncrementCounter(0)); + EXPECT_CALL(foo, DoThat()) + .WillRepeatedly(IncrementCounter(0)); + foo.DoThis(); // Returns 1. + foo.DoThis(); // Returns 2. + foo.DoThat(); // Returns 1 - Blah() uses a different + // counter than Bar()'s. +``` + +versus + +```cpp +using ::testing::Action; +... + Action increment = IncrementCounter(0); + EXPECT_CALL(foo, DoThis()) + .WillRepeatedly(increment); + EXPECT_CALL(foo, DoThat()) + .WillRepeatedly(increment); + foo.DoThis(); // Returns 1. + foo.DoThis(); // Returns 2. + foo.DoThat(); // Returns 3 - the counter is shared. +``` + +### Testing Asynchronous Behavior + +One oft-encountered problem with gMock is that it can be hard to test +asynchronous behavior. Suppose you had a `EventQueue` class that you wanted to +test, and you created a separate `EventDispatcher` interface so that you could +easily mock it out. However, the implementation of the class fired all the +events on a background thread, which made test timings difficult. You could just +insert `sleep()` statements and hope for the best, but that makes your test +behavior nondeterministic. A better way is to use gMock actions and +`Notification` objects to force your asynchronous test to behave synchronously. + +```cpp +using ::testing::DoAll; +using ::testing::InvokeWithoutArgs; +using ::testing::Return; + +class MockEventDispatcher : public EventDispatcher { + MOCK_METHOD(bool, DispatchEvent, (int32), (override)); +}; + +ACTION_P(Notify, notification) { + notification->Notify(); +} + +TEST(EventQueueTest, EnqueueEventTest) { + MockEventDispatcher mock_event_dispatcher; + EventQueue event_queue(&mock_event_dispatcher); + + const int32 kEventId = 321; + absl::Notification done; + EXPECT_CALL(mock_event_dispatcher, DispatchEvent(kEventId)) + .WillOnce(Notify(&done)); + + event_queue.EnqueueEvent(kEventId); + done.WaitForNotification(); +} +``` + +In the example above, we set our normal gMock expectations, but then add an +additional action to notify the `Notification` object. Now we can just call +`Notification::WaitForNotification()` in the main thread to wait for the +asynchronous call to finish. After that, our test suite is complete and we can +safely exit. + +Note: this example has a downside: namely, if the expectation is not satisfied, +our test will run forever. It will eventually time-out and fail, but it will +take longer and be slightly harder to debug. To alleviate this problem, you can +use `WaitForNotificationWithTimeout(ms)` instead of `WaitForNotification()`. + +## Misc Recipes on Using gMock + +### Mocking Methods That Use Move-Only Types + +C++11 introduced *move-only types*. A move-only-typed value can be moved from +one object to another, but cannot be copied. `std::unique_ptr` is probably +the most commonly used move-only type. + +Mocking a method that takes and/or returns move-only types presents some +challenges, but nothing insurmountable. This recipe shows you how you can do it. +Note that the support for move-only method arguments was only introduced to +gMock in April 2017; in older code, you may find more complex +[workarounds](#LegacyMoveOnly) for lack of this feature. + +Let’s say we are working on a fictional project that lets one post and share +snippets called “buzzes”. Your code uses these types: + +```cpp +enum class AccessLevel { kInternal, kPublic }; + +class Buzz { + public: + explicit Buzz(AccessLevel access) { ... } + ... +}; + +class Buzzer { + public: + virtual ~Buzzer() {} + virtual std::unique_ptr MakeBuzz(StringPiece text) = 0; + virtual bool ShareBuzz(std::unique_ptr buzz, int64_t timestamp) = 0; + ... +}; +``` + +A `Buzz` object represents a snippet being posted. A class that implements the +`Buzzer` interface is capable of creating and sharing `Buzz`es. Methods in +`Buzzer` may return a `unique_ptr` or take a `unique_ptr`. Now we +need to mock `Buzzer` in our tests. + +To mock a method that accepts or returns move-only types, you just use the +familiar `MOCK_METHOD` syntax as usual: + +```cpp +class MockBuzzer : public Buzzer { + public: + MOCK_METHOD(std::unique_ptr, MakeBuzz, (StringPiece text), (override)); + MOCK_METHOD(bool, ShareBuzz, (std::unique_ptr buzz, int64_t timestamp), + (override)); +}; +``` + +Now that we have the mock class defined, we can use it in tests. In the +following code examples, we assume that we have defined a `MockBuzzer` object +named `mock_buzzer_`: + +```cpp + MockBuzzer mock_buzzer_; +``` + +First let’s see how we can set expectations on the `MakeBuzz()` method, which +returns a `unique_ptr`. + +As usual, if you set an expectation without an action (i.e. the `.WillOnce()` or +`.WillRepeatedly()` clause), when that expectation fires, the default action for +that method will be taken. Since `unique_ptr<>` has a default constructor that +returns a null `unique_ptr`, that’s what you’ll get if you don’t specify an +action: + +```cpp + // Use the default action. + EXPECT_CALL(mock_buzzer_, MakeBuzz("hello")); + + // Triggers the previous EXPECT_CALL. + EXPECT_EQ(nullptr, mock_buzzer_.MakeBuzz("hello")); +``` + +If you are not happy with the default action, you can tweak it as usual; see +[Setting Default Actions](#OnCall). + +If you just need to return a pre-defined move-only value, you can use the +`Return(ByMove(...))` action: + +```cpp + // When this fires, the unique_ptr<> specified by ByMove(...) will + // be returned. + EXPECT_CALL(mock_buzzer_, MakeBuzz("world")) + .WillOnce(Return(ByMove(MakeUnique(AccessLevel::kInternal)))); + + EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("world")); +``` + +Note that `ByMove()` is essential here - if you drop it, the code won’t compile. + +Quiz time! What do you think will happen if a `Return(ByMove(...))` action is +performed more than once (e.g. you write `... +.WillRepeatedly(Return(ByMove(...)));`)? Come think of it, after the first time +the action runs, the source value will be consumed (since it’s a move-only +value), so the next time around, there’s no value to move from -- you’ll get a +run-time error that `Return(ByMove(...))` can only be run once. + +If you need your mock method to do more than just moving a pre-defined value, +remember that you can always use a lambda or a callable object, which can do +pretty much anything you want: + +```cpp + EXPECT_CALL(mock_buzzer_, MakeBuzz("x")) + .WillRepeatedly([](StringPiece text) { + return MakeUnique(AccessLevel::kInternal); + }); + + EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x")); + EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x")); +``` + +Every time this `EXPECT_CALL` fires, a new `unique_ptr` will be created +and returned. You cannot do this with `Return(ByMove(...))`. + +That covers returning move-only values; but how do we work with methods +accepting move-only arguments? The answer is that they work normally, although +some actions will not compile when any of method's arguments are move-only. You +can always use `Return`, or a [lambda or functor](#FunctionsAsActions): + +```cpp + using ::testing::Unused; + + EXPECT_CALL(mock_buzzer_, ShareBuzz(NotNull(), _)).WillOnce(Return(true)); + EXPECT_TRUE(mock_buzzer_.ShareBuzz(MakeUnique(AccessLevel::kInternal)), + 0); + + EXPECT_CALL(mock_buzzer_, ShareBuzz(_, _)).WillOnce( + [](std::unique_ptr buzz, Unused) { return buzz != nullptr; }); + EXPECT_FALSE(mock_buzzer_.ShareBuzz(nullptr, 0)); +``` + +Many built-in actions (`WithArgs`, `WithoutArgs`,`DeleteArg`, `SaveArg`, ...) +could in principle support move-only arguments, but the support for this is not +implemented yet. If this is blocking you, please file a bug. + +A few actions (e.g. `DoAll`) copy their arguments internally, so they can never +work with non-copyable objects; you'll have to use functors instead. + +#### Legacy workarounds for move-only types {#LegacyMoveOnly} + +Support for move-only function arguments was only introduced to gMock in April +2017. In older code, you may encounter the following workaround for the lack of +this feature (it is no longer necessary - we're including it just for +reference): + +```cpp +class MockBuzzer : public Buzzer { + public: + MOCK_METHOD(bool, DoShareBuzz, (Buzz* buzz, Time timestamp)); + bool ShareBuzz(std::unique_ptr buzz, Time timestamp) override { + return DoShareBuzz(buzz.get(), timestamp); + } +}; +``` + +The trick is to delegate the `ShareBuzz()` method to a mock method (let’s call +it `DoShareBuzz()`) that does not take move-only parameters. Then, instead of +setting expectations on `ShareBuzz()`, you set them on the `DoShareBuzz()` mock +method: + +```cpp + MockBuzzer mock_buzzer_; + EXPECT_CALL(mock_buzzer_, DoShareBuzz(NotNull(), _)); + + // When one calls ShareBuzz() on the MockBuzzer like this, the call is + // forwarded to DoShareBuzz(), which is mocked. Therefore this statement + // will trigger the above EXPECT_CALL. + mock_buzzer_.ShareBuzz(MakeUnique(AccessLevel::kInternal), 0); +``` + +### Making the Compilation Faster + +Believe it or not, the *vast majority* of the time spent on compiling a mock +class is in generating its constructor and destructor, as they perform +non-trivial tasks (e.g. verification of the expectations). What's more, mock +methods with different signatures have different types and thus their +constructors/destructors need to be generated by the compiler separately. As a +result, if you mock many different types of methods, compiling your mock class +can get really slow. + +If you are experiencing slow compilation, you can move the definition of your +mock class' constructor and destructor out of the class body and into a `.cc` +file. This way, even if you `#include` your mock class in N files, the compiler +only needs to generate its constructor and destructor once, resulting in a much +faster compilation. + +Let's illustrate the idea using an example. Here's the definition of a mock +class before applying this recipe: + +```cpp +// File mock_foo.h. +... +class MockFoo : public Foo { + public: + // Since we don't declare the constructor or the destructor, + // the compiler will generate them in every translation unit + // where this mock class is used. + + MOCK_METHOD(int, DoThis, (), (override)); + MOCK_METHOD(bool, DoThat, (const char* str), (override)); + ... more mock methods ... +}; +``` + +After the change, it would look like: + +```cpp +// File mock_foo.h. +... +class MockFoo : public Foo { + public: + // The constructor and destructor are declared, but not defined, here. + MockFoo(); + virtual ~MockFoo(); + + MOCK_METHOD(int, DoThis, (), (override)); + MOCK_METHOD(bool, DoThat, (const char* str), (override)); + ... more mock methods ... +}; +``` + +and + +```cpp +// File mock_foo.cc. +#include "path/to/mock_foo.h" + +// The definitions may appear trivial, but the functions actually do a +// lot of things through the constructors/destructors of the member +// variables used to implement the mock methods. +MockFoo::MockFoo() {} +MockFoo::~MockFoo() {} +``` + +### Forcing a Verification + +When it's being destroyed, your friendly mock object will automatically verify +that all expectations on it have been satisfied, and will generate googletest +failures if not. This is convenient as it leaves you with one less thing to +worry about. That is, unless you are not sure if your mock object will be +destroyed. + +How could it be that your mock object won't eventually be destroyed? Well, it +might be created on the heap and owned by the code you are testing. Suppose +there's a bug in that code and it doesn't delete the mock object properly - you +could end up with a passing test when there's actually a bug. + +Using a heap checker is a good idea and can alleviate the concern, but its +implementation is not 100% reliable. So, sometimes you do want to *force* gMock +to verify a mock object before it is (hopefully) destructed. You can do this +with `Mock::VerifyAndClearExpectations(&mock_object)`: + +```cpp +TEST(MyServerTest, ProcessesRequest) { + using ::testing::Mock; + + MockFoo* const foo = new MockFoo; + EXPECT_CALL(*foo, ...)...; + // ... other expectations ... + + // server now owns foo. + MyServer server(foo); + server.ProcessRequest(...); + + // In case that server's destructor will forget to delete foo, + // this will verify the expectations anyway. + Mock::VerifyAndClearExpectations(foo); +} // server is destroyed when it goes out of scope here. +``` + +**Tip:** The `Mock::VerifyAndClearExpectations()` function returns a `bool` to +indicate whether the verification was successful (`true` for yes), so you can +wrap that function call inside a `ASSERT_TRUE()` if there is no point going +further when the verification has failed. + +### Using Check Points {#UsingCheckPoints} + +Sometimes you may want to "reset" a mock object at various check points in your +test: at each check point, you verify that all existing expectations on the mock +object have been satisfied, and then you set some new expectations on it as if +it's newly created. This allows you to work with a mock object in "phases" whose +sizes are each manageable. + +One such scenario is that in your test's `SetUp()` function, you may want to put +the object you are testing into a certain state, with the help from a mock +object. Once in the desired state, you want to clear all expectations on the +mock, such that in the `TEST_F` body you can set fresh expectations on it. + +As you may have figured out, the `Mock::VerifyAndClearExpectations()` function +we saw in the previous recipe can help you here. Or, if you are using +`ON_CALL()` to set default actions on the mock object and want to clear the +default actions as well, use `Mock::VerifyAndClear(&mock_object)` instead. This +function does what `Mock::VerifyAndClearExpectations(&mock_object)` does and +returns the same `bool`, **plus** it clears the `ON_CALL()` statements on +`mock_object` too. + +Another trick you can use to achieve the same effect is to put the expectations +in sequences and insert calls to a dummy "check-point" function at specific +places. Then you can verify that the mock function calls do happen at the right +time. For example, if you are exercising code: + +```cpp + Foo(1); + Foo(2); + Foo(3); +``` + +and want to verify that `Foo(1)` and `Foo(3)` both invoke `mock.Bar("a")`, but +`Foo(2)` doesn't invoke anything. You can write: + +```cpp +using ::testing::MockFunction; + +TEST(FooTest, InvokesBarCorrectly) { + MyMock mock; + // Class MockFunction has exactly one mock method. It is named + // Call() and has type F. + MockFunction check; + { + InSequence s; + + EXPECT_CALL(mock, Bar("a")); + EXPECT_CALL(check, Call("1")); + EXPECT_CALL(check, Call("2")); + EXPECT_CALL(mock, Bar("a")); + } + Foo(1); + check.Call("1"); + Foo(2); + check.Call("2"); + Foo(3); +} +``` + +The expectation spec says that the first `Bar("a")` must happen before check +point "1", the second `Bar("a")` must happen after check point "2", and nothing +should happen between the two check points. The explicit check points make it +easy to tell which `Bar("a")` is called by which call to `Foo()`. + +### Mocking Destructors + +Sometimes you want to make sure a mock object is destructed at the right time, +e.g. after `bar->A()` is called but before `bar->B()` is called. We already know +that you can specify constraints on the [order](#OrderedCalls) of mock function +calls, so all we need to do is to mock the destructor of the mock function. + +This sounds simple, except for one problem: a destructor is a special function +with special syntax and special semantics, and the `MOCK_METHOD` macro doesn't +work for it: + +```cpp +MOCK_METHOD(void, ~MockFoo, ()); // Won't compile! +``` + +The good news is that you can use a simple pattern to achieve the same effect. +First, add a mock function `Die()` to your mock class and call it in the +destructor, like this: + +```cpp +class MockFoo : public Foo { + ... + // Add the following two lines to the mock class. + MOCK_METHOD(void, Die, ()); + ~MockFoo() override { Die(); } +}; +``` + +(If the name `Die()` clashes with an existing symbol, choose another name.) Now, +we have translated the problem of testing when a `MockFoo` object dies to +testing when its `Die()` method is called: + +```cpp + MockFoo* foo = new MockFoo; + MockBar* bar = new MockBar; + ... + { + InSequence s; + + // Expects *foo to die after bar->A() and before bar->B(). + EXPECT_CALL(*bar, A()); + EXPECT_CALL(*foo, Die()); + EXPECT_CALL(*bar, B()); + } +``` + +And that's that. + +### Using gMock and Threads {#UsingThreads} + +In a **unit** test, it's best if you could isolate and test a piece of code in a +single-threaded context. That avoids race conditions and dead locks, and makes +debugging your test much easier. + +Yet most programs are multi-threaded, and sometimes to test something we need to +pound on it from more than one thread. gMock works for this purpose too. + +Remember the steps for using a mock: + +1. Create a mock object `foo`. +2. Set its default actions and expectations using `ON_CALL()` and + `EXPECT_CALL()`. +3. The code under test calls methods of `foo`. +4. Optionally, verify and reset the mock. +5. Destroy the mock yourself, or let the code under test destroy it. The + destructor will automatically verify it. + +If you follow the following simple rules, your mocks and threads can live +happily together: + +* Execute your *test code* (as opposed to the code being tested) in *one* + thread. This makes your test easy to follow. +* Obviously, you can do step #1 without locking. +* When doing step #2 and #5, make sure no other thread is accessing `foo`. + Obvious too, huh? +* #3 and #4 can be done either in one thread or in multiple threads - anyway + you want. gMock takes care of the locking, so you don't have to do any - + unless required by your test logic. + +If you violate the rules (for example, if you set expectations on a mock while +another thread is calling its methods), you get undefined behavior. That's not +fun, so don't do it. + +gMock guarantees that the action for a mock function is done in the same thread +that called the mock function. For example, in + +```cpp + EXPECT_CALL(mock, Foo(1)) + .WillOnce(action1); + EXPECT_CALL(mock, Foo(2)) + .WillOnce(action2); +``` + +if `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2, gMock will +execute `action1` in thread 1 and `action2` in thread 2. + +gMock does *not* impose a sequence on actions performed in different threads +(doing so may create deadlocks as the actions may need to cooperate). This means +that the execution of `action1` and `action2` in the above example *may* +interleave. If this is a problem, you should add proper synchronization logic to +`action1` and `action2` to make the test thread-safe. + +Also, remember that `DefaultValue` is a global resource that potentially +affects *all* living mock objects in your program. Naturally, you won't want to +mess with it from multiple threads or when there still are mocks in action. + +### Controlling How Much Information gMock Prints + +When gMock sees something that has the potential of being an error (e.g. a mock +function with no expectation is called, a.k.a. an uninteresting call, which is +allowed but perhaps you forgot to explicitly ban the call), it prints some +warning messages, including the arguments of the function, the return value, and +the stack trace. Hopefully this will remind you to take a look and see if there +is indeed a problem. + +Sometimes you are confident that your tests are correct and may not appreciate +such friendly messages. Some other times, you are debugging your tests or +learning about the behavior of the code you are testing, and wish you could +observe every mock call that happens (including argument values, the return +value, and the stack trace). Clearly, one size doesn't fit all. + +You can control how much gMock tells you using the `--gmock_verbose=LEVEL` +command-line flag, where `LEVEL` is a string with three possible values: + +* `info`: gMock will print all informational messages, warnings, and errors + (most verbose). At this setting, gMock will also log any calls to the + `ON_CALL/EXPECT_CALL` macros. It will include a stack trace in + "uninteresting call" warnings. +* `warning`: gMock will print both warnings and errors (less verbose); it will + omit the stack traces in "uninteresting call" warnings. This is the default. +* `error`: gMock will print errors only (least verbose). + +Alternatively, you can adjust the value of that flag from within your tests like +so: + +```cpp + ::testing::FLAGS_gmock_verbose = "error"; +``` + +If you find gMock printing too many stack frames with its informational or +warning messages, remember that you can control their amount with the +`--gtest_stack_trace_depth=max_depth` flag. + +Now, judiciously use the right flag to enable gMock serve you better! + +### Gaining Super Vision into Mock Calls + +You have a test using gMock. It fails: gMock tells you some expectations aren't +satisfied. However, you aren't sure why: Is there a typo somewhere in the +matchers? Did you mess up the order of the `EXPECT_CALL`s? Or is the code under +test doing something wrong? How can you find out the cause? + +Won't it be nice if you have X-ray vision and can actually see the trace of all +`EXPECT_CALL`s and mock method calls as they are made? For each call, would you +like to see its actual argument values and which `EXPECT_CALL` gMock thinks it +matches? If you still need some help to figure out who made these calls, how +about being able to see the complete stack trace at each mock call? + +You can unlock this power by running your test with the `--gmock_verbose=info` +flag. For example, given the test program: + +```cpp +#include "gmock/gmock.h" + +using testing::_; +using testing::HasSubstr; +using testing::Return; + +class MockFoo { + public: + MOCK_METHOD(void, F, (const string& x, const string& y)); +}; + +TEST(Foo, Bar) { + MockFoo mock; + EXPECT_CALL(mock, F(_, _)).WillRepeatedly(Return()); + EXPECT_CALL(mock, F("a", "b")); + EXPECT_CALL(mock, F("c", HasSubstr("d"))); + + mock.F("a", "good"); + mock.F("a", "b"); +} +``` + +if you run it with `--gmock_verbose=info`, you will see this output: + +```shell +[ RUN ] Foo.Bar + +foo_test.cc:14: EXPECT_CALL(mock, F(_, _)) invoked +Stack trace: ... + +foo_test.cc:15: EXPECT_CALL(mock, F("a", "b")) invoked +Stack trace: ... + +foo_test.cc:16: EXPECT_CALL(mock, F("c", HasSubstr("d"))) invoked +Stack trace: ... + +foo_test.cc:14: Mock function call matches EXPECT_CALL(mock, F(_, _))... + Function call: F(@0x7fff7c8dad40"a",@0x7fff7c8dad10"good") +Stack trace: ... + +foo_test.cc:15: Mock function call matches EXPECT_CALL(mock, F("a", "b"))... + Function call: F(@0x7fff7c8dada0"a",@0x7fff7c8dad70"b") +Stack trace: ... + +foo_test.cc:16: Failure +Actual function call count doesn't match EXPECT_CALL(mock, F("c", HasSubstr("d")))... + Expected: to be called once + Actual: never called - unsatisfied and active +[ FAILED ] Foo.Bar +``` + +Suppose the bug is that the `"c"` in the third `EXPECT_CALL` is a typo and +should actually be `"a"`. With the above message, you should see that the actual +`F("a", "good")` call is matched by the first `EXPECT_CALL`, not the third as +you thought. From that it should be obvious that the third `EXPECT_CALL` is +written wrong. Case solved. + +If you are interested in the mock call trace but not the stack traces, you can +combine `--gmock_verbose=info` with `--gtest_stack_trace_depth=0` on the test +command line. + + + +### Running Tests in Emacs + +If you build and run your tests in Emacs using the `M-x google-compile` command +(as many googletest users do), the source file locations of gMock and googletest +errors will be highlighted. Just press `` on one of them and you'll be +taken to the offending line. Or, you can just type `C-x`` to jump to the next +error. + +To make it even easier, you can add the following lines to your `~/.emacs` file: + +```text +(global-set-key "\M-m" 'google-compile) ; m is for make +(global-set-key [M-down] 'next-error) +(global-set-key [M-up] '(lambda () (interactive) (next-error -1))) +``` + +Then you can type `M-m` to start a build (if you want to run the test as well, +just make sure `foo_test.run` or `runtests` is in the build command you supply +after typing `M-m`), or `M-up`/`M-down` to move back and forth between errors. + +## Extending gMock + +### Writing New Matchers Quickly {#NewMatchers} + +WARNING: gMock does not guarantee when or how many times a matcher will be +invoked. Therefore, all matchers must be functionally pure. See +[this section](#PureMatchers) for more details. + +The `MATCHER*` family of macros can be used to define custom matchers easily. +The syntax: + +```cpp +MATCHER(name, description_string_expression) { statements; } +``` + +will define a matcher with the given name that executes the statements, which +must return a `bool` to indicate if the match succeeds. Inside the statements, +you can refer to the value being matched by `arg`, and refer to its type by +`arg_type`. + +The *description string* is a `string`-typed expression that documents what the +matcher does, and is used to generate the failure message when the match fails. +It can (and should) reference the special `bool` variable `negation`, and should +evaluate to the description of the matcher when `negation` is `false`, or that +of the matcher's negation when `negation` is `true`. + +For convenience, we allow the description string to be empty (`""`), in which +case gMock will use the sequence of words in the matcher name as the +description. + +For example: + +```cpp +MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; } +``` + +allows you to write + +```cpp + // Expects mock_foo.Bar(n) to be called where n is divisible by 7. + EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7())); +``` + +or, + +```cpp + using ::testing::Not; + ... + // Verifies that two values are divisible by 7. + EXPECT_THAT(some_expression, IsDivisibleBy7()); + EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7())); +``` + +If the above assertions fail, they will print something like: + +```shell + Value of: some_expression + Expected: is divisible by 7 + Actual: 27 + ... + Value of: some_other_expression + Expected: not (is divisible by 7) + Actual: 21 +``` + +where the descriptions `"is divisible by 7"` and `"not (is divisible by 7)"` are +automatically calculated from the matcher name `IsDivisibleBy7`. + +As you may have noticed, the auto-generated descriptions (especially those for +the negation) may not be so great. You can always override them with a `string` +expression of your own: + +```cpp +MATCHER(IsDivisibleBy7, + absl::StrCat(negation ? "isn't" : "is", " divisible by 7")) { + return (arg % 7) == 0; +} +``` + +Optionally, you can stream additional information to a hidden argument named +`result_listener` to explain the match result. For example, a better definition +of `IsDivisibleBy7` is: + +```cpp +MATCHER(IsDivisibleBy7, "") { + if ((arg % 7) == 0) + return true; + + *result_listener << "the remainder is " << (arg % 7); + return false; +} +``` + +With this definition, the above assertion will give a better message: + +```shell + Value of: some_expression + Expected: is divisible by 7 + Actual: 27 (the remainder is 6) +``` + +You should let `MatchAndExplain()` print *any additional information* that can +help a user understand the match result. Note that it should explain why the +match succeeds in case of a success (unless it's obvious) - this is useful when +the matcher is used inside `Not()`. There is no need to print the argument value +itself, as gMock already prints it for you. + +NOTE: The type of the value being matched (`arg_type`) is determined by the +context in which you use the matcher and is supplied to you by the compiler, so +you don't need to worry about declaring it (nor can you). This allows the +matcher to be polymorphic. For example, `IsDivisibleBy7()` can be used to match +any type where the value of `(arg % 7) == 0` can be implicitly converted to a +`bool`. In the `Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an +`int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will +be `unsigned long`; and so on. + +### Writing New Parameterized Matchers Quickly + +Sometimes you'll want to define a matcher that has parameters. For that you can +use the macro: + +```cpp +MATCHER_P(name, param_name, description_string) { statements; } +``` + +where the description string can be either `""` or a `string` expression that +references `negation` and `param_name`. + +For example: + +```cpp +MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; } +``` + +will allow you to write: + +```cpp + EXPECT_THAT(Blah("a"), HasAbsoluteValue(n)); +``` + +which may lead to this message (assuming `n` is 10): + +```shell + Value of: Blah("a") + Expected: has absolute value 10 + Actual: -9 +``` + +Note that both the matcher description and its parameter are printed, making the +message human-friendly. + +In the matcher definition body, you can write `foo_type` to reference the type +of a parameter named `foo`. For example, in the body of +`MATCHER_P(HasAbsoluteValue, value)` above, you can write `value_type` to refer +to the type of `value`. + +gMock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to `MATCHER_P10` to +support multi-parameter matchers: + +```cpp +MATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; } +``` + +Please note that the custom description string is for a particular *instance* of +the matcher, where the parameters have been bound to actual values. Therefore +usually you'll want the parameter values to be part of the description. gMock +lets you do that by referencing the matcher parameters in the description string +expression. + +For example, + +```cpp +using ::testing::PrintToString; +MATCHER_P2(InClosedRange, low, hi, + absl::StrFormat("%s in range [%s, %s]", negation ? "isn't" : "is", + PrintToString(low), PrintToString(hi))) { + return low <= arg && arg <= hi; +} +... +EXPECT_THAT(3, InClosedRange(4, 6)); +``` + +would generate a failure that contains the message: + +```shell + Expected: is in range [4, 6] +``` + +If you specify `""` as the description, the failure message will contain the +sequence of words in the matcher name followed by the parameter values printed +as a tuple. For example, + +```cpp + MATCHER_P2(InClosedRange, low, hi, "") { ... } + ... + EXPECT_THAT(3, InClosedRange(4, 6)); +``` + +would generate a failure that contains the text: + +```shell + Expected: in closed range (4, 6) +``` + +For the purpose of typing, you can view + +```cpp +MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... } +``` + +as shorthand for + +```cpp +template +FooMatcherPk +Foo(p1_type p1, ..., pk_type pk) { ... } +``` + +When you write `Foo(v1, ..., vk)`, the compiler infers the types of the +parameters `v1`, ..., and `vk` for you. If you are not happy with the result of +the type inference, you can specify the types by explicitly instantiating the +template, as in `Foo(5, false)`. As said earlier, you don't get to +(or need to) specify `arg_type` as that's determined by the context in which the +matcher is used. + +You can assign the result of expression `Foo(p1, ..., pk)` to a variable of type +`FooMatcherPk`. This can be useful when composing +matchers. Matchers that don't have a parameter or have only one parameter have +special types: you can assign `Foo()` to a `FooMatcher`-typed variable, and +assign `Foo(p)` to a `FooMatcherP`-typed variable. + +While you can instantiate a matcher template with reference types, passing the +parameters by pointer usually makes your code more readable. If, however, you +still want to pass a parameter by reference, be aware that in the failure +message generated by the matcher you will see the value of the referenced object +but not its address. + +You can overload matchers with different numbers of parameters: + +```cpp +MATCHER_P(Blah, a, description_string_1) { ... } +MATCHER_P2(Blah, a, b, description_string_2) { ... } +``` + +While it's tempting to always use the `MATCHER*` macros when defining a new +matcher, you should also consider implementing `MatcherInterface` or using +`MakePolymorphicMatcher()` instead (see the recipes that follow), especially if +you need to use the matcher a lot. While these approaches require more work, +they give you more control on the types of the value being matched and the +matcher parameters, which in general leads to better compiler error messages +that pay off in the long run. They also allow overloading matchers based on +parameter types (as opposed to just based on the number of parameters). + +### Writing New Monomorphic Matchers + +A matcher of argument type `T` implements `::testing::MatcherInterface` and +does two things: it tests whether a value of type `T` matches the matcher, and +can describe what kind of values it matches. The latter ability is used for +generating readable error messages when expectations are violated. + +The interface looks like this: + +```cpp +class MatchResultListener { + public: + ... + // Streams x to the underlying ostream; does nothing if the ostream + // is NULL. + template + MatchResultListener& operator<<(const T& x); + + // Returns the underlying ostream. + std::ostream* stream(); +}; + +template +class MatcherInterface { + public: + virtual ~MatcherInterface(); + + // Returns true if and only if the matcher matches x; also explains the match + // result to 'listener'. + virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0; + + // Describes this matcher to an ostream. + virtual void DescribeTo(std::ostream* os) const = 0; + + // Describes the negation of this matcher to an ostream. + virtual void DescribeNegationTo(std::ostream* os) const; +}; +``` + +If you need a custom matcher but `Truly()` is not a good option (for example, +you may not be happy with the way `Truly(predicate)` describes itself, or you +may want your matcher to be polymorphic as `Eq(value)` is), you can define a +matcher to do whatever you want in two steps: first implement the matcher +interface, and then define a factory function to create a matcher instance. The +second step is not strictly needed but it makes the syntax of using the matcher +nicer. + +For example, you can define a matcher to test whether an `int` is divisible by 7 +and then use it like this: + +```cpp +using ::testing::MakeMatcher; +using ::testing::Matcher; +using ::testing::MatcherInterface; +using ::testing::MatchResultListener; + +class DivisibleBy7Matcher : public MatcherInterface { + public: + bool MatchAndExplain(int n, + MatchResultListener* /* listener */) const override { + return (n % 7) == 0; + } + + void DescribeTo(std::ostream* os) const override { + *os << "is divisible by 7"; + } + + void DescribeNegationTo(std::ostream* os) const override { + *os << "is not divisible by 7"; + } +}; + +Matcher DivisibleBy7() { + return MakeMatcher(new DivisibleBy7Matcher); +} + +... + EXPECT_CALL(foo, Bar(DivisibleBy7())); +``` + +You may improve the matcher message by streaming additional information to the +`listener` argument in `MatchAndExplain()`: + +```cpp +class DivisibleBy7Matcher : public MatcherInterface { + public: + bool MatchAndExplain(int n, + MatchResultListener* listener) const override { + const int remainder = n % 7; + if (remainder != 0) { + *listener << "the remainder is " << remainder; + } + return remainder == 0; + } + ... +}; +``` + +Then, `EXPECT_THAT(x, DivisibleBy7());` may generate a message like this: + +```shell +Value of: x +Expected: is divisible by 7 + Actual: 23 (the remainder is 2) +``` + +### Writing New Polymorphic Matchers + +You've learned how to write your own matchers in the previous recipe. Just one +problem: a matcher created using `MakeMatcher()` only works for one particular +type of arguments. If you want a *polymorphic* matcher that works with arguments +of several types (for instance, `Eq(x)` can be used to match a *`value`* as long +as `value == x` compiles -- *`value`* and `x` don't have to share the same +type), you can learn the trick from `testing/base/public/gmock-matchers.h` but +it's a bit involved. + +Fortunately, most of the time you can define a polymorphic matcher easily with +the help of `MakePolymorphicMatcher()`. Here's how you can define `NotNull()` as +an example: + +```cpp +using ::testing::MakePolymorphicMatcher; +using ::testing::MatchResultListener; +using ::testing::PolymorphicMatcher; + +class NotNullMatcher { + public: + // To implement a polymorphic matcher, first define a COPYABLE class + // that has three members MatchAndExplain(), DescribeTo(), and + // DescribeNegationTo(), like the following. + + // In this example, we want to use NotNull() with any pointer, so + // MatchAndExplain() accepts a pointer of any type as its first argument. + // In general, you can define MatchAndExplain() as an ordinary method or + // a method template, or even overload it. + template + bool MatchAndExplain(T* p, + MatchResultListener* /* listener */) const { + return p != NULL; + } + + // Describes the property of a value matching this matcher. + void DescribeTo(std::ostream* os) const { *os << "is not NULL"; } + + // Describes the property of a value NOT matching this matcher. + void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; } +}; + +// To construct a polymorphic matcher, pass an instance of the class +// to MakePolymorphicMatcher(). Note the return type. +PolymorphicMatcher NotNull() { + return MakePolymorphicMatcher(NotNullMatcher()); +} + +... + + EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer. +``` + +**Note:** Your polymorphic matcher class does **not** need to inherit from +`MatcherInterface` or any other class, and its methods do **not** need to be +virtual. + +Like in a monomorphic matcher, you may explain the match result by streaming +additional information to the `listener` argument in `MatchAndExplain()`. + +### Writing New Cardinalities + +A cardinality is used in `Times()` to tell gMock how many times you expect a +call to occur. It doesn't have to be exact. For example, you can say +`AtLeast(5)` or `Between(2, 4)`. + +If the [built-in set](gmock_cheat_sheet.md#CardinalityList) of cardinalities +doesn't suit you, you are free to define your own by implementing the following +interface (in namespace `testing`): + +```cpp +class CardinalityInterface { + public: + virtual ~CardinalityInterface(); + + // Returns true if and only if call_count calls will satisfy this cardinality. + virtual bool IsSatisfiedByCallCount(int call_count) const = 0; + + // Returns true if and only if call_count calls will saturate this + // cardinality. + virtual bool IsSaturatedByCallCount(int call_count) const = 0; + + // Describes self to an ostream. + virtual void DescribeTo(std::ostream* os) const = 0; +}; +``` + +For example, to specify that a call must occur even number of times, you can +write + +```cpp +using ::testing::Cardinality; +using ::testing::CardinalityInterface; +using ::testing::MakeCardinality; + +class EvenNumberCardinality : public CardinalityInterface { + public: + bool IsSatisfiedByCallCount(int call_count) const override { + return (call_count % 2) == 0; + } + + bool IsSaturatedByCallCount(int call_count) const override { + return false; + } + + void DescribeTo(std::ostream* os) const { + *os << "called even number of times"; + } +}; + +Cardinality EvenNumber() { + return MakeCardinality(new EvenNumberCardinality); +} + +... + EXPECT_CALL(foo, Bar(3)) + .Times(EvenNumber()); +``` + +### Writing New Actions Quickly {#QuickNewActions} + +If the built-in actions don't work for you, you can easily define your own one. +Just define a functor class with a (possibly templated) call operator, matching +the signature of your action. + +```cpp +struct Increment { + template + T operator()(T* arg) { + return ++(*arg); + } +} +``` + +The same approach works with stateful functors (or any callable, really): + +``` +struct MultiplyBy { + template + T operator()(T arg) { return arg * multiplier; } + + int multiplier; +} + +// Then use: +// EXPECT_CALL(...).WillOnce(MultiplyBy{7}); +``` + +#### Legacy macro-based Actions + +Before C++11, the functor-based actions were not supported; the old way of +writing actions was through a set of `ACTION*` macros. We suggest to avoid them +in new code; they hide a lot of logic behind the macro, potentially leading to +harder-to-understand compiler errors. Nevertheless, we cover them here for +completeness. + +By writing + +```cpp +ACTION(name) { statements; } +``` + +in a namespace scope (i.e. not inside a class or function), you will define an +action with the given name that executes the statements. The value returned by +`statements` will be used as the return value of the action. Inside the +statements, you can refer to the K-th (0-based) argument of the mock function as +`argK`. For example: + +```cpp +ACTION(IncrementArg1) { return ++(*arg1); } +``` + +allows you to write + +```cpp +... WillOnce(IncrementArg1()); +``` + +Note that you don't need to specify the types of the mock function arguments. +Rest assured that your code is type-safe though: you'll get a compiler error if +`*arg1` doesn't support the `++` operator, or if the type of `++(*arg1)` isn't +compatible with the mock function's return type. + +Another example: + +```cpp +ACTION(Foo) { + (*arg2)(5); + Blah(); + *arg1 = 0; + return arg0; +} +``` + +defines an action `Foo()` that invokes argument #2 (a function pointer) with 5, +calls function `Blah()`, sets the value pointed to by argument #1 to 0, and +returns argument #0. + +For more convenience and flexibility, you can also use the following pre-defined +symbols in the body of `ACTION`: + +`argK_type` | The type of the K-th (0-based) argument of the mock function +:-------------- | :----------------------------------------------------------- +`args` | All arguments of the mock function as a tuple +`args_type` | The type of all arguments of the mock function as a tuple +`return_type` | The return type of the mock function +`function_type` | The type of the mock function + +For example, when using an `ACTION` as a stub action for mock function: + +```cpp +int DoSomething(bool flag, int* ptr); +``` + +we have: + +Pre-defined Symbol | Is Bound To +------------------ | --------------------------------- +`arg0` | the value of `flag` +`arg0_type` | the type `bool` +`arg1` | the value of `ptr` +`arg1_type` | the type `int*` +`args` | the tuple `(flag, ptr)` +`args_type` | the type `std::tuple` +`return_type` | the type `int` +`function_type` | the type `int(bool, int*)` + +#### Legacy macro-based parameterized Actions + +Sometimes you'll want to parameterize an action you define. For that we have +another macro + +```cpp +ACTION_P(name, param) { statements; } +``` + +For example, + +```cpp +ACTION_P(Add, n) { return arg0 + n; } +``` + +will allow you to write + +```cpp +// Returns argument #0 + 5. +... WillOnce(Add(5)); +``` + +For convenience, we use the term *arguments* for the values used to invoke the +mock function, and the term *parameters* for the values used to instantiate an +action. + +Note that you don't need to provide the type of the parameter either. Suppose +the parameter is named `param`, you can also use the gMock-defined symbol +`param_type` to refer to the type of the parameter as inferred by the compiler. +For example, in the body of `ACTION_P(Add, n)` above, you can write `n_type` for +the type of `n`. + +gMock also provides `ACTION_P2`, `ACTION_P3`, and etc to support multi-parameter +actions. For example, + +```cpp +ACTION_P2(ReturnDistanceTo, x, y) { + double dx = arg0 - x; + double dy = arg1 - y; + return sqrt(dx*dx + dy*dy); +} +``` + +lets you write + +```cpp +... WillOnce(ReturnDistanceTo(5.0, 26.5)); +``` + +You can view `ACTION` as a degenerated parameterized action where the number of +parameters is 0. + +You can also easily define actions overloaded on the number of parameters: + +```cpp +ACTION_P(Plus, a) { ... } +ACTION_P2(Plus, a, b) { ... } +``` + +### Restricting the Type of an Argument or Parameter in an ACTION + +For maximum brevity and reusability, the `ACTION*` macros don't ask you to +provide the types of the mock function arguments and the action parameters. +Instead, we let the compiler infer the types for us. + +Sometimes, however, we may want to be more explicit about the types. There are +several tricks to do that. For example: + +```cpp +ACTION(Foo) { + // Makes sure arg0 can be converted to int. + int n = arg0; + ... use n instead of arg0 here ... +} + +ACTION_P(Bar, param) { + // Makes sure the type of arg1 is const char*. + ::testing::StaticAssertTypeEq(); + + // Makes sure param can be converted to bool. + bool flag = param; +} +``` + +where `StaticAssertTypeEq` is a compile-time assertion in googletest that +verifies two types are the same. + +### Writing New Action Templates Quickly + +Sometimes you want to give an action explicit template parameters that cannot be +inferred from its value parameters. `ACTION_TEMPLATE()` supports that and can be +viewed as an extension to `ACTION()` and `ACTION_P*()`. + +The syntax: + +```cpp +ACTION_TEMPLATE(ActionName, + HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m), + AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; } +``` + +defines an action template that takes *m* explicit template parameters and *n* +value parameters, where *m* is in [1, 10] and *n* is in [0, 10]. `name_i` is the +name of the *i*-th template parameter, and `kind_i` specifies whether it's a +`typename`, an integral constant, or a template. `p_i` is the name of the *i*-th +value parameter. + +Example: + +```cpp +// DuplicateArg(output) converts the k-th argument of the mock +// function to type T and copies it to *output. +ACTION_TEMPLATE(DuplicateArg, + // Note the comma between int and k: + HAS_2_TEMPLATE_PARAMS(int, k, typename, T), + AND_1_VALUE_PARAMS(output)) { + *output = T(std::get(args)); +} +``` + +To create an instance of an action template, write: + +```cpp +ActionName(v1, ..., v_n) +``` + +where the `t`s are the template arguments and the `v`s are the value arguments. +The value argument types are inferred by the compiler. For example: + +```cpp +using ::testing::_; +... + int n; + EXPECT_CALL(mock, Foo).WillOnce(DuplicateArg<1, unsigned char>(&n)); +``` + +If you want to explicitly specify the value argument types, you can provide +additional template arguments: + +```cpp +ActionName(v1, ..., v_n) +``` + +where `u_i` is the desired type of `v_i`. + +`ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the number of +value parameters, but not on the number of template parameters. Without the +restriction, the meaning of the following is unclear: + +```cpp + OverloadedAction(x); +``` + +Are we using a single-template-parameter action where `bool` refers to the type +of `x`, or a two-template-parameter action where the compiler is asked to infer +the type of `x`? + +### Using the ACTION Object's Type + +If you are writing a function that returns an `ACTION` object, you'll need to +know its type. The type depends on the macro used to define the action and the +parameter types. The rule is relatively simple: + +| Given Definition | Expression | Has Type | +| ----------------------------- | ------------------- | --------------------- | +| `ACTION(Foo)` | `Foo()` | `FooAction` | +| `ACTION_TEMPLATE(Foo,` | `Foo()` : t_m>` : +: `AND_0_VALUE_PARAMS())` : : : +| `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP` | +| `ACTION_TEMPLATE(Bar,` | `Bar` | `FooActionP` : +: `AND_1_VALUE_PARAMS(p1))` : : : +| `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value,` | `BazActionP2` : +| `ACTION_TEMPLATE(Baz,` | `Baz` | `FooActionP2` : +: `AND_2_VALUE_PARAMS(p1, p2))` : `int_value)` : : +| ... | ... | ... | + +Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`, +and etc) for actions with different numbers of value parameters, or the action +definitions cannot be overloaded on the number of them. + +### Writing New Monomorphic Actions {#NewMonoActions} + +While the `ACTION*` macros are very convenient, sometimes they are +inappropriate. For example, despite the tricks shown in the previous recipes, +they don't let you directly specify the types of the mock function arguments and +the action parameters, which in general leads to unoptimized compiler error +messages that can baffle unfamiliar users. They also don't allow overloading +actions based on parameter types without jumping through some hoops. + +An alternative to the `ACTION*` macros is to implement +`::testing::ActionInterface`, where `F` is the type of the mock function in +which the action will be used. For example: + +```cpp +template +class ActionInterface { + public: + virtual ~ActionInterface(); + + // Performs the action. Result is the return type of function type + // F, and ArgumentTuple is the tuple of arguments of F. + // + + // For example, if F is int(bool, const string&), then Result would + // be int, and ArgumentTuple would be std::tuple. + virtual Result Perform(const ArgumentTuple& args) = 0; +}; +``` + +```cpp +using ::testing::_; +using ::testing::Action; +using ::testing::ActionInterface; +using ::testing::MakeAction; + +typedef int IncrementMethod(int*); + +class IncrementArgumentAction : public ActionInterface { + public: + int Perform(const std::tuple& args) override { + int* p = std::get<0>(args); // Grabs the first argument. + return *p++; + } +}; + +Action IncrementArgument() { + return MakeAction(new IncrementArgumentAction); +} + +... + EXPECT_CALL(foo, Baz(_)) + .WillOnce(IncrementArgument()); + + int n = 5; + foo.Baz(&n); // Should return 5 and change n to 6. +``` + +### Writing New Polymorphic Actions {#NewPolyActions} + +The previous recipe showed you how to define your own action. This is all good, +except that you need to know the type of the function in which the action will +be used. Sometimes that can be a problem. For example, if you want to use the +action in functions with *different* types (e.g. like `Return()` and +`SetArgPointee()`). + +If an action can be used in several types of mock functions, we say it's +*polymorphic*. The `MakePolymorphicAction()` function template makes it easy to +define such an action: + +```cpp +namespace testing { +template +PolymorphicAction MakePolymorphicAction(const Impl& impl); +} // namespace testing +``` + +As an example, let's define an action that returns the second argument in the +mock function's argument list. The first step is to define an implementation +class: + +```cpp +class ReturnSecondArgumentAction { + public: + template + Result Perform(const ArgumentTuple& args) const { + // To get the i-th (0-based) argument, use std::get(args). + return std::get<1>(args); + } +}; +``` + +This implementation class does *not* need to inherit from any particular class. +What matters is that it must have a `Perform()` method template. This method +template takes the mock function's arguments as a tuple in a **single** +argument, and returns the result of the action. It can be either `const` or not, +but must be invokable with exactly one template argument, which is the result +type. In other words, you must be able to call `Perform(args)` where `R` is +the mock function's return type and `args` is its arguments in a tuple. + +Next, we use `MakePolymorphicAction()` to turn an instance of the implementation +class into the polymorphic action we need. It will be convenient to have a +wrapper for this: + +```cpp +using ::testing::MakePolymorphicAction; +using ::testing::PolymorphicAction; + +PolymorphicAction ReturnSecondArgument() { + return MakePolymorphicAction(ReturnSecondArgumentAction()); +} +``` + +Now, you can use this polymorphic action the same way you use the built-in ones: + +```cpp +using ::testing::_; + +class MockFoo : public Foo { + public: + MOCK_METHOD(int, DoThis, (bool flag, int n), (override)); + MOCK_METHOD(string, DoThat, (int x, const char* str1, const char* str2), + (override)); +}; + + ... + MockFoo foo; + EXPECT_CALL(foo, DoThis).WillOnce(ReturnSecondArgument()); + EXPECT_CALL(foo, DoThat).WillOnce(ReturnSecondArgument()); + ... + foo.DoThis(true, 5); // Will return 5. + foo.DoThat(1, "Hi", "Bye"); // Will return "Hi". +``` + +### Teaching gMock How to Print Your Values + +When an uninteresting or unexpected call occurs, gMock prints the argument +values and the stack trace to help you debug. Assertion macros like +`EXPECT_THAT` and `EXPECT_EQ` also print the values in question when the +assertion fails. gMock and googletest do this using googletest's user-extensible +value printer. + +This printer knows how to print built-in C++ types, native arrays, STL +containers, and any type that supports the `<<` operator. For other types, it +prints the raw bytes in the value and hopes that you the user can figure it out. +[googletest's advanced guide](../../googletest/docs/advanced.md#teaching-googletest-how-to-print-your-values) +explains how to extend the printer to do a better job at printing your +particular type than to dump the bytes. + +## Useful Mocks Created Using gMock + + + + +### Mock std::function {#MockFunction} + +`std::function` is a general function type introduced in C++11. It is a +preferred way of passing callbacks to new interfaces. Functions are copiable, +and are not usually passed around by pointer, which makes them tricky to mock. +But fear not - `MockFunction` can help you with that. + +`MockFunction` has a mock method `Call()` with the signature: + +```cpp + R Call(T1, ..., Tn); +``` + +It also has a `AsStdFunction()` method, which creates a `std::function` proxy +forwarding to Call: + +```cpp + std::function AsStdFunction(); +``` + +To use `MockFunction`, first create `MockFunction` object and set up +expectations on its `Call` method. Then pass proxy obtained from +`AsStdFunction()` to the code you are testing. For example: + +```cpp +TEST(FooTest, RunsCallbackWithBarArgument) { + // 1. Create a mock object. + MockFunction mock_function; + + // 2. Set expectations on Call() method. + EXPECT_CALL(mock_function, Call("bar")).WillOnce(Return(1)); + + // 3. Exercise code that uses std::function. + Foo(mock_function.AsStdFunction()); + // Foo's signature can be either of: + // void Foo(const std::function& fun); + // void Foo(std::function fun); + + // 4. All expectations will be verified when mock_function + // goes out of scope and is destroyed. +} +``` + +Remember that function objects created with `AsStdFunction()` are just +forwarders. If you create multiple of them, they will share the same set of +expectations. + +Although `std::function` supports unlimited number of arguments, `MockFunction` +implementation is limited to ten. If you ever hit that limit... well, your +callback has bigger problems than being mockable. :-) + + diff --git a/docs/gmock_faq.md b/docs/gmock_faq.md new file mode 100644 index 0000000..dc4a11d --- /dev/null +++ b/docs/gmock_faq.md @@ -0,0 +1,398 @@ +## Legacy gMock FAQ {#GMockFaq} + + + + + +### When I call a method on my mock object, the method for the real object is invoked instead. What's the problem? + +In order for a method to be mocked, it must be *virtual*, unless you use the +[high-perf dependency injection technique](gmock_cook_book.md#MockingNonVirtualMethods). + +### Can I mock a variadic function? + +You cannot mock a variadic function (i.e. a function taking ellipsis (`...`) +arguments) directly in gMock. + +The problem is that in general, there is *no way* for a mock object to know how +many arguments are passed to the variadic method, and what the arguments' types +are. Only the *author of the base class* knows the protocol, and we cannot look +into his or her head. + +Therefore, to mock such a function, the *user* must teach the mock object how to +figure out the number of arguments and their types. One way to do it is to +provide overloaded versions of the function. + +Ellipsis arguments are inherited from C and not really a C++ feature. They are +unsafe to use and don't work with arguments that have constructors or +destructors. Therefore we recommend to avoid them in C++ as much as possible. + +### MSVC gives me warning C4301 or C4373 when I define a mock method with a const parameter. Why? + +If you compile this using Microsoft Visual C++ 2005 SP1: + +```cpp +class Foo { + ... + virtual void Bar(const int i) = 0; +}; + +class MockFoo : public Foo { + ... + MOCK_METHOD(void, Bar, (const int i), (override)); +}; +``` + +You may get the following warning: + +```shell +warning C4301: 'MockFoo::Bar': overriding virtual function only differs from 'Foo::Bar' by const/volatile qualifier +``` + +This is a MSVC bug. The same code compiles fine with gcc, for example. If you +use Visual C++ 2008 SP1, you would get the warning: + +```shell +warning C4373: 'MockFoo::Bar': virtual function overrides 'Foo::Bar', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers +``` + +In C++, if you *declare* a function with a `const` parameter, the `const` +modifier is ignored. Therefore, the `Foo` base class above is equivalent to: + +```cpp +class Foo { + ... + virtual void Bar(int i) = 0; // int or const int? Makes no difference. +}; +``` + +In fact, you can *declare* `Bar()` with an `int` parameter, and define it with a +`const int` parameter. The compiler will still match them up. + +Since making a parameter `const` is meaningless in the method declaration, we +recommend to remove it in both `Foo` and `MockFoo`. That should workaround the +VC bug. + +Note that we are talking about the *top-level* `const` modifier here. If the +function parameter is passed by pointer or reference, declaring the pointee or +referee as `const` is still meaningful. For example, the following two +declarations are *not* equivalent: + +```cpp +void Bar(int* p); // Neither p nor *p is const. +void Bar(const int* p); // p is not const, but *p is. +``` + + + +### I can't figure out why gMock thinks my expectations are not satisfied. What should I do? + +You might want to run your test with `--gmock_verbose=info`. This flag lets +gMock print a trace of every mock function call it receives. By studying the +trace, you'll gain insights on why the expectations you set are not met. + +If you see the message "The mock function has no default action set, and its +return type has no default value set.", then try +[adding a default action](gmock_for_dummies.md#DefaultValue). Due to a known +issue, unexpected calls on mocks without default actions don't print out a +detailed comparison between the actual arguments and the expected arguments. + +### My program crashed and `ScopedMockLog` spit out tons of messages. Is it a gMock bug? + +gMock and `ScopedMockLog` are likely doing the right thing here. + +When a test crashes, the failure signal handler will try to log a lot of +information (the stack trace, and the address map, for example). The messages +are compounded if you have many threads with depth stacks. When `ScopedMockLog` +intercepts these messages and finds that they don't match any expectations, it +prints an error for each of them. + +You can learn to ignore the errors, or you can rewrite your expectations to make +your test more robust, for example, by adding something like: + +```cpp +using ::testing::AnyNumber; +using ::testing::Not; +... + // Ignores any log not done by us. + EXPECT_CALL(log, Log(_, Not(EndsWith("/my_file.cc")), _)) + .Times(AnyNumber()); +``` + +### How can I assert that a function is NEVER called? + +```cpp +using ::testing::_; +... + EXPECT_CALL(foo, Bar(_)) + .Times(0); +``` + + + +### I have a failed test where gMock tells me TWICE that a particular expectation is not satisfied. Isn't this redundant? + +When gMock detects a failure, it prints relevant information (the mock function +arguments, the state of relevant expectations, and etc) to help the user debug. +If another failure is detected, gMock will do the same, including printing the +state of relevant expectations. + +Sometimes an expectation's state didn't change between two failures, and you'll +see the same description of the state twice. They are however *not* redundant, +as they refer to *different points in time*. The fact they are the same *is* +interesting information. + +### I get a heapcheck failure when using a mock object, but using a real object is fine. What can be wrong? + +Does the class (hopefully a pure interface) you are mocking have a virtual +destructor? + +Whenever you derive from a base class, make sure its destructor is virtual. +Otherwise Bad Things will happen. Consider the following code: + +```cpp +class Base { + public: + // Not virtual, but should be. + ~Base() { ... } + ... +}; + +class Derived : public Base { + public: + ... + private: + std::string value_; +}; + +... + Base* p = new Derived; + ... + delete p; // Surprise! ~Base() will be called, but ~Derived() will not + // - value_ is leaked. +``` + +By changing `~Base()` to virtual, `~Derived()` will be correctly called when +`delete p` is executed, and the heap checker will be happy. + +### The "newer expectations override older ones" rule makes writing expectations awkward. Why does gMock do that? + +When people complain about this, often they are referring to code like: + +```cpp +using ::testing::Return; +... + // foo.Bar() should be called twice, return 1 the first time, and return + // 2 the second time. However, I have to write the expectations in the + // reverse order. This sucks big time!!! + EXPECT_CALL(foo, Bar()) + .WillOnce(Return(2)) + .RetiresOnSaturation(); + EXPECT_CALL(foo, Bar()) + .WillOnce(Return(1)) + .RetiresOnSaturation(); +``` + +The problem, is that they didn't pick the **best** way to express the test's +intent. + +By default, expectations don't have to be matched in *any* particular order. If +you want them to match in a certain order, you need to be explicit. This is +gMock's (and jMock's) fundamental philosophy: it's easy to accidentally +over-specify your tests, and we want to make it harder to do so. + +There are two better ways to write the test spec. You could either put the +expectations in sequence: + +```cpp +using ::testing::Return; +... + // foo.Bar() should be called twice, return 1 the first time, and return + // 2 the second time. Using a sequence, we can write the expectations + // in their natural order. + { + InSequence s; + EXPECT_CALL(foo, Bar()) + .WillOnce(Return(1)) + .RetiresOnSaturation(); + EXPECT_CALL(foo, Bar()) + .WillOnce(Return(2)) + .RetiresOnSaturation(); + } +``` + +or you can put the sequence of actions in the same expectation: + +```cpp +using ::testing::Return; +... + // foo.Bar() should be called twice, return 1 the first time, and return + // 2 the second time. + EXPECT_CALL(foo, Bar()) + .WillOnce(Return(1)) + .WillOnce(Return(2)) + .RetiresOnSaturation(); +``` + +Back to the original questions: why does gMock search the expectations (and +`ON_CALL`s) from back to front? Because this allows a user to set up a mock's +behavior for the common case early (e.g. in the mock's constructor or the test +fixture's set-up phase) and customize it with more specific rules later. If +gMock searches from front to back, this very useful pattern won't be possible. + +### gMock prints a warning when a function without EXPECT_CALL is called, even if I have set its behavior using ON_CALL. Would it be reasonable not to show the warning in this case? + +When choosing between being neat and being safe, we lean toward the latter. So +the answer is that we think it's better to show the warning. + +Often people write `ON_CALL`s in the mock object's constructor or `SetUp()`, as +the default behavior rarely changes from test to test. Then in the test body +they set the expectations, which are often different for each test. Having an +`ON_CALL` in the set-up part of a test doesn't mean that the calls are expected. +If there's no `EXPECT_CALL` and the method is called, it's possibly an error. If +we quietly let the call go through without notifying the user, bugs may creep in +unnoticed. + +If, however, you are sure that the calls are OK, you can write + +```cpp +using ::testing::_; +... + EXPECT_CALL(foo, Bar(_)) + .WillRepeatedly(...); +``` + +instead of + +```cpp +using ::testing::_; +... + ON_CALL(foo, Bar(_)) + .WillByDefault(...); +``` + +This tells gMock that you do expect the calls and no warning should be printed. + +Also, you can control the verbosity by specifying `--gmock_verbose=error`. Other +values are `info` and `warning`. If you find the output too noisy when +debugging, just choose a less verbose level. + +### How can I delete the mock function's argument in an action? + +If your mock function takes a pointer argument and you want to delete that +argument, you can use testing::DeleteArg() to delete the N'th (zero-indexed) +argument: + +```cpp +using ::testing::_; + ... + MOCK_METHOD(void, Bar, (X* x, const Y& y)); + ... + EXPECT_CALL(mock_foo_, Bar(_, _)) + .WillOnce(testing::DeleteArg<0>())); +``` + +### How can I perform an arbitrary action on a mock function's argument? + +If you find yourself needing to perform some action that's not supported by +gMock directly, remember that you can define your own actions using +[`MakeAction()`](#NewMonoActions) or +[`MakePolymorphicAction()`](#NewPolyActions), or you can write a stub function +and invoke it using [`Invoke()`](#FunctionsAsActions). + +```cpp +using ::testing::_; +using ::testing::Invoke; + ... + MOCK_METHOD(void, Bar, (X* p)); + ... + EXPECT_CALL(mock_foo_, Bar(_)) + .WillOnce(Invoke(MyAction(...))); +``` + +### My code calls a static/global function. Can I mock it? + +You can, but you need to make some changes. + +In general, if you find yourself needing to mock a static function, it's a sign +that your modules are too tightly coupled (and less flexible, less reusable, +less testable, etc). You are probably better off defining a small interface and +call the function through that interface, which then can be easily mocked. It's +a bit of work initially, but usually pays for itself quickly. + +This Google Testing Blog +[post](https://testing.googleblog.com/2008/06/defeat-static-cling.html) says it +excellently. Check it out. + +### My mock object needs to do complex stuff. It's a lot of pain to specify the actions. gMock sucks! + +I know it's not a question, but you get an answer for free any way. :-) + +With gMock, you can create mocks in C++ easily. And people might be tempted to +use them everywhere. Sometimes they work great, and sometimes you may find them, +well, a pain to use. So, what's wrong in the latter case? + +When you write a test without using mocks, you exercise the code and assert that +it returns the correct value or that the system is in an expected state. This is +sometimes called "state-based testing". + +Mocks are great for what some call "interaction-based" testing: instead of +checking the system state at the very end, mock objects verify that they are +invoked the right way and report an error as soon as it arises, giving you a +handle on the precise context in which the error was triggered. This is often +more effective and economical to do than state-based testing. + +If you are doing state-based testing and using a test double just to simulate +the real object, you are probably better off using a fake. Using a mock in this +case causes pain, as it's not a strong point for mocks to perform complex +actions. If you experience this and think that mocks suck, you are just not +using the right tool for your problem. Or, you might be trying to solve the +wrong problem. :-) + +### I got a warning "Uninteresting function call encountered - default action taken.." Should I panic? + +By all means, NO! It's just an FYI. :-) + +What it means is that you have a mock function, you haven't set any expectations +on it (by gMock's rule this means that you are not interested in calls to this +function and therefore it can be called any number of times), and it is called. +That's OK - you didn't say it's not OK to call the function! + +What if you actually meant to disallow this function to be called, but forgot to +write `EXPECT_CALL(foo, Bar()).Times(0)`? While one can argue that it's the +user's fault, gMock tries to be nice and prints you a note. + +So, when you see the message and believe that there shouldn't be any +uninteresting calls, you should investigate what's going on. To make your life +easier, gMock dumps the stack trace when an uninteresting call is encountered. +From that you can figure out which mock function it is, and how it is called. + +### I want to define a custom action. Should I use Invoke() or implement the ActionInterface interface? + +Either way is fine - you want to choose the one that's more convenient for your +circumstance. + +Usually, if your action is for a particular function type, defining it using +`Invoke()` should be easier; if your action can be used in functions of +different types (e.g. if you are defining `Return(*value*)`), +`MakePolymorphicAction()` is easiest. Sometimes you want precise control on what +types of functions the action can be used in, and implementing `ActionInterface` +is the way to go here. See the implementation of `Return()` in +`testing/base/public/gmock-actions.h` for an example. + +### I use SetArgPointee() in WillOnce(), but gcc complains about "conflicting return type specified". What does it mean? + +You got this error as gMock has no idea what value it should return when the +mock method is called. `SetArgPointee()` says what the side effect is, but +doesn't say what the return value should be. You need `DoAll()` to chain a +`SetArgPointee()` with a `Return()` that provides a value appropriate to the API +being mocked. + +See this [recipe](gmock_cook_book.md#mocking-side-effects) for more details and +an example. + +### I have a huge mock class, and Microsoft Visual C++ runs out of memory when compiling it. What can I do? + +We've noticed that when the `/clr` compiler flag is used, Visual C++ uses 5~6 +times as much memory when compiling a mock class. We suggest to avoid `/clr` +when compiling native C++ mocks. diff --git a/docs/gmock_for_dummies.md b/docs/gmock_for_dummies.md new file mode 100644 index 0000000..7bec29a --- /dev/null +++ b/docs/gmock_for_dummies.md @@ -0,0 +1,702 @@ +# gMock for Dummies {#GMockForDummies} + + + + + +## What Is gMock? + +When you write a prototype or test, often it's not feasible or wise to rely on +real objects entirely. A **mock object** implements the same interface as a real +object (so it can be used as one), but lets you specify at run time how it will +be used and what it should do (which methods will be called? in which order? how +many times? with what arguments? what will they return? etc). + +**Note:** It is easy to confuse the term *fake objects* with mock objects. Fakes +and mocks actually mean very different things in the Test-Driven Development +(TDD) community: + +* **Fake** objects have working implementations, but usually take some + shortcut (perhaps to make the operations less expensive), which makes them + not suitable for production. An in-memory file system would be an example of + a fake. +* **Mocks** are objects pre-programmed with *expectations*, which form a + specification of the calls they are expected to receive. + +If all this seems too abstract for you, don't worry - the most important thing +to remember is that a mock allows you to check the *interaction* between itself +and code that uses it. The difference between fakes and mocks shall become much +clearer once you start to use mocks. + +**gMock** is a library (sometimes we also call it a "framework" to make it sound +cool) for creating mock classes and using them. It does to C++ what +jMock/EasyMock does to Java (well, more or less). + +When using gMock, + +1. first, you use some simple macros to describe the interface you want to + mock, and they will expand to the implementation of your mock class; +2. next, you create some mock objects and specify its expectations and behavior + using an intuitive syntax; +3. then you exercise code that uses the mock objects. gMock will catch any + violation to the expectations as soon as it arises. + +## Why gMock? + +While mock objects help you remove unnecessary dependencies in tests and make +them fast and reliable, using mocks manually in C++ is *hard*: + +* Someone has to implement the mocks. The job is usually tedious and + error-prone. No wonder people go great distance to avoid it. +* The quality of those manually written mocks is a bit, uh, unpredictable. You + may see some really polished ones, but you may also see some that were + hacked up in a hurry and have all sorts of ad hoc restrictions. +* The knowledge you gained from using one mock doesn't transfer to the next + one. + +In contrast, Java and Python programmers have some fine mock frameworks (jMock, +EasyMock, [Mox](http://wtf/mox), etc), which automate the creation of mocks. As +a result, mocking is a proven effective technique and widely adopted practice in +those communities. Having the right tool absolutely makes the difference. + +gMock was built to help C++ programmers. It was inspired by jMock and EasyMock, +but designed with C++'s specifics in mind. It is your friend if any of the +following problems is bothering you: + +* You are stuck with a sub-optimal design and wish you had done more + prototyping before it was too late, but prototyping in C++ is by no means + "rapid". +* Your tests are slow as they depend on too many libraries or use expensive + resources (e.g. a database). +* Your tests are brittle as some resources they use are unreliable (e.g. the + network). +* You want to test how your code handles a failure (e.g. a file checksum + error), but it's not easy to cause one. +* You need to make sure that your module interacts with other modules in the + right way, but it's hard to observe the interaction; therefore you resort to + observing the side effects at the end of the action, but it's awkward at + best. +* You want to "mock out" your dependencies, except that they don't have mock + implementations yet; and, frankly, you aren't thrilled by some of those + hand-written mocks. + +We encourage you to use gMock as + +* a *design* tool, for it lets you experiment with your interface design early + and often. More iterations lead to better designs! +* a *testing* tool to cut your tests' outbound dependencies and probe the + interaction between your module and its collaborators. + +## Getting Started + +gMock is bundled with googletest. + +## A Case for Mock Turtles + +Let's look at an example. Suppose you are developing a graphics program that +relies on a [LOGO](http://en.wikipedia.org/wiki/Logo_programming_language)-like +API for drawing. How would you test that it does the right thing? Well, you can +run it and compare the screen with a golden screen snapshot, but let's admit it: +tests like this are expensive to run and fragile (What if you just upgraded to a +shiny new graphics card that has better anti-aliasing? Suddenly you have to +update all your golden images.). It would be too painful if all your tests are +like this. Fortunately, you learned about +[Dependency Injection](http://en.wikipedia.org/wiki/Dependency_injection) and know the right thing +to do: instead of having your application talk to the system API directly, wrap +the API in an interface (say, `Turtle`) and code to that interface: + +```cpp +class Turtle { + ... + virtual ~Turtle() {} + virtual void PenUp() = 0; + virtual void PenDown() = 0; + virtual void Forward(int distance) = 0; + virtual void Turn(int degrees) = 0; + virtual void GoTo(int x, int y) = 0; + virtual int GetX() const = 0; + virtual int GetY() const = 0; +}; +``` + +(Note that the destructor of `Turtle` **must** be virtual, as is the case for +**all** classes you intend to inherit from - otherwise the destructor of the +derived class will not be called when you delete an object through a base +pointer, and you'll get corrupted program states like memory leaks.) + +You can control whether the turtle's movement will leave a trace using `PenUp()` +and `PenDown()`, and control its movement using `Forward()`, `Turn()`, and +`GoTo()`. Finally, `GetX()` and `GetY()` tell you the current position of the +turtle. + +Your program will normally use a real implementation of this interface. In +tests, you can use a mock implementation instead. This allows you to easily +check what drawing primitives your program is calling, with what arguments, and +in which order. Tests written this way are much more robust (they won't break +because your new machine does anti-aliasing differently), easier to read and +maintain (the intent of a test is expressed in the code, not in some binary +images), and run *much, much faster*. + +## Writing the Mock Class + +If you are lucky, the mocks you need to use have already been implemented by +some nice people. If, however, you find yourself in the position to write a mock +class, relax - gMock turns this task into a fun game! (Well, almost.) + +### How to Define It + +Using the `Turtle` interface as example, here are the simple steps you need to +follow: + +* Derive a class `MockTurtle` from `Turtle`. +* Take a *virtual* function of `Turtle` (while it's possible to + [mock non-virtual methods using templates](gmock_cook_book.md#MockingNonVirtualMethods), + it's much more involved). +* In the `public:` section of the child class, write `MOCK_METHOD();` +* Now comes the fun part: you take the function signature, cut-and-paste it + into the macro, and add two commas - one between the return type and the + name, another between the name and the argument list. +* If you're mocking a const method, add a 4th parameter containing `(const)` + (the parentheses are required). +* Since you're overriding a virtual method, we suggest adding the `override` + keyword. For const methods the 4th parameter becomes `(const, override)`, + for non-const methods just `(override)`. This isn't mandatory. +* Repeat until all virtual functions you want to mock are done. (It goes + without saying that *all* pure virtual methods in your abstract class must + be either mocked or overridden.) + +After the process, you should have something like: + +```cpp +#include "gmock/gmock.h" // Brings in gMock. + +class MockTurtle : public Turtle { + public: + ... + MOCK_METHOD(void, PenUp, (), (override)); + MOCK_METHOD(void, PenDown, (), (override)); + MOCK_METHOD(void, Forward, (int distance), (override)); + MOCK_METHOD(void, Turn, (int degrees), (override)); + MOCK_METHOD(void, GoTo, (int x, int y), (override)); + MOCK_METHOD(int, GetX, (), (const, override)); + MOCK_METHOD(int, GetY, (), (const, override)); +}; +``` + +You don't need to define these mock methods somewhere else - the `MOCK_METHOD` +macro will generate the definitions for you. It's that simple! + +### Where to Put It + +When you define a mock class, you need to decide where to put its definition. +Some people put it in a `_test.cc`. This is fine when the interface being mocked +(say, `Foo`) is owned by the same person or team. Otherwise, when the owner of +`Foo` changes it, your test could break. (You can't really expect `Foo`'s +maintainer to fix every test that uses `Foo`, can you?) + +So, the rule of thumb is: if you need to mock `Foo` and it's owned by others, +define the mock class in `Foo`'s package (better, in a `testing` sub-package +such that you can clearly separate production code and testing utilities), put +it in a `.h` and a `cc_library`. Then everyone can reference them from their +tests. If `Foo` ever changes, there is only one copy of `MockFoo` to change, and +only tests that depend on the changed methods need to be fixed. + +Another way to do it: you can introduce a thin layer `FooAdaptor` on top of +`Foo` and code to this new interface. Since you own `FooAdaptor`, you can absorb +changes in `Foo` much more easily. While this is more work initially, carefully +choosing the adaptor interface can make your code easier to write and more +readable (a net win in the long run), as you can choose `FooAdaptor` to fit your +specific domain much better than `Foo` does. + + + +## Using Mocks in Tests + +Once you have a mock class, using it is easy. The typical work flow is: + +1. Import the gMock names from the `testing` namespace such that you can use + them unqualified (You only have to do it once per file). Remember that + namespaces are a good idea. +2. Create some mock objects. +3. Specify your expectations on them (How many times will a method be called? + With what arguments? What should it do? etc.). +4. Exercise some code that uses the mocks; optionally, check the result using + googletest assertions. If a mock method is called more than expected or with + wrong arguments, you'll get an error immediately. +5. When a mock is destructed, gMock will automatically check whether all + expectations on it have been satisfied. + +Here's an example: + +```cpp +#include "path/to/mock-turtle.h" +#include "gmock/gmock.h" +#include "gtest/gtest.h" + +using ::testing::AtLeast; // #1 + +TEST(PainterTest, CanDrawSomething) { + MockTurtle turtle; // #2 + EXPECT_CALL(turtle, PenDown()) // #3 + .Times(AtLeast(1)); + + Painter painter(&turtle); // #4 + + EXPECT_TRUE(painter.DrawCircle(0, 0, 10)); // #5 +} +``` + +As you might have guessed, this test checks that `PenDown()` is called at least +once. If the `painter` object didn't call this method, your test will fail with +a message like this: + +```text +path/to/my_test.cc:119: Failure +Actual function call count doesn't match this expectation: +Actually: never called; +Expected: called at least once. +Stack trace: +... +``` + +**Tip 1:** If you run the test from an Emacs buffer, you can hit `` on +the line number to jump right to the failed expectation. + +**Tip 2:** If your mock objects are never deleted, the final verification won't +happen. Therefore it's a good idea to turn on the heap checker in your tests +when you allocate mocks on the heap. You get that automatically if you use the +`gtest_main` library already. + +**Important note:** gMock requires expectations to be set **before** the mock +functions are called, otherwise the behavior is **undefined**. In particular, +you mustn't interleave `EXPECT_CALL()s` and calls to the mock functions. + +This means `EXPECT_CALL()` should be read as expecting that a call will occur +*in the future*, not that a call has occurred. Why does gMock work like that? +Well, specifying the expectation beforehand allows gMock to report a violation +as soon as it rises, when the context (stack trace, etc) is still available. +This makes debugging much easier. + +Admittedly, this test is contrived and doesn't do much. You can easily achieve +the same effect without using gMock. However, as we shall reveal soon, gMock +allows you to do *so much more* with the mocks. + +## Setting Expectations + +The key to using a mock object successfully is to set the *right expectations* +on it. If you set the expectations too strict, your test will fail as the result +of unrelated changes. If you set them too loose, bugs can slip through. You want +to do it just right such that your test can catch exactly the kind of bugs you +intend it to catch. gMock provides the necessary means for you to do it "just +right." + +### General Syntax + +In gMock we use the `EXPECT_CALL()` macro to set an expectation on a mock +method. The general syntax is: + +```cpp +EXPECT_CALL(mock_object, method(matchers)) + .Times(cardinality) + .WillOnce(action) + .WillRepeatedly(action); +``` + +The macro has two arguments: first the mock object, and then the method and its +arguments. Note that the two are separated by a comma (`,`), not a period (`.`). +(Why using a comma? The answer is that it was necessary for technical reasons.) +If the method is not overloaded, the macro can also be called without matchers: + +```cpp +EXPECT_CALL(mock_object, non-overloaded-method) + .Times(cardinality) + .WillOnce(action) + .WillRepeatedly(action); +``` + +This syntax allows the test writer to specify "called with any arguments" +without explicitly specifying the number or types of arguments. To avoid +unintended ambiguity, this syntax may only be used for methods which are not +overloaded + +Either form of the macro can be followed by some optional *clauses* that provide +more information about the expectation. We'll discuss how each clause works in +the coming sections. + +This syntax is designed to make an expectation read like English. For example, +you can probably guess that + +```cpp +using ::testing::Return; +... +EXPECT_CALL(turtle, GetX()) + .Times(5) + .WillOnce(Return(100)) + .WillOnce(Return(150)) + .WillRepeatedly(Return(200)); +``` + +says that the `turtle` object's `GetX()` method will be called five times, it +will return 100 the first time, 150 the second time, and then 200 every time. +Some people like to call this style of syntax a Domain-Specific Language (DSL). + +**Note:** Why do we use a macro to do this? Well it serves two purposes: first +it makes expectations easily identifiable (either by `gsearch` or by a human +reader), and second it allows gMock to include the source file location of a +failed expectation in messages, making debugging easier. + +### Matchers: What Arguments Do We Expect? + +When a mock function takes arguments, we may specify what arguments we are +expecting, for example: + +```cpp +// Expects the turtle to move forward by 100 units. +EXPECT_CALL(turtle, Forward(100)); +``` + +Oftentimes you do not want to be too specific. Remember that talk about tests +being too rigid? Over specification leads to brittle tests and obscures the +intent of tests. Therefore we encourage you to specify only what's necessary—no +more, no less. If you aren't interested in the value of an argument, write `_` +as the argument, which means "anything goes": + +```cpp +using ::testing::_; +... +// Expects that the turtle jumps to somewhere on the x=50 line. +EXPECT_CALL(turtle, GoTo(50, _)); +``` + +`_` is an instance of what we call **matchers**. A matcher is like a predicate +and can test whether an argument is what we'd expect. You can use a matcher +inside `EXPECT_CALL()` wherever a function argument is expected. `_` is a +convenient way of saying "any value". + +In the above examples, `100` and `50` are also matchers; implicitly, they are +the same as `Eq(100)` and `Eq(50)`, which specify that the argument must be +equal (using `operator==`) to the matcher argument. There are many +[built-in matchers](gmock_cheat_sheet.md#MatcherList) for common types (as well +as [custom matchers](gmock_cook_book.md#NewMatchers)); for example: + +```cpp +using ::testing::Ge; +... +// Expects the turtle moves forward by at least 100. +EXPECT_CALL(turtle, Forward(Ge(100))); +``` + +If you don't care about *any* arguments, rather than specify `_` for each of +them you may instead omit the parameter list: + +```cpp +// Expects the turtle to move forward. +EXPECT_CALL(turtle, Forward); +// Expects the turtle to jump somewhere. +EXPECT_CALL(turtle, GoTo); +``` + +This works for all non-overloaded methods; if a method is overloaded, you need +to help gMock resolve which overload is expected by specifying the number of +arguments and possibly also the +[types of the arguments](gmock_cook_book.md#SelectOverload). + +### Cardinalities: How Many Times Will It Be Called? + +The first clause we can specify following an `EXPECT_CALL()` is `Times()`. We +call its argument a **cardinality** as it tells *how many times* the call should +occur. It allows us to repeat an expectation many times without actually writing +it as many times. More importantly, a cardinality can be "fuzzy", just like a +matcher can be. This allows a user to express the intent of a test exactly. + +An interesting special case is when we say `Times(0)`. You may have guessed - it +means that the function shouldn't be called with the given arguments at all, and +gMock will report a googletest failure whenever the function is (wrongfully) +called. + +We've seen `AtLeast(n)` as an example of fuzzy cardinalities earlier. For the +list of built-in cardinalities you can use, see +[here](gmock_cheat_sheet.md#CardinalityList). + +The `Times()` clause can be omitted. **If you omit `Times()`, gMock will infer +the cardinality for you.** The rules are easy to remember: + +* If **neither** `WillOnce()` **nor** `WillRepeatedly()` is in the + `EXPECT_CALL()`, the inferred cardinality is `Times(1)`. +* If there are *n* `WillOnce()`'s but **no** `WillRepeatedly()`, where *n* >= + 1, the cardinality is `Times(n)`. +* If there are *n* `WillOnce()`'s and **one** `WillRepeatedly()`, where *n* >= + 0, the cardinality is `Times(AtLeast(n))`. + +**Quick quiz:** what do you think will happen if a function is expected to be +called twice but actually called four times? + +### Actions: What Should It Do? + +Remember that a mock object doesn't really have a working implementation? We as +users have to tell it what to do when a method is invoked. This is easy in +gMock. + +First, if the return type of a mock function is a built-in type or a pointer, +the function has a **default action** (a `void` function will just return, a +`bool` function will return `false`, and other functions will return 0). In +addition, in C++ 11 and above, a mock function whose return type is +default-constructible (i.e. has a default constructor) has a default action of +returning a default-constructed value. If you don't say anything, this behavior +will be used. + +Second, if a mock function doesn't have a default action, or the default action +doesn't suit you, you can specify the action to be taken each time the +expectation matches using a series of `WillOnce()` clauses followed by an +optional `WillRepeatedly()`. For example, + +```cpp +using ::testing::Return; +... +EXPECT_CALL(turtle, GetX()) + .WillOnce(Return(100)) + .WillOnce(Return(200)) + .WillOnce(Return(300)); +``` + +says that `turtle.GetX()` will be called *exactly three times* (gMock inferred +this from how many `WillOnce()` clauses we've written, since we didn't +explicitly write `Times()`), and will return 100, 200, and 300 respectively. + +```cpp +using ::testing::Return; +... +EXPECT_CALL(turtle, GetY()) + .WillOnce(Return(100)) + .WillOnce(Return(200)) + .WillRepeatedly(Return(300)); +``` + +says that `turtle.GetY()` will be called *at least twice* (gMock knows this as +we've written two `WillOnce()` clauses and a `WillRepeatedly()` while having no +explicit `Times()`), will return 100 and 200 respectively the first two times, +and 300 from the third time on. + +Of course, if you explicitly write a `Times()`, gMock will not try to infer the +cardinality itself. What if the number you specified is larger than there are +`WillOnce()` clauses? Well, after all `WillOnce()`s are used up, gMock will do +the *default* action for the function every time (unless, of course, you have a +`WillRepeatedly()`.). + +What can we do inside `WillOnce()` besides `Return()`? You can return a +reference using `ReturnRef(*variable*)`, or invoke a pre-defined function, among +[others](gmock_cook_book.md#using-actions). + +**Important note:** The `EXPECT_CALL()` statement evaluates the action clause +only once, even though the action may be performed many times. Therefore you +must be careful about side effects. The following may not do what you want: + +```cpp +using ::testing::Return; +... +int n = 100; +EXPECT_CALL(turtle, GetX()) + .Times(4) + .WillRepeatedly(Return(n++)); +``` + +Instead of returning 100, 101, 102, ..., consecutively, this mock function will +always return 100 as `n++` is only evaluated once. Similarly, `Return(new Foo)` +will create a new `Foo` object when the `EXPECT_CALL()` is executed, and will +return the same pointer every time. If you want the side effect to happen every +time, you need to define a custom action, which we'll teach in the +[cook book](http://). + +Time for another quiz! What do you think the following means? + +```cpp +using ::testing::Return; +... +EXPECT_CALL(turtle, GetY()) + .Times(4) + .WillOnce(Return(100)); +``` + +Obviously `turtle.GetY()` is expected to be called four times. But if you think +it will return 100 every time, think twice! Remember that one `WillOnce()` +clause will be consumed each time the function is invoked and the default action +will be taken afterwards. So the right answer is that `turtle.GetY()` will +return 100 the first time, but **return 0 from the second time on**, as +returning 0 is the default action for `int` functions. + +### Using Multiple Expectations {#MultiExpectations} + +So far we've only shown examples where you have a single expectation. More +realistically, you'll specify expectations on multiple mock methods which may be +from multiple mock objects. + +By default, when a mock method is invoked, gMock will search the expectations in +the **reverse order** they are defined, and stop when an active expectation that +matches the arguments is found (you can think of it as "newer rules override +older ones."). If the matching expectation cannot take any more calls, you will +get an upper-bound-violated failure. Here's an example: + +```cpp +using ::testing::_; +... +EXPECT_CALL(turtle, Forward(_)); // #1 +EXPECT_CALL(turtle, Forward(10)) // #2 + .Times(2); +``` + +If `Forward(10)` is called three times in a row, the third time it will be an +error, as the last matching expectation (#2) has been saturated. If, however, +the third `Forward(10)` call is replaced by `Forward(20)`, then it would be OK, +as now #1 will be the matching expectation. + +**Note:** Why does gMock search for a match in the *reverse* order of the +expectations? The reason is that this allows a user to set up the default +expectations in a mock object's constructor or the test fixture's set-up phase +and then customize the mock by writing more specific expectations in the test +body. So, if you have two expectations on the same method, you want to put the +one with more specific matchers **after** the other, or the more specific rule +would be shadowed by the more general one that comes after it. + +**Tip:** It is very common to start with a catch-all expectation for a method +and `Times(AnyNumber())` (omitting arguments, or with `_` for all arguments, if +overloaded). This makes any calls to the method expected. This is not necessary +for methods that are not mentioned at all (these are "uninteresting"), but is +useful for methods that have some expectations, but for which other calls are +ok. See +[Understanding Uninteresting vs Unexpected Calls](gmock_cook_book.md#uninteresting-vs-unexpected). + +### Ordered vs Unordered Calls {#OrderedCalls} + +By default, an expectation can match a call even though an earlier expectation +hasn't been satisfied. In other words, the calls don't have to occur in the +order the expectations are specified. + +Sometimes, you may want all the expected calls to occur in a strict order. To +say this in gMock is easy: + +```cpp +using ::testing::InSequence; +... +TEST(FooTest, DrawsLineSegment) { + ... + { + InSequence seq; + + EXPECT_CALL(turtle, PenDown()); + EXPECT_CALL(turtle, Forward(100)); + EXPECT_CALL(turtle, PenUp()); + } + Foo(); +} +``` + +By creating an object of type `InSequence`, all expectations in its scope are +put into a *sequence* and have to occur *sequentially*. Since we are just +relying on the constructor and destructor of this object to do the actual work, +its name is really irrelevant. + +In this example, we test that `Foo()` calls the three expected functions in the +order as written. If a call is made out-of-order, it will be an error. + +(What if you care about the relative order of some of the calls, but not all of +them? Can you specify an arbitrary partial order? The answer is ... yes! The +details can be found [here](gmock_cook_book.md#OrderedCalls).) + +### All Expectations Are Sticky (Unless Said Otherwise) {#StickyExpectations} + +Now let's do a quick quiz to see how well you can use this mock stuff already. +How would you test that the turtle is asked to go to the origin *exactly twice* +(you want to ignore any other instructions it receives)? + +After you've come up with your answer, take a look at ours and compare notes +(solve it yourself first - don't cheat!): + +```cpp +using ::testing::_; +using ::testing::AnyNumber; +... +EXPECT_CALL(turtle, GoTo(_, _)) // #1 + .Times(AnyNumber()); +EXPECT_CALL(turtle, GoTo(0, 0)) // #2 + .Times(2); +``` + +Suppose `turtle.GoTo(0, 0)` is called three times. In the third time, gMock will +see that the arguments match expectation #2 (remember that we always pick the +last matching expectation). Now, since we said that there should be only two +such calls, gMock will report an error immediately. This is basically what we've +told you in the [Using Multiple Expectations](#MultiExpectations) section above. + +This example shows that **expectations in gMock are "sticky" by default**, in +the sense that they remain active even after we have reached their invocation +upper bounds. This is an important rule to remember, as it affects the meaning +of the spec, and is **different** to how it's done in many other mocking +frameworks (Why'd we do that? Because we think our rule makes the common cases +easier to express and understand.). + +Simple? Let's see if you've really understood it: what does the following code +say? + +```cpp +using ::testing::Return; +... +for (int i = n; i > 0; i--) { + EXPECT_CALL(turtle, GetX()) + .WillOnce(Return(10*i)); +} +``` + +If you think it says that `turtle.GetX()` will be called `n` times and will +return 10, 20, 30, ..., consecutively, think twice! The problem is that, as we +said, expectations are sticky. So, the second time `turtle.GetX()` is called, +the last (latest) `EXPECT_CALL()` statement will match, and will immediately +lead to an "upper bound violated" error - this piece of code is not very useful! + +One correct way of saying that `turtle.GetX()` will return 10, 20, 30, ..., is +to explicitly say that the expectations are *not* sticky. In other words, they +should *retire* as soon as they are saturated: + +```cpp +using ::testing::Return; +... +for (int i = n; i > 0; i--) { + EXPECT_CALL(turtle, GetX()) + .WillOnce(Return(10*i)) + .RetiresOnSaturation(); +} +``` + +And, there's a better way to do it: in this case, we expect the calls to occur +in a specific order, and we line up the actions to match the order. Since the +order is important here, we should make it explicit using a sequence: + +```cpp +using ::testing::InSequence; +using ::testing::Return; +... +{ + InSequence s; + + for (int i = 1; i <= n; i++) { + EXPECT_CALL(turtle, GetX()) + .WillOnce(Return(10*i)) + .RetiresOnSaturation(); + } +} +``` + +By the way, the other situation where an expectation may *not* be sticky is when +it's in a sequence - as soon as another expectation that comes after it in the +sequence has been used, it automatically retires (and will never be used to +match any call). + +### Uninteresting Calls + +A mock object may have many methods, and not all of them are that interesting. +For example, in some tests we may not care about how many times `GetX()` and +`GetY()` get called. + +In gMock, if you are not interested in a method, just don't say anything about +it. If a call to this method occurs, you'll see a warning in the test output, +but it won't be a failure. This is called "naggy" behavior; to change, see +[The Nice, the Strict, and the Naggy](gmock_cook_book.md#NiceStrictNaggy). diff --git a/docs/pkgconfig.md b/docs/pkgconfig.md new file mode 100644 index 0000000..aed4ad4 --- /dev/null +++ b/docs/pkgconfig.md @@ -0,0 +1,150 @@ +## Using GoogleTest from various build systems + + + +GoogleTest comes with pkg-config files that can be used to determine all +necessary flags for compiling and linking to GoogleTest (and GoogleMock). +Pkg-config is a standardised plain-text format containing + +* the includedir (-I) path +* necessary macro (-D) definitions +* further required flags (-pthread) +* the library (-L) path +* the library (-l) to link to + +All current build systems support pkg-config in one way or another. For all +examples here we assume you want to compile the sample +`samples/sample3_unittest.cc`. + +### CMake + +Using `pkg-config` in CMake is fairly easy: + +```cmake +cmake_minimum_required(VERSION 3.0) + +cmake_policy(SET CMP0048 NEW) +project(my_gtest_pkgconfig VERSION 0.0.1 LANGUAGES CXX) + +find_package(PkgConfig) +pkg_search_module(GTEST REQUIRED gtest_main) + +add_executable(testapp samples/sample3_unittest.cc) +target_link_libraries(testapp ${GTEST_LDFLAGS}) +target_compile_options(testapp PUBLIC ${GTEST_CFLAGS}) + +include(CTest) +add_test(first_and_only_test testapp) +``` + +It is generally recommended that you use `target_compile_options` + `_CFLAGS` +over `target_include_directories` + `_INCLUDE_DIRS` as the former includes not +just -I flags (GoogleTest might require a macro indicating to internal headers +that all libraries have been compiled with threading enabled. In addition, +GoogleTest might also require `-pthread` in the compiling step, and as such +splitting the pkg-config `Cflags` variable into include dirs and macros for +`target_compile_definitions()` might still miss this). The same recommendation +goes for using `_LDFLAGS` over the more commonplace `_LIBRARIES`, which happens +to discard `-L` flags and `-pthread`. + +### Help! pkg-config can't find GoogleTest! + +Let's say you have a `CMakeLists.txt` along the lines of the one in this +tutorial and you try to run `cmake`. It is very possible that you get a failure +along the lines of: + +``` +-- Checking for one of the modules 'gtest_main' +CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:640 (message): + None of the required 'gtest_main' found +``` + +These failures are common if you installed GoogleTest yourself and have not +sourced it from a distro or other package manager. If so, you need to tell +pkg-config where it can find the `.pc` files containing the information. Say you +installed GoogleTest to `/usr/local`, then it might be that the `.pc` files are +installed under `/usr/local/lib64/pkgconfig`. If you set + +``` +export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig +``` + +pkg-config will also try to look in `PKG_CONFIG_PATH` to find `gtest_main.pc`. + +### Using pkg-config in a cross-compilation setting + +Pkg-config can be used in a cross-compilation setting too. To do this, let's +assume the final prefix of the cross-compiled installation will be `/usr`, and +your sysroot is `/home/MYUSER/sysroot`. Configure and install GTest using + +``` +mkdir build && cmake -DCMAKE_INSTALL_PREFIX=/usr .. +``` + +Install into the sysroot using `DESTDIR`: + +``` +make -j install DESTDIR=/home/MYUSER/sysroot +``` + +Before we continue, it is recommended to **always** define the following two +variables for pkg-config in a cross-compilation setting: + +``` +export PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=yes +export PKG_CONFIG_ALLOW_SYSTEM_LIBS=yes +``` + +otherwise `pkg-config` will filter `-I` and `-L` flags against standard prefixes +such as `/usr` (see https://bugs.freedesktop.org/show_bug.cgi?id=28264#c3 for +reasons why this stripping needs to occur usually). + +If you look at the generated pkg-config file, it will look something like + +``` +libdir=/usr/lib64 +includedir=/usr/include + +Name: gtest +Description: GoogleTest (without main() function) +Version: 1.10.0 +URL: https://github.com/google/googletest +Libs: -L${libdir} -lgtest -lpthread +Cflags: -I${includedir} -DGTEST_HAS_PTHREAD=1 -lpthread +``` + +Notice that the sysroot is not included in `libdir` and `includedir`! If you try +to run `pkg-config` with the correct +`PKG_CONFIG_LIBDIR=/home/MYUSER/sysroot/usr/lib64/pkgconfig` against this `.pc` +file, you will get + +``` +$ pkg-config --cflags gtest +-DGTEST_HAS_PTHREAD=1 -lpthread -I/usr/include +$ pkg-config --libs gtest +-L/usr/lib64 -lgtest -lpthread +``` + +which is obviously wrong and points to the `CBUILD` and not `CHOST` root. In +order to use this in a cross-compilation setting, we need to tell pkg-config to +inject the actual sysroot into `-I` and `-L` variables. Let us now tell +pkg-config about the actual sysroot + +``` +export PKG_CONFIG_DIR= +export PKG_CONFIG_SYSROOT_DIR=/home/MYUSER/sysroot +export PKG_CONFIG_LIBDIR=${PKG_CONFIG_SYSROOT_DIR}/usr/lib64/pkgconfig +``` + +and running `pkg-config` again we get + +``` +$ pkg-config --cflags gtest +-DGTEST_HAS_PTHREAD=1 -lpthread -I/home/MYUSER/sysroot/usr/include +$ pkg-config --libs gtest +-L/home/MYUSER/sysroot/usr/lib64 -lgtest -lpthread +``` + +which contains the correct sysroot now. For a more comprehensive guide to also +including `${CHOST}` in build system calls, see the excellent tutorial by Diego +Elio Pettenò: https://autotools.io/pkgconfig/cross-compiling.html diff --git a/docs/primer.md b/docs/primer.md new file mode 100644 index 0000000..28c1691 --- /dev/null +++ b/docs/primer.md @@ -0,0 +1,583 @@ +# Googletest Primer + + + + + +## Introduction: Why googletest? + +*googletest* helps you write better C++ tests. + +googletest is a testing framework developed by the Testing Technology team with +Google's specific requirements and constraints in mind. Whether you work on +Linux, Windows, or a Mac, if you write C++ code, googletest can help you. And it +supports *any* kind of tests, not just unit tests. + +So what makes a good test, and how does googletest fit in? We believe: + +1. Tests should be *independent* and *repeatable*. It's a pain to debug a test + that succeeds or fails as a result of other tests. googletest isolates the + tests by running each of them on a different object. When a test fails, + googletest allows you to run it in isolation for quick debugging. +2. Tests should be well *organized* and reflect the structure of the tested + code. googletest groups related tests into test suites that can share data + and subroutines. This common pattern is easy to recognize and makes tests + easy to maintain. Such consistency is especially helpful when people switch + projects and start to work on a new code base. +3. Tests should be *portable* and *reusable*. Google has a lot of code that is + platform-neutral; its tests should also be platform-neutral. googletest + works on different OSes, with different compilers, with or without + exceptions, so googletest tests can work with a variety of configurations. +4. When tests fail, they should provide as much *information* about the problem + as possible. googletest doesn't stop at the first test failure. Instead, it + only stops the current test and continues with the next. You can also set up + tests that report non-fatal failures after which the current test continues. + Thus, you can detect and fix multiple bugs in a single run-edit-compile + cycle. +5. The testing framework should liberate test writers from housekeeping chores + and let them focus on the test *content*. googletest automatically keeps + track of all tests defined, and doesn't require the user to enumerate them + in order to run them. +6. Tests should be *fast*. With googletest, you can reuse shared resources + across tests and pay for the set-up/tear-down only once, without making + tests depend on each other. + +Since googletest is based on the popular xUnit architecture, you'll feel right +at home if you've used JUnit or PyUnit before. If not, it will take you about 10 +minutes to learn the basics and get started. So let's go! + +## Beware of the nomenclature + +_Note:_ There might be some confusion arising from different definitions of the +terms _Test_, _Test Case_ and _Test Suite_, so beware of misunderstanding these. + +Historically, googletest started to use the term _Test Case_ for grouping +related tests, whereas current publications, including International Software +Testing Qualifications Board ([ISTQB](http://www.istqb.org/)) materials and +various textbooks on software quality, use the term +_[Test Suite][istqb test suite]_ for this. + +The related term _Test_, as it is used in googletest, corresponds to the term +_[Test Case][istqb test case]_ of ISTQB and others. + +The term _Test_ is commonly of broad enough sense, including ISTQB's definition +of _Test Case_, so it's not much of a problem here. But the term _Test Case_ as +was used in Google Test is of contradictory sense and thus confusing. + +googletest recently started replacing the term _Test Case_ with _Test Suite_. +The preferred API is *TestSuite*. The older TestCase API is being slowly +deprecated and refactored away. + +So please be aware of the different definitions of the terms: + + + +Meaning | googletest Term | [ISTQB](http://www.istqb.org/) Term +:----------------------------------------------------------------------------------- | :---------------------- | :---------------------------------- +Exercise a particular program path with specific input values and verify the results | [TEST()](#simple-tests) | [Test Case][istqb test case] + + + +[istqb test case]: http://glossary.istqb.org/en/search/test%20case +[istqb test suite]: http://glossary.istqb.org/en/search/test%20suite + +## Basic Concepts + +When using googletest, you start by writing *assertions*, which are statements +that check whether a condition is true. An assertion's result can be *success*, +*nonfatal failure*, or *fatal failure*. If a fatal failure occurs, it aborts the +current function; otherwise the program continues normally. + +*Tests* use assertions to verify the tested code's behavior. If a test crashes +or has a failed assertion, then it *fails*; otherwise it *succeeds*. + +A *test suite* contains one or many tests. You should group your tests into test +suites that reflect the structure of the tested code. When multiple tests in a +test suite need to share common objects and subroutines, you can put them into a +*test fixture* class. + +A *test program* can contain multiple test suites. + +We'll now explain how to write a test program, starting at the individual +assertion level and building up to tests and test suites. + +## Assertions + +googletest assertions are macros that resemble function calls. You test a class +or function by making assertions about its behavior. When an assertion fails, +googletest prints the assertion's source file and line number location, along +with a failure message. You may also supply a custom failure message which will +be appended to googletest's message. + +The assertions come in pairs that test the same thing but have different effects +on the current function. `ASSERT_*` versions generate fatal failures when they +fail, and **abort the current function**. `EXPECT_*` versions generate nonfatal +failures, which don't abort the current function. Usually `EXPECT_*` are +preferred, as they allow more than one failure to be reported in a test. +However, you should use `ASSERT_*` if it doesn't make sense to continue when the +assertion in question fails. + +Since a failed `ASSERT_*` returns from the current function immediately, +possibly skipping clean-up code that comes after it, it may cause a space leak. +Depending on the nature of the leak, it may or may not be worth fixing - so keep +this in mind if you get a heap checker error in addition to assertion errors. + +To provide a custom failure message, simply stream it into the macro using the +`<<` operator or a sequence of such operators. An example: + +```c++ +ASSERT_EQ(x.size(), y.size()) << "Vectors x and y are of unequal length"; + +for (int i = 0; i < x.size(); ++i) { + EXPECT_EQ(x[i], y[i]) << "Vectors x and y differ at index " << i; +} +``` + +Anything that can be streamed to an `ostream` can be streamed to an assertion +macro--in particular, C strings and `string` objects. If a wide string +(`wchar_t*`, `TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is +streamed to an assertion, it will be translated to UTF-8 when printed. + +### Basic Assertions + +These assertions do basic true/false condition testing. + +Fatal assertion | Nonfatal assertion | Verifies +-------------------------- | -------------------------- | -------------------- +`ASSERT_TRUE(condition);` | `EXPECT_TRUE(condition);` | `condition` is true +`ASSERT_FALSE(condition);` | `EXPECT_FALSE(condition);` | `condition` is false + +Remember, when they fail, `ASSERT_*` yields a fatal failure and returns from the +current function, while `EXPECT_*` yields a nonfatal failure, allowing the +function to continue running. In either case, an assertion failure means its +containing test fails. + +**Availability**: Linux, Windows, Mac. + +### Binary Comparison + +This section describes assertions that compare two values. + +Fatal assertion | Nonfatal assertion | Verifies +------------------------ | ------------------------ | -------------- +`ASSERT_EQ(val1, val2);` | `EXPECT_EQ(val1, val2);` | `val1 == val2` +`ASSERT_NE(val1, val2);` | `EXPECT_NE(val1, val2);` | `val1 != val2` +`ASSERT_LT(val1, val2);` | `EXPECT_LT(val1, val2);` | `val1 < val2` +`ASSERT_LE(val1, val2);` | `EXPECT_LE(val1, val2);` | `val1 <= val2` +`ASSERT_GT(val1, val2);` | `EXPECT_GT(val1, val2);` | `val1 > val2` +`ASSERT_GE(val1, val2);` | `EXPECT_GE(val1, val2);` | `val1 >= val2` + +Value arguments must be comparable by the assertion's comparison operator or +you'll get a compiler error. We used to require the arguments to support the +`<<` operator for streaming to an `ostream`, but this is no longer necessary. If +`<<` is supported, it will be called to print the arguments when the assertion +fails; otherwise googletest will attempt to print them in the best way it can. +For more details and how to customize the printing of the arguments, see the +[documentation](./advanced.md#teaching-googletest-how-to-print-your-values). + +These assertions can work with a user-defined type, but only if you define the +corresponding comparison operator (e.g., `==` or `<`). Since this is discouraged +by the Google +[C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Operator_Overloading), +you may need to use `ASSERT_TRUE()` or `EXPECT_TRUE()` to assert the equality of +two objects of a user-defined type. + +However, when possible, `ASSERT_EQ(actual, expected)` is preferred to +`ASSERT_TRUE(actual == expected)`, since it tells you `actual` and `expected`'s +values on failure. + +Arguments are always evaluated exactly once. Therefore, it's OK for the +arguments to have side effects. However, as with any ordinary C/C++ function, +the arguments' evaluation order is undefined (i.e., the compiler is free to +choose any order), and your code should not depend on any particular argument +evaluation order. + +`ASSERT_EQ()` does pointer equality on pointers. If used on two C strings, it +tests if they are in the same memory location, not if they have the same value. +Therefore, if you want to compare C strings (e.g. `const char*`) by value, use +`ASSERT_STREQ()`, which will be described later on. In particular, to assert +that a C string is `NULL`, use `ASSERT_STREQ(c_string, NULL)`. Consider using +`ASSERT_EQ(c_string, nullptr)` if c++11 is supported. To compare two `string` +objects, you should use `ASSERT_EQ`. + +When doing pointer comparisons use `*_EQ(ptr, nullptr)` and `*_NE(ptr, nullptr)` +instead of `*_EQ(ptr, NULL)` and `*_NE(ptr, NULL)`. This is because `nullptr` is +typed, while `NULL` is not. See the [FAQ](faq.md) for more details. + +If you're working with floating point numbers, you may want to use the floating +point variations of some of these macros in order to avoid problems caused by +rounding. See [Advanced googletest Topics](advanced.md) for details. + +Macros in this section work with both narrow and wide string objects (`string` +and `wstring`). + +**Availability**: Linux, Windows, Mac. + +**Historical note**: Before February 2016 `*_EQ` had a convention of calling it +as `ASSERT_EQ(expected, actual)`, so lots of existing code uses this order. Now +`*_EQ` treats both parameters in the same way. + +### String Comparison + +The assertions in this group compare two **C strings**. If you want to compare +two `string` objects, use `EXPECT_EQ`, `EXPECT_NE`, and etc instead. + + + +| Fatal assertion | Nonfatal assertion | Verifies | +| -------------------------- | ------------------------------ | -------------------------------------------------------- | +| `ASSERT_STREQ(str1,str2);` | `EXPECT_STREQ(str1,str2);` | the two C strings have the same content | +| `ASSERT_STRNE(str1,str2);` | `EXPECT_STRNE(str1,str2);` | the two C strings have different contents | +| `ASSERT_STRCASEEQ(str1,str2);` | `EXPECT_STRCASEEQ(str1,str2);` | the two C strings have the same content, ignoring case | +| `ASSERT_STRCASENE(str1,str2);` | `EXPECT_STRCASENE(str1,str2);` | the two C strings have different contents, ignoring case | + + + +Note that "CASE" in an assertion name means that case is ignored. A `NULL` +pointer and an empty string are considered *different*. + +`*STREQ*` and `*STRNE*` also accept wide C strings (`wchar_t*`). If a comparison +of two wide strings fails, their values will be printed as UTF-8 narrow strings. + +**Availability**: Linux, Windows, Mac. + +**See also**: For more string comparison tricks (substring, prefix, suffix, and +regular expression matching, for example), see [this](advanced.md) in the +Advanced googletest Guide. + +## Simple Tests + +To create a test: + +1. Use the `TEST()` macro to define and name a test function. These are + ordinary C++ functions that don't return a value. +2. In this function, along with any valid C++ statements you want to include, + use the various googletest assertions to check values. +3. The test's result is determined by the assertions; if any assertion in the + test fails (either fatally or non-fatally), or if the test crashes, the + entire test fails. Otherwise, it succeeds. + +```c++ +TEST(TestSuiteName, TestName) { + ... test body ... +} +``` + +`TEST()` arguments go from general to specific. The *first* argument is the name +of the test suite, and the *second* argument is the test's name within the test +suite. Both names must be valid C++ identifiers, and they should not contain +any underscores (`_`). A test's *full name* consists of its containing test suite and +its individual name. Tests from different test suites can have the same +individual name. + +For example, let's take a simple integer function: + +```c++ +int Factorial(int n); // Returns the factorial of n +``` + +A test suite for this function might look like: + +```c++ +// Tests factorial of 0. +TEST(FactorialTest, HandlesZeroInput) { + EXPECT_EQ(Factorial(0), 1); +} + +// Tests factorial of positive numbers. +TEST(FactorialTest, HandlesPositiveInput) { + EXPECT_EQ(Factorial(1), 1); + EXPECT_EQ(Factorial(2), 2); + EXPECT_EQ(Factorial(3), 6); + EXPECT_EQ(Factorial(8), 40320); +} +``` + +googletest groups the test results by test suites, so logically related tests +should be in the same test suite; in other words, the first argument to their +`TEST()` should be the same. In the above example, we have two tests, +`HandlesZeroInput` and `HandlesPositiveInput`, that belong to the same test +suite `FactorialTest`. + +When naming your test suites and tests, you should follow the same convention as +for +[naming functions and classes](https://google.github.io/styleguide/cppguide.html#Function_Names). + +**Availability**: Linux, Windows, Mac. + +## Test Fixtures: Using the Same Data Configuration for Multiple Tests {#same-data-multiple-tests} + +If you find yourself writing two or more tests that operate on similar data, you +can use a *test fixture*. This allows you to reuse the same configuration of +objects for several different tests. + +To create a fixture: + +1. Derive a class from `::testing::Test` . Start its body with `protected:`, as + we'll want to access fixture members from sub-classes. +2. Inside the class, declare any objects you plan to use. +3. If necessary, write a default constructor or `SetUp()` function to prepare + the objects for each test. A common mistake is to spell `SetUp()` as + **`Setup()`** with a small `u` - Use `override` in C++11 to make sure you + spelled it correctly. +4. If necessary, write a destructor or `TearDown()` function to release any + resources you allocated in `SetUp()` . To learn when you should use the + constructor/destructor and when you should use `SetUp()/TearDown()`, read + the [FAQ](faq.md#CtorVsSetUp). +5. If needed, define subroutines for your tests to share. + +When using a fixture, use `TEST_F()` instead of `TEST()` as it allows you to +access objects and subroutines in the test fixture: + +```c++ +TEST_F(TestFixtureName, TestName) { + ... test body ... +} +``` + +Like `TEST()`, the first argument is the test suite name, but for `TEST_F()` +this must be the name of the test fixture class. You've probably guessed: `_F` +is for fixture. + +Unfortunately, the C++ macro system does not allow us to create a single macro +that can handle both types of tests. Using the wrong macro causes a compiler +error. + +Also, you must first define a test fixture class before using it in a +`TEST_F()`, or you'll get the compiler error "`virtual outside class +declaration`". + +For each test defined with `TEST_F()`, googletest will create a *fresh* test +fixture at runtime, immediately initialize it via `SetUp()`, run the test, +clean up by calling `TearDown()`, and then delete the test fixture. Note that +different tests in the same test suite have different test fixture objects, and +googletest always deletes a test fixture before it creates the next one. +googletest does **not** reuse the same test fixture for multiple tests. Any +changes one test makes to the fixture do not affect other tests. + +As an example, let's write tests for a FIFO queue class named `Queue`, which has +the following interface: + +```c++ +template // E is the element type. +class Queue { + public: + Queue(); + void Enqueue(const E& element); + E* Dequeue(); // Returns NULL if the queue is empty. + size_t size() const; + ... +}; +``` + +First, define a fixture class. By convention, you should give it the name +`FooTest` where `Foo` is the class being tested. + +```c++ +class QueueTest : public ::testing::Test { + protected: + void SetUp() override { + q1_.Enqueue(1); + q2_.Enqueue(2); + q2_.Enqueue(3); + } + + // void TearDown() override {} + + Queue q0_; + Queue q1_; + Queue q2_; +}; +``` + +In this case, `TearDown()` is not needed since we don't have to clean up after +each test, other than what's already done by the destructor. + +Now we'll write tests using `TEST_F()` and this fixture. + +```c++ +TEST_F(QueueTest, IsEmptyInitially) { + EXPECT_EQ(q0_.size(), 0); +} + +TEST_F(QueueTest, DequeueWorks) { + int* n = q0_.Dequeue(); + EXPECT_EQ(n, nullptr); + + n = q1_.Dequeue(); + ASSERT_NE(n, nullptr); + EXPECT_EQ(*n, 1); + EXPECT_EQ(q1_.size(), 0); + delete n; + + n = q2_.Dequeue(); + ASSERT_NE(n, nullptr); + EXPECT_EQ(*n, 2); + EXPECT_EQ(q2_.size(), 1); + delete n; +} +``` + +The above uses both `ASSERT_*` and `EXPECT_*` assertions. The rule of thumb is +to use `EXPECT_*` when you want the test to continue to reveal more errors after +the assertion failure, and use `ASSERT_*` when continuing after failure doesn't +make sense. For example, the second assertion in the `Dequeue` test is +`ASSERT_NE(nullptr, n)`, as we need to dereference the pointer `n` later, which +would lead to a segfault when `n` is `NULL`. + +When these tests run, the following happens: + +1. googletest constructs a `QueueTest` object (let's call it `t1`). +2. `t1.SetUp()` initializes `t1`. +3. The first test (`IsEmptyInitially`) runs on `t1`. +4. `t1.TearDown()` cleans up after the test finishes. +5. `t1` is destructed. +6. The above steps are repeated on another `QueueTest` object, this time + running the `DequeueWorks` test. + +**Availability**: Linux, Windows, Mac. + +## Invoking the Tests + +`TEST()` and `TEST_F()` implicitly register their tests with googletest. So, +unlike with many other C++ testing frameworks, you don't have to re-list all +your defined tests in order to run them. + +After defining your tests, you can run them with `RUN_ALL_TESTS()`, which +returns `0` if all the tests are successful, or `1` otherwise. Note that +`RUN_ALL_TESTS()` runs *all tests* in your link unit--they can be from +different test suites, or even different source files. + +When invoked, the `RUN_ALL_TESTS()` macro: + +* Saves the state of all googletest flags. + +* Creates a test fixture object for the first test. + +* Initializes it via `SetUp()`. + +* Runs the test on the fixture object. + +* Cleans up the fixture via `TearDown()`. + +* Deletes the fixture. + +* Restores the state of all googletest flags. + +* Repeats the above steps for the next test, until all tests have run. + +If a fatal failure happens the subsequent steps will be skipped. + +> IMPORTANT: You must **not** ignore the return value of `RUN_ALL_TESTS()`, or +> you will get a compiler error. The rationale for this design is that the +> automated testing service determines whether a test has passed based on its +> exit code, not on its stdout/stderr output; thus your `main()` function must +> return the value of `RUN_ALL_TESTS()`. +> +> Also, you should call `RUN_ALL_TESTS()` only **once**. Calling it more than +> once conflicts with some advanced googletest features (e.g., thread-safe +> [death tests](advanced.md#death-tests)) and thus is not supported. + +**Availability**: Linux, Windows, Mac. + +## Writing the main() Function + +Most users should _not_ need to write their own `main` function and instead link +with `gtest_main` (as opposed to with `gtest`), which defines a suitable entry +point. See the end of this section for details. The remainder of this section +should only apply when you need to do something custom before the tests run that +cannot be expressed within the framework of fixtures and test suites. + +If you write your own `main` function, it should return the value of +`RUN_ALL_TESTS()`. + +You can start from this boilerplate: + +```c++ +#include "this/package/foo.h" + +#include "gtest/gtest.h" + +namespace my { +namespace project { +namespace { + +// The fixture for testing class Foo. +class FooTest : public ::testing::Test { + protected: + // You can remove any or all of the following functions if their bodies would + // be empty. + + FooTest() { + // You can do set-up work for each test here. + } + + ~FooTest() override { + // You can do clean-up work that doesn't throw exceptions here. + } + + // If the constructor and destructor are not enough for setting up + // and cleaning up each test, you can define the following methods: + + void SetUp() override { + // Code here will be called immediately after the constructor (right + // before each test). + } + + void TearDown() override { + // Code here will be called immediately after each test (right + // before the destructor). + } + + // Class members declared here can be used by all tests in the test suite + // for Foo. +}; + +// Tests that the Foo::Bar() method does Abc. +TEST_F(FooTest, MethodBarDoesAbc) { + const std::string input_filepath = "this/package/testdata/myinputfile.dat"; + const std::string output_filepath = "this/package/testdata/myoutputfile.dat"; + Foo f; + EXPECT_EQ(f.Bar(input_filepath, output_filepath), 0); +} + +// Tests that Foo does Xyz. +TEST_F(FooTest, DoesXyz) { + // Exercises the Xyz feature of Foo. +} + +} // namespace +} // namespace project +} // namespace my + +int main(int argc, char **argv) { + ::testing::InitGoogleTest(&argc, argv); + return RUN_ALL_TESTS(); +} +``` + +The `::testing::InitGoogleTest()` function parses the command line for +googletest flags, and removes all recognized flags. This allows the user to +control a test program's behavior via various flags, which we'll cover in +the [AdvancedGuide](advanced.md). You **must** call this function before calling +`RUN_ALL_TESTS()`, or the flags won't be properly initialized. + +On Windows, `InitGoogleTest()` also works with wide strings, so it can be used +in programs compiled in `UNICODE` mode as well. + +But maybe you think that writing all those `main` functions is too much work? We +agree with you completely, and that's why Google Test provides a basic +implementation of main(). If it fits your needs, then just link your test with +the `gtest_main` library and you are good to go. + +NOTE: `ParseGUnitFlags()` is deprecated in favor of `InitGoogleTest()`. + +## Known Limitations + +* Google Test is designed to be thread-safe. The implementation is thread-safe + on systems where the `pthreads` library is available. It is currently + _unsafe_ to use Google Test assertions from two threads concurrently on + other systems (e.g. Windows). In most tests this is not an issue as usually + the assertions are done in the main thread. If you want to help, you can + volunteer to implement the necessary synchronization primitives in + `gtest-port.h` for your platform. diff --git a/docs/pump_manual.md b/docs/pump_manual.md new file mode 100644 index 0000000..9dbe15b --- /dev/null +++ b/docs/pump_manual.md @@ -0,0 +1,190 @@ +Pump is Useful for Meta Programming. + + + +# The Problem + +Template and macro libraries often need to define many classes, functions, or +macros that vary only (or almost only) in the number of arguments they take. +It's a lot of repetitive, mechanical, and error-prone work. + +Our experience is that it's tedious to write custom scripts, which tend to +reflect the structure of the generated code poorly and are often hard to read +and edit. For example, a small change needed in the generated code may require +some non-intuitive, non-trivial changes in the script. This is especially +painful when experimenting with the code. + +This script may be useful for generating meta code, for example a series of +macros of FOO1, FOO2, etc. Nevertheless, please make it your last resort +technique by favouring C++ template metaprogramming or variadic macros. + +# Our Solution + +Pump (for Pump is Useful for Meta Programming, Pretty Useful for Meta +Programming, or Practical Utility for Meta Programming, whichever you prefer) is +a simple meta-programming tool for C++. The idea is that a programmer writes a +`foo.pump` file which contains C++ code plus meta code that manipulates the C++ +code. The meta code can handle iterations over a range, nested iterations, local +meta variable definitions, simple arithmetic, and conditional expressions. You +can view it as a small Domain-Specific Language. The meta language is designed +to be non-intrusive (s.t. it won't confuse Emacs' C++ mode, for example) and +concise, making Pump code intuitive and easy to maintain. + +## Highlights + +* The implementation is in a single Python script and thus ultra portable: no + build or installation is needed and it works cross platforms. +* Pump tries to be smart with respect to + [Google's style guide](https://github.com/google/styleguide): it breaks long + lines (easy to have when they are generated) at acceptable places to fit + within 80 columns and indent the continuation lines correctly. +* The format is human-readable and more concise than XML. +* The format works relatively well with Emacs' C++ mode. + +## Examples + +The following Pump code (where meta keywords start with `$`, `[[` and `]]` are +meta brackets, and `$$` starts a meta comment that ends with the line): + +``` +$var n = 3 $$ Defines a meta variable n. +$range i 0..n $$ Declares the range of meta iterator i (inclusive). +$for i [[ + $$ Meta loop. +// Foo$i does blah for $i-ary predicates. +$range j 1..i +template +class Foo$i { +$if i == 0 [[ + blah a; +]] $elif i <= 2 [[ + blah b; +]] $else [[ + blah c; +]] +}; + +]] +``` + +will be translated by the Pump compiler to: + +```cpp +// Foo0 does blah for 0-ary predicates. +template +class Foo0 { + blah a; +}; + +// Foo1 does blah for 1-ary predicates. +template +class Foo1 { + blah b; +}; + +// Foo2 does blah for 2-ary predicates. +template +class Foo2 { + blah b; +}; + +// Foo3 does blah for 3-ary predicates. +template +class Foo3 { + blah c; +}; +``` + +In another example, + +``` +$range i 1..n +Func($for i + [[a$i]]); +$$ The text between i and [[ is the separator between iterations. +``` + +will generate one of the following lines (without the comments), depending on +the value of `n`: + +```cpp +Func(); // If n is 0. +Func(a1); // If n is 1. +Func(a1 + a2); // If n is 2. +Func(a1 + a2 + a3); // If n is 3. +// And so on... +``` + +## Constructs + +We support the following meta programming constructs: + +| `$var id = exp` | Defines a named constant value. `$id` is | +: : valid until the end of the current meta : +: : lexical block. : +| :------------------------------- | :--------------------------------------- | +| `$range id exp..exp` | Sets the range of an iteration variable, | +: : which can be reused in multiple loops : +: : later. : +| `$for id sep [[ code ]]` | Iteration. The range of `id` must have | +: : been defined earlier. `$id` is valid in : +: : `code`. : +| `$($)` | Generates a single `$` character. | +| `$id` | Value of the named constant or iteration | +: : variable. : +| `$(exp)` | Value of the expression. | +| `$if exp [[ code ]] else_branch` | Conditional. | +| `[[ code ]]` | Meta lexical block. | +| `cpp_code` | Raw C++ code. | +| `$$ comment` | Meta comment. | + +**Note:** To give the user some freedom in formatting the Pump source code, Pump +ignores a new-line character if it's right after `$for foo` or next to `[[` or +`]]`. Without this rule you'll often be forced to write very long lines to get +the desired output. Therefore sometimes you may need to insert an extra new-line +in such places for a new-line to show up in your output. + +## Grammar + +```ebnf +code ::= atomic_code* +atomic_code ::= $var id = exp + | $var id = [[ code ]] + | $range id exp..exp + | $for id sep [[ code ]] + | $($) + | $id + | $(exp) + | $if exp [[ code ]] else_branch + | [[ code ]] + | cpp_code +sep ::= cpp_code | empty_string +else_branch ::= $else [[ code ]] + | $elif exp [[ code ]] else_branch + | empty_string +exp ::= simple_expression_in_Python_syntax +``` + +## Code + +You can find the source code of Pump in +[googlemock/scripts/pump.py](../googlemock/scripts/pump.py). It is still very +unpolished and lacks automated tests, although it has been successfully used +many times. If you find a chance to use it in your project, please let us know +what you think! We also welcome help on improving Pump. + +## Real Examples + +You can find real-world applications of Pump in +[Google Test](https://github.com/google/googletest/tree/master/googletest) and +[Google Mock](https://github.com/google/googletest/tree/master/googlemock). The +source file `foo.h.pump` generates `foo.h`. + +## Tips + +* If a meta variable is followed by a letter or digit, you can separate them + using `[[]]`, which inserts an empty string. For example `Foo$j[[]]Helper` + generate `Foo1Helper` when `j` is 1. +* To avoid extra-long Pump source lines, you can break a line anywhere you + want by inserting `[[]]` followed by a new line. Since any new-line + character next to `[[` or `]]` is ignored, the generated code won't contain + this new line. diff --git a/docs/samples.md b/docs/samples.md new file mode 100644 index 0000000..aaa5883 --- /dev/null +++ b/docs/samples.md @@ -0,0 +1,22 @@ +# Googletest Samples {#samples} + +If you're like us, you'd like to look at +[googletest samples.](https://github.com/google/googletest/tree/master/googletest/samples) +The sample directory has a number of well-commented samples showing how to use a +variety of googletest features. + +* Sample #1 shows the basic steps of using googletest to test C++ functions. +* Sample #2 shows a more complex unit test for a class with multiple member + functions. +* Sample #3 uses a test fixture. +* Sample #4 teaches you how to use googletest and `googletest.h` together to + get the best of both libraries. +* Sample #5 puts shared testing logic in a base test fixture, and reuses it in + derived fixtures. +* Sample #6 demonstrates type-parameterized tests. +* Sample #7 teaches the basics of value-parameterized tests. +* Sample #8 shows using `Combine()` in value-parameterized tests. +* Sample #9 shows use of the listener API to modify Google Test's console + output and the use of its reflection API to inspect test results. +* Sample #10 shows use of the listener API to implement a primitive memory + leak checker. diff --git a/googlemock/docs/README.md b/googlemock/docs/README.md new file mode 100644 index 0000000..1bc57b7 --- /dev/null +++ b/googlemock/docs/README.md @@ -0,0 +1,4 @@ +# Content Moved + +We are working on updates to the GoogleTest documentation, which has moved to +the top-level [docs](../../docs) directory. diff --git a/googlemock/docs/cheat_sheet.md b/googlemock/docs/cheat_sheet.md deleted file mode 100644 index dc2428e..0000000 --- a/googlemock/docs/cheat_sheet.md +++ /dev/null @@ -1,786 +0,0 @@ -# gMock Cheat Sheet - - - - - - - -## Defining a Mock Class - -### Mocking a Normal Class {#MockClass} - -Given - -```cpp -class Foo { - ... - virtual ~Foo(); - virtual int GetSize() const = 0; - virtual string Describe(const char* name) = 0; - virtual string Describe(int type) = 0; - virtual bool Process(Bar elem, int count) = 0; -}; -``` - -(note that `~Foo()` **must** be virtual) we can define its mock as - -```cpp -#include "gmock/gmock.h" - -class MockFoo : public Foo { - ... - MOCK_METHOD(int, GetSize, (), (const, override)); - MOCK_METHOD(string, Describe, (const char* name), (override)); - MOCK_METHOD(string, Describe, (int type), (override)); - MOCK_METHOD(bool, Process, (Bar elem, int count), (override)); -}; -``` - -To create a "nice" mock, which ignores all uninteresting calls, a "naggy" mock, -which warns on all uninteresting calls, or a "strict" mock, which treats them as -failures: - -```cpp -using ::testing::NiceMock; -using ::testing::NaggyMock; -using ::testing::StrictMock; - -NiceMock nice_foo; // The type is a subclass of MockFoo. -NaggyMock naggy_foo; // The type is a subclass of MockFoo. -StrictMock strict_foo; // The type is a subclass of MockFoo. -``` - -**Note:** A mock object is currently naggy by default. We may make it nice by -default in the future. - -### Mocking a Class Template {#MockTemplate} - -Class templates can be mocked just like any class. - -To mock - -```cpp -template -class StackInterface { - ... - virtual ~StackInterface(); - virtual int GetSize() const = 0; - virtual void Push(const Elem& x) = 0; -}; -``` - -(note that all member functions that are mocked, including `~StackInterface()` -**must** be virtual). - -```cpp -template -class MockStack : public StackInterface { - ... - MOCK_METHOD(int, GetSize, (), (const, override)); - MOCK_METHOD(void, Push, (const Elem& x), (override)); -}; -``` - -### Specifying Calling Conventions for Mock Functions - -If your mock function doesn't use the default calling convention, you can -specify it by adding `Calltype(convention)` to `MOCK_METHOD`'s 4th parameter. -For example, - -```cpp - MOCK_METHOD(bool, Foo, (int n), (Calltype(STDMETHODCALLTYPE))); - MOCK_METHOD(int, Bar, (double x, double y), - (const, Calltype(STDMETHODCALLTYPE))); -``` - -where `STDMETHODCALLTYPE` is defined by `` on Windows. - -## Using Mocks in Tests {#UsingMocks} - -The typical work flow is: - -1. Import the gMock names you need to use. All gMock symbols are in the - `testing` namespace unless they are macros or otherwise noted. -2. Create the mock objects. -3. Optionally, set the default actions of the mock objects. -4. Set your expectations on the mock objects (How will they be called? What - will they do?). -5. Exercise code that uses the mock objects; if necessary, check the result - using googletest assertions. -6. When a mock object is destructed, gMock automatically verifies that all - expectations on it have been satisfied. - -Here's an example: - -```cpp -using ::testing::Return; // #1 - -TEST(BarTest, DoesThis) { - MockFoo foo; // #2 - - ON_CALL(foo, GetSize()) // #3 - .WillByDefault(Return(1)); - // ... other default actions ... - - EXPECT_CALL(foo, Describe(5)) // #4 - .Times(3) - .WillRepeatedly(Return("Category 5")); - // ... other expectations ... - - EXPECT_EQ("good", MyProductionFunction(&foo)); // #5 -} // #6 -``` - -## Setting Default Actions {#OnCall} - -gMock has a **built-in default action** for any function that returns `void`, -`bool`, a numeric value, or a pointer. In C++11, it will additionally returns -the default-constructed value, if one exists for the given type. - -To customize the default action for functions with return type *`T`*: - -```cpp -using ::testing::DefaultValue; - -// Sets the default value to be returned. T must be CopyConstructible. -DefaultValue::Set(value); -// Sets a factory. Will be invoked on demand. T must be MoveConstructible. -// T MakeT(); -DefaultValue::SetFactory(&MakeT); -// ... use the mocks ... -// Resets the default value. -DefaultValue::Clear(); -``` - -Example usage: - -```cpp - // Sets the default action for return type std::unique_ptr to - // creating a new Buzz every time. - DefaultValue>::SetFactory( - [] { return MakeUnique(AccessLevel::kInternal); }); - - // When this fires, the default action of MakeBuzz() will run, which - // will return a new Buzz object. - EXPECT_CALL(mock_buzzer_, MakeBuzz("hello")).Times(AnyNumber()); - - auto buzz1 = mock_buzzer_.MakeBuzz("hello"); - auto buzz2 = mock_buzzer_.MakeBuzz("hello"); - EXPECT_NE(nullptr, buzz1); - EXPECT_NE(nullptr, buzz2); - EXPECT_NE(buzz1, buzz2); - - // Resets the default action for return type std::unique_ptr, - // to avoid interfere with other tests. - DefaultValue>::Clear(); -``` - -To customize the default action for a particular method of a specific mock -object, use `ON_CALL()`. `ON_CALL()` has a similar syntax to `EXPECT_CALL()`, -but it is used for setting default behaviors (when you do not require that the -mock method is called). See [here](cook_book.md#UseOnCall) for a more detailed -discussion. - -```cpp -ON_CALL(mock-object, method(matchers)) - .With(multi-argument-matcher) ? - .WillByDefault(action); -``` - -## Setting Expectations {#ExpectCall} - -`EXPECT_CALL()` sets **expectations** on a mock method (How will it be called? -What will it do?): - -```cpp -EXPECT_CALL(mock-object, method (matchers)?) - .With(multi-argument-matcher) ? - .Times(cardinality) ? - .InSequence(sequences) * - .After(expectations) * - .WillOnce(action) * - .WillRepeatedly(action) ? - .RetiresOnSaturation(); ? -``` - -For each item above, `?` means it can be used at most once, while `*` means it -can be used any number of times. - -In order to pass, `EXPECT_CALL` must be used before the calls are actually made. - -The `(matchers)` is a comma-separated list of matchers that correspond to each -of the arguments of `method`, and sets the expectation only for calls of -`method` that matches all of the matchers. - -If `(matchers)` is omitted, the expectation is the same as if the matchers were -set to anything matchers (for example, `(_, _, _, _)` for a four-arg method). - -If `Times()` is omitted, the cardinality is assumed to be: - -* `Times(1)` when there is neither `WillOnce()` nor `WillRepeatedly()`; -* `Times(n)` when there are `n` `WillOnce()`s but no `WillRepeatedly()`, where - `n` >= 1; or -* `Times(AtLeast(n))` when there are `n` `WillOnce()`s and a - `WillRepeatedly()`, where `n` >= 0. - -A method with no `EXPECT_CALL()` is free to be invoked *any number of times*, -and the default action will be taken each time. - -## Matchers {#MatcherList} - - - -A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or -`EXPECT_CALL()`, or use it to validate a value directly using two macros: - - -| Macro | Description | -| :----------------------------------- | :------------------------------------ | -| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. | -| `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. | - - -**Note:** Although equality matching via `EXPECT_THAT(actual_value, -expected_value)` is supported, prefer to make the comparison explicit via -`EXPECT_THAT(actual_value, Eq(expected_value))` or `EXPECT_EQ(actual_value, -expected_value)`. - -Built-in matchers (where `argument` is the function argument, e.g. -`actual_value` in the example above, or when used in the context of -`EXPECT_CALL(mock_object, method(matchers))`, the arguments of `method`) are -divided into several categories: - -### Wildcard - -Matcher | Description -:-------------------------- | :----------------------------------------------- -`_` | `argument` can be any value of the correct type. -`A()` or `An()` | `argument` can be any value of type `type`. - -### Generic Comparison - - -| Matcher | Description | -| :--------------------- | :-------------------------------------------------- | -| `Eq(value)` or `value` | `argument == value` | -| `Ge(value)` | `argument >= value` | -| `Gt(value)` | `argument > value` | -| `Le(value)` | `argument <= value` | -| `Lt(value)` | `argument < value` | -| `Ne(value)` | `argument != value` | -| `IsFalse()` | `argument` evaluates to `false` in a Boolean context. | -| `IsTrue()` | `argument` evaluates to `true` in a Boolean context. | -| `IsNull()` | `argument` is a `NULL` pointer (raw or smart). | -| `NotNull()` | `argument` is a non-null pointer (raw or smart). | -| `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. (For testing whether an `optional<>` is set, check for equality with `nullopt`. You may need to use `Eq(nullopt)` if the inner type doesn't have `==`.)| -| `VariantWith(m)` | `argument` is `variant<>` that holds the alternative of type T with a value matching `m`. | -| `Ref(variable)` | `argument` is a reference to `variable`. | -| `TypedEq(value)` | `argument` has type `type` and is equal to `value`. You may need to use this instead of `Eq(value)` when the mock function is overloaded. | - - -Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or -destructed later. If the compiler complains that `value` doesn't have a public -copy constructor, try wrap it in `std::ref()`, e.g. -`Eq(std::ref(non_copyable_value))`. If you do that, make sure -`non_copyable_value` is not changed afterwards, or the meaning of your matcher -will be changed. - -`IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types -that can be explicitly converted to Boolean, but are not implicitly converted to -Boolean. In other cases, you can use the basic -[`EXPECT_TRUE` and `EXPECT_FALSE`](../../googletest/docs/primer#basic-assertions) -assertions. - -### Floating-Point Matchers {#FpMatchers} - - -| Matcher | Description | -| :------------------------------- | :--------------------------------- | -| `DoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. | -| `FloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. | -| `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. | -| `NanSensitiveFloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. | -| `IsNan()` | `argument` is any floating-point type with a NaN value. | - - -The above matchers use ULP-based comparison (the same as used in googletest). -They automatically pick a reasonable error bound based on the absolute value of -the expected value. `DoubleEq()` and `FloatEq()` conform to the IEEE standard, -which requires comparing two NaNs for equality to return false. The -`NanSensitive*` version instead treats two NaNs as equal, which is often what a -user wants. - - -| Matcher | Description | -| :------------------------------------------------ | :----------------------- | -| `DoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as unequal. | -| `FloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as unequal. | -| `NanSensitiveDoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as equal. | -| `NanSensitiveFloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as equal. | - - -### String Matchers - -The `argument` can be either a C string or a C++ string object: - - -| Matcher | Description | -| :---------------------- | :------------------------------------------------- | -| `ContainsRegex(string)` | `argument` matches the given regular expression. | -| `EndsWith(suffix)` | `argument` ends with string `suffix`. | -| `HasSubstr(string)` | `argument` contains `string` as a sub-string. | -| `MatchesRegex(string)` | `argument` matches the given regular expression with the match starting at the first character and ending at the last character. | -| `StartsWith(prefix)` | `argument` starts with string `prefix`. | -| `StrCaseEq(string)` | `argument` is equal to `string`, ignoring case. | -| `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring case. | -| `StrEq(string)` | `argument` is equal to `string`. | -| `StrNe(string)` | `argument` is not equal to `string`. | - - -`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They -use the regular expression syntax defined -[here](../../googletest/docs/advanced.md#regular-expression-syntax). All of -these matchers, except `ContainsRegex()` and `MatchesRegex()` work for wide -strings as well. - -### Container Matchers - -Most STL-style containers support `==`, so you can use `Eq(expected_container)` -or simply `expected_container` to match a container exactly. If you want to -write the elements in-line, match them more flexibly, or get more informative -messages, you can use: - - -| Matcher | Description | -| :---------------------------------------- | :------------------------------- | -| `BeginEndDistanceIs(m)` | `argument` is a container whose `begin()` and `end()` iterators are separated by a number of increments matching `m`. E.g. `BeginEndDistanceIs(2)` or `BeginEndDistanceIs(Lt(2))`. For containers that define a `size()` method, `SizeIs(m)` may be more efficient. | -| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. | -| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. | -| `Each(e)` | `argument` is a container where *every* element matches `e`, which can be either a value or a matcher. | -| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. | -| `ElementsAreArray({e0, e1, ..., en})`, `ElementsAreArray(a_container)`, `ElementsAreArray(begin, end)`, `ElementsAreArray(array)`, or `ElementsAreArray(array, count)` | The same as `ElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. | -| `IsEmpty()` | `argument` is an empty container (`container.empty()`). | -| `IsSubsetOf({e0, e1, ..., en})`, `IsSubsetOf(a_container)`, `IsSubsetOf(begin, end)`, `IsSubsetOf(array)`, or `IsSubsetOf(array, count)` | `argument` matches `UnorderedElementsAre(x0, x1, ..., xk)` for some subset `{x0, x1, ..., xk}` of the expected matchers. | -| `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. | -| `Pointwise(m, container)`, `Pointwise(m, {e0, e1, ..., en})` | `argument` contains the same number of elements as in `container`, and for all i, (the i-th element in `argument`, the i-th element in `container`) match `m`, which is a matcher on 2-tuples. E.g. `Pointwise(Le(), upper_bounds)` verifies that each element in `argument` doesn't exceed the corresponding element in `upper_bounds`. See more detail below. | -| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. | -| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, and under *some* permutation of the elements, each element matches an `ei` (for a different `i`), which can be a value or a matcher. | -| `UnorderedElementsAreArray({e0, e1, ..., en})`, `UnorderedElementsAreArray(a_container)`, `UnorderedElementsAreArray(begin, end)`, `UnorderedElementsAreArray(array)`, or `UnorderedElementsAreArray(array, count)` | The same as `UnorderedElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. | -| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. | -| `WhenSorted(m)` | When `argument` is sorted using the `<` operator, it matches container matcher `m`. E.g. `WhenSorted(ElementsAre(1, 2, 3))` verifies that `argument` contains elements 1, 2, and 3, ignoring order. | -| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, except that the given comparator instead of `<` is used to sort `argument`. E.g. `WhenSortedBy(std::greater(), ElementsAre(3, 2, 1))`. | - - -**Notes:** - -* These matchers can also match: - 1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`), - and - 2. an array passed as a pointer and a count (e.g. in `Bar(const T* buffer, - int len)` -- see [Multi-argument Matchers](#MultiArgMatchers)). -* The array being matched may be multi-dimensional (i.e. its elements can be - arrays). -* `m` in `Pointwise(m, ...)` should be a matcher for `::std::tuple` - where `T` and `U` are the element type of the actual container and the - expected container, respectively. For example, to compare two `Foo` - containers where `Foo` doesn't support `operator==`, one might write: - - ```cpp - using ::std::get; - MATCHER(FooEq, "") { - return std::get<0>(arg).Equals(std::get<1>(arg)); - } - ... - EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos)); - ``` - -### Member Matchers - - -| Matcher | Description | -| :------------------------------ | :----------------------------------------- | -| `Field(&class::field, m)` | `argument.field` (or `argument->field` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. | -| `Key(e)` | `argument.first` matches `e`, which can be either a value or a matcher. E.g. `Contains(Key(Le(5)))` can verify that a `map` contains a key `<= 5`. | -| `Pair(m1, m2)` | `argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. | -| `FieldsAre(m...)` | `argument` is a compatible object where each field matches piecewise with `m...`. A compatible object is any that supports the `std::tuple_size`+`get(obj)` protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates. | -| `Property(&class::property, m)` | `argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. | - - -### Matching the Result of a Function, Functor, or Callback - - -| Matcher | Description | -| :--------------- | :------------------------------------------------ | -| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. | - - -### Pointer Matchers - - -| Matcher | Description | -| :------------------------ | :---------------------------------------------- | -| `Address(m)` | the result of `std::addressof(argument)` matches `m`. | -| `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. | -| `Pointer(m)` | `argument` (either a smart pointer or a raw pointer) contains a pointer that matches `m`. `m` will match against the raw pointer regardless of the type of `argument`. | -| `WhenDynamicCastTo(m)` | when `argument` is passed through `dynamic_cast()`, it matches matcher `m`. | - - - - - - -### Multi-argument Matchers {#MultiArgMatchers} - -Technically, all matchers match a *single* value. A "multi-argument" matcher is -just one that matches a *tuple*. The following matchers can be used to match a -tuple `(x, y)`: - -Matcher | Description -:------ | :---------- -`Eq()` | `x == y` -`Ge()` | `x >= y` -`Gt()` | `x > y` -`Le()` | `x <= y` -`Lt()` | `x < y` -`Ne()` | `x != y` - -You can use the following selectors to pick a subset of the arguments (or -reorder them) to participate in the matching: - - -| Matcher | Description | -| :------------------------- | :---------------------------------------------- | -| `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`. | -| `Args(m)` | The tuple of the `k` selected (using 0-based indices) arguments matches `m`, e.g. `Args<1, 2>(Eq())`. | - - -### Composite Matchers - -You can make a matcher from one or more other matchers: - - -| Matcher | Description | -| :------------------------------- | :-------------------------------------- | -| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. | -| `AllOfArray({m0, m1, ..., mn})`, `AllOfArray(a_container)`, `AllOfArray(begin, end)`, `AllOfArray(array)`, or `AllOfArray(array, count)` | The same as `AllOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. | -| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. | -| `AnyOfArray({m0, m1, ..., mn})`, `AnyOfArray(a_container)`, `AnyOfArray(begin, end)`, `AnyOfArray(array)`, or `AnyOfArray(array, count)` | The same as `AnyOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. | -| `Not(m)` | `argument` doesn't match matcher `m`. | - - - - -### Adapters for Matchers - - -| Matcher | Description | -| :---------------------- | :------------------------------------ | -| `MatcherCast(m)` | casts matcher `m` to type `Matcher`. | -| `SafeMatcherCast(m)` | [safely casts](cook_book.md#casting-matchers) matcher `m` to type `Matcher`. | -| `Truly(predicate)` | `predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor. | - - -`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`, -which must be a permanent callback. - -### Using Matchers as Predicates {#MatchersAsPredicatesCheat} - - -| Matcher | Description | -| :---------------------------- | :------------------------------------------ | -| `Matches(m)(value)` | evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor. | -| `ExplainMatchResult(m, value, result_listener)` | evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. | -| `Value(value, m)` | evaluates to `true` if `value` matches `m`. | - - -### Defining Matchers - - -| Matcher | Description | -| :----------------------------------- | :------------------------------------ | -| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. | -| `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a matcher `IsDivisibleBy(n)` to match a number divisible by `n`. | -| `MATCHER_P2(IsBetween, a, b, absl::StrCat(negation ? "isn't" : "is", " between ", PrintToString(a), " and ", PrintToString(b))) { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. | - - -**Notes:** - -1. The `MATCHER*` macros cannot be used inside a function or class. -2. The matcher body must be *purely functional* (i.e. it cannot have any side - effect, and the result must not depend on anything other than the value - being matched and the matcher parameters). -3. You can use `PrintToString(x)` to convert a value `x` of any type to a - string. - -## Actions {#ActionList} - -**Actions** specify what a mock function should do when invoked. - -### Returning a Value - - -| | | -| :-------------------------------- | :-------------------------------------------- | -| `Return()` | Return from a `void` mock function. | -| `Return(value)` | Return `value`. If the type of `value` is different to the mock function's return type, `value` is converted to the latter type at the time the expectation is set, not when the action is executed. | -| `ReturnArg()` | Return the `N`-th (0-based) argument. | -| `ReturnNew(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different object is created each time. | -| `ReturnNull()` | Return a null pointer. | -| `ReturnPointee(ptr)` | Return the value pointed to by `ptr`. | -| `ReturnRef(variable)` | Return a reference to `variable`. | -| `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. | -| `ReturnRoundRobin({a1, ..., ak})` | Each call will return the next `ai` in the list, starting at the beginning when the end of the list is reached. | - - -### Side Effects - - -| | | -| :--------------------------------- | :-------------------------------------- | -| `Assign(&variable, value)` | Assign `value` to variable. | -| `DeleteArg()` | Delete the `N`-th (0-based) argument, which must be a pointer. | -| `SaveArg(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. | -| `SaveArgPointee(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. | -| `SetArgReferee(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. | -| `SetArgPointee(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. | -| `SetArgumentPointee(value)` | Same as `SetArgPointee(value)`. Deprecated. Will be removed in v1.7.0. | -| `SetArrayArgument(first, last)` | Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range. | -| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. | -| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. | - - -### Using a Function, Functor, or Lambda as an Action - -In the following, by "callable" we mean a free function, `std::function`, -functor, or lambda. - - -| | | -| :---------------------------------- | :------------------------------------- | -| `f` | Invoke f with the arguments passed to the mock function, where f is a callable. | -| `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. | -| `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. | -| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. | -| `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. | -| `InvokeArgument(arg1, arg2, ..., argk)` | Invoke the mock function's `N`-th (0-based) argument, which must be a function or a functor, with the `k` arguments. | - - -The return value of the invoked function is used as the return value of the -action. - -When defining a callable to be used with `Invoke*()`, you can declare any unused -parameters as `Unused`: - -```cpp -using ::testing::Invoke; -double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); } -... -EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance)); -``` - -`Invoke(callback)` and `InvokeWithoutArgs(callback)` take ownership of -`callback`, which must be permanent. The type of `callback` must be a base -callback type instead of a derived one, e.g. - -```cpp - BlockingClosure* done = new BlockingClosure; - ... Invoke(done) ...; // This won't compile! - - Closure* done2 = new BlockingClosure; - ... Invoke(done2) ...; // This works. -``` - -In `InvokeArgument(...)`, if an argument needs to be passed by reference, -wrap it inside `std::ref()`. For example, - -```cpp -using ::testing::InvokeArgument; -... -InvokeArgument<2>(5, string("Hi"), std::ref(foo)) -``` - -calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by -value, and `foo` by reference. - -### Default Action - - -| Matcher | Description | -| :------------ | :----------------------------------------------------- | -| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). | - - -**Note:** due to technical reasons, `DoDefault()` cannot be used inside a -composite action - trying to do so will result in a run-time error. - - - -### Composite Actions - - -| | | -| :----------------------------- | :------------------------------------------ | -| `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the result of `an` in each invocation. The first `n - 1` sub-actions must return void and will receive a readonly view of the arguments. | -| `IgnoreResult(a)` | Perform action `a` and ignore its result. `a` must not return void. | -| `WithArg(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. | -| `WithArgs(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. | -| `WithoutArgs(a)` | Perform action `a` without any arguments. | - - -### Defining Actions - - -| | | -| :--------------------------------- | :-------------------------------------- | -| `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. | -| `ACTION_P(Plus, n) { return arg0 + n; }` | Defines an action `Plus(n)` to return the sum of the mock function's argument #0 and `n`. | -| `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. | - - -The `ACTION*` macros cannot be used inside a function or class. - -## Cardinalities {#CardinalityList} - -These are used in `Times()` to specify how many times a mock function will be -called: - - -| | | -| :---------------- | :----------------------------------------------------- | -| `AnyNumber()` | The function can be called any number of times. | -| `AtLeast(n)` | The call is expected at least `n` times. | -| `AtMost(n)` | The call is expected at most `n` times. | -| `Between(m, n)` | The call is expected between `m` and `n` (inclusive) times. | -| `Exactly(n) or n` | The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0. | - - -## Expectation Order - -By default, the expectations can be matched in *any* order. If some or all -expectations must be matched in a given order, there are two ways to specify it. -They can be used either independently or together. - -### The After Clause {#AfterClause} - -```cpp -using ::testing::Expectation; -... -Expectation init_x = EXPECT_CALL(foo, InitX()); -Expectation init_y = EXPECT_CALL(foo, InitY()); -EXPECT_CALL(foo, Bar()) - .After(init_x, init_y); -``` - -says that `Bar()` can be called only after both `InitX()` and `InitY()` have -been called. - -If you don't know how many pre-requisites an expectation has when you write it, -you can use an `ExpectationSet` to collect them: - -```cpp -using ::testing::ExpectationSet; -... -ExpectationSet all_inits; -for (int i = 0; i < element_count; i++) { - all_inits += EXPECT_CALL(foo, InitElement(i)); -} -EXPECT_CALL(foo, Bar()) - .After(all_inits); -``` - -says that `Bar()` can be called only after all elements have been initialized -(but we don't care about which elements get initialized before the others). - -Modifying an `ExpectationSet` after using it in an `.After()` doesn't affect the -meaning of the `.After()`. - -### Sequences {#UsingSequences} - -When you have a long chain of sequential expectations, it's easier to specify -the order using **sequences**, which don't require you to given each expectation -in the chain a different name. *All expected calls* in the same sequence must -occur in the order they are specified. - -```cpp -using ::testing::Return; -using ::testing::Sequence; -Sequence s1, s2; -... -EXPECT_CALL(foo, Reset()) - .InSequence(s1, s2) - .WillOnce(Return(true)); -EXPECT_CALL(foo, GetSize()) - .InSequence(s1) - .WillOnce(Return(1)); -EXPECT_CALL(foo, Describe(A())) - .InSequence(s2) - .WillOnce(Return("dummy")); -``` - -says that `Reset()` must be called before *both* `GetSize()` *and* `Describe()`, -and the latter two can occur in any order. - -To put many expectations in a sequence conveniently: - -```cpp -using ::testing::InSequence; -{ - InSequence seq; - - EXPECT_CALL(...)...; - EXPECT_CALL(...)...; - ... - EXPECT_CALL(...)...; -} -``` - -says that all expected calls in the scope of `seq` must occur in strict order. -The name `seq` is irrelevant. - -## Verifying and Resetting a Mock - -gMock will verify the expectations on a mock object when it is destructed, or -you can do it earlier: - -```cpp -using ::testing::Mock; -... -// Verifies and removes the expectations on mock_obj; -// returns true if and only if successful. -Mock::VerifyAndClearExpectations(&mock_obj); -... -// Verifies and removes the expectations on mock_obj; -// also removes the default actions set by ON_CALL(); -// returns true if and only if successful. -Mock::VerifyAndClear(&mock_obj); -``` - -You can also tell gMock that a mock object can be leaked and doesn't need to be -verified: - -```cpp -Mock::AllowLeak(&mock_obj); -``` - -## Mock Classes - -gMock defines a convenient mock class template - -```cpp -class MockFunction { - public: - MOCK_METHOD(R, Call, (A1, ..., An)); -}; -``` - -See this [recipe](cook_book.md#using-check-points) for one application of it. - -## Flags - - -| Flag | Description | -| :----------------------------- | :---------------------------------------- | -| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. | -| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. | - diff --git a/googlemock/docs/community_created_documentation.md b/googlemock/docs/community_created_documentation.md deleted file mode 100644 index dfd87f7..0000000 --- a/googlemock/docs/community_created_documentation.md +++ /dev/null @@ -1,9 +0,0 @@ -# Community-Created Documentation - -go/gunit-community-created-docs - -The following is a list, in no particular order, of links to documentation -created by the Googletest community. - -* [Googlemock Insights](https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles/blob/master/googletest/insights.md), - by [ElectricRCAircraftGuy](https://github.com/ElectricRCAircraftGuy) diff --git a/googlemock/docs/contribute.md b/googlemock/docs/contribute.md deleted file mode 100644 index 087654c..0000000 --- a/googlemock/docs/contribute.md +++ /dev/null @@ -1,5 +0,0 @@ -# How to Contribute - -googletest development is Piper-First. Just create a regular Piper CL. When the -CL is accepted and submitted, it will make its way to OSS via regular releasing -process. diff --git a/googlemock/docs/cook_book.md b/googlemock/docs/cook_book.md deleted file mode 100644 index cd64150..0000000 --- a/googlemock/docs/cook_book.md +++ /dev/null @@ -1,4266 +0,0 @@ -# gMock Cookbook - - - -You can find recipes for using gMock here. If you haven't yet, please read -[the dummy guide](for_dummies.md) first to make sure you understand the basics. - -**Note:** gMock lives in the `testing` name space. For readability, it is -recommended to write `using ::testing::Foo;` once in your file before using the -name `Foo` defined by gMock. We omit such `using` statements in this section for -brevity, but you should do it in your own code. - - - -## Creating Mock Classes - -Mock classes are defined as normal classes, using the `MOCK_METHOD` macro to -generate mocked methods. The macro gets 3 or 4 parameters: - -```cpp -class MyMock { - public: - MOCK_METHOD(ReturnType, MethodName, (Args...)); - MOCK_METHOD(ReturnType, MethodName, (Args...), (Specs...)); -}; -``` - -The first 3 parameters are simply the method declaration, split into 3 parts. -The 4th parameter accepts a closed list of qualifiers, which affect the -generated method: - -* **`const`** - Makes the mocked method a `const` method. Required if - overriding a `const` method. -* **`override`** - Marks the method with `override`. Recommended if overriding - a `virtual` method. -* **`noexcept`** - Marks the method with `noexcept`. Required if overriding a - `noexcept` method. -* **`Calltype(...)`** - Sets the call type for the method (e.g. to - `STDMETHODCALLTYPE`), useful in Windows. -* **`ref(...)`** - Marks the method with the reference qualification - specified. Required if overriding a method that has reference - qualifications. Eg `ref(&)` or `ref(&&)`. - -### Dealing with unprotected commas - -Unprotected commas, i.e. commas which are not surrounded by parentheses, prevent -`MOCK_METHOD` from parsing its arguments correctly: - -```cpp {.bad} -class MockFoo { - public: - MOCK_METHOD(std::pair, GetPair, ()); // Won't compile! - MOCK_METHOD(bool, CheckMap, (std::map, bool)); // Won't compile! -}; -``` - -Solution 1 - wrap with parentheses: - -```cpp {.good} -class MockFoo { - public: - MOCK_METHOD((std::pair), GetPair, ()); - MOCK_METHOD(bool, CheckMap, ((std::map), bool)); -}; -``` - -Note that wrapping a return or argument type with parentheses is, in general, -invalid C++. `MOCK_METHOD` removes the parentheses. - -Solution 2 - define an alias: - -```cpp {.good} -class MockFoo { - public: - using BoolAndInt = std::pair; - MOCK_METHOD(BoolAndInt, GetPair, ()); - using MapIntDouble = std::map; - MOCK_METHOD(bool, CheckMap, (MapIntDouble, bool)); -}; -``` - -### Mocking Private or Protected Methods - -You must always put a mock method definition (`MOCK_METHOD`) in a `public:` -section of the mock class, regardless of the method being mocked being `public`, -`protected`, or `private` in the base class. This allows `ON_CALL` and -`EXPECT_CALL` to reference the mock function from outside of the mock class. -(Yes, C++ allows a subclass to change the access level of a virtual function in -the base class.) Example: - -```cpp -class Foo { - public: - ... - virtual bool Transform(Gadget* g) = 0; - - protected: - virtual void Resume(); - - private: - virtual int GetTimeOut(); -}; - -class MockFoo : public Foo { - public: - ... - MOCK_METHOD(bool, Transform, (Gadget* g), (override)); - - // The following must be in the public section, even though the - // methods are protected or private in the base class. - MOCK_METHOD(void, Resume, (), (override)); - MOCK_METHOD(int, GetTimeOut, (), (override)); -}; -``` - -### Mocking Overloaded Methods - -You can mock overloaded functions as usual. No special attention is required: - -```cpp -class Foo { - ... - - // Must be virtual as we'll inherit from Foo. - virtual ~Foo(); - - // Overloaded on the types and/or numbers of arguments. - virtual int Add(Element x); - virtual int Add(int times, Element x); - - // Overloaded on the const-ness of this object. - virtual Bar& GetBar(); - virtual const Bar& GetBar() const; -}; - -class MockFoo : public Foo { - ... - MOCK_METHOD(int, Add, (Element x), (override)); - MOCK_METHOD(int, Add, (int times, Element x), (override)); - - MOCK_METHOD(Bar&, GetBar, (), (override)); - MOCK_METHOD(const Bar&, GetBar, (), (const, override)); -}; -``` - -**Note:** if you don't mock all versions of the overloaded method, the compiler -will give you a warning about some methods in the base class being hidden. To -fix that, use `using` to bring them in scope: - -```cpp -class MockFoo : public Foo { - ... - using Foo::Add; - MOCK_METHOD(int, Add, (Element x), (override)); - // We don't want to mock int Add(int times, Element x); - ... -}; -``` - -### Mocking Class Templates - -You can mock class templates just like any class. - -```cpp -template -class StackInterface { - ... - // Must be virtual as we'll inherit from StackInterface. - virtual ~StackInterface(); - - virtual int GetSize() const = 0; - virtual void Push(const Elem& x) = 0; -}; - -template -class MockStack : public StackInterface { - ... - MOCK_METHOD(int, GetSize, (), (override)); - MOCK_METHOD(void, Push, (const Elem& x), (override)); -}; -``` - -### Mocking Non-virtual Methods {#MockingNonVirtualMethods} - -gMock can mock non-virtual functions to be used in Hi-perf dependency -injection. - -In this case, instead of sharing a common base class with the real class, your -mock class will be *unrelated* to the real class, but contain methods with the -same signatures. The syntax for mocking non-virtual methods is the *same* as -mocking virtual methods (just don't add `override`): - -```cpp -// A simple packet stream class. None of its members is virtual. -class ConcretePacketStream { - public: - void AppendPacket(Packet* new_packet); - const Packet* GetPacket(size_t packet_number) const; - size_t NumberOfPackets() const; - ... -}; - -// A mock packet stream class. It inherits from no other, but defines -// GetPacket() and NumberOfPackets(). -class MockPacketStream { - public: - MOCK_METHOD(const Packet*, GetPacket, (size_t packet_number), (const)); - MOCK_METHOD(size_t, NumberOfPackets, (), (const)); - ... -}; -``` - -Note that the mock class doesn't define `AppendPacket()`, unlike the real class. -That's fine as long as the test doesn't need to call it. - -Next, you need a way to say that you want to use `ConcretePacketStream` in -production code, and use `MockPacketStream` in tests. Since the functions are -not virtual and the two classes are unrelated, you must specify your choice at -*compile time* (as opposed to run time). - -One way to do it is to templatize your code that needs to use a packet stream. -More specifically, you will give your code a template type argument for the type -of the packet stream. In production, you will instantiate your template with -`ConcretePacketStream` as the type argument. In tests, you will instantiate the -same template with `MockPacketStream`. For example, you may write: - -```cpp -template -void CreateConnection(PacketStream* stream) { ... } - -template -class PacketReader { - public: - void ReadPackets(PacketStream* stream, size_t packet_num); -}; -``` - -Then you can use `CreateConnection()` and -`PacketReader` in production code, and use -`CreateConnection()` and `PacketReader` in -tests. - -```cpp - MockPacketStream mock_stream; - EXPECT_CALL(mock_stream, ...)...; - .. set more expectations on mock_stream ... - PacketReader reader(&mock_stream); - ... exercise reader ... -``` - -### Mocking Free Functions - -It's possible to use gMock to mock a free function (i.e. a C-style function or a -static method). You just need to rewrite your code to use an interface (abstract -class). - -Instead of calling a free function (say, `OpenFile`) directly, introduce an -interface for it and have a concrete subclass that calls the free function: - -```cpp -class FileInterface { - public: - ... - virtual bool Open(const char* path, const char* mode) = 0; -}; - -class File : public FileInterface { - public: - ... - virtual bool Open(const char* path, const char* mode) { - return OpenFile(path, mode); - } -}; -``` - -Your code should talk to `FileInterface` to open a file. Now it's easy to mock -out the function. - -This may seem like a lot of hassle, but in practice you often have multiple -related functions that you can put in the same interface, so the per-function -syntactic overhead will be much lower. - -If you are concerned about the performance overhead incurred by virtual -functions, and profiling confirms your concern, you can combine this with the -recipe for [mocking non-virtual methods](#MockingNonVirtualMethods). - -### Old-Style `MOCK_METHODn` Macros - -Before the generic `MOCK_METHOD` macro -[was introduced in 2018](https://github.com/google/googletest/commit/c5f08bf91944ce1b19bcf414fa1760e69d20afc2), -mocks where created using a family of macros collectively called `MOCK_METHODn`. -These macros are still supported, though migration to the new `MOCK_METHOD` is -recommended. - -The macros in the `MOCK_METHODn` family differ from `MOCK_METHOD`: - -* The general structure is `MOCK_METHODn(MethodName, ReturnType(Args))`, - instead of `MOCK_METHOD(ReturnType, MethodName, (Args))`. -* The number `n` must equal the number of arguments. -* When mocking a const method, one must use `MOCK_CONST_METHODn`. -* When mocking a class template, the macro name must be suffixed with `_T`. -* In order to specify the call type, the macro name must be suffixed with - `_WITH_CALLTYPE`, and the call type is the first macro argument. - -Old macros and their new equivalents: - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Simple
Old `MOCK_METHOD1(Foo, bool(int))`
New `MOCK_METHOD(bool, Foo, (int))`
Const Method
Old -`MOCK_CONST_METHOD1(Foo, bool(int))`
New -`MOCK_METHOD(bool, Foo, (int), (const))`
Method in a Class Template
Old `MOCK_METHOD1_T(Foo, bool(int))`
New -`MOCK_METHOD(bool, Foo, (int))`
Const Method in a Class Template
Old - `MOCK_CONST_METHOD1_T(Foo, bool(int))`
New - `MOCK_METHOD(bool, Foo, (int), (const))`
Method with Call Type
Old -`MOCK_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))`
New `MOCK_METHOD(bool, Foo, (int), -(Calltype(STDMETHODCALLTYPE)))`
Const Method with Call Type
Old `MOCK_CONST_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))`
New `MOCK_METHOD(bool, Foo, (int), (const, -Calltype(STDMETHODCALLTYPE)))`
Method with Call Type in a Class Template
Old `MOCK_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, -bool(int))`
New `MOCK_METHOD(bool, Foo, (int), -(Calltype(STDMETHODCALLTYPE)))`
Const Method with Call Type in a Class Template
Old `MOCK_CONST_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, -Foo, bool(int))`
New `MOCK_METHOD(bool, Foo, -(int), (const, Calltype(STDMETHODCALLTYPE)))`
- -### The Nice, the Strict, and the Naggy {#NiceStrictNaggy} - -If a mock method has no `EXPECT_CALL` spec but is called, we say that it's an -"uninteresting call", and the default action (which can be specified using -`ON_CALL()`) of the method will be taken. Currently, an uninteresting call will -also by default cause gMock to print a warning. (In the future, we might remove -this warning by default.) - -However, sometimes you may want to ignore these uninteresting calls, and -sometimes you may want to treat them as errors. gMock lets you make the decision -on a per-mock-object basis. - -Suppose your test uses a mock class `MockFoo`: - -```cpp -TEST(...) { - MockFoo mock_foo; - EXPECT_CALL(mock_foo, DoThis()); - ... code that uses mock_foo ... -} -``` - -If a method of `mock_foo` other than `DoThis()` is called, you will get a -warning. However, if you rewrite your test to use `NiceMock` instead, -you can suppress the warning: - -```cpp -using ::testing::NiceMock; - -TEST(...) { - NiceMock mock_foo; - EXPECT_CALL(mock_foo, DoThis()); - ... code that uses mock_foo ... -} -``` - -`NiceMock` is a subclass of `MockFoo`, so it can be used wherever -`MockFoo` is accepted. - -It also works if `MockFoo`'s constructor takes some arguments, as -`NiceMock` "inherits" `MockFoo`'s constructors: - -```cpp -using ::testing::NiceMock; - -TEST(...) { - NiceMock mock_foo(5, "hi"); // Calls MockFoo(5, "hi"). - EXPECT_CALL(mock_foo, DoThis()); - ... code that uses mock_foo ... -} -``` - -The usage of `StrictMock` is similar, except that it makes all uninteresting -calls failures: - -```cpp -using ::testing::StrictMock; - -TEST(...) { - StrictMock mock_foo; - EXPECT_CALL(mock_foo, DoThis()); - ... code that uses mock_foo ... - - // The test will fail if a method of mock_foo other than DoThis() - // is called. -} -``` - -NOTE: `NiceMock` and `StrictMock` only affects *uninteresting* calls (calls of -*methods* with no expectations); they do not affect *unexpected* calls (calls of -methods with expectations, but they don't match). See -[Understanding Uninteresting vs Unexpected Calls](#uninteresting-vs-unexpected). - -There are some caveats though (sadly they are side effects of C++'s -limitations): - -1. `NiceMock` and `StrictMock` only work for mock methods - defined using the `MOCK_METHOD` macro **directly** in the `MockFoo` class. - If a mock method is defined in a **base class** of `MockFoo`, the "nice" or - "strict" modifier may not affect it, depending on the compiler. In - particular, nesting `NiceMock` and `StrictMock` (e.g. - `NiceMock >`) is **not** supported. -2. `NiceMock` and `StrictMock` may not work correctly if the - destructor of `MockFoo` is not virtual. We would like to fix this, but it - requires cleaning up existing tests. - -Finally, you should be **very cautious** about when to use naggy or strict -mocks, as they tend to make tests more brittle and harder to maintain. When you -refactor your code without changing its externally visible behavior, ideally you -shouldn't need to update any tests. If your code interacts with a naggy mock, -however, you may start to get spammed with warnings as the result of your -change. Worse, if your code interacts with a strict mock, your tests may start -to fail and you'll be forced to fix them. Our general recommendation is to use -nice mocks (not yet the default) most of the time, use naggy mocks (the current -default) when developing or debugging tests, and use strict mocks only as the -last resort. - -### Simplifying the Interface without Breaking Existing Code {#SimplerInterfaces} - -Sometimes a method has a long list of arguments that is mostly uninteresting. -For example: - -```cpp -class LogSink { - public: - ... - virtual void send(LogSeverity severity, const char* full_filename, - const char* base_filename, int line, - const struct tm* tm_time, - const char* message, size_t message_len) = 0; -}; -``` - -This method's argument list is lengthy and hard to work with (the `message` -argument is not even 0-terminated). If we mock it as is, using the mock will be -awkward. If, however, we try to simplify this interface, we'll need to fix all -clients depending on it, which is often infeasible. - -The trick is to redispatch the method in the mock class: - -```cpp -class ScopedMockLog : public LogSink { - public: - ... - virtual void send(LogSeverity severity, const char* full_filename, - const char* base_filename, int line, const tm* tm_time, - const char* message, size_t message_len) { - // We are only interested in the log severity, full file name, and - // log message. - Log(severity, full_filename, std::string(message, message_len)); - } - - // Implements the mock method: - // - // void Log(LogSeverity severity, - // const string& file_path, - // const string& message); - MOCK_METHOD(void, Log, - (LogSeverity severity, const string& file_path, - const string& message)); -}; -``` - -By defining a new mock method with a trimmed argument list, we make the mock -class more user-friendly. - -This technique may also be applied to make overloaded methods more amenable to -mocking. For example, when overloads have been used to implement default -arguments: - -```cpp -class MockTurtleFactory : public TurtleFactory { - public: - Turtle* MakeTurtle(int length, int weight) override { ... } - Turtle* MakeTurtle(int length, int weight, int speed) override { ... } - - // the above methods delegate to this one: - MOCK_METHOD(Turtle*, DoMakeTurtle, ()); -}; -``` - -This allows tests that don't care which overload was invoked to avoid specifying -argument matchers: - -```cpp -ON_CALL(factory, DoMakeTurtle) - .WillByDefault(Return(MakeMockTurtle())); -``` - -### Alternative to Mocking Concrete Classes - -Often you may find yourself using classes that don't implement interfaces. In -order to test your code that uses such a class (let's call it `Concrete`), you -may be tempted to make the methods of `Concrete` virtual and then mock it. - -Try not to do that. - -Making a non-virtual function virtual is a big decision. It creates an extension -point where subclasses can tweak your class' behavior. This weakens your control -on the class because now it's harder to maintain the class invariants. You -should make a function virtual only when there is a valid reason for a subclass -to override it. - -Mocking concrete classes directly is problematic as it creates a tight coupling -between the class and the tests - any small change in the class may invalidate -your tests and make test maintenance a pain. - -To avoid such problems, many programmers have been practicing "coding to -interfaces": instead of talking to the `Concrete` class, your code would define -an interface and talk to it. Then you implement that interface as an adaptor on -top of `Concrete`. In tests, you can easily mock that interface to observe how -your code is doing. - -This technique incurs some overhead: - -* You pay the cost of virtual function calls (usually not a problem). -* There is more abstraction for the programmers to learn. - -However, it can also bring significant benefits in addition to better -testability: - -* `Concrete`'s API may not fit your problem domain very well, as you may not - be the only client it tries to serve. By designing your own interface, you - have a chance to tailor it to your need - you may add higher-level - functionalities, rename stuff, etc instead of just trimming the class. This - allows you to write your code (user of the interface) in a more natural way, - which means it will be more readable, more maintainable, and you'll be more - productive. -* If `Concrete`'s implementation ever has to change, you don't have to rewrite - everywhere it is used. Instead, you can absorb the change in your - implementation of the interface, and your other code and tests will be - insulated from this change. - -Some people worry that if everyone is practicing this technique, they will end -up writing lots of redundant code. This concern is totally understandable. -However, there are two reasons why it may not be the case: - -* Different projects may need to use `Concrete` in different ways, so the best - interfaces for them will be different. Therefore, each of them will have its - own domain-specific interface on top of `Concrete`, and they will not be the - same code. -* If enough projects want to use the same interface, they can always share it, - just like they have been sharing `Concrete`. You can check in the interface - and the adaptor somewhere near `Concrete` (perhaps in a `contrib` - sub-directory) and let many projects use it. - -You need to weigh the pros and cons carefully for your particular problem, but -I'd like to assure you that the Java community has been practicing this for a -long time and it's a proven effective technique applicable in a wide variety of -situations. :-) - -### Delegating Calls to a Fake {#DelegatingToFake} - -Some times you have a non-trivial fake implementation of an interface. For -example: - -```cpp -class Foo { - public: - virtual ~Foo() {} - virtual char DoThis(int n) = 0; - virtual void DoThat(const char* s, int* p) = 0; -}; - -class FakeFoo : public Foo { - public: - char DoThis(int n) override { - return (n > 0) ? '+' : - (n < 0) ? '-' : '0'; - } - - void DoThat(const char* s, int* p) override { - *p = strlen(s); - } -}; -``` - -Now you want to mock this interface such that you can set expectations on it. -However, you also want to use `FakeFoo` for the default behavior, as duplicating -it in the mock object is, well, a lot of work. - -When you define the mock class using gMock, you can have it delegate its default -action to a fake class you already have, using this pattern: - -```cpp -class MockFoo : public Foo { - public: - // Normal mock method definitions using gMock. - MOCK_METHOD(char, DoThis, (int n), (override)); - MOCK_METHOD(void, DoThat, (const char* s, int* p), (override)); - - // Delegates the default actions of the methods to a FakeFoo object. - // This must be called *before* the custom ON_CALL() statements. - void DelegateToFake() { - ON_CALL(*this, DoThis).WillByDefault([this](int n) { - return fake_.DoThis(n); - }); - ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) { - fake_.DoThat(s, p); - }); - } - - private: - FakeFoo fake_; // Keeps an instance of the fake in the mock. -}; -``` - -With that, you can use `MockFoo` in your tests as usual. Just remember that if -you don't explicitly set an action in an `ON_CALL()` or `EXPECT_CALL()`, the -fake will be called upon to do it.: - -```cpp -using ::testing::_; - -TEST(AbcTest, Xyz) { - MockFoo foo; - - foo.DelegateToFake(); // Enables the fake for delegation. - - // Put your ON_CALL(foo, ...)s here, if any. - - // No action specified, meaning to use the default action. - EXPECT_CALL(foo, DoThis(5)); - EXPECT_CALL(foo, DoThat(_, _)); - - int n = 0; - EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked. - foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked. - EXPECT_EQ(2, n); -} -``` - -**Some tips:** - -* If you want, you can still override the default action by providing your own - `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`. -* In `DelegateToFake()`, you only need to delegate the methods whose fake - implementation you intend to use. - -* The general technique discussed here works for overloaded methods, but - you'll need to tell the compiler which version you mean. To disambiguate a - mock function (the one you specify inside the parentheses of `ON_CALL()`), - use [this technique](#SelectOverload); to disambiguate a fake function (the - one you place inside `Invoke()`), use a `static_cast` to specify the - function's type. For instance, if class `Foo` has methods `char DoThis(int - n)` and `bool DoThis(double x) const`, and you want to invoke the latter, - you need to write `Invoke(&fake_, static_cast(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)` - (The strange-looking thing inside the angled brackets of `static_cast` is - the type of a function pointer to the second `DoThis()` method.). - -* Having to mix a mock and a fake is often a sign of something gone wrong. - Perhaps you haven't got used to the interaction-based way of testing yet. Or - perhaps your interface is taking on too many roles and should be split up. - Therefore, **don't abuse this**. We would only recommend to do it as an - intermediate step when you are refactoring your code. - -Regarding the tip on mixing a mock and a fake, here's an example on why it may -be a bad sign: Suppose you have a class `System` for low-level system -operations. In particular, it does file and I/O operations. And suppose you want -to test how your code uses `System` to do I/O, and you just want the file -operations to work normally. If you mock out the entire `System` class, you'll -have to provide a fake implementation for the file operation part, which -suggests that `System` is taking on too many roles. - -Instead, you can define a `FileOps` interface and an `IOOps` interface and split -`System`'s functionalities into the two. Then you can mock `IOOps` without -mocking `FileOps`. - -### Delegating Calls to a Real Object - -When using testing doubles (mocks, fakes, stubs, and etc), sometimes their -behaviors will differ from those of the real objects. This difference could be -either intentional (as in simulating an error such that you can test the error -handling code) or unintentional. If your mocks have different behaviors than the -real objects by mistake, you could end up with code that passes the tests but -fails in production. - -You can use the *delegating-to-real* technique to ensure that your mock has the -same behavior as the real object while retaining the ability to validate calls. -This technique is very similar to the [delegating-to-fake](#DelegatingToFake) -technique, the difference being that we use a real object instead of a fake. -Here's an example: - -```cpp -using ::testing::AtLeast; - -class MockFoo : public Foo { - public: - MockFoo() { - // By default, all calls are delegated to the real object. - ON_CALL(*this, DoThis).WillByDefault([this](int n) { - return real_.DoThis(n); - }); - ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) { - real_.DoThat(s, p); - }); - ... - } - MOCK_METHOD(char, DoThis, ...); - MOCK_METHOD(void, DoThat, ...); - ... - private: - Foo real_; -}; - -... - MockFoo mock; - EXPECT_CALL(mock, DoThis()) - .Times(3); - EXPECT_CALL(mock, DoThat("Hi")) - .Times(AtLeast(1)); - ... use mock in test ... -``` - -With this, gMock will verify that your code made the right calls (with the right -arguments, in the right order, called the right number of times, etc), and a -real object will answer the calls (so the behavior will be the same as in -production). This gives you the best of both worlds. - -### Delegating Calls to a Parent Class - -Ideally, you should code to interfaces, whose methods are all pure virtual. In -reality, sometimes you do need to mock a virtual method that is not pure (i.e, -it already has an implementation). For example: - -```cpp -class Foo { - public: - virtual ~Foo(); - - virtual void Pure(int n) = 0; - virtual int Concrete(const char* str) { ... } -}; - -class MockFoo : public Foo { - public: - // Mocking a pure method. - MOCK_METHOD(void, Pure, (int n), (override)); - // Mocking a concrete method. Foo::Concrete() is shadowed. - MOCK_METHOD(int, Concrete, (const char* str), (override)); -}; -``` - -Sometimes you may want to call `Foo::Concrete()` instead of -`MockFoo::Concrete()`. Perhaps you want to do it as part of a stub action, or -perhaps your test doesn't need to mock `Concrete()` at all (but it would be -oh-so painful to have to define a new mock class whenever you don't need to mock -one of its methods). - -You can call `Foo::Concrete()` inside an action by: - -```cpp -... - EXPECT_CALL(foo, Concrete).WillOnce([&foo](const char* str) { - return foo.Foo::Concrete(str); - }); -``` - -or tell the mock object that you don't want to mock `Concrete()`: - -```cpp -... - ON_CALL(foo, Concrete).WillByDefault([&foo](const char* str) { - return foo.Foo::Concrete(str); - }); -``` - -(Why don't we just write `{ return foo.Concrete(str); }`? If you do that, -`MockFoo::Concrete()` will be called (and cause an infinite recursion) since -`Foo::Concrete()` is virtual. That's just how C++ works.) - -## Using Matchers - -### Matching Argument Values Exactly - -You can specify exactly which arguments a mock method is expecting: - -```cpp -using ::testing::Return; -... - EXPECT_CALL(foo, DoThis(5)) - .WillOnce(Return('a')); - EXPECT_CALL(foo, DoThat("Hello", bar)); -``` - -### Using Simple Matchers - -You can use matchers to match arguments that have a certain property: - -```cpp -using ::testing::NotNull; -using ::testing::Return; -... - EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5. - .WillOnce(Return('a')); - EXPECT_CALL(foo, DoThat("Hello", NotNull())); - // The second argument must not be NULL. -``` - -A frequently used matcher is `_`, which matches anything: - -```cpp - EXPECT_CALL(foo, DoThat(_, NotNull())); -``` - - -### Combining Matchers {#CombiningMatchers} - -You can build complex matchers from existing ones using `AllOf()`, -`AllOfArray()`, `AnyOf()`, `AnyOfArray()` and `Not()`: - -```cpp -using ::testing::AllOf; -using ::testing::Gt; -using ::testing::HasSubstr; -using ::testing::Ne; -using ::testing::Not; -... - // The argument must be > 5 and != 10. - EXPECT_CALL(foo, DoThis(AllOf(Gt(5), - Ne(10)))); - - // The first argument must not contain sub-string "blah". - EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")), - NULL)); -``` - -Matchers are function objects, and parametrized matchers can be composed just -like any other function. However because their types can be long and rarely -provide meaningful information, it can be easier to express them with C++14 -generic lambdas to avoid specifying types. For example, - -```cpp -using ::testing::Contains; -using ::testing::Property; - -inline constexpr auto HasFoo = [](const auto& f) { - return Property(&MyClass::foo, Contains(f)); -}; -... - EXPECT_THAT(x, HasFoo("blah")); -``` - -### Casting Matchers {#SafeMatcherCast} - -gMock matchers are statically typed, meaning that the compiler can catch your -mistake if you use a matcher of the wrong type (for example, if you use `Eq(5)` -to match a `string` argument). Good for you! - -Sometimes, however, you know what you're doing and want the compiler to give you -some slack. One example is that you have a matcher for `long` and the argument -you want to match is `int`. While the two types aren't exactly the same, there -is nothing really wrong with using a `Matcher` to match an `int` - after -all, we can first convert the `int` argument to a `long` losslessly before -giving it to the matcher. - -To support this need, gMock gives you the `SafeMatcherCast(m)` function. It -casts a matcher `m` to type `Matcher`. To ensure safety, gMock checks that -(let `U` be the type `m` accepts : - -1. Type `T` can be *implicitly* cast to type `U`; -2. When both `T` and `U` are built-in arithmetic types (`bool`, integers, and - floating-point numbers), the conversion from `T` to `U` is not lossy (in - other words, any value representable by `T` can also be represented by `U`); - and -3. When `U` is a reference, `T` must also be a reference (as the underlying - matcher may be interested in the address of the `U` value). - -The code won't compile if any of these conditions isn't met. - -Here's one example: - -```cpp -using ::testing::SafeMatcherCast; - -// A base class and a child class. -class Base { ... }; -class Derived : public Base { ... }; - -class MockFoo : public Foo { - public: - MOCK_METHOD(void, DoThis, (Derived* derived), (override)); -}; - -... - MockFoo foo; - // m is a Matcher we got from somewhere. - EXPECT_CALL(foo, DoThis(SafeMatcherCast(m))); -``` - -If you find `SafeMatcherCast(m)` too limiting, you can use a similar function -`MatcherCast(m)`. The difference is that `MatcherCast` works as long as you -can `static_cast` type `T` to type `U`. - -`MatcherCast` essentially lets you bypass C++'s type system (`static_cast` isn't -always safe as it could throw away information, for example), so be careful not -to misuse/abuse it. - -### Selecting Between Overloaded Functions {#SelectOverload} - -If you expect an overloaded function to be called, the compiler may need some -help on which overloaded version it is. - -To disambiguate functions overloaded on the const-ness of this object, use the -`Const()` argument wrapper. - -```cpp -using ::testing::ReturnRef; - -class MockFoo : public Foo { - ... - MOCK_METHOD(Bar&, GetBar, (), (override)); - MOCK_METHOD(const Bar&, GetBar, (), (const, override)); -}; - -... - MockFoo foo; - Bar bar1, bar2; - EXPECT_CALL(foo, GetBar()) // The non-const GetBar(). - .WillOnce(ReturnRef(bar1)); - EXPECT_CALL(Const(foo), GetBar()) // The const GetBar(). - .WillOnce(ReturnRef(bar2)); -``` - -(`Const()` is defined by gMock and returns a `const` reference to its argument.) - -To disambiguate overloaded functions with the same number of arguments but -different argument types, you may need to specify the exact type of a matcher, -either by wrapping your matcher in `Matcher()`, or using a matcher whose -type is fixed (`TypedEq`, `An()`, etc): - -```cpp -using ::testing::An; -using ::testing::Matcher; -using ::testing::TypedEq; - -class MockPrinter : public Printer { - public: - MOCK_METHOD(void, Print, (int n), (override)); - MOCK_METHOD(void, Print, (char c), (override)); -}; - -TEST(PrinterTest, Print) { - MockPrinter printer; - - EXPECT_CALL(printer, Print(An())); // void Print(int); - EXPECT_CALL(printer, Print(Matcher(Lt(5)))); // void Print(int); - EXPECT_CALL(printer, Print(TypedEq('a'))); // void Print(char); - - printer.Print(3); - printer.Print(6); - printer.Print('a'); -} -``` - -### Performing Different Actions Based on the Arguments - -When a mock method is called, the *last* matching expectation that's still -active will be selected (think "newer overrides older"). So, you can make a -method do different things depending on its argument values like this: - -```cpp -using ::testing::_; -using ::testing::Lt; -using ::testing::Return; -... - // The default case. - EXPECT_CALL(foo, DoThis(_)) - .WillRepeatedly(Return('b')); - // The more specific case. - EXPECT_CALL(foo, DoThis(Lt(5))) - .WillRepeatedly(Return('a')); -``` - -Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will be -returned; otherwise `'b'` will be returned. - -### Matching Multiple Arguments as a Whole - -Sometimes it's not enough to match the arguments individually. For example, we -may want to say that the first argument must be less than the second argument. -The `With()` clause allows us to match all arguments of a mock function as a -whole. For example, - -```cpp -using ::testing::_; -using ::testing::Ne; -using ::testing::Lt; -... - EXPECT_CALL(foo, InRange(Ne(0), _)) - .With(Lt()); -``` - -says that the first argument of `InRange()` must not be 0, and must be less than -the second argument. - -The expression inside `With()` must be a matcher of type `Matcher>`, where `A1`, ..., `An` are the types of the function arguments. - -You can also write `AllArgs(m)` instead of `m` inside `.With()`. The two forms -are equivalent, but `.With(AllArgs(Lt()))` is more readable than `.With(Lt())`. - -You can use `Args(m)` to match the `n` selected arguments (as a -tuple) against `m`. For example, - -```cpp -using ::testing::_; -using ::testing::AllOf; -using ::testing::Args; -using ::testing::Lt; -... - EXPECT_CALL(foo, Blah) - .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt()))); -``` - -says that `Blah` will be called with arguments `x`, `y`, and `z` where `x < y < -z`. Note that in this example, it wasn't necessary specify the positional -matchers. - -As a convenience and example, gMock provides some matchers for 2-tuples, -including the `Lt()` matcher above. See [here](#MultiArgMatchers) for the -complete list. - -Note that if you want to pass the arguments to a predicate of your own (e.g. -`.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be written to -take a `std::tuple` as its argument; gMock will pass the `n` selected arguments -as *one* single tuple to the predicate. - -### Using Matchers as Predicates - -Have you noticed that a matcher is just a fancy predicate that also knows how to -describe itself? Many existing algorithms take predicates as arguments (e.g. -those defined in STL's `` header), and it would be a shame if gMock -matchers were not allowed to participate. - -Luckily, you can use a matcher where a unary predicate functor is expected by -wrapping it inside the `Matches()` function. For example, - -```cpp -#include -#include - -using ::testing::Matches; -using ::testing::Ge; - -vector v; -... -// How many elements in v are >= 10? -const int count = count_if(v.begin(), v.end(), Matches(Ge(10))); -``` - -Since you can build complex matchers from simpler ones easily using gMock, this -gives you a way to conveniently construct composite predicates (doing the same -using STL's `` header is just painful). For example, here's a -predicate that's satisfied by any number that is >= 0, <= 100, and != 50: - -```cpp -using testing::AllOf; -using testing::Ge; -using testing::Le; -using testing::Matches; -using testing::Ne; -... -Matches(AllOf(Ge(0), Le(100), Ne(50))) -``` - -### Using Matchers in googletest Assertions - -Since matchers are basically predicates that also know how to describe -themselves, there is a way to take advantage of them in googletest assertions. -It's called `ASSERT_THAT` and `EXPECT_THAT`: - -```cpp - ASSERT_THAT(value, matcher); // Asserts that value matches matcher. - EXPECT_THAT(value, matcher); // The non-fatal version. -``` - -For example, in a googletest test you can write: - -```cpp -#include "gmock/gmock.h" - -using ::testing::AllOf; -using ::testing::Ge; -using ::testing::Le; -using ::testing::MatchesRegex; -using ::testing::StartsWith; - -... - EXPECT_THAT(Foo(), StartsWith("Hello")); - EXPECT_THAT(Bar(), MatchesRegex("Line \\d+")); - ASSERT_THAT(Baz(), AllOf(Ge(5), Le(10))); -``` - -which (as you can probably guess) executes `Foo()`, `Bar()`, and `Baz()`, and -verifies that: - -* `Foo()` returns a string that starts with `"Hello"`. -* `Bar()` returns a string that matches regular expression `"Line \\d+"`. -* `Baz()` returns a number in the range [5, 10]. - -The nice thing about these macros is that *they read like English*. They -generate informative messages too. For example, if the first `EXPECT_THAT()` -above fails, the message will be something like: - -```cpp -Value of: Foo() - Actual: "Hi, world!" -Expected: starts with "Hello" -``` - -**Credit:** The idea of `(ASSERT|EXPECT)_THAT` was borrowed from Joe Walnes' -Hamcrest project, which adds `assertThat()` to JUnit. - -### Using Predicates as Matchers - -gMock provides a [built-in set](cheat_sheet.md#MatcherList) of matchers. In case -you find them lacking, you can use an arbitrary unary predicate function or -functor as a matcher - as long as the predicate accepts a value of the type you -want. You do this by wrapping the predicate inside the `Truly()` function, for -example: - -```cpp -using ::testing::Truly; - -int IsEven(int n) { return (n % 2) == 0 ? 1 : 0; } -... - // Bar() must be called with an even number. - EXPECT_CALL(foo, Bar(Truly(IsEven))); -``` - -Note that the predicate function / functor doesn't have to return `bool`. It -works as long as the return value can be used as the condition in in statement -`if (condition) ...`. - - - -### Matching Arguments that Are Not Copyable - -When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of -`bar`. When `Foo()` is called later, gMock compares the argument to `Foo()` with -the saved copy of `bar`. This way, you don't need to worry about `bar` being -modified or destroyed after the `EXPECT_CALL()` is executed. The same is true -when you use matchers like `Eq(bar)`, `Le(bar)`, and so on. - -But what if `bar` cannot be copied (i.e. has no copy constructor)? You could -define your own matcher function or callback and use it with `Truly()`, as the -previous couple of recipes have shown. Or, you may be able to get away from it -if you can guarantee that `bar` won't be changed after the `EXPECT_CALL()` is -executed. Just tell gMock that it should save a reference to `bar`, instead of a -copy of it. Here's how: - -```cpp -using ::testing::Eq; -using ::testing::Lt; -... - // Expects that Foo()'s argument == bar. - EXPECT_CALL(mock_obj, Foo(Eq(std::ref(bar)))); - - // Expects that Foo()'s argument < bar. - EXPECT_CALL(mock_obj, Foo(Lt(std::ref(bar)))); -``` - -Remember: if you do this, don't change `bar` after the `EXPECT_CALL()`, or the -result is undefined. - -### Validating a Member of an Object - -Often a mock function takes a reference to object as an argument. When matching -the argument, you may not want to compare the entire object against a fixed -object, as that may be over-specification. Instead, you may need to validate a -certain member variable or the result of a certain getter method of the object. -You can do this with `Field()` and `Property()`. More specifically, - -```cpp -Field(&Foo::bar, m) -``` - -is a matcher that matches a `Foo` object whose `bar` member variable satisfies -matcher `m`. - -```cpp -Property(&Foo::baz, m) -``` - -is a matcher that matches a `Foo` object whose `baz()` method returns a value -that satisfies matcher `m`. - -For example: - - -| Expression | Description | -| :--------------------------- | :--------------------------------------- | -| `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. | -| `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. | - - -Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument -and be declared as `const`. - -BTW, `Field()` and `Property()` can also match plain pointers to objects. For -instance, - -```cpp -using ::testing::Field; -using ::testing::Ge; -... -Field(&Foo::number, Ge(3)) -``` - -matches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`, the match -will always fail regardless of the inner matcher. - -What if you want to validate more than one members at the same time? Remember -that there are [`AllOf()` and `AllOfArray()`](#CombiningMatchers). - -Finally `Field()` and `Property()` provide overloads that take the field or -property names as the first argument to include it in the error message. This -can be useful when creating combined matchers. - -```cpp -using ::testing::AllOf; -using ::testing::Field; -using ::testing::Matcher; -using ::testing::SafeMatcherCast; - -Matcher IsFoo(const Foo& foo) { - return AllOf(Field("some_field", &Foo::some_field, foo.some_field), - Field("other_field", &Foo::other_field, foo.other_field), - Field("last_field", &Foo::last_field, foo.last_field)); -} -``` - -### Validating the Value Pointed to by a Pointer Argument - -C++ functions often take pointers as arguments. You can use matchers like -`IsNull()`, `NotNull()`, and other comparison matchers to match a pointer, but -what if you want to make sure the value *pointed to* by the pointer, instead of -the pointer itself, has a certain property? Well, you can use the `Pointee(m)` -matcher. - -`Pointee(m)` matches a pointer if and only if `m` matches the value the pointer -points to. For example: - -```cpp -using ::testing::Ge; -using ::testing::Pointee; -... - EXPECT_CALL(foo, Bar(Pointee(Ge(3)))); -``` - -expects `foo.Bar()` to be called with a pointer that points to a value greater -than or equal to 3. - -One nice thing about `Pointee()` is that it treats a `NULL` pointer as a match -failure, so you can write `Pointee(m)` instead of - -```cpp -using ::testing::AllOf; -using ::testing::NotNull; -using ::testing::Pointee; -... - AllOf(NotNull(), Pointee(m)) -``` - -without worrying that a `NULL` pointer will crash your test. - -Also, did we tell you that `Pointee()` works with both raw pointers **and** -smart pointers (`std::unique_ptr`, `std::shared_ptr`, etc)? - -What if you have a pointer to pointer? You guessed it - you can use nested -`Pointee()` to probe deeper inside the value. For example, -`Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer that points -to a number less than 3 (what a mouthful...). - -### Testing a Certain Property of an Object - -Sometimes you want to specify that an object argument has a certain property, -but there is no existing matcher that does this. If you want good error -messages, you should [define a matcher](#NewMatchers). If you want to do it -quick and dirty, you could get away with writing an ordinary function. - -Let's say you have a mock function that takes an object of type `Foo`, which has -an `int bar()` method and an `int baz()` method, and you want to constrain that -the argument's `bar()` value plus its `baz()` value is a given number. Here's -how you can define a matcher to do it: - -```cpp -using ::testing::Matcher; -using ::testing::MatcherInterface; -using ::testing::MatchResultListener; - -class BarPlusBazEqMatcher : public MatcherInterface { - public: - explicit BarPlusBazEqMatcher(int expected_sum) - : expected_sum_(expected_sum) {} - - bool MatchAndExplain(const Foo& foo, - MatchResultListener* /* listener */) const override { - return (foo.bar() + foo.baz()) == expected_sum_; - } - - void DescribeTo(std::ostream* os) const override { - *os << "bar() + baz() equals " << expected_sum_; - } - - void DescribeNegationTo(std::ostream* os) const override { - *os << "bar() + baz() does not equal " << expected_sum_; - } - private: - const int expected_sum_; -}; - -Matcher BarPlusBazEq(int expected_sum) { - return MakeMatcher(new BarPlusBazEqMatcher(expected_sum)); -} - -... - EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...; -``` - -### Matching Containers - -Sometimes an STL container (e.g. list, vector, map, ...) is passed to a mock -function and you may want to validate it. Since most STL containers support the -`==` operator, you can write `Eq(expected_container)` or simply -`expected_container` to match a container exactly. - -Sometimes, though, you may want to be more flexible (for example, the first -element must be an exact match, but the second element can be any positive -number, and so on). Also, containers used in tests often have a small number of -elements, and having to define the expected container out-of-line is a bit of a -hassle. - -You can use the `ElementsAre()` or `UnorderedElementsAre()` matcher in such -cases: - -```cpp -using ::testing::_; -using ::testing::ElementsAre; -using ::testing::Gt; -... - MOCK_METHOD(void, Foo, (const vector& numbers), (override)); -... - EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5))); -``` - -The above matcher says that the container must have 4 elements, which must be 1, -greater than 0, anything, and 5 respectively. - -If you instead write: - -```cpp -using ::testing::_; -using ::testing::Gt; -using ::testing::UnorderedElementsAre; -... - MOCK_METHOD(void, Foo, (const vector& numbers), (override)); -... - EXPECT_CALL(mock, Foo(UnorderedElementsAre(1, Gt(0), _, 5))); -``` - -It means that the container must have 4 elements, which (under some permutation) -must be 1, greater than 0, anything, and 5 respectively. - -As an alternative you can place the arguments in a C-style array and use -`ElementsAreArray()` or `UnorderedElementsAreArray()` instead: - -```cpp -using ::testing::ElementsAreArray; -... - // ElementsAreArray accepts an array of element values. - const int expected_vector1[] = {1, 5, 2, 4, ...}; - EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1))); - - // Or, an array of element matchers. - Matcher expected_vector2[] = {1, Gt(2), _, 3, ...}; - EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2))); -``` - -In case the array needs to be dynamically created (and therefore the array size -cannot be inferred by the compiler), you can give `ElementsAreArray()` an -additional argument to specify the array size: - -```cpp -using ::testing::ElementsAreArray; -... - int* const expected_vector3 = new int[count]; - ... fill expected_vector3 with values ... - EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count))); -``` - -Use `Pair` when comparing maps or other associative containers. - -```cpp -using testing::ElementsAre; -using testing::Pair; -... - std::map m = {{"a", 1}, {"b", 2}, {"c", 3}}; - EXPECT_THAT(m, ElementsAre(Pair("a", 1), Pair("b", 2), Pair("c", 3))); -``` - -**Tips:** - -* `ElementsAre*()` can be used to match *any* container that implements the - STL iterator pattern (i.e. it has a `const_iterator` type and supports - `begin()/end()`), not just the ones defined in STL. It will even work with - container types yet to be written - as long as they follows the above - pattern. -* You can use nested `ElementsAre*()` to match nested (multi-dimensional) - containers. -* If the container is passed by pointer instead of by reference, just write - `Pointee(ElementsAre*(...))`. -* The order of elements *matters* for `ElementsAre*()`. If you are using it - with containers whose element order are undefined (e.g. `hash_map`) you - should use `WhenSorted` around `ElementsAre`. - -### Sharing Matchers - -Under the hood, a gMock matcher object consists of a pointer to a ref-counted -implementation object. Copying matchers is allowed and very efficient, as only -the pointer is copied. When the last matcher that references the implementation -object dies, the implementation object will be deleted. - -Therefore, if you have some complex matcher that you want to use again and -again, there is no need to build it everytime. Just assign it to a matcher -variable and use that variable repeatedly! For example, - -```cpp -using ::testing::AllOf; -using ::testing::Gt; -using ::testing::Le; -using ::testing::Matcher; -... - Matcher in_range = AllOf(Gt(5), Le(10)); - ... use in_range as a matcher in multiple EXPECT_CALLs ... -``` - -### Matchers must have no side-effects {#PureMatchers} - -WARNING: gMock does not guarantee when or how many times a matcher will be -invoked. Therefore, all matchers must be *purely functional*: they cannot have -any side effects, and the match result must not depend on anything other than -the matcher's parameters and the value being matched. - -This requirement must be satisfied no matter how a matcher is defined (e.g., if -it is one of the standard matchers, or a custom matcher). In particular, a -matcher can never call a mock function, as that will affect the state of the -mock object and gMock. - -## Setting Expectations - -### Knowing When to Expect {#UseOnCall} - - - -**`ON_CALL`** is likely the *single most under-utilized construct* in gMock. - -There are basically two constructs for defining the behavior of a mock object: -`ON_CALL` and `EXPECT_CALL`. The difference? `ON_CALL` defines what happens when -a mock method is called, but doesn't imply any expectation on the method -being called. `EXPECT_CALL` not only defines the behavior, but also sets an -expectation that the method will be called with the given arguments, for the -given number of times (and *in the given order* when you specify the order -too). - -Since `EXPECT_CALL` does more, isn't it better than `ON_CALL`? Not really. Every -`EXPECT_CALL` adds a constraint on the behavior of the code under test. Having -more constraints than necessary is *baaad* - even worse than not having enough -constraints. - -This may be counter-intuitive. How could tests that verify more be worse than -tests that verify less? Isn't verification the whole point of tests? - -The answer lies in *what* a test should verify. **A good test verifies the -contract of the code.** If a test over-specifies, it doesn't leave enough -freedom to the implementation. As a result, changing the implementation without -breaking the contract (e.g. refactoring and optimization), which should be -perfectly fine to do, can break such tests. Then you have to spend time fixing -them, only to see them broken again the next time the implementation is changed. - -Keep in mind that one doesn't have to verify more than one property in one test. -In fact, **it's a good style to verify only one thing in one test.** If you do -that, a bug will likely break only one or two tests instead of dozens (which -case would you rather debug?). If you are also in the habit of giving tests -descriptive names that tell what they verify, you can often easily guess what's -wrong just from the test log itself. - -So use `ON_CALL` by default, and only use `EXPECT_CALL` when you actually intend -to verify that the call is made. For example, you may have a bunch of `ON_CALL`s -in your test fixture to set the common mock behavior shared by all tests in the -same group, and write (scarcely) different `EXPECT_CALL`s in different `TEST_F`s -to verify different aspects of the code's behavior. Compared with the style -where each `TEST` has many `EXPECT_CALL`s, this leads to tests that are more -resilient to implementational changes (and thus less likely to require -maintenance) and makes the intent of the tests more obvious (so they are easier -to maintain when you do need to maintain them). - -If you are bothered by the "Uninteresting mock function call" message printed -when a mock method without an `EXPECT_CALL` is called, you may use a `NiceMock` -instead to suppress all such messages for the mock object, or suppress the -message for specific methods by adding `EXPECT_CALL(...).Times(AnyNumber())`. DO -NOT suppress it by blindly adding an `EXPECT_CALL(...)`, or you'll have a test -that's a pain to maintain. - -### Ignoring Uninteresting Calls - -If you are not interested in how a mock method is called, just don't say -anything about it. In this case, if the method is ever called, gMock will -perform its default action to allow the test program to continue. If you are not -happy with the default action taken by gMock, you can override it using -`DefaultValue::Set()` (described [here](#DefaultValue)) or `ON_CALL()`. - -Please note that once you expressed interest in a particular mock method (via -`EXPECT_CALL()`), all invocations to it must match some expectation. If this -function is called but the arguments don't match any `EXPECT_CALL()` statement, -it will be an error. - -### Disallowing Unexpected Calls - -If a mock method shouldn't be called at all, explicitly say so: - -```cpp -using ::testing::_; -... - EXPECT_CALL(foo, Bar(_)) - .Times(0); -``` - -If some calls to the method are allowed, but the rest are not, just list all the -expected calls: - -```cpp -using ::testing::AnyNumber; -using ::testing::Gt; -... - EXPECT_CALL(foo, Bar(5)); - EXPECT_CALL(foo, Bar(Gt(10))) - .Times(AnyNumber()); -``` - -A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` statements -will be an error. - -### Understanding Uninteresting vs Unexpected Calls {#uninteresting-vs-unexpected} - -*Uninteresting* calls and *unexpected* calls are different concepts in gMock. -*Very* different. - -A call `x.Y(...)` is **uninteresting** if there's *not even a single* -`EXPECT_CALL(x, Y(...))` set. In other words, the test isn't interested in the -`x.Y()` method at all, as evident in that the test doesn't care to say anything -about it. - -A call `x.Y(...)` is **unexpected** if there are *some* `EXPECT_CALL(x, -Y(...))`s set, but none of them matches the call. Put another way, the test is -interested in the `x.Y()` method (therefore it explicitly sets some -`EXPECT_CALL` to verify how it's called); however, the verification fails as the -test doesn't expect this particular call to happen. - -**An unexpected call is always an error,** as the code under test doesn't behave -the way the test expects it to behave. - -**By default, an uninteresting call is not an error,** as it violates no -constraint specified by the test. (gMock's philosophy is that saying nothing -means there is no constraint.) However, it leads to a warning, as it *might* -indicate a problem (e.g. the test author might have forgotten to specify a -constraint). - -In gMock, `NiceMock` and `StrictMock` can be used to make a mock class "nice" or -"strict". How does this affect uninteresting calls and unexpected calls? - -A **nice mock** suppresses uninteresting call *warnings*. It is less chatty than -the default mock, but otherwise is the same. If a test fails with a default -mock, it will also fail using a nice mock instead. And vice versa. Don't expect -making a mock nice to change the test's result. - -A **strict mock** turns uninteresting call warnings into errors. So making a -mock strict may change the test's result. - -Let's look at an example: - -```cpp -TEST(...) { - NiceMock mock_registry; - EXPECT_CALL(mock_registry, GetDomainOwner("google.com")) - .WillRepeatedly(Return("Larry Page")); - - // Use mock_registry in code under test. - ... &mock_registry ... -} -``` - -The sole `EXPECT_CALL` here says that all calls to `GetDomainOwner()` must have -`"google.com"` as the argument. If `GetDomainOwner("yahoo.com")` is called, it -will be an unexpected call, and thus an error. *Having a nice mock doesn't -change the severity of an unexpected call.* - -So how do we tell gMock that `GetDomainOwner()` can be called with some other -arguments as well? The standard technique is to add a "catch all" `EXPECT_CALL`: - -```cpp - EXPECT_CALL(mock_registry, GetDomainOwner(_)) - .Times(AnyNumber()); // catches all other calls to this method. - EXPECT_CALL(mock_registry, GetDomainOwner("google.com")) - .WillRepeatedly(Return("Larry Page")); -``` - -Remember that `_` is the wildcard matcher that matches anything. With this, if -`GetDomainOwner("google.com")` is called, it will do what the second -`EXPECT_CALL` says; if it is called with a different argument, it will do what -the first `EXPECT_CALL` says. - -Note that the order of the two `EXPECT_CALL`s is important, as a newer -`EXPECT_CALL` takes precedence over an older one. - -For more on uninteresting calls, nice mocks, and strict mocks, read -["The Nice, the Strict, and the Naggy"](#NiceStrictNaggy). - -### Ignoring Uninteresting Arguments {#ParameterlessExpectations} - -If your test doesn't care about the parameters (it only cares about the number -or order of calls), you can often simply omit the parameter list: - -```cpp - // Expect foo.Bar( ... ) twice with any arguments. - EXPECT_CALL(foo, Bar).Times(2); - - // Delegate to the given method whenever the factory is invoked. - ON_CALL(foo_factory, MakeFoo) - .WillByDefault(&BuildFooForTest); -``` - -This functionality is only available when a method is not overloaded; to prevent -unexpected behavior it is a compilation error to try to set an expectation on a -method where the specific overload is ambiguous. You can work around this by -supplying a [simpler mock interface](#SimplerInterfaces) than the mocked class -provides. - -This pattern is also useful when the arguments are interesting, but match logic -is substantially complex. You can leave the argument list unspecified and use -SaveArg actions to [save the values for later verification](#SaveArgVerify). If -you do that, you can easily differentiate calling the method the wrong number of -times from calling it with the wrong arguments. - -### Expecting Ordered Calls {#OrderedCalls} - -Although an `EXPECT_CALL()` statement defined later takes precedence when gMock -tries to match a function call with an expectation, by default calls don't have -to happen in the order `EXPECT_CALL()` statements are written. For example, if -the arguments match the matchers in the second `EXPECT_CALL()`, but not those in -the first and third, then the second expectation will be used. - -If you would rather have all calls occur in the order of the expectations, put -the `EXPECT_CALL()` statements in a block where you define a variable of type -`InSequence`: - -```cpp -using ::testing::_; -using ::testing::InSequence; - - { - InSequence s; - - EXPECT_CALL(foo, DoThis(5)); - EXPECT_CALL(bar, DoThat(_)) - .Times(2); - EXPECT_CALL(foo, DoThis(6)); - } -``` - -In this example, we expect a call to `foo.DoThis(5)`, followed by two calls to -`bar.DoThat()` where the argument can be anything, which are in turn followed by -a call to `foo.DoThis(6)`. If a call occurred out-of-order, gMock will report an -error. - -### Expecting Partially Ordered Calls {#PartialOrder} - -Sometimes requiring everything to occur in a predetermined order can lead to -brittle tests. For example, we may care about `A` occurring before both `B` and -`C`, but aren't interested in the relative order of `B` and `C`. In this case, -the test should reflect our real intent, instead of being overly constraining. - -gMock allows you to impose an arbitrary DAG (directed acyclic graph) on the -calls. One way to express the DAG is to use the -[After](cheat_sheet.md#AfterClause) clause of `EXPECT_CALL`. - -Another way is via the `InSequence()` clause (not the same as the `InSequence` -class), which we borrowed from jMock 2. It's less flexible than `After()`, but -more convenient when you have long chains of sequential calls, as it doesn't -require you to come up with different names for the expectations in the chains. -Here's how it works: - -If we view `EXPECT_CALL()` statements as nodes in a graph, and add an edge from -node A to node B wherever A must occur before B, we can get a DAG. We use the -term "sequence" to mean a directed path in this DAG. Now, if we decompose the -DAG into sequences, we just need to know which sequences each `EXPECT_CALL()` -belongs to in order to be able to reconstruct the original DAG. - -So, to specify the partial order on the expectations we need to do two things: -first to define some `Sequence` objects, and then for each `EXPECT_CALL()` say -which `Sequence` objects it is part of. - -Expectations in the same sequence must occur in the order they are written. For -example, - -```cpp -using ::testing::Sequence; -... - Sequence s1, s2; - - EXPECT_CALL(foo, A()) - .InSequence(s1, s2); - EXPECT_CALL(bar, B()) - .InSequence(s1); - EXPECT_CALL(bar, C()) - .InSequence(s2); - EXPECT_CALL(foo, D()) - .InSequence(s2); -``` - -specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> C -> D`): - -```text - +---> B - | - A ---| - | - +---> C ---> D -``` - -This means that A must occur before B and C, and C must occur before D. There's -no restriction about the order other than these. - -### Controlling When an Expectation Retires - -When a mock method is called, gMock only considers expectations that are still -active. An expectation is active when created, and becomes inactive (aka -*retires*) when a call that has to occur later has occurred. For example, in - -```cpp -using ::testing::_; -using ::testing::Sequence; -... - Sequence s1, s2; - - EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1 - .Times(AnyNumber()) - .InSequence(s1, s2); - EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2 - .InSequence(s1); - EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3 - .InSequence(s2); -``` - -as soon as either #2 or #3 is matched, #1 will retire. If a warning `"File too -large."` is logged after this, it will be an error. - -Note that an expectation doesn't retire automatically when it's saturated. For -example, - -```cpp -using ::testing::_; -... - EXPECT_CALL(log, Log(WARNING, _, _)); // #1 - EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2 -``` - -says that there will be exactly one warning with the message `"File too -large."`. If the second warning contains this message too, #2 will match again -and result in an upper-bound-violated error. - -If this is not what you want, you can ask an expectation to retire as soon as it -becomes saturated: - -```cpp -using ::testing::_; -... - EXPECT_CALL(log, Log(WARNING, _, _)); // #1 - EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2 - .RetiresOnSaturation(); -``` - -Here #2 can be used only once, so if you have two warnings with the message -`"File too large."`, the first will match #2 and the second will match #1 - -there will be no error. - -## Using Actions - -### Returning References from Mock Methods - -If a mock function's return type is a reference, you need to use `ReturnRef()` -instead of `Return()` to return a result: - -```cpp -using ::testing::ReturnRef; - -class MockFoo : public Foo { - public: - MOCK_METHOD(Bar&, GetBar, (), (override)); -}; -... - MockFoo foo; - Bar bar; - EXPECT_CALL(foo, GetBar()) - .WillOnce(ReturnRef(bar)); -... -``` - -### Returning Live Values from Mock Methods - -The `Return(x)` action saves a copy of `x` when the action is created, and -always returns the same value whenever it's executed. Sometimes you may want to -instead return the *live* value of `x` (i.e. its value at the time when the -action is *executed*.). Use either `ReturnRef()` or `ReturnPointee()` for this -purpose. - -If the mock function's return type is a reference, you can do it using -`ReturnRef(x)`, as shown in the previous recipe ("Returning References from Mock -Methods"). However, gMock doesn't let you use `ReturnRef()` in a mock function -whose return type is not a reference, as doing that usually indicates a user -error. So, what shall you do? - -Though you may be tempted, DO NOT use `std::ref()`: - -```cpp -using testing::Return; - -class MockFoo : public Foo { - public: - MOCK_METHOD(int, GetValue, (), (override)); -}; -... - int x = 0; - MockFoo foo; - EXPECT_CALL(foo, GetValue()) - .WillRepeatedly(Return(std::ref(x))); // Wrong! - x = 42; - EXPECT_EQ(42, foo.GetValue()); -``` - -Unfortunately, it doesn't work here. The above code will fail with error: - -```text -Value of: foo.GetValue() - Actual: 0 -Expected: 42 -``` - -The reason is that `Return(*value*)` converts `value` to the actual return type -of the mock function at the time when the action is *created*, not when it is -*executed*. (This behavior was chosen for the action to be safe when `value` is -a proxy object that references some temporary objects.) As a result, -`std::ref(x)` is converted to an `int` value (instead of a `const int&`) when -the expectation is set, and `Return(std::ref(x))` will always return 0. - -`ReturnPointee(pointer)` was provided to solve this problem specifically. It -returns the value pointed to by `pointer` at the time the action is *executed*: - -```cpp -using testing::ReturnPointee; -... - int x = 0; - MockFoo foo; - EXPECT_CALL(foo, GetValue()) - .WillRepeatedly(ReturnPointee(&x)); // Note the & here. - x = 42; - EXPECT_EQ(42, foo.GetValue()); // This will succeed now. -``` - -### Combining Actions - -Want to do more than one thing when a function is called? That's fine. `DoAll()` -allow you to do sequence of actions every time. Only the return value of the -last action in the sequence will be used. - -```cpp -using ::testing::_; -using ::testing::DoAll; - -class MockFoo : public Foo { - public: - MOCK_METHOD(bool, Bar, (int n), (override)); -}; -... - EXPECT_CALL(foo, Bar(_)) - .WillOnce(DoAll(action_1, - action_2, - ... - action_n)); -``` - -### Verifying Complex Arguments {#SaveArgVerify} - -If you want to verify that a method is called with a particular argument but the -match criteria is complex, it can be difficult to distinguish between -cardinality failures (calling the method the wrong number of times) and argument -match failures. Similarly, if you are matching multiple parameters, it may not -be easy to distinguishing which argument failed to match. For example: - -```cpp - // Not ideal: this could fail because of a problem with arg1 or arg2, or maybe - // just the method wasn't called. - EXPECT_CALL(foo, SendValues(_, ElementsAre(1, 4, 4, 7), EqualsProto( ... ))); -``` - -You can instead save the arguments and test them individually: - -```cpp - EXPECT_CALL(foo, SendValues) - .WillOnce(DoAll(SaveArg<1>(&actual_array), SaveArg<2>(&actual_proto))); - ... run the test - EXPECT_THAT(actual_array, ElementsAre(1, 4, 4, 7)); - EXPECT_THAT(actual_proto, EqualsProto( ... )); -``` - -### Mocking Side Effects {#MockingSideEffects} - -Sometimes a method exhibits its effect not via returning a value but via side -effects. For example, it may change some global state or modify an output -argument. To mock side effects, in general you can define your own action by -implementing `::testing::ActionInterface`. - -If all you need to do is to change an output argument, the built-in -`SetArgPointee()` action is convenient: - -```cpp -using ::testing::_; -using ::testing::SetArgPointee; - -class MockMutator : public Mutator { - public: - MOCK_METHOD(void, Mutate, (bool mutate, int* value), (override)); - ... -} -... - MockMutator mutator; - EXPECT_CALL(mutator, Mutate(true, _)) - .WillOnce(SetArgPointee<1>(5)); -``` - -In this example, when `mutator.Mutate()` is called, we will assign 5 to the -`int` variable pointed to by argument #1 (0-based). - -`SetArgPointee()` conveniently makes an internal copy of the value you pass to -it, removing the need to keep the value in scope and alive. The implication -however is that the value must have a copy constructor and assignment operator. - -If the mock method also needs to return a value as well, you can chain -`SetArgPointee()` with `Return()` using `DoAll()`, remembering to put the -`Return()` statement last: - -```cpp -using ::testing::_; -using ::testing::Return; -using ::testing::SetArgPointee; - -class MockMutator : public Mutator { - public: - ... - MOCK_METHOD(bool, MutateInt, (int* value), (override)); -} -... - MockMutator mutator; - EXPECT_CALL(mutator, MutateInt(_)) - .WillOnce(DoAll(SetArgPointee<0>(5), - Return(true))); -``` - -Note, however, that if you use the `ReturnOKWith()` method, it will override the -values provided by `SetArgPointee()` in the response parameters of your function -call. - -If the output argument is an array, use the `SetArrayArgument(first, last)` -action instead. It copies the elements in source range `[first, last)` to the -array pointed to by the `N`-th (0-based) argument: - -```cpp -using ::testing::NotNull; -using ::testing::SetArrayArgument; - -class MockArrayMutator : public ArrayMutator { - public: - MOCK_METHOD(void, Mutate, (int* values, int num_values), (override)); - ... -} -... - MockArrayMutator mutator; - int values[5] = {1, 2, 3, 4, 5}; - EXPECT_CALL(mutator, Mutate(NotNull(), 5)) - .WillOnce(SetArrayArgument<0>(values, values + 5)); -``` - -This also works when the argument is an output iterator: - -```cpp -using ::testing::_; -using ::testing::SetArrayArgument; - -class MockRolodex : public Rolodex { - public: - MOCK_METHOD(void, GetNames, (std::back_insert_iterator>), - (override)); - ... -} -... - MockRolodex rolodex; - vector names; - names.push_back("George"); - names.push_back("John"); - names.push_back("Thomas"); - EXPECT_CALL(rolodex, GetNames(_)) - .WillOnce(SetArrayArgument<0>(names.begin(), names.end())); -``` - -### Changing a Mock Object's Behavior Based on the State - -If you expect a call to change the behavior of a mock object, you can use -`::testing::InSequence` to specify different behaviors before and after the -call: - -```cpp -using ::testing::InSequence; -using ::testing::Return; - -... - { - InSequence seq; - EXPECT_CALL(my_mock, IsDirty()) - .WillRepeatedly(Return(true)); - EXPECT_CALL(my_mock, Flush()); - EXPECT_CALL(my_mock, IsDirty()) - .WillRepeatedly(Return(false)); - } - my_mock.FlushIfDirty(); -``` - -This makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called -and return `false` afterwards. - -If the behavior change is more complex, you can store the effects in a variable -and make a mock method get its return value from that variable: - -```cpp -using ::testing::_; -using ::testing::SaveArg; -using ::testing::Return; - -ACTION_P(ReturnPointee, p) { return *p; } -... - int previous_value = 0; - EXPECT_CALL(my_mock, GetPrevValue) - .WillRepeatedly(ReturnPointee(&previous_value)); - EXPECT_CALL(my_mock, UpdateValue) - .WillRepeatedly(SaveArg<0>(&previous_value)); - my_mock.DoSomethingToUpdateValue(); -``` - -Here `my_mock.GetPrevValue()` will always return the argument of the last -`UpdateValue()` call. - -### Setting the Default Value for a Return Type {#DefaultValue} - -If a mock method's return type is a built-in C++ type or pointer, by default it -will return 0 when invoked. Also, in C++ 11 and above, a mock method whose -return type has a default constructor will return a default-constructed value by -default. You only need to specify an action if this default value doesn't work -for you. - -Sometimes, you may want to change this default value, or you may want to specify -a default value for types gMock doesn't know about. You can do this using the -`::testing::DefaultValue` class template: - -```cpp -using ::testing::DefaultValue; - -class MockFoo : public Foo { - public: - MOCK_METHOD(Bar, CalculateBar, (), (override)); -}; - - -... - Bar default_bar; - // Sets the default return value for type Bar. - DefaultValue::Set(default_bar); - - MockFoo foo; - - // We don't need to specify an action here, as the default - // return value works for us. - EXPECT_CALL(foo, CalculateBar()); - - foo.CalculateBar(); // This should return default_bar. - - // Unsets the default return value. - DefaultValue::Clear(); -``` - -Please note that changing the default value for a type can make your tests hard -to understand. We recommend you to use this feature judiciously. For example, -you may want to make sure the `Set()` and `Clear()` calls are right next to the -code that uses your mock. - -### Setting the Default Actions for a Mock Method - -You've learned how to change the default value of a given type. However, this -may be too coarse for your purpose: perhaps you have two mock methods with the -same return type and you want them to have different behaviors. The `ON_CALL()` -macro allows you to customize your mock's behavior at the method level: - -```cpp -using ::testing::_; -using ::testing::AnyNumber; -using ::testing::Gt; -using ::testing::Return; -... - ON_CALL(foo, Sign(_)) - .WillByDefault(Return(-1)); - ON_CALL(foo, Sign(0)) - .WillByDefault(Return(0)); - ON_CALL(foo, Sign(Gt(0))) - .WillByDefault(Return(1)); - - EXPECT_CALL(foo, Sign(_)) - .Times(AnyNumber()); - - foo.Sign(5); // This should return 1. - foo.Sign(-9); // This should return -1. - foo.Sign(0); // This should return 0. -``` - -As you may have guessed, when there are more than one `ON_CALL()` statements, -the newer ones in the order take precedence over the older ones. In other words, -the **last** one that matches the function arguments will be used. This matching -order allows you to set up the common behavior in a mock object's constructor or -the test fixture's set-up phase and specialize the mock's behavior later. - -Note that both `ON_CALL` and `EXPECT_CALL` have the same "later statements take -precedence" rule, but they don't interact. That is, `EXPECT_CALL`s have their -own precedence order distinct from the `ON_CALL` precedence order. - -### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions} - -If the built-in actions don't suit you, you can use an existing callable -(function, `std::function`, method, functor, lambda) as an action. - - - -```cpp -using ::testing::_; using ::testing::Invoke; - -class MockFoo : public Foo { - public: - MOCK_METHOD(int, Sum, (int x, int y), (override)); - MOCK_METHOD(bool, ComplexJob, (int x), (override)); -}; - -int CalculateSum(int x, int y) { return x + y; } -int Sum3(int x, int y, int z) { return x + y + z; } - -class Helper { - public: - bool ComplexJob(int x); -}; - -... - MockFoo foo; - Helper helper; - EXPECT_CALL(foo, Sum(_, _)) - .WillOnce(&CalculateSum) - .WillRepeatedly(Invoke(NewPermanentCallback(Sum3, 1))); - EXPECT_CALL(foo, ComplexJob(_)) - .WillOnce(Invoke(&helper, &Helper::ComplexJob)) - .WillOnce([] { return true; }) - .WillRepeatedly([](int x) { return x > 0; }); - - foo.Sum(5, 6); // Invokes CalculateSum(5, 6). - foo.Sum(2, 3); // Invokes Sum3(1, 2, 3). - foo.ComplexJob(10); // Invokes helper.ComplexJob(10). - foo.ComplexJob(-1); // Invokes the inline lambda. -``` - -The only requirement is that the type of the function, etc must be *compatible* -with the signature of the mock function, meaning that the latter's arguments (if -it takes any) can be implicitly converted to the corresponding arguments of the -former, and the former's return type can be implicitly converted to that of the -latter. So, you can invoke something whose type is *not* exactly the same as the -mock function, as long as it's safe to do so - nice, huh? - -**`Note:`{.escaped}** - -* The action takes ownership of the callback and will delete it when the - action itself is destructed. -* If the type of a callback is derived from a base callback type `C`, you need - to implicitly cast it to `C` to resolve the overloading, e.g. - - ```cpp - using ::testing::Invoke; - ... - ResultCallback* is_ok = ...; - ... Invoke(is_ok) ...; // This works. - - BlockingClosure* done = new BlockingClosure; - ... Invoke(implicit_cast(done)) ...; // The cast is necessary. - ``` - -### Using Functions with Extra Info as Actions - -The function or functor you call using `Invoke()` must have the same number of -arguments as the mock function you use it for. Sometimes you may have a function -that takes more arguments, and you are willing to pass in the extra arguments -yourself to fill the gap. You can do this in gMock using callbacks with -pre-bound arguments. Here's an example: - -```cpp -using ::testing::Invoke; - -class MockFoo : public Foo { - public: - MOCK_METHOD(char, DoThis, (int n), (override)); -}; - -char SignOfSum(int x, int y) { - const int sum = x + y; - return (sum > 0) ? '+' : (sum < 0) ? '-' : '0'; -} - -TEST_F(FooTest, Test) { - MockFoo foo; - - EXPECT_CALL(foo, DoThis(2)) - .WillOnce(Invoke(NewPermanentCallback(SignOfSum, 5))); - EXPECT_EQ('+', foo.DoThis(2)); // Invokes SignOfSum(5, 2). -} -``` - -### Invoking a Function/Method/Functor/Lambda/Callback Without Arguments - -`Invoke()` passes the mock function's arguments to the function, etc being -invoked such that the callee has the full context of the call to work with. If -the invoked function is not interested in some or all of the arguments, it can -simply ignore them. - -Yet, a common pattern is that a test author wants to invoke a function without -the arguments of the mock function. She could do that using a wrapper function -that throws away the arguments before invoking an underlining nullary function. -Needless to say, this can be tedious and obscures the intent of the test. - -There are two solutions to this problem. First, you can pass any callable of -zero args as an action. Alternatively, use `InvokeWithoutArgs()`, which is like -`Invoke()` except that it doesn't pass the mock function's arguments to the -callee. Here's an example of each: - -```cpp -using ::testing::_; -using ::testing::InvokeWithoutArgs; - -class MockFoo : public Foo { - public: - MOCK_METHOD(bool, ComplexJob, (int n), (override)); -}; - -bool Job1() { ... } -bool Job2(int n, char c) { ... } - -... - MockFoo foo; - EXPECT_CALL(foo, ComplexJob(_)) - .WillOnce([] { Job1(); }); - .WillOnce(InvokeWithoutArgs(NewPermanentCallback(Job2, 5, 'a'))); - - foo.ComplexJob(10); // Invokes Job1(). - foo.ComplexJob(20); // Invokes Job2(5, 'a'). -``` - -**`Note:`{.escaped}** - -* The action takes ownership of the callback and will delete it when the - action itself is destructed. -* If the type of a callback is derived from a base callback type `C`, you need - to implicitly cast it to `C` to resolve the overloading, e.g. - - ```cpp - using ::testing::InvokeWithoutArgs; - ... - ResultCallback* is_ok = ...; - ... InvokeWithoutArgs(is_ok) ...; // This works. - - BlockingClosure* done = ...; - ... InvokeWithoutArgs(implicit_cast(done)) ...; - // The cast is necessary. - ``` - -### Invoking an Argument of the Mock Function - -Sometimes a mock function will receive a function pointer, a functor (in other -words, a "callable") as an argument, e.g. - -```cpp -class MockFoo : public Foo { - public: - MOCK_METHOD(bool, DoThis, (int n, (ResultCallback1* callback)), - (override)); -}; -``` - -and you may want to invoke this callable argument: - -```cpp -using ::testing::_; -... - MockFoo foo; - EXPECT_CALL(foo, DoThis(_, _)) - .WillOnce(...); - // Will execute callback->Run(5), where callback is the - // second argument DoThis() receives. -``` - -NOTE: The section below is legacy documentation from before C++ had lambdas: - -Arghh, you need to refer to a mock function argument but C++ has no lambda -(yet), so you have to define your own action. :-( Or do you really? - -Well, gMock has an action to solve *exactly* this problem: - -```cpp -InvokeArgument(arg_1, arg_2, ..., arg_m) -``` - -will invoke the `N`-th (0-based) argument the mock function receives, with -`arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is a function -pointer, a functor, or a callback. gMock handles them all. - -With that, you could write: - -```cpp -using ::testing::_; -using ::testing::InvokeArgument; -... - EXPECT_CALL(foo, DoThis(_, _)) - .WillOnce(InvokeArgument<1>(5)); - // Will execute callback->Run(5), where callback is the - // second argument DoThis() receives. -``` - -What if the callable takes an argument by reference? No problem - just wrap it -inside `std::ref()`: - -```cpp - ... - MOCK_METHOD(bool, Bar, - ((ResultCallback2* callback)), - (override)); - ... - using ::testing::_; - using ::testing::InvokeArgument; - ... - MockFoo foo; - Helper helper; - ... - EXPECT_CALL(foo, Bar(_)) - .WillOnce(InvokeArgument<0>(5, std::ref(helper))); - // std::ref(helper) guarantees that a reference to helper, not a copy of - // it, will be passed to the callback. -``` - -What if the callable takes an argument by reference and we do **not** wrap the -argument in `std::ref()`? Then `InvokeArgument()` will *make a copy* of the -argument, and pass a *reference to the copy*, instead of a reference to the -original value, to the callable. This is especially handy when the argument is a -temporary value: - -```cpp - ... - MOCK_METHOD(bool, DoThat, (bool (*f)(const double& x, const string& s)), - (override)); - ... - using ::testing::_; - using ::testing::InvokeArgument; - ... - MockFoo foo; - ... - EXPECT_CALL(foo, DoThat(_)) - .WillOnce(InvokeArgument<0>(5.0, string("Hi"))); - // Will execute (*f)(5.0, string("Hi")), where f is the function pointer - // DoThat() receives. Note that the values 5.0 and string("Hi") are - // temporary and dead once the EXPECT_CALL() statement finishes. Yet - // it's fine to perform this action later, since a copy of the values - // are kept inside the InvokeArgument action. -``` - -### Ignoring an Action's Result - -Sometimes you have an action that returns *something*, but you need an action -that returns `void` (perhaps you want to use it in a mock function that returns -`void`, or perhaps it needs to be used in `DoAll()` and it's not the last in the -list). `IgnoreResult()` lets you do that. For example: - -```cpp -using ::testing::_; -using ::testing::DoAll; -using ::testing::IgnoreResult; -using ::testing::Return; - -int Process(const MyData& data); -string DoSomething(); - -class MockFoo : public Foo { - public: - MOCK_METHOD(void, Abc, (const MyData& data), (override)); - MOCK_METHOD(bool, Xyz, (), (override)); -}; - - ... - MockFoo foo; - EXPECT_CALL(foo, Abc(_)) - // .WillOnce(Invoke(Process)); - // The above line won't compile as Process() returns int but Abc() needs - // to return void. - .WillOnce(IgnoreResult(Process)); - EXPECT_CALL(foo, Xyz()) - .WillOnce(DoAll(IgnoreResult(DoSomething), - // Ignores the string DoSomething() returns. - Return(true))); -``` - -Note that you **cannot** use `IgnoreResult()` on an action that already returns -`void`. Doing so will lead to ugly compiler errors. - -### Selecting an Action's Arguments {#SelectingArgs} - -Say you have a mock function `Foo()` that takes seven arguments, and you have a -custom action that you want to invoke when `Foo()` is called. Trouble is, the -custom action only wants three arguments: - -```cpp -using ::testing::_; -using ::testing::Invoke; -... - MOCK_METHOD(bool, Foo, - (bool visible, const string& name, int x, int y, - (const map>), double& weight, double min_weight, - double max_wight)); -... -bool IsVisibleInQuadrant1(bool visible, int x, int y) { - return visible && x >= 0 && y >= 0; -} -... - EXPECT_CALL(mock, Foo) - .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-( -``` - -To please the compiler God, you need to define an "adaptor" that has the same -signature as `Foo()` and calls the custom action with the right arguments: - -```cpp -using ::testing::_; -using ::testing::Invoke; -... -bool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y, - const map, double>& weight, - double min_weight, double max_wight) { - return IsVisibleInQuadrant1(visible, x, y); -} -... - EXPECT_CALL(mock, Foo) - .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works. -``` - -But isn't this awkward? - -gMock provides a generic *action adaptor*, so you can spend your time minding -more important business than writing your own adaptors. Here's the syntax: - -```cpp -WithArgs(action) -``` - -creates an action that passes the arguments of the mock function at the given -indices (0-based) to the inner `action` and performs it. Using `WithArgs`, our -original example can be written as: - -```cpp -using ::testing::_; -using ::testing::Invoke; -using ::testing::WithArgs; -... - EXPECT_CALL(mock, Foo) - .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1))); // No need to define your own adaptor. -``` - -For better readability, gMock also gives you: - -* `WithoutArgs(action)` when the inner `action` takes *no* argument, and -* `WithArg(action)` (no `s` after `Arg`) when the inner `action` takes - *one* argument. - -As you may have realized, `InvokeWithoutArgs(...)` is just syntactic sugar for -`WithoutArgs(Invoke(...))`. - -Here are more tips: - -* The inner action used in `WithArgs` and friends does not have to be - `Invoke()` -- it can be anything. -* You can repeat an argument in the argument list if necessary, e.g. - `WithArgs<2, 3, 3, 5>(...)`. -* You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`. -* The types of the selected arguments do *not* have to match the signature of - the inner action exactly. It works as long as they can be implicitly - converted to the corresponding arguments of the inner action. For example, - if the 4-th argument of the mock function is an `int` and `my_action` takes - a `double`, `WithArg<4>(my_action)` will work. - -### Ignoring Arguments in Action Functions - -The [selecting-an-action's-arguments](#SelectingArgs) recipe showed us one way -to make a mock function and an action with incompatible argument lists fit -together. The downside is that wrapping the action in `WithArgs<...>()` can get -tedious for people writing the tests. - -If you are defining a function (or method, functor, lambda, callback) to be used -with `Invoke*()`, and you are not interested in some of its arguments, an -alternative to `WithArgs` is to declare the uninteresting arguments as `Unused`. -This makes the definition less cluttered and less fragile in case the types of -the uninteresting arguments change. It could also increase the chance the action -function can be reused. For example, given - -```cpp - public: - MOCK_METHOD(double, Foo, double(const string& label, double x, double y), - (override)); - MOCK_METHOD(double, Bar, (int index, double x, double y), (override)); -``` - -instead of - -```cpp -using ::testing::_; -using ::testing::Invoke; - -double DistanceToOriginWithLabel(const string& label, double x, double y) { - return sqrt(x*x + y*y); -} -double DistanceToOriginWithIndex(int index, double x, double y) { - return sqrt(x*x + y*y); -} -... - EXPECT_CALL(mock, Foo("abc", _, _)) - .WillOnce(Invoke(DistanceToOriginWithLabel)); - EXPECT_CALL(mock, Bar(5, _, _)) - .WillOnce(Invoke(DistanceToOriginWithIndex)); -``` - -you could write - -```cpp -using ::testing::_; -using ::testing::Invoke; -using ::testing::Unused; - -double DistanceToOrigin(Unused, double x, double y) { - return sqrt(x*x + y*y); -} -... - EXPECT_CALL(mock, Foo("abc", _, _)) - .WillOnce(Invoke(DistanceToOrigin)); - EXPECT_CALL(mock, Bar(5, _, _)) - .WillOnce(Invoke(DistanceToOrigin)); -``` - -### Sharing Actions - -Just like matchers, a gMock action object consists of a pointer to a ref-counted -implementation object. Therefore copying actions is also allowed and very -efficient. When the last action that references the implementation object dies, -the implementation object will be deleted. - -If you have some complex action that you want to use again and again, you may -not have to build it from scratch everytime. If the action doesn't have an -internal state (i.e. if it always does the same thing no matter how many times -it has been called), you can assign it to an action variable and use that -variable repeatedly. For example: - -```cpp -using ::testing::Action; -using ::testing::DoAll; -using ::testing::Return; -using ::testing::SetArgPointee; -... - Action set_flag = DoAll(SetArgPointee<0>(5), - Return(true)); - ... use set_flag in .WillOnce() and .WillRepeatedly() ... -``` - -However, if the action has its own state, you may be surprised if you share the -action object. Suppose you have an action factory `IncrementCounter(init)` which -creates an action that increments and returns a counter whose initial value is -`init`, using two actions created from the same expression and using a shared -action will exhibit different behaviors. Example: - -```cpp - EXPECT_CALL(foo, DoThis()) - .WillRepeatedly(IncrementCounter(0)); - EXPECT_CALL(foo, DoThat()) - .WillRepeatedly(IncrementCounter(0)); - foo.DoThis(); // Returns 1. - foo.DoThis(); // Returns 2. - foo.DoThat(); // Returns 1 - Blah() uses a different - // counter than Bar()'s. -``` - -versus - -```cpp -using ::testing::Action; -... - Action increment = IncrementCounter(0); - EXPECT_CALL(foo, DoThis()) - .WillRepeatedly(increment); - EXPECT_CALL(foo, DoThat()) - .WillRepeatedly(increment); - foo.DoThis(); // Returns 1. - foo.DoThis(); // Returns 2. - foo.DoThat(); // Returns 3 - the counter is shared. -``` - -### Testing Asynchronous Behavior - -One oft-encountered problem with gMock is that it can be hard to test -asynchronous behavior. Suppose you had a `EventQueue` class that you wanted to -test, and you created a separate `EventDispatcher` interface so that you could -easily mock it out. However, the implementation of the class fired all the -events on a background thread, which made test timings difficult. You could just -insert `sleep()` statements and hope for the best, but that makes your test -behavior nondeterministic. A better way is to use gMock actions and -`Notification` objects to force your asynchronous test to behave synchronously. - -```cpp -using ::testing::DoAll; -using ::testing::InvokeWithoutArgs; -using ::testing::Return; - -class MockEventDispatcher : public EventDispatcher { - MOCK_METHOD(bool, DispatchEvent, (int32), (override)); -}; - -ACTION_P(Notify, notification) { - notification->Notify(); -} - -TEST(EventQueueTest, EnqueueEventTest) { - MockEventDispatcher mock_event_dispatcher; - EventQueue event_queue(&mock_event_dispatcher); - - const int32 kEventId = 321; - absl::Notification done; - EXPECT_CALL(mock_event_dispatcher, DispatchEvent(kEventId)) - .WillOnce(Notify(&done)); - - event_queue.EnqueueEvent(kEventId); - done.WaitForNotification(); -} -``` - -In the example above, we set our normal gMock expectations, but then add an -additional action to notify the `Notification` object. Now we can just call -`Notification::WaitForNotification()` in the main thread to wait for the -asynchronous call to finish. After that, our test suite is complete and we can -safely exit. - -Note: this example has a downside: namely, if the expectation is not satisfied, -our test will run forever. It will eventually time-out and fail, but it will -take longer and be slightly harder to debug. To alleviate this problem, you can -use `WaitForNotificationWithTimeout(ms)` instead of `WaitForNotification()`. - -## Misc Recipes on Using gMock - -### Mocking Methods That Use Move-Only Types - -C++11 introduced *move-only types*. A move-only-typed value can be moved from -one object to another, but cannot be copied. `std::unique_ptr` is probably -the most commonly used move-only type. - -Mocking a method that takes and/or returns move-only types presents some -challenges, but nothing insurmountable. This recipe shows you how you can do it. -Note that the support for move-only method arguments was only introduced to -gMock in April 2017; in older code, you may find more complex -[workarounds](#LegacyMoveOnly) for lack of this feature. - -Let’s say we are working on a fictional project that lets one post and share -snippets called “buzzes”. Your code uses these types: - -```cpp -enum class AccessLevel { kInternal, kPublic }; - -class Buzz { - public: - explicit Buzz(AccessLevel access) { ... } - ... -}; - -class Buzzer { - public: - virtual ~Buzzer() {} - virtual std::unique_ptr MakeBuzz(StringPiece text) = 0; - virtual bool ShareBuzz(std::unique_ptr buzz, int64_t timestamp) = 0; - ... -}; -``` - -A `Buzz` object represents a snippet being posted. A class that implements the -`Buzzer` interface is capable of creating and sharing `Buzz`es. Methods in -`Buzzer` may return a `unique_ptr` or take a `unique_ptr`. Now we -need to mock `Buzzer` in our tests. - -To mock a method that accepts or returns move-only types, you just use the -familiar `MOCK_METHOD` syntax as usual: - -```cpp -class MockBuzzer : public Buzzer { - public: - MOCK_METHOD(std::unique_ptr, MakeBuzz, (StringPiece text), (override)); - MOCK_METHOD(bool, ShareBuzz, (std::unique_ptr buzz, int64_t timestamp), - (override)); -}; -``` - -Now that we have the mock class defined, we can use it in tests. In the -following code examples, we assume that we have defined a `MockBuzzer` object -named `mock_buzzer_`: - -```cpp - MockBuzzer mock_buzzer_; -``` - -First let’s see how we can set expectations on the `MakeBuzz()` method, which -returns a `unique_ptr`. - -As usual, if you set an expectation without an action (i.e. the `.WillOnce()` or -`.WillRepeatedly()` clause), when that expectation fires, the default action for -that method will be taken. Since `unique_ptr<>` has a default constructor that -returns a null `unique_ptr`, that’s what you’ll get if you don’t specify an -action: - -```cpp - // Use the default action. - EXPECT_CALL(mock_buzzer_, MakeBuzz("hello")); - - // Triggers the previous EXPECT_CALL. - EXPECT_EQ(nullptr, mock_buzzer_.MakeBuzz("hello")); -``` - -If you are not happy with the default action, you can tweak it as usual; see -[Setting Default Actions](#OnCall). - -If you just need to return a pre-defined move-only value, you can use the -`Return(ByMove(...))` action: - -```cpp - // When this fires, the unique_ptr<> specified by ByMove(...) will - // be returned. - EXPECT_CALL(mock_buzzer_, MakeBuzz("world")) - .WillOnce(Return(ByMove(MakeUnique(AccessLevel::kInternal)))); - - EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("world")); -``` - -Note that `ByMove()` is essential here - if you drop it, the code won’t compile. - -Quiz time! What do you think will happen if a `Return(ByMove(...))` action is -performed more than once (e.g. you write `... -.WillRepeatedly(Return(ByMove(...)));`)? Come think of it, after the first time -the action runs, the source value will be consumed (since it’s a move-only -value), so the next time around, there’s no value to move from -- you’ll get a -run-time error that `Return(ByMove(...))` can only be run once. - -If you need your mock method to do more than just moving a pre-defined value, -remember that you can always use a lambda or a callable object, which can do -pretty much anything you want: - -```cpp - EXPECT_CALL(mock_buzzer_, MakeBuzz("x")) - .WillRepeatedly([](StringPiece text) { - return MakeUnique(AccessLevel::kInternal); - }); - - EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x")); - EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x")); -``` - -Every time this `EXPECT_CALL` fires, a new `unique_ptr` will be created -and returned. You cannot do this with `Return(ByMove(...))`. - -That covers returning move-only values; but how do we work with methods -accepting move-only arguments? The answer is that they work normally, although -some actions will not compile when any of method's arguments are move-only. You -can always use `Return`, or a [lambda or functor](#FunctionsAsActions): - -```cpp - using ::testing::Unused; - - EXPECT_CALL(mock_buzzer_, ShareBuzz(NotNull(), _)).WillOnce(Return(true)); - EXPECT_TRUE(mock_buzzer_.ShareBuzz(MakeUnique(AccessLevel::kInternal)), - 0); - - EXPECT_CALL(mock_buzzer_, ShareBuzz(_, _)).WillOnce( - [](std::unique_ptr buzz, Unused) { return buzz != nullptr; }); - EXPECT_FALSE(mock_buzzer_.ShareBuzz(nullptr, 0)); -``` - -Many built-in actions (`WithArgs`, `WithoutArgs`,`DeleteArg`, `SaveArg`, ...) -could in principle support move-only arguments, but the support for this is not -implemented yet. If this is blocking you, please file a bug. - -A few actions (e.g. `DoAll`) copy their arguments internally, so they can never -work with non-copyable objects; you'll have to use functors instead. - -#### Legacy workarounds for move-only types {#LegacyMoveOnly} - -Support for move-only function arguments was only introduced to gMock in April -2017. In older code, you may encounter the following workaround for the lack of -this feature (it is no longer necessary - we're including it just for -reference): - -```cpp -class MockBuzzer : public Buzzer { - public: - MOCK_METHOD(bool, DoShareBuzz, (Buzz* buzz, Time timestamp)); - bool ShareBuzz(std::unique_ptr buzz, Time timestamp) override { - return DoShareBuzz(buzz.get(), timestamp); - } -}; -``` - -The trick is to delegate the `ShareBuzz()` method to a mock method (let’s call -it `DoShareBuzz()`) that does not take move-only parameters. Then, instead of -setting expectations on `ShareBuzz()`, you set them on the `DoShareBuzz()` mock -method: - -```cpp - MockBuzzer mock_buzzer_; - EXPECT_CALL(mock_buzzer_, DoShareBuzz(NotNull(), _)); - - // When one calls ShareBuzz() on the MockBuzzer like this, the call is - // forwarded to DoShareBuzz(), which is mocked. Therefore this statement - // will trigger the above EXPECT_CALL. - mock_buzzer_.ShareBuzz(MakeUnique(AccessLevel::kInternal), 0); -``` - -### Making the Compilation Faster - -Believe it or not, the *vast majority* of the time spent on compiling a mock -class is in generating its constructor and destructor, as they perform -non-trivial tasks (e.g. verification of the expectations). What's more, mock -methods with different signatures have different types and thus their -constructors/destructors need to be generated by the compiler separately. As a -result, if you mock many different types of methods, compiling your mock class -can get really slow. - -If you are experiencing slow compilation, you can move the definition of your -mock class' constructor and destructor out of the class body and into a `.cc` -file. This way, even if you `#include` your mock class in N files, the compiler -only needs to generate its constructor and destructor once, resulting in a much -faster compilation. - -Let's illustrate the idea using an example. Here's the definition of a mock -class before applying this recipe: - -```cpp -// File mock_foo.h. -... -class MockFoo : public Foo { - public: - // Since we don't declare the constructor or the destructor, - // the compiler will generate them in every translation unit - // where this mock class is used. - - MOCK_METHOD(int, DoThis, (), (override)); - MOCK_METHOD(bool, DoThat, (const char* str), (override)); - ... more mock methods ... -}; -``` - -After the change, it would look like: - -```cpp -// File mock_foo.h. -... -class MockFoo : public Foo { - public: - // The constructor and destructor are declared, but not defined, here. - MockFoo(); - virtual ~MockFoo(); - - MOCK_METHOD(int, DoThis, (), (override)); - MOCK_METHOD(bool, DoThat, (const char* str), (override)); - ... more mock methods ... -}; -``` - -and - -```cpp -// File mock_foo.cc. -#include "path/to/mock_foo.h" - -// The definitions may appear trivial, but the functions actually do a -// lot of things through the constructors/destructors of the member -// variables used to implement the mock methods. -MockFoo::MockFoo() {} -MockFoo::~MockFoo() {} -``` - -### Forcing a Verification - -When it's being destroyed, your friendly mock object will automatically verify -that all expectations on it have been satisfied, and will generate googletest -failures if not. This is convenient as it leaves you with one less thing to -worry about. That is, unless you are not sure if your mock object will be -destroyed. - -How could it be that your mock object won't eventually be destroyed? Well, it -might be created on the heap and owned by the code you are testing. Suppose -there's a bug in that code and it doesn't delete the mock object properly - you -could end up with a passing test when there's actually a bug. - -Using a heap checker is a good idea and can alleviate the concern, but its -implementation is not 100% reliable. So, sometimes you do want to *force* gMock -to verify a mock object before it is (hopefully) destructed. You can do this -with `Mock::VerifyAndClearExpectations(&mock_object)`: - -```cpp -TEST(MyServerTest, ProcessesRequest) { - using ::testing::Mock; - - MockFoo* const foo = new MockFoo; - EXPECT_CALL(*foo, ...)...; - // ... other expectations ... - - // server now owns foo. - MyServer server(foo); - server.ProcessRequest(...); - - // In case that server's destructor will forget to delete foo, - // this will verify the expectations anyway. - Mock::VerifyAndClearExpectations(foo); -} // server is destroyed when it goes out of scope here. -``` - -**Tip:** The `Mock::VerifyAndClearExpectations()` function returns a `bool` to -indicate whether the verification was successful (`true` for yes), so you can -wrap that function call inside a `ASSERT_TRUE()` if there is no point going -further when the verification has failed. - -### Using Check Points {#UsingCheckPoints} - -Sometimes you may want to "reset" a mock object at various check points in your -test: at each check point, you verify that all existing expectations on the mock -object have been satisfied, and then you set some new expectations on it as if -it's newly created. This allows you to work with a mock object in "phases" whose -sizes are each manageable. - -One such scenario is that in your test's `SetUp()` function, you may want to put -the object you are testing into a certain state, with the help from a mock -object. Once in the desired state, you want to clear all expectations on the -mock, such that in the `TEST_F` body you can set fresh expectations on it. - -As you may have figured out, the `Mock::VerifyAndClearExpectations()` function -we saw in the previous recipe can help you here. Or, if you are using -`ON_CALL()` to set default actions on the mock object and want to clear the -default actions as well, use `Mock::VerifyAndClear(&mock_object)` instead. This -function does what `Mock::VerifyAndClearExpectations(&mock_object)` does and -returns the same `bool`, **plus** it clears the `ON_CALL()` statements on -`mock_object` too. - -Another trick you can use to achieve the same effect is to put the expectations -in sequences and insert calls to a dummy "check-point" function at specific -places. Then you can verify that the mock function calls do happen at the right -time. For example, if you are exercising code: - -```cpp - Foo(1); - Foo(2); - Foo(3); -``` - -and want to verify that `Foo(1)` and `Foo(3)` both invoke `mock.Bar("a")`, but -`Foo(2)` doesn't invoke anything. You can write: - -```cpp -using ::testing::MockFunction; - -TEST(FooTest, InvokesBarCorrectly) { - MyMock mock; - // Class MockFunction has exactly one mock method. It is named - // Call() and has type F. - MockFunction check; - { - InSequence s; - - EXPECT_CALL(mock, Bar("a")); - EXPECT_CALL(check, Call("1")); - EXPECT_CALL(check, Call("2")); - EXPECT_CALL(mock, Bar("a")); - } - Foo(1); - check.Call("1"); - Foo(2); - check.Call("2"); - Foo(3); -} -``` - -The expectation spec says that the first `Bar("a")` must happen before check -point "1", the second `Bar("a")` must happen after check point "2", and nothing -should happen between the two check points. The explicit check points make it -easy to tell which `Bar("a")` is called by which call to `Foo()`. - -### Mocking Destructors - -Sometimes you want to make sure a mock object is destructed at the right time, -e.g. after `bar->A()` is called but before `bar->B()` is called. We already know -that you can specify constraints on the [order](#OrderedCalls) of mock function -calls, so all we need to do is to mock the destructor of the mock function. - -This sounds simple, except for one problem: a destructor is a special function -with special syntax and special semantics, and the `MOCK_METHOD` macro doesn't -work for it: - -```cpp -MOCK_METHOD(void, ~MockFoo, ()); // Won't compile! -``` - -The good news is that you can use a simple pattern to achieve the same effect. -First, add a mock function `Die()` to your mock class and call it in the -destructor, like this: - -```cpp -class MockFoo : public Foo { - ... - // Add the following two lines to the mock class. - MOCK_METHOD(void, Die, ()); - ~MockFoo() override { Die(); } -}; -``` - -(If the name `Die()` clashes with an existing symbol, choose another name.) Now, -we have translated the problem of testing when a `MockFoo` object dies to -testing when its `Die()` method is called: - -```cpp - MockFoo* foo = new MockFoo; - MockBar* bar = new MockBar; - ... - { - InSequence s; - - // Expects *foo to die after bar->A() and before bar->B(). - EXPECT_CALL(*bar, A()); - EXPECT_CALL(*foo, Die()); - EXPECT_CALL(*bar, B()); - } -``` - -And that's that. - -### Using gMock and Threads {#UsingThreads} - -In a **unit** test, it's best if you could isolate and test a piece of code in a -single-threaded context. That avoids race conditions and dead locks, and makes -debugging your test much easier. - -Yet most programs are multi-threaded, and sometimes to test something we need to -pound on it from more than one thread. gMock works for this purpose too. - -Remember the steps for using a mock: - -1. Create a mock object `foo`. -2. Set its default actions and expectations using `ON_CALL()` and - `EXPECT_CALL()`. -3. The code under test calls methods of `foo`. -4. Optionally, verify and reset the mock. -5. Destroy the mock yourself, or let the code under test destroy it. The - destructor will automatically verify it. - -If you follow the following simple rules, your mocks and threads can live -happily together: - -* Execute your *test code* (as opposed to the code being tested) in *one* - thread. This makes your test easy to follow. -* Obviously, you can do step #1 without locking. -* When doing step #2 and #5, make sure no other thread is accessing `foo`. - Obvious too, huh? -* #3 and #4 can be done either in one thread or in multiple threads - anyway - you want. gMock takes care of the locking, so you don't have to do any - - unless required by your test logic. - -If you violate the rules (for example, if you set expectations on a mock while -another thread is calling its methods), you get undefined behavior. That's not -fun, so don't do it. - -gMock guarantees that the action for a mock function is done in the same thread -that called the mock function. For example, in - -```cpp - EXPECT_CALL(mock, Foo(1)) - .WillOnce(action1); - EXPECT_CALL(mock, Foo(2)) - .WillOnce(action2); -``` - -if `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2, gMock will -execute `action1` in thread 1 and `action2` in thread 2. - -gMock does *not* impose a sequence on actions performed in different threads -(doing so may create deadlocks as the actions may need to cooperate). This means -that the execution of `action1` and `action2` in the above example *may* -interleave. If this is a problem, you should add proper synchronization logic to -`action1` and `action2` to make the test thread-safe. - -Also, remember that `DefaultValue` is a global resource that potentially -affects *all* living mock objects in your program. Naturally, you won't want to -mess with it from multiple threads or when there still are mocks in action. - -### Controlling How Much Information gMock Prints - -When gMock sees something that has the potential of being an error (e.g. a mock -function with no expectation is called, a.k.a. an uninteresting call, which is -allowed but perhaps you forgot to explicitly ban the call), it prints some -warning messages, including the arguments of the function, the return value, and -the stack trace. Hopefully this will remind you to take a look and see if there -is indeed a problem. - -Sometimes you are confident that your tests are correct and may not appreciate -such friendly messages. Some other times, you are debugging your tests or -learning about the behavior of the code you are testing, and wish you could -observe every mock call that happens (including argument values, the return -value, and the stack trace). Clearly, one size doesn't fit all. - -You can control how much gMock tells you using the `--gmock_verbose=LEVEL` -command-line flag, where `LEVEL` is a string with three possible values: - -* `info`: gMock will print all informational messages, warnings, and errors - (most verbose). At this setting, gMock will also log any calls to the - `ON_CALL/EXPECT_CALL` macros. It will include a stack trace in - "uninteresting call" warnings. -* `warning`: gMock will print both warnings and errors (less verbose); it will - omit the stack traces in "uninteresting call" warnings. This is the default. -* `error`: gMock will print errors only (least verbose). - -Alternatively, you can adjust the value of that flag from within your tests like -so: - -```cpp - ::testing::FLAGS_gmock_verbose = "error"; -``` - -If you find gMock printing too many stack frames with its informational or -warning messages, remember that you can control their amount with the -`--gtest_stack_trace_depth=max_depth` flag. - -Now, judiciously use the right flag to enable gMock serve you better! - -### Gaining Super Vision into Mock Calls - -You have a test using gMock. It fails: gMock tells you some expectations aren't -satisfied. However, you aren't sure why: Is there a typo somewhere in the -matchers? Did you mess up the order of the `EXPECT_CALL`s? Or is the code under -test doing something wrong? How can you find out the cause? - -Won't it be nice if you have X-ray vision and can actually see the trace of all -`EXPECT_CALL`s and mock method calls as they are made? For each call, would you -like to see its actual argument values and which `EXPECT_CALL` gMock thinks it -matches? If you still need some help to figure out who made these calls, how -about being able to see the complete stack trace at each mock call? - -You can unlock this power by running your test with the `--gmock_verbose=info` -flag. For example, given the test program: - -```cpp -#include "gmock/gmock.h" - -using testing::_; -using testing::HasSubstr; -using testing::Return; - -class MockFoo { - public: - MOCK_METHOD(void, F, (const string& x, const string& y)); -}; - -TEST(Foo, Bar) { - MockFoo mock; - EXPECT_CALL(mock, F(_, _)).WillRepeatedly(Return()); - EXPECT_CALL(mock, F("a", "b")); - EXPECT_CALL(mock, F("c", HasSubstr("d"))); - - mock.F("a", "good"); - mock.F("a", "b"); -} -``` - -if you run it with `--gmock_verbose=info`, you will see this output: - -```shell -[ RUN ] Foo.Bar - -foo_test.cc:14: EXPECT_CALL(mock, F(_, _)) invoked -Stack trace: ... - -foo_test.cc:15: EXPECT_CALL(mock, F("a", "b")) invoked -Stack trace: ... - -foo_test.cc:16: EXPECT_CALL(mock, F("c", HasSubstr("d"))) invoked -Stack trace: ... - -foo_test.cc:14: Mock function call matches EXPECT_CALL(mock, F(_, _))... - Function call: F(@0x7fff7c8dad40"a",@0x7fff7c8dad10"good") -Stack trace: ... - -foo_test.cc:15: Mock function call matches EXPECT_CALL(mock, F("a", "b"))... - Function call: F(@0x7fff7c8dada0"a",@0x7fff7c8dad70"b") -Stack trace: ... - -foo_test.cc:16: Failure -Actual function call count doesn't match EXPECT_CALL(mock, F("c", HasSubstr("d")))... - Expected: to be called once - Actual: never called - unsatisfied and active -[ FAILED ] Foo.Bar -``` - -Suppose the bug is that the `"c"` in the third `EXPECT_CALL` is a typo and -should actually be `"a"`. With the above message, you should see that the actual -`F("a", "good")` call is matched by the first `EXPECT_CALL`, not the third as -you thought. From that it should be obvious that the third `EXPECT_CALL` is -written wrong. Case solved. - -If you are interested in the mock call trace but not the stack traces, you can -combine `--gmock_verbose=info` with `--gtest_stack_trace_depth=0` on the test -command line. - - - -### Running Tests in Emacs - -If you build and run your tests in Emacs using the `M-x google-compile` command -(as many googletest users do), the source file locations of gMock and googletest -errors will be highlighted. Just press `` on one of them and you'll be -taken to the offending line. Or, you can just type `C-x`` to jump to the next -error. - -To make it even easier, you can add the following lines to your `~/.emacs` file: - -```text -(global-set-key "\M-m" 'google-compile) ; m is for make -(global-set-key [M-down] 'next-error) -(global-set-key [M-up] '(lambda () (interactive) (next-error -1))) -``` - -Then you can type `M-m` to start a build (if you want to run the test as well, -just make sure `foo_test.run` or `runtests` is in the build command you supply -after typing `M-m`), or `M-up`/`M-down` to move back and forth between errors. - -## Extending gMock - -### Writing New Matchers Quickly {#NewMatchers} - -WARNING: gMock does not guarantee when or how many times a matcher will be -invoked. Therefore, all matchers must be functionally pure. See -[this section](#PureMatchers) for more details. - -The `MATCHER*` family of macros can be used to define custom matchers easily. -The syntax: - -```cpp -MATCHER(name, description_string_expression) { statements; } -``` - -will define a matcher with the given name that executes the statements, which -must return a `bool` to indicate if the match succeeds. Inside the statements, -you can refer to the value being matched by `arg`, and refer to its type by -`arg_type`. - -The *description string* is a `string`-typed expression that documents what the -matcher does, and is used to generate the failure message when the match fails. -It can (and should) reference the special `bool` variable `negation`, and should -evaluate to the description of the matcher when `negation` is `false`, or that -of the matcher's negation when `negation` is `true`. - -For convenience, we allow the description string to be empty (`""`), in which -case gMock will use the sequence of words in the matcher name as the -description. - -For example: - -```cpp -MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; } -``` - -allows you to write - -```cpp - // Expects mock_foo.Bar(n) to be called where n is divisible by 7. - EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7())); -``` - -or, - -```cpp - using ::testing::Not; - ... - // Verifies that two values are divisible by 7. - EXPECT_THAT(some_expression, IsDivisibleBy7()); - EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7())); -``` - -If the above assertions fail, they will print something like: - -```shell - Value of: some_expression - Expected: is divisible by 7 - Actual: 27 - ... - Value of: some_other_expression - Expected: not (is divisible by 7) - Actual: 21 -``` - -where the descriptions `"is divisible by 7"` and `"not (is divisible by 7)"` are -automatically calculated from the matcher name `IsDivisibleBy7`. - -As you may have noticed, the auto-generated descriptions (especially those for -the negation) may not be so great. You can always override them with a `string` -expression of your own: - -```cpp -MATCHER(IsDivisibleBy7, - absl::StrCat(negation ? "isn't" : "is", " divisible by 7")) { - return (arg % 7) == 0; -} -``` - -Optionally, you can stream additional information to a hidden argument named -`result_listener` to explain the match result. For example, a better definition -of `IsDivisibleBy7` is: - -```cpp -MATCHER(IsDivisibleBy7, "") { - if ((arg % 7) == 0) - return true; - - *result_listener << "the remainder is " << (arg % 7); - return false; -} -``` - -With this definition, the above assertion will give a better message: - -```shell - Value of: some_expression - Expected: is divisible by 7 - Actual: 27 (the remainder is 6) -``` - -You should let `MatchAndExplain()` print *any additional information* that can -help a user understand the match result. Note that it should explain why the -match succeeds in case of a success (unless it's obvious) - this is useful when -the matcher is used inside `Not()`. There is no need to print the argument value -itself, as gMock already prints it for you. - -NOTE: The type of the value being matched (`arg_type`) is determined by the -context in which you use the matcher and is supplied to you by the compiler, so -you don't need to worry about declaring it (nor can you). This allows the -matcher to be polymorphic. For example, `IsDivisibleBy7()` can be used to match -any type where the value of `(arg % 7) == 0` can be implicitly converted to a -`bool`. In the `Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an -`int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will -be `unsigned long`; and so on. - -### Writing New Parameterized Matchers Quickly - -Sometimes you'll want to define a matcher that has parameters. For that you can -use the macro: - -```cpp -MATCHER_P(name, param_name, description_string) { statements; } -``` - -where the description string can be either `""` or a `string` expression that -references `negation` and `param_name`. - -For example: - -```cpp -MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; } -``` - -will allow you to write: - -```cpp - EXPECT_THAT(Blah("a"), HasAbsoluteValue(n)); -``` - -which may lead to this message (assuming `n` is 10): - -```shell - Value of: Blah("a") - Expected: has absolute value 10 - Actual: -9 -``` - -Note that both the matcher description and its parameter are printed, making the -message human-friendly. - -In the matcher definition body, you can write `foo_type` to reference the type -of a parameter named `foo`. For example, in the body of -`MATCHER_P(HasAbsoluteValue, value)` above, you can write `value_type` to refer -to the type of `value`. - -gMock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to `MATCHER_P10` to -support multi-parameter matchers: - -```cpp -MATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; } -``` - -Please note that the custom description string is for a particular *instance* of -the matcher, where the parameters have been bound to actual values. Therefore -usually you'll want the parameter values to be part of the description. gMock -lets you do that by referencing the matcher parameters in the description string -expression. - -For example, - -```cpp -using ::testing::PrintToString; -MATCHER_P2(InClosedRange, low, hi, - absl::StrFormat("%s in range [%s, %s]", negation ? "isn't" : "is", - PrintToString(low), PrintToString(hi))) { - return low <= arg && arg <= hi; -} -... -EXPECT_THAT(3, InClosedRange(4, 6)); -``` - -would generate a failure that contains the message: - -```shell - Expected: is in range [4, 6] -``` - -If you specify `""` as the description, the failure message will contain the -sequence of words in the matcher name followed by the parameter values printed -as a tuple. For example, - -```cpp - MATCHER_P2(InClosedRange, low, hi, "") { ... } - ... - EXPECT_THAT(3, InClosedRange(4, 6)); -``` - -would generate a failure that contains the text: - -```shell - Expected: in closed range (4, 6) -``` - -For the purpose of typing, you can view - -```cpp -MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... } -``` - -as shorthand for - -```cpp -template -FooMatcherPk -Foo(p1_type p1, ..., pk_type pk) { ... } -``` - -When you write `Foo(v1, ..., vk)`, the compiler infers the types of the -parameters `v1`, ..., and `vk` for you. If you are not happy with the result of -the type inference, you can specify the types by explicitly instantiating the -template, as in `Foo(5, false)`. As said earlier, you don't get to -(or need to) specify `arg_type` as that's determined by the context in which the -matcher is used. - -You can assign the result of expression `Foo(p1, ..., pk)` to a variable of type -`FooMatcherPk`. This can be useful when composing -matchers. Matchers that don't have a parameter or have only one parameter have -special types: you can assign `Foo()` to a `FooMatcher`-typed variable, and -assign `Foo(p)` to a `FooMatcherP`-typed variable. - -While you can instantiate a matcher template with reference types, passing the -parameters by pointer usually makes your code more readable. If, however, you -still want to pass a parameter by reference, be aware that in the failure -message generated by the matcher you will see the value of the referenced object -but not its address. - -You can overload matchers with different numbers of parameters: - -```cpp -MATCHER_P(Blah, a, description_string_1) { ... } -MATCHER_P2(Blah, a, b, description_string_2) { ... } -``` - -While it's tempting to always use the `MATCHER*` macros when defining a new -matcher, you should also consider implementing `MatcherInterface` or using -`MakePolymorphicMatcher()` instead (see the recipes that follow), especially if -you need to use the matcher a lot. While these approaches require more work, -they give you more control on the types of the value being matched and the -matcher parameters, which in general leads to better compiler error messages -that pay off in the long run. They also allow overloading matchers based on -parameter types (as opposed to just based on the number of parameters). - -### Writing New Monomorphic Matchers - -A matcher of argument type `T` implements `::testing::MatcherInterface` and -does two things: it tests whether a value of type `T` matches the matcher, and -can describe what kind of values it matches. The latter ability is used for -generating readable error messages when expectations are violated. - -The interface looks like this: - -```cpp -class MatchResultListener { - public: - ... - // Streams x to the underlying ostream; does nothing if the ostream - // is NULL. - template - MatchResultListener& operator<<(const T& x); - - // Returns the underlying ostream. - std::ostream* stream(); -}; - -template -class MatcherInterface { - public: - virtual ~MatcherInterface(); - - // Returns true if and only if the matcher matches x; also explains the match - // result to 'listener'. - virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0; - - // Describes this matcher to an ostream. - virtual void DescribeTo(std::ostream* os) const = 0; - - // Describes the negation of this matcher to an ostream. - virtual void DescribeNegationTo(std::ostream* os) const; -}; -``` - -If you need a custom matcher but `Truly()` is not a good option (for example, -you may not be happy with the way `Truly(predicate)` describes itself, or you -may want your matcher to be polymorphic as `Eq(value)` is), you can define a -matcher to do whatever you want in two steps: first implement the matcher -interface, and then define a factory function to create a matcher instance. The -second step is not strictly needed but it makes the syntax of using the matcher -nicer. - -For example, you can define a matcher to test whether an `int` is divisible by 7 -and then use it like this: - -```cpp -using ::testing::MakeMatcher; -using ::testing::Matcher; -using ::testing::MatcherInterface; -using ::testing::MatchResultListener; - -class DivisibleBy7Matcher : public MatcherInterface { - public: - bool MatchAndExplain(int n, - MatchResultListener* /* listener */) const override { - return (n % 7) == 0; - } - - void DescribeTo(std::ostream* os) const override { - *os << "is divisible by 7"; - } - - void DescribeNegationTo(std::ostream* os) const override { - *os << "is not divisible by 7"; - } -}; - -Matcher DivisibleBy7() { - return MakeMatcher(new DivisibleBy7Matcher); -} - -... - EXPECT_CALL(foo, Bar(DivisibleBy7())); -``` - -You may improve the matcher message by streaming additional information to the -`listener` argument in `MatchAndExplain()`: - -```cpp -class DivisibleBy7Matcher : public MatcherInterface { - public: - bool MatchAndExplain(int n, - MatchResultListener* listener) const override { - const int remainder = n % 7; - if (remainder != 0) { - *listener << "the remainder is " << remainder; - } - return remainder == 0; - } - ... -}; -``` - -Then, `EXPECT_THAT(x, DivisibleBy7());` may generate a message like this: - -```shell -Value of: x -Expected: is divisible by 7 - Actual: 23 (the remainder is 2) -``` - -### Writing New Polymorphic Matchers - -You've learned how to write your own matchers in the previous recipe. Just one -problem: a matcher created using `MakeMatcher()` only works for one particular -type of arguments. If you want a *polymorphic* matcher that works with arguments -of several types (for instance, `Eq(x)` can be used to match a *`value`* as long -as `value == x` compiles -- *`value`* and `x` don't have to share the same -type), you can learn the trick from `testing/base/public/gmock-matchers.h` but -it's a bit involved. - -Fortunately, most of the time you can define a polymorphic matcher easily with -the help of `MakePolymorphicMatcher()`. Here's how you can define `NotNull()` as -an example: - -```cpp -using ::testing::MakePolymorphicMatcher; -using ::testing::MatchResultListener; -using ::testing::PolymorphicMatcher; - -class NotNullMatcher { - public: - // To implement a polymorphic matcher, first define a COPYABLE class - // that has three members MatchAndExplain(), DescribeTo(), and - // DescribeNegationTo(), like the following. - - // In this example, we want to use NotNull() with any pointer, so - // MatchAndExplain() accepts a pointer of any type as its first argument. - // In general, you can define MatchAndExplain() as an ordinary method or - // a method template, or even overload it. - template - bool MatchAndExplain(T* p, - MatchResultListener* /* listener */) const { - return p != NULL; - } - - // Describes the property of a value matching this matcher. - void DescribeTo(std::ostream* os) const { *os << "is not NULL"; } - - // Describes the property of a value NOT matching this matcher. - void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; } -}; - -// To construct a polymorphic matcher, pass an instance of the class -// to MakePolymorphicMatcher(). Note the return type. -PolymorphicMatcher NotNull() { - return MakePolymorphicMatcher(NotNullMatcher()); -} - -... - - EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer. -``` - -**Note:** Your polymorphic matcher class does **not** need to inherit from -`MatcherInterface` or any other class, and its methods do **not** need to be -virtual. - -Like in a monomorphic matcher, you may explain the match result by streaming -additional information to the `listener` argument in `MatchAndExplain()`. - -### Writing New Cardinalities - -A cardinality is used in `Times()` to tell gMock how many times you expect a -call to occur. It doesn't have to be exact. For example, you can say -`AtLeast(5)` or `Between(2, 4)`. - -If the [built-in set](cheat_sheet.md#CardinalityList) of cardinalities doesn't -suit you, you are free to define your own by implementing the following -interface (in namespace `testing`): - -```cpp -class CardinalityInterface { - public: - virtual ~CardinalityInterface(); - - // Returns true if and only if call_count calls will satisfy this cardinality. - virtual bool IsSatisfiedByCallCount(int call_count) const = 0; - - // Returns true if and only if call_count calls will saturate this - // cardinality. - virtual bool IsSaturatedByCallCount(int call_count) const = 0; - - // Describes self to an ostream. - virtual void DescribeTo(std::ostream* os) const = 0; -}; -``` - -For example, to specify that a call must occur even number of times, you can -write - -```cpp -using ::testing::Cardinality; -using ::testing::CardinalityInterface; -using ::testing::MakeCardinality; - -class EvenNumberCardinality : public CardinalityInterface { - public: - bool IsSatisfiedByCallCount(int call_count) const override { - return (call_count % 2) == 0; - } - - bool IsSaturatedByCallCount(int call_count) const override { - return false; - } - - void DescribeTo(std::ostream* os) const { - *os << "called even number of times"; - } -}; - -Cardinality EvenNumber() { - return MakeCardinality(new EvenNumberCardinality); -} - -... - EXPECT_CALL(foo, Bar(3)) - .Times(EvenNumber()); -``` - -### Writing New Actions Quickly {#QuickNewActions} - -If the built-in actions don't work for you, you can easily define your own one. -Just define a functor class with a (possibly templated) call operator, matching -the signature of your action. - -```cpp -struct Increment { - template - T operator()(T* arg) { - return ++(*arg); - } -} -``` - -The same approach works with stateful functors (or any callable, really): - -``` -struct MultiplyBy { - template - T operator()(T arg) { return arg * multiplier; } - - int multiplier; -} - -// Then use: -// EXPECT_CALL(...).WillOnce(MultiplyBy{7}); -``` - -#### Legacy macro-based Actions - -Before C++11, the functor-based actions were not supported; the old way of -writing actions was through a set of `ACTION*` macros. We suggest to avoid them -in new code; they hide a lot of logic behind the macro, potentially leading to -harder-to-understand compiler errors. Nevertheless, we cover them here for -completeness. - -By writing - -```cpp -ACTION(name) { statements; } -``` - -in a namespace scope (i.e. not inside a class or function), you will define an -action with the given name that executes the statements. The value returned by -`statements` will be used as the return value of the action. Inside the -statements, you can refer to the K-th (0-based) argument of the mock function as -`argK`. For example: - -```cpp -ACTION(IncrementArg1) { return ++(*arg1); } -``` - -allows you to write - -```cpp -... WillOnce(IncrementArg1()); -``` - -Note that you don't need to specify the types of the mock function arguments. -Rest assured that your code is type-safe though: you'll get a compiler error if -`*arg1` doesn't support the `++` operator, or if the type of `++(*arg1)` isn't -compatible with the mock function's return type. - -Another example: - -```cpp -ACTION(Foo) { - (*arg2)(5); - Blah(); - *arg1 = 0; - return arg0; -} -``` - -defines an action `Foo()` that invokes argument #2 (a function pointer) with 5, -calls function `Blah()`, sets the value pointed to by argument #1 to 0, and -returns argument #0. - -For more convenience and flexibility, you can also use the following pre-defined -symbols in the body of `ACTION`: - -`argK_type` | The type of the K-th (0-based) argument of the mock function -:-------------- | :----------------------------------------------------------- -`args` | All arguments of the mock function as a tuple -`args_type` | The type of all arguments of the mock function as a tuple -`return_type` | The return type of the mock function -`function_type` | The type of the mock function - -For example, when using an `ACTION` as a stub action for mock function: - -```cpp -int DoSomething(bool flag, int* ptr); -``` - -we have: - -Pre-defined Symbol | Is Bound To ------------------- | --------------------------------- -`arg0` | the value of `flag` -`arg0_type` | the type `bool` -`arg1` | the value of `ptr` -`arg1_type` | the type `int*` -`args` | the tuple `(flag, ptr)` -`args_type` | the type `std::tuple` -`return_type` | the type `int` -`function_type` | the type `int(bool, int*)` - -#### Legacy macro-based parameterized Actions - -Sometimes you'll want to parameterize an action you define. For that we have -another macro - -```cpp -ACTION_P(name, param) { statements; } -``` - -For example, - -```cpp -ACTION_P(Add, n) { return arg0 + n; } -``` - -will allow you to write - -```cpp -// Returns argument #0 + 5. -... WillOnce(Add(5)); -``` - -For convenience, we use the term *arguments* for the values used to invoke the -mock function, and the term *parameters* for the values used to instantiate an -action. - -Note that you don't need to provide the type of the parameter either. Suppose -the parameter is named `param`, you can also use the gMock-defined symbol -`param_type` to refer to the type of the parameter as inferred by the compiler. -For example, in the body of `ACTION_P(Add, n)` above, you can write `n_type` for -the type of `n`. - -gMock also provides `ACTION_P2`, `ACTION_P3`, and etc to support multi-parameter -actions. For example, - -```cpp -ACTION_P2(ReturnDistanceTo, x, y) { - double dx = arg0 - x; - double dy = arg1 - y; - return sqrt(dx*dx + dy*dy); -} -``` - -lets you write - -```cpp -... WillOnce(ReturnDistanceTo(5.0, 26.5)); -``` - -You can view `ACTION` as a degenerated parameterized action where the number of -parameters is 0. - -You can also easily define actions overloaded on the number of parameters: - -```cpp -ACTION_P(Plus, a) { ... } -ACTION_P2(Plus, a, b) { ... } -``` - -### Restricting the Type of an Argument or Parameter in an ACTION - -For maximum brevity and reusability, the `ACTION*` macros don't ask you to -provide the types of the mock function arguments and the action parameters. -Instead, we let the compiler infer the types for us. - -Sometimes, however, we may want to be more explicit about the types. There are -several tricks to do that. For example: - -```cpp -ACTION(Foo) { - // Makes sure arg0 can be converted to int. - int n = arg0; - ... use n instead of arg0 here ... -} - -ACTION_P(Bar, param) { - // Makes sure the type of arg1 is const char*. - ::testing::StaticAssertTypeEq(); - - // Makes sure param can be converted to bool. - bool flag = param; -} -``` - -where `StaticAssertTypeEq` is a compile-time assertion in googletest that -verifies two types are the same. - -### Writing New Action Templates Quickly - -Sometimes you want to give an action explicit template parameters that cannot be -inferred from its value parameters. `ACTION_TEMPLATE()` supports that and can be -viewed as an extension to `ACTION()` and `ACTION_P*()`. - -The syntax: - -```cpp -ACTION_TEMPLATE(ActionName, - HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m), - AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; } -``` - -defines an action template that takes *m* explicit template parameters and *n* -value parameters, where *m* is in [1, 10] and *n* is in [0, 10]. `name_i` is the -name of the *i*-th template parameter, and `kind_i` specifies whether it's a -`typename`, an integral constant, or a template. `p_i` is the name of the *i*-th -value parameter. - -Example: - -```cpp -// DuplicateArg(output) converts the k-th argument of the mock -// function to type T and copies it to *output. -ACTION_TEMPLATE(DuplicateArg, - // Note the comma between int and k: - HAS_2_TEMPLATE_PARAMS(int, k, typename, T), - AND_1_VALUE_PARAMS(output)) { - *output = T(std::get(args)); -} -``` - -To create an instance of an action template, write: - -```cpp -ActionName(v1, ..., v_n) -``` - -where the `t`s are the template arguments and the `v`s are the value arguments. -The value argument types are inferred by the compiler. For example: - -```cpp -using ::testing::_; -... - int n; - EXPECT_CALL(mock, Foo).WillOnce(DuplicateArg<1, unsigned char>(&n)); -``` - -If you want to explicitly specify the value argument types, you can provide -additional template arguments: - -```cpp -ActionName(v1, ..., v_n) -``` - -where `u_i` is the desired type of `v_i`. - -`ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the number of -value parameters, but not on the number of template parameters. Without the -restriction, the meaning of the following is unclear: - -```cpp - OverloadedAction(x); -``` - -Are we using a single-template-parameter action where `bool` refers to the type -of `x`, or a two-template-parameter action where the compiler is asked to infer -the type of `x`? - -### Using the ACTION Object's Type - -If you are writing a function that returns an `ACTION` object, you'll need to -know its type. The type depends on the macro used to define the action and the -parameter types. The rule is relatively simple: - -| Given Definition | Expression | Has Type | -| ----------------------------- | ------------------- | --------------------- | -| `ACTION(Foo)` | `Foo()` | `FooAction` | -| `ACTION_TEMPLATE(Foo,` | `Foo()` : t_m>` : -: `AND_0_VALUE_PARAMS())` : : : -| `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP` | -| `ACTION_TEMPLATE(Bar,` | `Bar` | `FooActionP` : -: `AND_1_VALUE_PARAMS(p1))` : : : -| `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value,` | `BazActionP2` : -| `ACTION_TEMPLATE(Baz,` | `Baz` | `FooActionP2` : -: `AND_2_VALUE_PARAMS(p1, p2))` : `int_value)` : : -| ... | ... | ... | - -Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`, -and etc) for actions with different numbers of value parameters, or the action -definitions cannot be overloaded on the number of them. - -### Writing New Monomorphic Actions {#NewMonoActions} - -While the `ACTION*` macros are very convenient, sometimes they are -inappropriate. For example, despite the tricks shown in the previous recipes, -they don't let you directly specify the types of the mock function arguments and -the action parameters, which in general leads to unoptimized compiler error -messages that can baffle unfamiliar users. They also don't allow overloading -actions based on parameter types without jumping through some hoops. - -An alternative to the `ACTION*` macros is to implement -`::testing::ActionInterface`, where `F` is the type of the mock function in -which the action will be used. For example: - -```cpp -template -class ActionInterface { - public: - virtual ~ActionInterface(); - - // Performs the action. Result is the return type of function type - // F, and ArgumentTuple is the tuple of arguments of F. - // - - // For example, if F is int(bool, const string&), then Result would - // be int, and ArgumentTuple would be std::tuple. - virtual Result Perform(const ArgumentTuple& args) = 0; -}; -``` - -```cpp -using ::testing::_; -using ::testing::Action; -using ::testing::ActionInterface; -using ::testing::MakeAction; - -typedef int IncrementMethod(int*); - -class IncrementArgumentAction : public ActionInterface { - public: - int Perform(const std::tuple& args) override { - int* p = std::get<0>(args); // Grabs the first argument. - return *p++; - } -}; - -Action IncrementArgument() { - return MakeAction(new IncrementArgumentAction); -} - -... - EXPECT_CALL(foo, Baz(_)) - .WillOnce(IncrementArgument()); - - int n = 5; - foo.Baz(&n); // Should return 5 and change n to 6. -``` - -### Writing New Polymorphic Actions {#NewPolyActions} - -The previous recipe showed you how to define your own action. This is all good, -except that you need to know the type of the function in which the action will -be used. Sometimes that can be a problem. For example, if you want to use the -action in functions with *different* types (e.g. like `Return()` and -`SetArgPointee()`). - -If an action can be used in several types of mock functions, we say it's -*polymorphic*. The `MakePolymorphicAction()` function template makes it easy to -define such an action: - -```cpp -namespace testing { -template -PolymorphicAction MakePolymorphicAction(const Impl& impl); -} // namespace testing -``` - -As an example, let's define an action that returns the second argument in the -mock function's argument list. The first step is to define an implementation -class: - -```cpp -class ReturnSecondArgumentAction { - public: - template - Result Perform(const ArgumentTuple& args) const { - // To get the i-th (0-based) argument, use std::get(args). - return std::get<1>(args); - } -}; -``` - -This implementation class does *not* need to inherit from any particular class. -What matters is that it must have a `Perform()` method template. This method -template takes the mock function's arguments as a tuple in a **single** -argument, and returns the result of the action. It can be either `const` or not, -but must be invokable with exactly one template argument, which is the result -type. In other words, you must be able to call `Perform(args)` where `R` is -the mock function's return type and `args` is its arguments in a tuple. - -Next, we use `MakePolymorphicAction()` to turn an instance of the implementation -class into the polymorphic action we need. It will be convenient to have a -wrapper for this: - -```cpp -using ::testing::MakePolymorphicAction; -using ::testing::PolymorphicAction; - -PolymorphicAction ReturnSecondArgument() { - return MakePolymorphicAction(ReturnSecondArgumentAction()); -} -``` - -Now, you can use this polymorphic action the same way you use the built-in ones: - -```cpp -using ::testing::_; - -class MockFoo : public Foo { - public: - MOCK_METHOD(int, DoThis, (bool flag, int n), (override)); - MOCK_METHOD(string, DoThat, (int x, const char* str1, const char* str2), - (override)); -}; - - ... - MockFoo foo; - EXPECT_CALL(foo, DoThis).WillOnce(ReturnSecondArgument()); - EXPECT_CALL(foo, DoThat).WillOnce(ReturnSecondArgument()); - ... - foo.DoThis(true, 5); // Will return 5. - foo.DoThat(1, "Hi", "Bye"); // Will return "Hi". -``` - -### Teaching gMock How to Print Your Values - -When an uninteresting or unexpected call occurs, gMock prints the argument -values and the stack trace to help you debug. Assertion macros like -`EXPECT_THAT` and `EXPECT_EQ` also print the values in question when the -assertion fails. gMock and googletest do this using googletest's user-extensible -value printer. - -This printer knows how to print built-in C++ types, native arrays, STL -containers, and any type that supports the `<<` operator. For other types, it -prints the raw bytes in the value and hopes that you the user can figure it out. -[googletest's advanced guide](../../googletest/docs/advanced.md#teaching-googletest-how-to-print-your-values) -explains how to extend the printer to do a better job at printing your -particular type than to dump the bytes. - -## Useful Mocks Created Using gMock - - - - -### Mock std::function {#MockFunction} - -`std::function` is a general function type introduced in C++11. It is a -preferred way of passing callbacks to new interfaces. Functions are copiable, -and are not usually passed around by pointer, which makes them tricky to mock. -But fear not - `MockFunction` can help you with that. - -`MockFunction` has a mock method `Call()` with the signature: - -```cpp - R Call(T1, ..., Tn); -``` - -It also has a `AsStdFunction()` method, which creates a `std::function` proxy -forwarding to Call: - -```cpp - std::function AsStdFunction(); -``` - -To use `MockFunction`, first create `MockFunction` object and set up -expectations on its `Call` method. Then pass proxy obtained from -`AsStdFunction()` to the code you are testing. For example: - -```cpp -TEST(FooTest, RunsCallbackWithBarArgument) { - // 1. Create a mock object. - MockFunction mock_function; - - // 2. Set expectations on Call() method. - EXPECT_CALL(mock_function, Call("bar")).WillOnce(Return(1)); - - // 3. Exercise code that uses std::function. - Foo(mock_function.AsStdFunction()); - // Foo's signature can be either of: - // void Foo(const std::function& fun); - // void Foo(std::function fun); - - // 4. All expectations will be verified when mock_function - // goes out of scope and is destroyed. -} -``` - -Remember that function objects created with `AsStdFunction()` are just -forwarders. If you create multiple of them, they will share the same set of -expectations. - -Although `std::function` supports unlimited number of arguments, `MockFunction` -implementation is limited to ten. If you ever hit that limit... well, your -callback has bigger problems than being mockable. :-) - - diff --git a/googlemock/docs/design.md b/googlemock/docs/design.md deleted file mode 100644 index 3dd4025..0000000 --- a/googlemock/docs/design.md +++ /dev/null @@ -1,1600 +0,0 @@ -# gMock - a Framework for Writing and Using C++ Mock Classes - - - -**Status:** Draft \ -**Tiny URL:** http://go/gmockdesign \ -**Author:** Zhanyong Wan (who/wan) - - - -(To participate in discussions on gMock, please subscribe to -[opensource-gmock](https://groups.google.com/a/google.com/group/opensource-gmock/subscribe). -Past discussions can be viewed -[here](https://groups.google.com/a/google.com/group/opensource-gmock/topics) and -[here](https://mailman.corp.google.com/pipermail/c-mock-dev/).) - -(The slides for my gMock preview talk can be found here: -[ppt](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0706-beijing-gmock-preview.ppt).) - -## Objective - -[Mock objects](http://en.wikipedia.org/wiki/Mock_object) are simulated objects -that mimic real objects in controlled ways. They are useful for driving the -design of a system, and for testing some other object when it's difficult to use -real objects in a test. - -While the idea of mocks applies to all objected-oriented languages, writing them -in C++ has many practical difficulties, due to the lack of support for -reflection in the language, the complexity and irregularity of C++, and the lack -of adequate tools. As an unfortunate result, C++ programmers often avoid writing -mocks, resulting in big, monolithic classes in production, and slow, brittle, -and difficult-to-maintain tests. - -We believe that a good framework can make it much more pleasant to write and use -mocks in C++. Such a tool would help people write more -[small](https://wiki.corp.google.com/twiki/bin/view/Main/GoogleTestDefinitions) -tests that are quick, robust, and precise. Perhaps more importantly, -incorporating mocks early and often in the design process helps people discover -the role interfaces in the system and thus often leads to -[better designs](http://www.jmock.org/oopsla2004.pdf). - -We plan to develop *gMock* as a generic framework for creating and using mock -classes in C++. We would encourage people to *use gMock as a design tool as much -as a testing tool*. - -### Goals of gMock - -* **Supporting all interfaces:** A user should be able to use gMock to create - a mock class for any C++ interface (i.e. a class whose methods are virtual). - In particular, interface templates should be supported, and there should be - no restriction on the types of the parameters - `const` parameters, pointer - parameters, reference parameters, reference-to-`const` parameters, and etc - should all be allowed. - - gMock can also be used to mock a "loose" interface (i.e. the set of - operations a template class or template function expects its type argument - to support). This is useful for testing code that uses the - ["high-performance dependency injection"](https://engdoc.corp.google.com/eng/doc/tott/episodes/33.md) - technique. - -* **Precise specification of the intention:** gMock should enable a user to - precisely specify the intended behavior of a mock object, and how its - methods are expected to be called (in what order, with what arguments, etc). - In particular, it should not force the user to over-specify the problem - (which results in brittle tests that break when unrelated changes to the - code are made), or to under-specify the problem (which results in tests that - continue to pass when they shouldn't). - -* **Intuitive and declarative syntax:** A declarative syntax fosters thinking - at the right abstraction level, and makes the code readable and less - error-prone. Therefore gMock should provide intuitive and declarative syntax - for: - - 1. creating a mock class, and - 2. controlling the behavior of a mock object. When the two goals conflict, - the latter takes precedence, as it usually needs to be done many more - times than the former. - -* **Extensible:** No framework can be expected to cover all users' needs. - Therefore, gMock shouldn't tie the users to whatever it provides. Instead, a - user should be able to easily extend the framework to accomplish more - advanced tasks. - -* **Helpful error messages:** Bad error messages are a sure-fire way to - frustrate the users and drive them away. Therefore, gMock should generate - clear and sensible messages - - 1. when the code fails to compile - this can be hard as lots of templates - have to be used in the implementation, but we should try our best; and - 2. when a user-supplied expectation fails. This also applies to - user-defined extensions, given that the user has done a good job - implementing the extensions. - -* **Easy to learn:** We want gMock to make people's life easier, not harder. - It defeats our purpose if the framework is complex and difficult to learn. - -* **Easily automatable:** The design of gMock should make the process of - creating a mock class from an interface fairly mechanical, and thus doable - by the automated - [mock class generator](https://wiki.corp.google.com/twiki/bin/view/Main/MockClassGeneratorDev). - -* **Working in Google's environment:** While we may be interested in open - sourcing gMock later, our primary goal is to serve Google. Therefore gMock - must work well in our environment. In particular, it must not use - exceptions, and should work well with - [gUnit](https://wiki.corp.google.com/twiki/bin/view/Main/GUnitGuide). - -### Non-goals - -* **Mocking non-virtual methods:** gMock is a source-level tool that works - with standard compilers and linkers. It doesn't attempt to swap the object - code of a mock class and that of a real class on-the-fly. Therefore, only - virtual methods and template arguments can be mocked by gMock. -* **Supporting arbitrary number of parameters:** Due to limitations of the C++ - language, there will be a practical limit on the number of parameters a mock - function can have. Support for more parameters can be added as needed. -* **Supporting non-Linux platforms:** The initial implementation may not run - on Windows or Mac OS. We have limited resources and need to make sure that - Linux users are served first. However, we'll try to avoid doing things that - will make porting gMock to non-Linux platforms difficult. -* **Special support for particular projects:** gMock is a generic framework - that makes mocking easy for *all* Google C++ projects. It should not contain - logic that's useful only to a small number of projects. - -## Background - -### Terminology - -Different people often use "mock" to mean different things. This document -borrows the terminology popularized by -Martin -Fowler: - -* **Dummy** objects are passed around but never actually used. Usually they - are just used to fill parameter lists. -* **Fake** objects actually have working implementations, but usually take - some shortcut (perhaps to make the operations less expensive), which makes - them not suitable for production. -* **Stubs** provide canned answers to calls made during the test, usually not - responding at all to anything outside what's programmed in for the test. -* **Mocks** are objects pre-programmed with expectations which form a - specification of the calls they are expected to receive. - -### Fakes vs Mocks - -Many people are not clear about the difference between a fake and a mock, and -use the terms interchangeably. However, to understand why we need gMock and what -it will deliver, it's crucial to distinguish the two. - -Compared with a fake, a mock object is "dumb" and usually doesn't have a working -implementation. However, it allows the user to control its behavior and set -expectations on the calls it will receive. For example, you can tell a mock -object that its `Foo()` method will be called twice with an argument that's -greater than 10, and it should return 12 and 14 respectively. - -It may seem that mocks are not very useful compared to fakes, but the Java -community has shown this perception to be wrong. The ability to control a mock -object's behavior and specify the expected interaction between it and the code -under test makes it far more flexible and useful than a fake in designing and -testing a software system. - -While fake classes have to be crafted with domain knowledge, mock classes can -actually be created mechanically - with suitable support from a framework. In -more dynamic languages like Java, C#, and Python, there are tools that create -mock objects on the fly without any user intervention. In C++, this cannot be -done within the language itself. However, a framework can make the task much -easier for a user, and the -[mock class generator](https://wiki.corp.google.com/twiki/bin/view/Main/MockClassGeneratorDev) -will make the process automated to a large extent. - -### C++ Mocking at Google - -To our knowledge, no tool or library is used at Google to facilitate the -creation of mock classes. As a result, people have been writing mock classes -manually. Such classes are typically tedious to create, and lack functionalities -for effective mocking. As a result, people are often frustrated and decided to -avoid mock classes. - -As a rough estimate, as of 3/15/2007, the number of existing C++ mock classes in -our source tree is: - -```shell -$ gsearch -f="\.(h|cc|cpp)$" -a -c "^\s*class\s+(Mock\w*|\w+Mock)\s*[:{]" -748 -``` - -while the number of all C++ classes is: - -```shell -$ gsearch -f="\.(h|cc|cpp)$" -a -c "^\s*class\s+\w+\s*[:{]" -188488 -``` - -Roughly 1 out of every 250 C++ classes has a corresponding mock class. Clearly -this is not enough. - -### Situation outside Google - -The situation of using C++ mocks outside of Google is not a lot brighter either. -Although there is an open-source framework -([mockpp](http://mockpp.sourceforge.net/)) for writing mock classes, it is -overly complex and has limited functionalities. As a result, it doesn't have a -large following. - -### Existing Mock Frameworks - -A good mock framework takes years of hard work and actual use in the field to -mature. Therefore, it pays hugely to learn from existing mock frameworks: what -they can and cannot do, why they are the way they are, how they have evolved, -what lessons their creators have learned, and what they intend to do next, etc. - -We studied some well-known mock frameworks for Java -([Mock Objects](http://www.mockobjects.com), -[EasyMock](http://www.easymock.org), [jMock 1](http://www.jmock.org), and -[jMock 2](http://cvs.jmock.codehaus.org/browse/~raw,r=1.3/jmock/website/content/cheat-sheet.html)) -and for C++ ([mockpp](http://mockpp.sourceforge.net/)). Our conclusion is: - -* Mock Objects is the most primitive of the four. It provides some basic - constructs for a user to set expected arguments and return values, but not - much beyond that. -* EasyMock makes the simple case very easy, but isn't flexible enough to - handle more advanced usage well. Often the users are forced to either - over-specify or under-specify their intention, resulting in brittle or - imprecise tests. -* jMock 1 and 2 share the same design philosophy, but have incompatible - syntaxes. They allow a user to precisely specify the intention of the test - in most cases, and can be easily extended by the user to handle more complex - situations. -* mockpp is a mixed bag of constructs from the above three. It doesn't have a - coherent design philosophy, and doesn't address C++'s specific requirements - well. It is more complex, redundant, and difficult to learn and use than we - would like. - -### Our Plan - -We believe that jMock is the most interesting and promising of the four. Its -creators have been aggressively experimenting with new ideas and designs, and -have produced many iterations before the current form. They have also documented -their experience and lessons in developing jMock in -[two](http://www.jmock.org/oopsla2004.pdf) -[papers](http://mockobjects.com/files/evolving_an_edsl.ooplsa2006.pdf), which -contain many valuable insights. - -Therefore, the design of gMock is heavily influenced by jMock. Many constructs -will be directly ported from jMock. Meanwhile, we'll revisit various design -decisions in C++'s context to make sure that we take advantages of C++ strengths -and avoid its weaknesses. We will also address some challenges that are unique -to C++. - -## Overview - -### Why a Framework - -Mock objects serve two distinct purposes in designing and testing a software -system: - -1. They implement the same interfaces as the real classes and provide canned - responses, allowing code that uses them to compile and run; and -2. They can verify that the actual interaction between them and the code under - test matches what the user expects (for example, the right functions are - called, in the right order, with the right arguments, etc). - -Without a framework, a user could manually implement mock functions to return -answers that are either pre-defined or computed using simplified logic. To -verify that the interaction that actually happens matches the expectation, a -user would typically let the mock functions record the interaction in some way, -and inspect the record in the end. This poor man's approach leaves several -things to be desired: - -1. Writing a mock class manually is not easy, and often viewed as a burden to - be avoided. -2. Different tests use a mock class in different ways. Therefore, it is often - impractical to provide a working fake implementation that is useful for all - tests. -3. Describing what the interaction should be by inspecting what really has - happened is round-about and unnatural. It obscure the intention of the test - author, and results in tests that are hard to read and understand. -4. It is often too late to check how the interaction went after it has - finished. Much better is to report a failure at the exact moment an - expectation is violated. This gives the user a chance to check the context - of the failure (the stack trace, the variables, etc) before important - information is lost. - -The purpose of gMock is to address the above problems. In particular, it will: - -1. make the task of writing a mock class much easier by hiding the low-level - mechanism from the user; -1. let the user of a mock class, rather than its creator, specify the intended - responses; -1. let the user specify the intended interaction in a clear and direct syntax; - and -1. catch violations to the specification as soon as they arise. - -### gMock's Expressiveness - -The Java community's years of experience using mocks shows that a mock framework -should enable a user to directly specify the following properties of the -interaction between a mock object and its surrounding code: - -* How many times will a function be called? -* What arguments will be used? -* In what order will the calls be made? -* What should the functions return? -* What side effects (if any) should the calls incur? - -Also, it's important to be able to loosen the constraints when necessary to -prevent brittle tests. For example, - -* If the test doesn't care about how many times a function will be called, the - test writer should be able to make that clear; -* If the exact value of an argument doesn't matter, the user should be able to - say so; -* If only a subset of the calls need to happen in a strict order, the user - should be allowed to specify a partial order. - -### Architecture of gMock - -gMock is a C++ library that will be linked into a user's test code. It consists -of the following components (the syntax used in the code samples is -*tentative*): - -1. **Function mockers:** A family of template classes will be provided for the - user to mock functions with different arities. For example, a field of type - - ``` - FunctionMocker - ``` - - will be used to mock a function with signature - - ``` - virtual int Foo(bool, const string&); - ``` - -1. **Specification builder:** This provides a syntax for the user to specify - the expected arguments and responses of a mock function. For example, to say - that `Foo()` will be called exactly twice with arguments `true` and a string - that contains `"hello"`, and will return 10 and 12 respectively, the user - can write: - - ``` - EXPECT_CALL(mock_object, Foo(Eq(true), HasSubstring("hello")) - .Times(2) - .WillOnce(Return(10)) - .WillOnce(Return(12)) - ``` - -1. **Cardinalities, matchers, and actions:** A collection of pre-defined - *cardinalities* (e.g. `2`), argument *matchers* (e.g. `Eq()` and - `HasSubstring()`), and stub *actions* (e.g. `Return()`) will enable the user - to precisely specify the intended interaction in most cases. When this set - is inadequate, the user can easily define new cardinalities, matchers, and - actions. - -1. **Specification interpreter:** An underlying interpreter will verify that - the actual calls made to the mock object conform to the user's expectations. - -gMock helps a user in two kinds of activities: *writing* mock classes and -*using* them in tests. When writing a mock class, a user employs the function -mockers (#1); when using a mock class, the user relies on #2 and #3 to specify -the expected interaction between the mock object and the code under test. As the -test runs and the mock functions are invoked, the specification interpreter (#4) -verifies that the actual interaction matches the expectation, and fails the test -when the two don't match. - -## Detailed Design - -### Implementing a Mock - -This section explains how a user would implement a mock class using gMock. The -final syntax may be slightly different to what's presented here, but the overall -idea should remain the same. - -The goal of the design is to allow mocking functions that take 0 or more -arguments, functions that are overloaded on the number/types of parameters, -const methods, and methods that are overloaded on the const-ness of this object. - -#### Using macros - -The easiest way to define a mock class is to use the `MOCK_METHOD` macro. -Specifically, to mock an interface - -```cpp -class FooInterface { - ... - virtual R Method(A1 a1, A2 a2, ..., Am am) = 0; - virtual S ConstMethod(B1 b1, B2 b2, ..., Bn bn) = 0; -}; -``` - -one would simply write - -```cpp -class MockFoo : public FooInterface { - ... - MOCK_METHOD(R, Method, (A1 a1, A2 a2, ..., Am am), (override)); - MOCK_METHOD(S, ConstMethod, (B1 b1, B2 b2, ..., Bn bn), (const, override)); -}; -``` - -#### Using no macro - -The user can also choose to implement a mock class without using the macros. - -For each function to be mocked that is not overloaded, the user should define a -**function mocker** member variable and implement the function by forwarding the -call to the function mocker, which knows how to respond to the given arguments. - -A user specifies the mock function's default behavior and expectations on it by -calling the *mock spec function* in an `ON_CALL()` or `EXPECT_CALL()` statement. - -Now let's see the concrete syntax. To mock a function that takes no argument: - -```cpp -class AbcInterface { - ... - virtual R Foo() = 0; -}; -``` - -a user would write: - -```cpp -class MockAbc : public AbcInterface { - ... - // Mock Foo(). Implements AbcInterface::Foo(). - virtual R Foo() { return gmock_Foo.Invoke(); } - - FunctionMocker gmock_Foo; -}; -``` - -To mock a function that takes some arguments: - -```cpp - virtual R Bar(A1 a1, A2 a2); -``` - -a user would write: - -```cpp - virtual R Bar(A1 a1, A2 a2) { return gmock_Bar.Invoke(a1, a2); } - - FunctionMocker gmock_Bar; -``` - -To mock a `const` method: - -```cpp - virtual R Baz(A1 a1) const; -``` - -a user would write: - -```cpp - virtual R Baz(A1 a1) const { return gmock_Baz.Invoke(a1); } - - mutable FunctionMocker gmock_Baz; -``` - -Mocking overloaded functions is a little bit more involved. For each overloaded -version, the user needs to define an overloaded mock controller function, e.g. - -```cpp - virtual R Bar(A a) { return gmock_Bar_1.Invoke(a); } - MockSpec& gmock_Bar(Matcher a) { - return gmock_Bar_1.With(a); - } - - virtual R Bar(B b, C c) { return gmock_Bar_2.Invoke(b, c); } - MockSpec& gmock_Bar(Matcher b, Matcher c) { - return gmock_Bar_2.With(b, c); - } - private: - FunctionMocker gmock_Bar_1; - FunctionMocker gmock_Bar_2; -``` - -If a method is overloaded on the const-ness of this object, the user can -distinguish between the two overloaded versions by using a const- vs non-const- -reference to the mock object. The `Const()` function provided by gMock can be -used to get a const reference to an object conveniently: - -```cpp -template -inline const T& Const(const T& x) { return x; } -``` - -### Syntax for Setting Default Actions and Expectations - -For each mock function, there are two interesting properties for a user to -specify: - -1. the **default action**: what the function should do by default when invoked, - and -2. the **expectations**: how the function will be called in a particular test. - -While the default actions of a mock class usually don't change from test to -test, a user typically sets different expectations in different tests. - -The following syntax is proposed for setting the default action of and the -expectations on a mock function: - -```cpp -ON_CALL(mock-object, method(argument-matchers)) - .With(multi-argument-matcher) ? - .WillByDefault(action); -``` - -The `ON_CALL()` statement defines what a mock function should do when its -arguments match the given matchers (unless the user overrides the behavior in -`EXPECT_CALL()`). The `With()` clause is optional. The `WillByDefault()` clause -must appear exactly once. - -```cpp -EXPECT_CALL(mock-object, method(argument-matchers)) - .With(multi-argument-matcher) ? - .Times(cardinality) ? - .InSequence(sequences) * - .WillOnce(action) * - .WillRepeatedly(action) ? - .RetiresOnSaturation(); ? -``` - -The `EXPECT_CALL()` statement says that the mock function should be called the -given number of times (`cardinality`), in the order determined by the -`sequences`, and with arguments that satisfy the given `matchers`. When it is -called, it will perform the given `action`. In this statement, all clauses are -optional and you can repeat `WillOnce()` any number of times. When no action is -specified, the default action defined by `ON_CALL()` will be taken. - -For non-overloaded methods, '(argument-matchers)' may be omitted: - -```cpp -ON_CALL(mock-object, method) - .With(multi-argument-matcher) ? - .WillByDefault(action); - -EXPECT_CALL(mock-object, method) - .With(multi-argument-matcher) ? - …cardinality and actions… -``` - -This allows test writers to omit the parameter list and match any call to the -method. Doing so eases the burden on test maintainers when refactoring method -signatures. The 'With()' clause is still optional when the parameter list is -omitted. - -We make `ON_CALL()` and `EXPECT_CALL()` macros such that we can tell the mock -object the file name and line number of a rule, which can be used to produce -better error messages at run time. When running a test inside Emacs and an -expectation is violated, the user can jump to the expectation by hitting -`` on the message. - -#### Argument Matchers - -An `argument-matcher` can be any of the following: - -```cpp -Void(), Eq(value), Ge(value), Gt(value), Le(value), Lt(value), Ne(value), -HasSubstring(string), SubstringOf(string), -Same(value), Anything(), Any(), Not(argument-matcher), AnyOf(argument-matchers), AllOf(argument-matchers) -``` - -In addition, a user can define custom matchers by implementing the -`MatcherImplInterface` interface (TBD). - -#### Multi-argument Matchers - -Matchers in the previous section match one argument at a time. Sometimes it's -necessary to check all arguments together. This is when multi-argument matchers -are needed: - -```cpp -Eq(), Ge(), Gt(), Le(), Lt(), Ne(), -HasSubstring(), SubstringOf(), -Same(), AnyThings(), Not(multi-argument-matcher), AnyOf(multi-argument-matchers), AllOf(multi-argument-matchers) -``` - -When there are multiple `WithArguments()` clauses in a rule, all of them have to -be satisfied for the rule to match a call. - -A user can define new multi-argument matchers by implementing the -`MatcherImplInterface >` interface (TBD). - -#### Actions - -```cpp -Return(), Return(value), DoDefault(), Fail(string), -SetArgPointee(value), DoAll(actions), ... -``` - -The version of `Return()` that takes no argument is for mocking `void`-returning -functions. The clauses are all statically typed, so a user won't be able to -mistakenly use `Return()` when the mocked function has a non-void return type, -or to use `Return(value)` when the function returns `void`. - -On consecutive calls that match a given expectation, actions specified in -multiple `WillOnce()` clauses in the expectation will be used in the order they -are presented. After all `WillOnce()` clauses have been exhausted, the action -specified by `WillRepeatedly()` will always be used. If there is no -`WillRepeatedly()`, the default action defined by `ON_CALL()` will be taken. - -When side effects need to be mocked (e.g. changing a field or a global variable, -calling a function of a class-typed argument, and so on), users can define a -custom action by implementing the `ActionImplInterface` interface (TBD). - -#### Cardinalities - -A cardinality tells how many times a function is expected to be called. The -number doesn't have to be always exact, as we don't want to over-specify the -behavior and result in brittle tests. - -```cpp -integer, AtLeast(n), AtMost(n), Between(m, n), AnyNumber() -``` - -This set can be extended by the user implementing the `CardinalityImplInterface` -interface (TBD). - -If no cardinality is specified in an `EXPECT_CALL()` statement, gMock will infer -it this way: - -* If there are n `WillOnce()` clauses but no `WillRepeatedly()`, the - cardinality is n; -* If there are n `WillOnce()` clauses and a `WillRepeatedly()`, the - cardinality is `AtLeast(n)`. - -#### Sequences - -Often we want to specify the order in which mock functions are called. However, -we may not want to specify a total order as that may lead to flaky tests that -will be broken by unrelated changes. For this reason, gMock allows the user to -specify a partial order on the calls by organizing them into *sequences*. - -Basically, a sequence is a chain of expectations that have to happen in the -order they are defined. Sequences are identified by their names. For example, -the following defines a sequence named `"a"`, which contains two expectations -where the first has to happen before the second: - -```cpp - Sequence a; - - EXPECT_CALL(mock_foo, Func1(Anything())) - .Times(1) - .InSequence(a); - - EXPECT_CALL(mock_bar, Func2(Eq(2))) - .Times(3) - .InSequence(a); -``` - -Note that expectations in the same sequence don't have to be on the same object -or same function, as the above example shows. - -An expectation can belong to any number of sequences, in which case all order -constraints have to be honored. For convenience, we allow `InSequence()` to take -multiple sequences. In the following example, the first expectation must be -matched before the second and the third, but we don't care about the relative -order of the latter two: - -```cpp - Sequence a, b; - - EXPECT_CALL(mock_foo, Func1(Anything())) - .Times(1) - .InSequence(a, b); - - EXPECT_CALL(mock_bar, Func2(Eq(2))) - .Times(AnyNumber()) - .InSequence(a); - - EXPECT_CALL(mock_bar, Func2(Eq(5))) - .Times(AnyNumber()) - .InSequence(b); -``` - -For convenience, we allow an expectation to contain multiple `InSequence()` -clauses, in which case their arguments will be joined. For example, another way -to write the first expectation in the above example is: - -```cpp - EXPECT_CALL(mock_foo, Func1(Anything())) - .Times(1) - .InSequence(a) - .InSequence(b); -``` - -A common scenario is that the user wants all expectations to match in the strict -order they are defined. Instead of letting the user put `InSequence()` in every -expectation, we provide the following short-hand: - -```cpp - { - InSequence s; - - EXPECT_CALL(...)...; - EXPECT_CALL(...)...; - ... - } -``` - -In the above snippet, when the variable `s` is constructed, gMock will generate -a unique new sequence and automatically put each `EXPECT_CALL()` in the scope of -`s` into this sequence. The result is that this group of expectations must match -in the strict order. - -The user can also use an existing sequence like this: - -```cpp - Sequence a; - ... - { - InSequence s(a); - - EXPECT_CALL(...)...; - EXPECT_CALL(...)...; - ... - } -``` - -This can be useful if an existing sequence needs to be extended. - -#### Examples - -```cpp -EXPECT_CALL(mock_goat, Eat(Eq(5), Anything())) - .WillOnce(Return(false)); -``` - -The mock goat will be told to `Eat()` 5 of something exactly once; the method -should return `false`. - -```cpp -EXPECT_CALL(mock_goat, Drink(HasSubstring("milk"))) - .Times(1); -``` - -The mock goat will be told to `Drink()` something that contains milk once; the -method should perform its default action when invoked. - -```cpp -EXPECT_CALL(mock_elephant, Eat(Same(mock_goat))) - .Times(0); -``` - -The mock elephant should never be told to `Eat()` the poor mock goat, which -would be a terrible thing. - -```cpp -Sequence a; - -EXPECT_CALL(mock_elephant, Eat(Anything())) - .InSequence(a) - .WillOnce(Return(true)); - -EXPECT_CALL(mock_elephant, Walk(Ge(5))) - .Times(AtLeast(1)) - .InSequence(a) - .WillOnce(Return(2)); -``` - -The mock elephant will be told to `Eat()` something; after that it will be told -to `Walk()` >= 5 meters at least once; the `Walk()` method should return 2 the -first time, and should do the default action in future calls. - -#### Syntax Checking - -We will use a combination of compile-time and run-time checks to catch syntax -errors. In particular, the spelling and types of the individual clauses will -(obviously) be done by the C++ compiler, while we'll enforce the order and -counts of the clauses via run-time checks. - -Please note that technically it is possible to do the latter checks at compile -time too, and that is the approach of jMock and Mockpp. For the designer of an -embedded domain-specific language (EDSL), it is appealing to leverage the -compiler of the hosting language (C++ in this case) to parse code in the EDSL -and catch errors in it as much as possible. It is also an interesting exercise -in pushing the envelope of EDSL implementation techniques. - -However, while we initially wanted to go with jMock's approach, we now think -it's better to defer such checks to run time. The reasons are: - -1. Doing the checks at run time *significantly* reduces the number of template - classes and simplifies the implementation. This is not only a benefit for - the author and maintainer of gMock, but also makes it much easier for a user - to learn gMock. New and existing users will have to read the gMock header - files from time to time, so it's important to keep the public interface - small. As an example of what happens when the API is not kept small, try to - read the header files of Mockpp - you will find a plethora of template - classes that reference each other, and it's very difficult to tell what - different roles they play. -1. The jMock approach enables the IDE to automatically suggest the next clause - when a user is writing an expectation statement and thus makes it trivial to - write syntactically correct expectations. Unfortunately, such benefit is - merely theoretic for most C++ users, as C++ is such a complex language that - most IDEs do a poor job at understanding the user's source code and - suggesting auto-completion. -1. C++ templates generate horrible, horrible compiler errors that often baffle - even experienced programmers. By enforcing the syntax at compile time, we - subject gMock's users to the mercy of the C++ compiler, which will generate - lengthy and cryptic errors when a user makes a small mistake in the syntax. - It would be much better for us to generate the errors at run time, as we can - control the messages and choose plain and clear language that guides the - user to fix the problem. -1. The default action and expectation statements in gMock are *declarative*, - and typically each of them will be executed once during the test (not to be - confused with a rule *matching* an invocation multiple times). Therefore - there should be little concern that a syntax error is not caught because the - statement is never actually executed. - -### Formal Semantics - -The previous section presented the syntax and informally explained the meanings -of various clauses. To avoid ambiguities and make sure we all have the same -understanding on the meaning of a complete test using mock objects, we need to -define the semantics of gMock more strictly. - -For an expectation rule to match an actual invocation, three types of -constraints have to be satisfied at the same time: - -1. the order constraints (does the call occur in the right order?), -2. the cardinality constraints (can the rule accept more invocations?), and -3. the argument constraints (do all arguments satisfy their matchers?). - -As the designer of gMock, we need to decide in which order these constraints -should be applied and how to resolve ambiguities. Our goal is to choose a -semantics that is easy to understand and allows the user to easily express -properties useful for writing tests. - -Given that gMock borrows heavily from jMock, naturally one would try to adopt -jMock's semantics. I couldn't find a documentation on that unfortunately. The -following semantics is based on my reverse-engineering jMock and what I think is -reasonable. It differs from the jMock semantics in several important regards. -The exact differences and the rationale behind our decision can be found on the -c-mock-dev [archive](https://g.corp.google.com/group/c-mock-dev-archive) and are -not repeated here. - -The proposed semantics can be summarized by two simple principles: - -1. **The orders are sacred**: under no circumstance can an expectation in a - sequence to match before all expectations that appear earlier in the same - sequence have been satisfied; and -2. **Earlier rules take precedence:** when multiple rules can match an - invocation without violating the order constraints, the one defined the - earliest wins. - -To define the semantics formally, we will use the following terminology: - -* An `ON_CALL()` statement defines a **default action**. -* An `EXPECT_CALL()` statement defines an **expectation**. -* An expectation is **active** iff it still can be used to match invocations. - Otherwise it is **retired**. Initially, all expectations are active. -* An expectation X is an **immediate pre-requisite** of another expectation Y - iff there exists a sequence S where X and Y are both in S, X is defined - before Y, and there is no expectation in S between X and Y. -* An expectation X is a **pre-requisite** of another expectation Y iff there - exists a list X[0] = X, X[1], ..., X[n] = Y, where X[i] is an immediate - pre-requisite of X[i+1] for all i. -* An expectation (or its cardinality constraint) is said to be **satisfied** - iff it has reached its minimum number of allowed invocations. -* An expectation (or its cardinality constraint) is said to be **saturated** - iff it has reached its maximum number of allowed invocations. A saturated - expectation by definition must be satisfied, but not vice versa. - -After the user has set the default action and the expectations, when a mock -function is called, the following algorithm (in pseudo code) will be used to -find the matching expectation and the matching action: - -```cpp -void TryToDoDefault(FunctionMocker& m, const Arguments& args) { - if (m has a default action for arguments args) { - perform the default action; - } else { - raise error("No action is specified."); - } -} - -void OnInvocation(FunctionMocker& m, const Arguments& args) { - for_each (active expectation e on function m in the order - the expectations are defined) { - if (all pre-requisites of e are satisfied && - args match e's argument matchers) { - // We found a match! - - if (e.is_saturated) - raise error("Invocation upper bound exceeded."); - - e.invocation_count++; - retire all prerequisites of e; - - if (e.retires_on_saturation && e.is_saturated) - e.is_active = false; - - if (e has more action left) { - a = e.get_next_action(); - perform a; - } else { - TryToDoDefault(m, args); - } - return; - } - } - - TryToDoDefault(m, args); -} -``` - -To find the default action for the given arguments, we look through all -`ON_CALL()` rules for the mock function, and pick the first one where all -argument matchers are satisfied, if any. - -Since C++ exceptions are disabled in `google3`, **we will abort the current -process when gMock raises an error**. We cannot just return from the current -function like what gUnit does, as the mock functions will be called from the -production code under test, and we don't have the luxury to change the -production code at each call site to propagate the error. This is unfortunate, -but I don't see a better solution without enabling exceptions. - -The real implementation will be more sophisticated in order to get a decent -performance (e.g. we'll memoize and use other tricks), but the end result must -match the above reference implementation. - -**Note:** If you carefully inspect the algorithm, you should convince yourself -that an expectation whose cardinality is `0` has no effect whatsoever, as it is -always satisfied and saturated. This means that you can write such an -expectation, but it won't affect your test in any way. Indeed, this is jMock's -behavior, and jMock's documentation suggests to use `Never()` (jMock's -equivalent of the `0` cardinality) for documentation purpose only. - -This bothers me as it contradicts with what one would naturally expect. When I -see - -```cpp - EXPECT_CALL(mock_foo, Bar(Eq(5))) - .Times(0); -``` - -I would think that it will be an error if `mock_foo.Bar(5)` is ever called, and -gMock will catch this error at run time. However, jMock tells me that it will -not try to enforce this, and I should treat the statement as if it doesn't -exist. - -I propose to give `Times(0)` a semantics that I think is more intuitive. Namely, -we should treat - -```cpp - EXPECT_CALL(mock-object, method(argument-matchers)) - .WithArguments(multi-argument-matcher) - .Times(0) - .InSequence(sequences); -``` - -as if it were - -```cpp - EXPECT_CALL(mock-object, method(argument-matchers)) - .WithArguments(multi-argument-matcher) - .Times(AnyNumber()) - .InSequence(sequences) - .WillOnce(Fail("Unexpected call.")); -``` - -I don't like making this a special case, but the other choice seems worse. - -**Note:** If a call doesn't match any explicitly written `EXPECT_CALL()` -statement, gMock will perform the default action (as long as it exists) instead -of raising an "unexpected call" error. If you want to assert that a function -should never be called, you must explicitly write an `EXPECT_CALL()` with a `0` -cardinality. This design is picked to allow modular tests: - -An interface may contain many methods. Typically, each test will be interested -in only a small number of them, as we favor small and focused tests. Such a test -shouldn't start to fail when the code under test is modified to call functions -not interesting to the test. If no `EXPECT_CALL()` were to mean "no call is -allowed", we would have to say - -```cpp - EXPECT_CALL(mock_foo, UninterestingMethod(Anything())) - .Times(AnyNumber()); -``` - -for **every** method we do **not** care about. It can be very tedious. Worse, -when we add methods to the interface or remove methods from it, we have to -update every existing test. Clearly this isn't modular and won't scale. - -#### Examples - -If you are not interested in whether a function will be called or not, you just -don't say anything about it. If the function is called, its default action will -be performed. - -If you want to make sure that a function is never called, say it explicitly: - -```cpp - EXPECT_CALL(mock_foo, Bar).Times(0); - // or: - EXPECT_CALL(mock_foo, Bar(Anything())).Times(0); -``` - -If you expect certain calls to a function and want to ignore the rest, just -specify the calls you are explicitly expecting: - -```cpp - EXPECT_CALL(mock_foo, Bar(Eq(1))) - .WillOnce(Return(2)); - EXPECT_CALL(mock_foo, Bar(Eq(2))) - .Times(AtMost(5)) - .WillRepeatedly(Return(3)); -``` - -If you expect certain calls to a function and don't want to allow any other -calls to it, just add a `Times(0)` expectation **after** the normal -expectations: - -```cpp - EXPECT_CALL(mock_foo, Bar(Eq(1))) - .WillOnce(Return(2)); - EXPECT_CALL(mock_foo, Bar(Eq(2))) - .Times(AtMost(5)) - .WillRepeatedly(Return(3)); - - // Any call to mock_foo.Bar() that doesn't match the above rules - // will be an error. - EXPECT_CALL(mock_foo, Bar(Anything())) - .Times(0); -``` - -Here's one complete example: - -```cpp - ON_CALL(mock_foo, Bar(Anything())) - .WillByDefault(Return(1)); - - Sequence x; - - EXPECT_CALL(mock_foo, Bar(Ne('a'))) // Expectation #1 - .InSequence(x) - .WillOnce(Return(2)) - .WillRepeatedly(Return(3)); - - EXPECT_CALL(mock_foo, Bar(Anything())) // Expectation #2 - .Times(AnyNumber()) - .InSequence(x); - - mock_foo.Bar('b'); // Matches expectation #1; returns 2. - mock_foo.Bar('c'); // Matches expectation #1; returns 3. - mock_foo.Bar('b'); // Matches expectation #1; returns 3. - mock_foo.Bar('a'); // Matches expectation #2; returns 1. - - // Now that expectation #2 has been used, expectation #1 becomes - // inactive (remember that the order is sacred), even though it's not - // yet saturated. - - mock_foo.Bar('b'); // Matches expectation #2, returns 1. -``` - -Another one: - -```cpp - Sequence a, b; - - EXPECT_CALL(mock_foo, Func1(Void())) // #1 - .Times(1) - .InSequence(a); - - EXPECT_CALL(mock_bar, Func2(Anything()) // #2 - .Times(AtLeast(1)) - .InSequence( b); - - EXPECT_CALL(mock_foo, Func3(Eq(0))) // #3 - .Times(AtMost(2)) - .InSequence(a, b); - - EXPECT_CALL(mock_foo, Func3(Anything())) // #4 - .InSequence(a); - - // The order constraints can be illustrated as - // - // #1 < #3 < #4 - // #2 < #3 - - mock_foo.Func1(); // Matches #1 - // Now #1 is saturated but not retired. - // If Func1() is called again here, it will be an upper-bound error. - - // It would be an error to call mock_foo.Func3(0) here, as #2 is its - // pre-requisite and hasn't been satisfied. - - mock_bar.Func2(1); // Matches #2, which is now satisfied. - - mock_foo.Func3(1); - // Matches #4. This causes all of #4's remaining pre-requisites (#2 - // and #3) to become inactive. Note that #3 is trivially satisfied - // as that AtMost(2) doesn't require it to match any invocation. -``` - -Yet another one: - -```cpp -EXPECT_CALL(mock_foo, Func(Eq(1))) // #1 - .WillOnce(Return(2)) - .RetiresOnSaturation(); - -EXPECT_CALL(mock_foo, Func(Anything())) // #2 - .WillOnce(Return(3)); - -mock_foo.Func(1); // Matches #1. -// Now #1 is satisfied, saturated, and retired. - -mock_foo.Func(1); // Matches #2. -// Since #1 is retired now, it doesn't participate in matching function -// calls. Otherwise this would cause an upper-bound-exceeded failure. -``` - -### Verifying that All Expectations Are Satisfied - -During a test, gMock will verify that each invocation to a mock function matches -one of the expectation rules. However, at the end of a test, we will want to -verify that *all expectations for the mock function have been satisfied*. This -is done by the destructor of the `FunctionMocker<...>` class: - -### Life of a Mock - -Now let's put the pieces together and see the complete process of using mock -objects in a test. Typically, the user should do it in the following order: - -* **C:** *Constructs* the mock objects; -* **B:** Set their default **behaviors** using `ON_CALL()`; -* **E:** Set **expectations** on them using `EXPECT_CALL()`; -* **I:** Exercise the production code, which will **invoke** methods of the - mock objects; -* **D:** *Destructs* the mock objects, which will cause gMock to verify that - all expectations are satisfied. - -Usually, the user can do step 1 and 2 during the set-up phase of the test, step -3 and 4 in the test function body, and step 5 in the tear-down phase. - -If the user performs a step out of sequence (e.g. an `EXPECT_CALL()` is -encountered after the mock function is already been called by the test and -before `Verify()` is called), the behavior is **undefined**. gMock will try to -print a friendly error message, but doesn't guarantee to catch all possible -violations, and the initial version may not implement this error check at all. - -Valid sequences of using a mock object can be described using the regular -expression - -```none -CB*E*I*D -``` - -### Typing of Argument Matchers - -Argument matchers in gMock are statically typed. If we don't provide automatic -conversion between matchers of "compatible" types, the user experience will be -rather unpleasant. Covariance and contravariance are two common schemes for -imposing a sub-typing relation between types. Our observation is that neither -works for matchers in general, and gMock must leave the decision to individual -matcher authors. - -#### Background: How Argument Matchers Work - -In gMock, argument matchers are used to determine if the actual arguments in a -function invocation match the test writer's expectation. Conceptually, a matcher -for arguments of type `T` implements the following interface: - -```cpp -class Matcher { - virtual bool Matches(T x) = 0; -}; -``` - -For a method with argument type `T`: - -```cpp -virtual void Func(T x); -``` - -its mock will be declared as something like (the actual declaration will be more -complicated but the idea remains the same): - -```cpp -void Func(Matcher* x); -``` - -When the mock `Func()` is invoked with an argument value `v`, which has type -`T`, `Matches(v)` will be called to determine if it's a match. - -#### Need for Sub-typing - -A straightforward way to mock a method with parameter types `T1`, `T2`, ..., and -`Tn` is to use a list of matchers of type `Matcher`, `Matcher`, ..., and -`Matcher`. However, this simplistic approach has a usability problem. -Suppose we have a series of functions and their mocks: - -```cpp -void Func1(char a); -void Func1(Matcher* a); - -void Func2(const char a); -void Func2(Matcher* a); - -void Func3(char& a); -void Func3(Matcher* a); - -void Func4(const char& a); -void Func4(Matcher* a); - -void Func5(char* a); -void Func5(Matcher* a); - -void Func6(const char* a); -void Func6(Matcher* a); -``` - -(note that `Func2()` has a `const` parameter. Since argument matchers are not -allowed to modify the arguments in any case, technically we could use a -`Matcher` in the mock of `Func2()`. However, we want to make sure that a -user can define the mock using a `Matcher` too, as this makes the -task of the mock class generator easier.) and some simple, pre-defined matcher -factories: - -```cpp -// Matches if the argument equals the given value x. -Matcher* Eq(T x); - -// Matches if the argument has the same identify as the -// given object x. -Matcher* Same(T& x); -``` - -then a user might be surprised when trying to use these mocks: - -```cpp - Func1('a'); // Invokes the real method. This works fine. - Func1(Eq('a')); // Invokes the mock method. This works fine too. - - Func2('a'); // Invokes the real method. This works fine. - Func2(Eq('a')); // Compiler ERROR - surprise!!! Why can't I say that - // the argument, which is a const char, should be equal - // to 'a'? - - char a = 'a'; - Func3(a); // Invokes the real method. This works fine. - Func3(Same(a)); // Fine. The argument should reference the variable a. - Func3(Eq('a')); // Compiler ERROR - surprise!!! Why can't I say that - // the argument, which is a char&, should have a value - // 'a', which is a char? - - const char b = 'b'; - Func4(b); // Fine. - Func4(Same(b)); // Fine. The argument should reference the variable b. - Func4(Eq(b)); // Compiler ERROR - surprise!!! Why can't I say that - // the argument, which is a const char&, should have - // a value equal to b, which is a const char? - Func4(Same(a)); // Compiler ERROR - surprise!!! Why can't I say that - // the argument, which is a const char&, should reference - // a, which is a char? - - char* p = NULL; - Func5(p); // Fine. - Func5(Eq(p)); // Fine. - - Func6("a"); // Fine. - Func6(Eq("a")); // Fine. - Func6(Eq(p)); // Compiler ERROR - surprise!!! Why can't I say that - // the argument, which is a const char*, should point - // to where p, which is a char*, points to? -``` - -(In Java, this issue isn't nearly as severe, as Java has neither reference nor -`const`. Lucky them.) - -The compiler errors can be worked around using explicit template instantiating -in most cases, but require more dirty hacks in some others: - -```cpp - // The following works: - Func2(Eq('a')); - Func4(Eq(b)); - Func4(Same(a)); - Func6(Eq(p)); - - // but this doesn't: - Func3(Eq('a')); // Compiler ERROR! - - // You have to use a temporary variable, and pray that it's not - // accidentally changed before the actual invocation occurs. - // No, you cannot make the temporary variable const - that won't - // compile. - char temp = 'a'; - Func3(Eq(temp)); -``` - -Having to use these tricks all the time is a big bummer and makes the tests -harder to read. The author of Mockpp either chose to ignore this problem, or -wasn't aware of it, but I don't think that's a good solution. - -To give the user a satisfying experience, I believe we should provide automatic -conversions between matchers of "compatible" types when it makes sense (i.e. we -should establish a sub-typing relation between matcher types). The challenges -are: - -1. Deciding when "it makes sense", -1. Making sure the conversions are neither too restricted nor too liberal, -1. Making it possible for the user to understand the compiler errors when - automatic conversions cannot be done, -1. Making the rules easy to learn and remember, and -1. Implementing it. - -#### Covariant or Contravariant? - -We already know that making the matchers **invariant** (i.e. no auto-conversion -between matcher types) doesn't work, but what about **covariant** (`Matcher` -can be used as `Matcher` as long as `A` can be used as `B`) or -**contravariant** (`Matcher` can be used as `Matcher` as long as `B` can -be used as `A`)? Would one of them work? - -It's easy to see that covariance doesn't work in general, as it requires a -matcher expecting a sub-type value to inspect a super-type value. What if the -matcher needs to look at a field that's only present in the sub-type? - -On the surface level, it seems that contravariance is what we need: if type `B` -can be implicitly converted to type `A`, then given an argument of type `B`, we -can convert it to type `A` and then ask a `Matcher` whether the converted -value matches. This means that we can use a `Matcher` in place of a -`Matcher`. - -For example, given a class hierarchy and some (real and mock) functions that use -the classes: - -```cpp -class Father { ... }; - -class Son : public Father { - public: - ... - // New method not present in Father: - virtual bool PropertyFoo() const; -}; - -class Grandson : public Son { ... }; - -void InviteFather(Father* obj); -void InviteFather(Matcher* m); - -void InviteGrandson(Grandson* obj); -void InviteGrandson(Matcher* m); -``` - -we can expect to write the following: - -```cpp -// Matches if the argument's PropertyFoo() method returns true. -Matcher* HasFoo() { ... } - -// The compiler should reject this as a Father object doesn't have -// the PropertyFoo() method: -// -// InviteFather(HasFoo()); - -// This should work, as a Grandson object is also a Son object and -// has the PropertyFoo() method. -InviteGrandson(HasFoo()); -``` - -In the latter case, the actual argument (of type `Grandson*`) will be implicitly -converted to a `Son*` and then passed to the matcher. - -However, things are not always so simple. Take the example of the equality -matcher, `Func5()`, and `Func6()` we saw earlier: - -```cpp -// Matches if the argument equals the given value x. -Matcher* Eq(T x); - -void Func5(char* a); -void Func5(Matcher* a); - -void Func6(const char* a); -void Func6(Matcher* a); -``` - -By making matchers contravariant, we have - -```cpp - // Remember that a char* can be implicitly converted to a const char*. - - Func5(Eq("a")); // Compiles, but we DON'T want it to!!! The user is - // trying to say that the actual argument (a char*) - // can be "a", and we should catch this error. - - char* p = ...; - Func6(Eq(p)); // Still a compiler ERROR, as a const char* cannot be - // implicitly converted to a char*, which Eq(p) expects. -``` - -Clearly this isn't what we want. In fact, we want `Eq(value)` to be covariant: - -```cpp - char* p = ...; - - Func5(p); - Func5(Eq(p)); - // Func5("a"); // The compiler will reject this, - // Func5(Eq("a")); // and thus should reject this too. - - Func6("a"); - Func6(Eq("a")); - Func6(p); // The compiler accepts this, - Func6(Eq(p)); // and thus should accept this too. -``` - -In another example: - -```cpp -void InviteSon(Son* obj); -void InviteSon(Matcher m); - -Father* father = ...; -Grandson* grandson = ...; - -InviteSon(grandson); // The compiler accepts this, -InviteSon(Eq(grandson)); // and thus should accept this too. - -// InviteSon(father); // The compiler will reject this, -// InviteSon(Eq(father)); // and thus should reject this too. -``` - -So, what was the problem? The key insight here is that *one size doesn't fit -all*. While some matchers should be contravariant (like `HasFoo()`), some should -be covariant (like `Eq(value)` and `Same(object)`). *The decision has to be left -to the individual matcher authors. gMock should not impose a global policy on -all the matchers.* - -#### Implementing Automatic Type Conversion - -In C++, you have several options if you want to make one class `A` act like -another class `B`: - -1. Derive `A` from `B`; -1. In class `B`, define a public single-parameter constructor `B::B(const A&)` - (don't make it `explicit`); -1. In class `A`, define a type-conversion operator for type `B`. - -Each of these approaches has its limitations: - -* #1 is most straightforward and requires the least amount of work. However, - it means that an `A` object will contain all the members of `B`. It may not - work for you if you want to be able to auto-convert `A` to multiple classes, - and it certainly won't work if you want to convert `A` to an infinite number - of other classes. -* #2 requires you to be able to edit the implementation of `B`. This is not - always possible, for example, when `B` is a class defined in a standard - library and you are a user of that library. It's a closed approach, meaning - that only the owner of `B` can decide which classes can be converted to `B`. -* #3 requires more work to implement typically, but doesn't have the problems - of #1 and #2. In particular, you can define a template type-conversion - operator to convert `A` to an infinite number of other classes of your - choice. - -Also, remember that the compiler will only automatically insert one level of -type conversion on your behalf. For example, if `A` can be implicitly converted -to `B`, which can be implicitly converted to `C`, and you have a function -expecting a `C`, you cannot give the function an `A` without explicit casting, -unless `A` can be implicitly converted to `C` too. - -gMock defines the `Matcher` interface, which a user cannot modify. When -defining a polymorphic matcher (e.g. `Eq(value)`), a user needs to make it -behave like a (potentially infinite) number of matchers of different types. This -means that the last implementation technique should be used. - -### Comparison with Mockpp and jMock - -See GMockVsMockppAndJMock. - -## Project - -This design doc describes the project "[gMock](http://p?p=6164) - a framework -for writing C++ mock classes" in PDB. - -## Code Location - -This is a new project, so no existing file is expected to be touched. The -implementation is added in directory `//depot/google3/testing/base`. - -## Group Members - -ZhanyongWan : spending 60% of his time on this. - -## Caveats - -We considered existing solutions, but don't think they would work well enough -for Google. For details, please refer to MockppStudy. - -TODO: - -* Explain why we pick the EDSL-style syntax. - -## Documentation Plan - -In additional to this design doc, a user's guide, an FAQ, and a codelab will -also be written. - -## Testing Plan - -gMock will be thoroughly tested on Linux using gUnit. - -## Work Estimates - -* **Inspecting existing solutions:** The goal is to understand how other - people have approached this problem, what they did well, and what did - poorly. In addition to studying solutions for C++ (mockpp), we will also - study solutions for Java (jMock and EasyMock). **3 weeks.** -* **Initial design and prototyping:** Come up with a design tailored to C++'s - specifics and Google's unique requirements, taking into account lessons - learned from other solutions. **3 weeks.** -* **Soliciting feedback on the design:** Listen to `testing-technology`, - `testing-grouplet`, `c-users`, `c-mock-dev`, and `gunit-users`; revise the - design based on the feedback. **3 weeks.** -* **Initial implementation:** **6 weeks.** -* **Documentation:** Write the user's guide and a codelab. **3 weeks.** -* **Company-wide roll-out:** Implement a process for promoting and tracking - adoption. **1 week.** -* **Customer support, incremental improvements, and maintenance:** **On-going - effort.** - -## Potential Patents - -We'll know whether there will be patentable inventions when we have a more -concrete design and prototype. At that time, we should talk to Google's -[patent counsel](mailto:patents@google.com). - -## Things that Don't Apply - -### Security Considerations - -This is an internal library for writing (unit) tests, and will not be used in -production. Therefore there is no security concern. - -### Privacy Considerations - -gMock will not touch any user data. Therefore there is no concern about user -privacy. - -### Standards - -There is no existing standard in creating C++ mocks. - -### Logging Plan - -This is an internal library and will not handle any user request. Therefore -there is no plan for logging. - -### Monitoring Plan - -This is an internal library and will not run on our production servers. -Therefore no monitoring is required. - -### Internationalization Plan - -gMock is not visible to external users, so there is no plan to internationalize -it. - -### Billing Plan and Tax Plan - -gMock is an internal library and doesn't involve money, so there is no billing -plan or tax plan. - -### Launch Plans - -gMock will not launch externally as a Google property. However, we may later -decide to open source it. - -## References - -* [jMock 1 cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/JMockOneCheatSheet) - - I compiled this from the downloaded jMock 1 source code. -* [jMock 1 JavaDoc](http://www.corp.google.com/~wan/jmock1/javadoc/) - I built - this locally. The one on http://jmock.org can be slow and may change. -* [jMock 2 cheat sheet](http://www.jmock.org/cheat-sheet.html) - as found on - http://jmock.org. -* [jMock 2 cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/JMockTwoCheatSheet) - - I compiled this from the jMock 2 source code in CVS as of 3/21. -* [jMock 2 JavaDoc](http://www.corp.google.com/~wan/jmock2/javadoc) - I - generated this locally from the jMock 2 source code in CVS as of 3/21. No - official jMock 2 JavaDoc is available yet, as the library hasn't been - released. -* [mockpp cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/MockppCheatSheet) - - I compiled this from the mockpp source code. -* [mockpp API docs](http://mockpp.sourceforge.net/api-doc/index.html) - - external. - -## Acknowledgments - -This design doc contains many ideas from PiotrKaminski. We'd also like to thank -the following people for contributing ideas to this project: - -JoeWalnes, CraigSilverstein, JeffreyYasskin, KeithRay, MikeBland. diff --git a/googlemock/docs/for_dummies.md b/googlemock/docs/for_dummies.md deleted file mode 100644 index 8ba164f..0000000 --- a/googlemock/docs/for_dummies.md +++ /dev/null @@ -1,702 +0,0 @@ -# gMock for Dummies {#GMockForDummies} - - - - - -## What Is gMock? - -When you write a prototype or test, often it's not feasible or wise to rely on -real objects entirely. A **mock object** implements the same interface as a real -object (so it can be used as one), but lets you specify at run time how it will -be used and what it should do (which methods will be called? in which order? how -many times? with what arguments? what will they return? etc). - -**Note:** It is easy to confuse the term *fake objects* with mock objects. Fakes -and mocks actually mean very different things in the Test-Driven Development -(TDD) community: - -* **Fake** objects have working implementations, but usually take some - shortcut (perhaps to make the operations less expensive), which makes them - not suitable for production. An in-memory file system would be an example of - a fake. -* **Mocks** are objects pre-programmed with *expectations*, which form a - specification of the calls they are expected to receive. - -If all this seems too abstract for you, don't worry - the most important thing -to remember is that a mock allows you to check the *interaction* between itself -and code that uses it. The difference between fakes and mocks shall become much -clearer once you start to use mocks. - -**gMock** is a library (sometimes we also call it a "framework" to make it sound -cool) for creating mock classes and using them. It does to C++ what -jMock/EasyMock does to Java (well, more or less). - -When using gMock, - -1. first, you use some simple macros to describe the interface you want to - mock, and they will expand to the implementation of your mock class; -2. next, you create some mock objects and specify its expectations and behavior - using an intuitive syntax; -3. then you exercise code that uses the mock objects. gMock will catch any - violation to the expectations as soon as it arises. - -## Why gMock? - -While mock objects help you remove unnecessary dependencies in tests and make -them fast and reliable, using mocks manually in C++ is *hard*: - -* Someone has to implement the mocks. The job is usually tedious and - error-prone. No wonder people go great distance to avoid it. -* The quality of those manually written mocks is a bit, uh, unpredictable. You - may see some really polished ones, but you may also see some that were - hacked up in a hurry and have all sorts of ad hoc restrictions. -* The knowledge you gained from using one mock doesn't transfer to the next - one. - -In contrast, Java and Python programmers have some fine mock frameworks (jMock, -EasyMock, [Mox](http://wtf/mox), etc), which automate the creation of mocks. As -a result, mocking is a proven effective technique and widely adopted practice in -those communities. Having the right tool absolutely makes the difference. - -gMock was built to help C++ programmers. It was inspired by jMock and EasyMock, -but designed with C++'s specifics in mind. It is your friend if any of the -following problems is bothering you: - -* You are stuck with a sub-optimal design and wish you had done more - prototyping before it was too late, but prototyping in C++ is by no means - "rapid". -* Your tests are slow as they depend on too many libraries or use expensive - resources (e.g. a database). -* Your tests are brittle as some resources they use are unreliable (e.g. the - network). -* You want to test how your code handles a failure (e.g. a file checksum - error), but it's not easy to cause one. -* You need to make sure that your module interacts with other modules in the - right way, but it's hard to observe the interaction; therefore you resort to - observing the side effects at the end of the action, but it's awkward at - best. -* You want to "mock out" your dependencies, except that they don't have mock - implementations yet; and, frankly, you aren't thrilled by some of those - hand-written mocks. - -We encourage you to use gMock as - -* a *design* tool, for it lets you experiment with your interface design early - and often. More iterations lead to better designs! -* a *testing* tool to cut your tests' outbound dependencies and probe the - interaction between your module and its collaborators. - -## Getting Started - -gMock is bundled with googletest. - -## A Case for Mock Turtles - -Let's look at an example. Suppose you are developing a graphics program that -relies on a [LOGO](http://en.wikipedia.org/wiki/Logo_programming_language)-like -API for drawing. How would you test that it does the right thing? Well, you can -run it and compare the screen with a golden screen snapshot, but let's admit it: -tests like this are expensive to run and fragile (What if you just upgraded to a -shiny new graphics card that has better anti-aliasing? Suddenly you have to -update all your golden images.). It would be too painful if all your tests are -like this. Fortunately, you learned about -[Dependency Injection](http://en.wikipedia.org/wiki/Dependency_injection) and know the right thing -to do: instead of having your application talk to the system API directly, wrap -the API in an interface (say, `Turtle`) and code to that interface: - -```cpp -class Turtle { - ... - virtual ~Turtle() {} - virtual void PenUp() = 0; - virtual void PenDown() = 0; - virtual void Forward(int distance) = 0; - virtual void Turn(int degrees) = 0; - virtual void GoTo(int x, int y) = 0; - virtual int GetX() const = 0; - virtual int GetY() const = 0; -}; -``` - -(Note that the destructor of `Turtle` **must** be virtual, as is the case for -**all** classes you intend to inherit from - otherwise the destructor of the -derived class will not be called when you delete an object through a base -pointer, and you'll get corrupted program states like memory leaks.) - -You can control whether the turtle's movement will leave a trace using `PenUp()` -and `PenDown()`, and control its movement using `Forward()`, `Turn()`, and -`GoTo()`. Finally, `GetX()` and `GetY()` tell you the current position of the -turtle. - -Your program will normally use a real implementation of this interface. In -tests, you can use a mock implementation instead. This allows you to easily -check what drawing primitives your program is calling, with what arguments, and -in which order. Tests written this way are much more robust (they won't break -because your new machine does anti-aliasing differently), easier to read and -maintain (the intent of a test is expressed in the code, not in some binary -images), and run *much, much faster*. - -## Writing the Mock Class - -If you are lucky, the mocks you need to use have already been implemented by -some nice people. If, however, you find yourself in the position to write a mock -class, relax - gMock turns this task into a fun game! (Well, almost.) - -### How to Define It - -Using the `Turtle` interface as example, here are the simple steps you need to -follow: - -* Derive a class `MockTurtle` from `Turtle`. -* Take a *virtual* function of `Turtle` (while it's possible to - [mock non-virtual methods using templates](cook_book.md#MockingNonVirtualMethods), - it's much more involved). -* In the `public:` section of the child class, write `MOCK_METHOD();` -* Now comes the fun part: you take the function signature, cut-and-paste it - into the macro, and add two commas - one between the return type and the - name, another between the name and the argument list. -* If you're mocking a const method, add a 4th parameter containing `(const)` - (the parentheses are required). -* Since you're overriding a virtual method, we suggest adding the `override` - keyword. For const methods the 4th parameter becomes `(const, override)`, - for non-const methods just `(override)`. This isn't mandatory. -* Repeat until all virtual functions you want to mock are done. (It goes - without saying that *all* pure virtual methods in your abstract class must - be either mocked or overridden.) - -After the process, you should have something like: - -```cpp -#include "gmock/gmock.h" // Brings in gMock. - -class MockTurtle : public Turtle { - public: - ... - MOCK_METHOD(void, PenUp, (), (override)); - MOCK_METHOD(void, PenDown, (), (override)); - MOCK_METHOD(void, Forward, (int distance), (override)); - MOCK_METHOD(void, Turn, (int degrees), (override)); - MOCK_METHOD(void, GoTo, (int x, int y), (override)); - MOCK_METHOD(int, GetX, (), (const, override)); - MOCK_METHOD(int, GetY, (), (const, override)); -}; -``` - -You don't need to define these mock methods somewhere else - the `MOCK_METHOD` -macro will generate the definitions for you. It's that simple! - -### Where to Put It - -When you define a mock class, you need to decide where to put its definition. -Some people put it in a `_test.cc`. This is fine when the interface being mocked -(say, `Foo`) is owned by the same person or team. Otherwise, when the owner of -`Foo` changes it, your test could break. (You can't really expect `Foo`'s -maintainer to fix every test that uses `Foo`, can you?) - -So, the rule of thumb is: if you need to mock `Foo` and it's owned by others, -define the mock class in `Foo`'s package (better, in a `testing` sub-package -such that you can clearly separate production code and testing utilities), put -it in a `.h` and a `cc_library`. Then everyone can reference them from their -tests. If `Foo` ever changes, there is only one copy of `MockFoo` to change, and -only tests that depend on the changed methods need to be fixed. - -Another way to do it: you can introduce a thin layer `FooAdaptor` on top of -`Foo` and code to this new interface. Since you own `FooAdaptor`, you can absorb -changes in `Foo` much more easily. While this is more work initially, carefully -choosing the adaptor interface can make your code easier to write and more -readable (a net win in the long run), as you can choose `FooAdaptor` to fit your -specific domain much better than `Foo` does. - - - -## Using Mocks in Tests - -Once you have a mock class, using it is easy. The typical work flow is: - -1. Import the gMock names from the `testing` namespace such that you can use - them unqualified (You only have to do it once per file). Remember that - namespaces are a good idea. -2. Create some mock objects. -3. Specify your expectations on them (How many times will a method be called? - With what arguments? What should it do? etc.). -4. Exercise some code that uses the mocks; optionally, check the result using - googletest assertions. If a mock method is called more than expected or with - wrong arguments, you'll get an error immediately. -5. When a mock is destructed, gMock will automatically check whether all - expectations on it have been satisfied. - -Here's an example: - -```cpp -#include "path/to/mock-turtle.h" -#include "gmock/gmock.h" -#include "gtest/gtest.h" - -using ::testing::AtLeast; // #1 - -TEST(PainterTest, CanDrawSomething) { - MockTurtle turtle; // #2 - EXPECT_CALL(turtle, PenDown()) // #3 - .Times(AtLeast(1)); - - Painter painter(&turtle); // #4 - - EXPECT_TRUE(painter.DrawCircle(0, 0, 10)); // #5 -} -``` - -As you might have guessed, this test checks that `PenDown()` is called at least -once. If the `painter` object didn't call this method, your test will fail with -a message like this: - -```text -path/to/my_test.cc:119: Failure -Actual function call count doesn't match this expectation: -Actually: never called; -Expected: called at least once. -Stack trace: -... -``` - -**Tip 1:** If you run the test from an Emacs buffer, you can hit `` on -the line number to jump right to the failed expectation. - -**Tip 2:** If your mock objects are never deleted, the final verification won't -happen. Therefore it's a good idea to turn on the heap checker in your tests -when you allocate mocks on the heap. You get that automatically if you use the -`gtest_main` library already. - -**Important note:** gMock requires expectations to be set **before** the mock -functions are called, otherwise the behavior is **undefined**. In particular, -you mustn't interleave `EXPECT_CALL()s` and calls to the mock functions. - -This means `EXPECT_CALL()` should be read as expecting that a call will occur -*in the future*, not that a call has occurred. Why does gMock work like that? -Well, specifying the expectation beforehand allows gMock to report a violation -as soon as it rises, when the context (stack trace, etc) is still available. -This makes debugging much easier. - -Admittedly, this test is contrived and doesn't do much. You can easily achieve -the same effect without using gMock. However, as we shall reveal soon, gMock -allows you to do *so much more* with the mocks. - -## Setting Expectations - -The key to using a mock object successfully is to set the *right expectations* -on it. If you set the expectations too strict, your test will fail as the result -of unrelated changes. If you set them too loose, bugs can slip through. You want -to do it just right such that your test can catch exactly the kind of bugs you -intend it to catch. gMock provides the necessary means for you to do it "just -right." - -### General Syntax - -In gMock we use the `EXPECT_CALL()` macro to set an expectation on a mock -method. The general syntax is: - -```cpp -EXPECT_CALL(mock_object, method(matchers)) - .Times(cardinality) - .WillOnce(action) - .WillRepeatedly(action); -``` - -The macro has two arguments: first the mock object, and then the method and its -arguments. Note that the two are separated by a comma (`,`), not a period (`.`). -(Why using a comma? The answer is that it was necessary for technical reasons.) -If the method is not overloaded, the macro can also be called without matchers: - -```cpp -EXPECT_CALL(mock_object, non-overloaded-method) - .Times(cardinality) - .WillOnce(action) - .WillRepeatedly(action); -``` - -This syntax allows the test writer to specify "called with any arguments" -without explicitly specifying the number or types of arguments. To avoid -unintended ambiguity, this syntax may only be used for methods which are not -overloaded - -Either form of the macro can be followed by some optional *clauses* that provide -more information about the expectation. We'll discuss how each clause works in -the coming sections. - -This syntax is designed to make an expectation read like English. For example, -you can probably guess that - -```cpp -using ::testing::Return; -... -EXPECT_CALL(turtle, GetX()) - .Times(5) - .WillOnce(Return(100)) - .WillOnce(Return(150)) - .WillRepeatedly(Return(200)); -``` - -says that the `turtle` object's `GetX()` method will be called five times, it -will return 100 the first time, 150 the second time, and then 200 every time. -Some people like to call this style of syntax a Domain-Specific Language (DSL). - -**Note:** Why do we use a macro to do this? Well it serves two purposes: first -it makes expectations easily identifiable (either by `gsearch` or by a human -reader), and second it allows gMock to include the source file location of a -failed expectation in messages, making debugging easier. - -### Matchers: What Arguments Do We Expect? - -When a mock function takes arguments, we may specify what arguments we are -expecting, for example: - -```cpp -// Expects the turtle to move forward by 100 units. -EXPECT_CALL(turtle, Forward(100)); -``` - -Oftentimes you do not want to be too specific. Remember that talk about tests -being too rigid? Over specification leads to brittle tests and obscures the -intent of tests. Therefore we encourage you to specify only what's necessary—no -more, no less. If you aren't interested in the value of an argument, write `_` -as the argument, which means "anything goes": - -```cpp -using ::testing::_; -... -// Expects that the turtle jumps to somewhere on the x=50 line. -EXPECT_CALL(turtle, GoTo(50, _)); -``` - -`_` is an instance of what we call **matchers**. A matcher is like a predicate -and can test whether an argument is what we'd expect. You can use a matcher -inside `EXPECT_CALL()` wherever a function argument is expected. `_` is a -convenient way of saying "any value". - -In the above examples, `100` and `50` are also matchers; implicitly, they are -the same as `Eq(100)` and `Eq(50)`, which specify that the argument must be -equal (using `operator==`) to the matcher argument. There are many -[built-in matchers](cheat_sheet.md#MatcherList) for common types (as well as -[custom matchers](cook_book.md#NewMatchers)); for example: - -```cpp -using ::testing::Ge; -... -// Expects the turtle moves forward by at least 100. -EXPECT_CALL(turtle, Forward(Ge(100))); -``` - -If you don't care about *any* arguments, rather than specify `_` for each of -them you may instead omit the parameter list: - -```cpp -// Expects the turtle to move forward. -EXPECT_CALL(turtle, Forward); -// Expects the turtle to jump somewhere. -EXPECT_CALL(turtle, GoTo); -``` - -This works for all non-overloaded methods; if a method is overloaded, you need -to help gMock resolve which overload is expected by specifying the number of -arguments and possibly also the -[types of the arguments](cook_book.md#SelectOverload). - -### Cardinalities: How Many Times Will It Be Called? - -The first clause we can specify following an `EXPECT_CALL()` is `Times()`. We -call its argument a **cardinality** as it tells *how many times* the call should -occur. It allows us to repeat an expectation many times without actually writing -it as many times. More importantly, a cardinality can be "fuzzy", just like a -matcher can be. This allows a user to express the intent of a test exactly. - -An interesting special case is when we say `Times(0)`. You may have guessed - it -means that the function shouldn't be called with the given arguments at all, and -gMock will report a googletest failure whenever the function is (wrongfully) -called. - -We've seen `AtLeast(n)` as an example of fuzzy cardinalities earlier. For the -list of built-in cardinalities you can use, see -[here](cheat_sheet.md#CardinalityList). - -The `Times()` clause can be omitted. **If you omit `Times()`, gMock will infer -the cardinality for you.** The rules are easy to remember: - -* If **neither** `WillOnce()` **nor** `WillRepeatedly()` is in the - `EXPECT_CALL()`, the inferred cardinality is `Times(1)`. -* If there are *n* `WillOnce()`'s but **no** `WillRepeatedly()`, where *n* >= - 1, the cardinality is `Times(n)`. -* If there are *n* `WillOnce()`'s and **one** `WillRepeatedly()`, where *n* >= - 0, the cardinality is `Times(AtLeast(n))`. - -**Quick quiz:** what do you think will happen if a function is expected to be -called twice but actually called four times? - -### Actions: What Should It Do? - -Remember that a mock object doesn't really have a working implementation? We as -users have to tell it what to do when a method is invoked. This is easy in -gMock. - -First, if the return type of a mock function is a built-in type or a pointer, -the function has a **default action** (a `void` function will just return, a -`bool` function will return `false`, and other functions will return 0). In -addition, in C++ 11 and above, a mock function whose return type is -default-constructible (i.e. has a default constructor) has a default action of -returning a default-constructed value. If you don't say anything, this behavior -will be used. - -Second, if a mock function doesn't have a default action, or the default action -doesn't suit you, you can specify the action to be taken each time the -expectation matches using a series of `WillOnce()` clauses followed by an -optional `WillRepeatedly()`. For example, - -```cpp -using ::testing::Return; -... -EXPECT_CALL(turtle, GetX()) - .WillOnce(Return(100)) - .WillOnce(Return(200)) - .WillOnce(Return(300)); -``` - -says that `turtle.GetX()` will be called *exactly three times* (gMock inferred -this from how many `WillOnce()` clauses we've written, since we didn't -explicitly write `Times()`), and will return 100, 200, and 300 respectively. - -```cpp -using ::testing::Return; -... -EXPECT_CALL(turtle, GetY()) - .WillOnce(Return(100)) - .WillOnce(Return(200)) - .WillRepeatedly(Return(300)); -``` - -says that `turtle.GetY()` will be called *at least twice* (gMock knows this as -we've written two `WillOnce()` clauses and a `WillRepeatedly()` while having no -explicit `Times()`), will return 100 and 200 respectively the first two times, -and 300 from the third time on. - -Of course, if you explicitly write a `Times()`, gMock will not try to infer the -cardinality itself. What if the number you specified is larger than there are -`WillOnce()` clauses? Well, after all `WillOnce()`s are used up, gMock will do -the *default* action for the function every time (unless, of course, you have a -`WillRepeatedly()`.). - -What can we do inside `WillOnce()` besides `Return()`? You can return a -reference using `ReturnRef(*variable*)`, or invoke a pre-defined function, among -[others](cook_book.md#using-actions). - -**Important note:** The `EXPECT_CALL()` statement evaluates the action clause -only once, even though the action may be performed many times. Therefore you -must be careful about side effects. The following may not do what you want: - -```cpp -using ::testing::Return; -... -int n = 100; -EXPECT_CALL(turtle, GetX()) - .Times(4) - .WillRepeatedly(Return(n++)); -``` - -Instead of returning 100, 101, 102, ..., consecutively, this mock function will -always return 100 as `n++` is only evaluated once. Similarly, `Return(new Foo)` -will create a new `Foo` object when the `EXPECT_CALL()` is executed, and will -return the same pointer every time. If you want the side effect to happen every -time, you need to define a custom action, which we'll teach in the -[cook book](http://). - -Time for another quiz! What do you think the following means? - -```cpp -using ::testing::Return; -... -EXPECT_CALL(turtle, GetY()) - .Times(4) - .WillOnce(Return(100)); -``` - -Obviously `turtle.GetY()` is expected to be called four times. But if you think -it will return 100 every time, think twice! Remember that one `WillOnce()` -clause will be consumed each time the function is invoked and the default action -will be taken afterwards. So the right answer is that `turtle.GetY()` will -return 100 the first time, but **return 0 from the second time on**, as -returning 0 is the default action for `int` functions. - -### Using Multiple Expectations {#MultiExpectations} - -So far we've only shown examples where you have a single expectation. More -realistically, you'll specify expectations on multiple mock methods which may be -from multiple mock objects. - -By default, when a mock method is invoked, gMock will search the expectations in -the **reverse order** they are defined, and stop when an active expectation that -matches the arguments is found (you can think of it as "newer rules override -older ones."). If the matching expectation cannot take any more calls, you will -get an upper-bound-violated failure. Here's an example: - -```cpp -using ::testing::_; -... -EXPECT_CALL(turtle, Forward(_)); // #1 -EXPECT_CALL(turtle, Forward(10)) // #2 - .Times(2); -``` - -If `Forward(10)` is called three times in a row, the third time it will be an -error, as the last matching expectation (#2) has been saturated. If, however, -the third `Forward(10)` call is replaced by `Forward(20)`, then it would be OK, -as now #1 will be the matching expectation. - -**Note:** Why does gMock search for a match in the *reverse* order of the -expectations? The reason is that this allows a user to set up the default -expectations in a mock object's constructor or the test fixture's set-up phase -and then customize the mock by writing more specific expectations in the test -body. So, if you have two expectations on the same method, you want to put the -one with more specific matchers **after** the other, or the more specific rule -would be shadowed by the more general one that comes after it. - -**Tip:** It is very common to start with a catch-all expectation for a method -and `Times(AnyNumber())` (omitting arguments, or with `_` for all arguments, if -overloaded). This makes any calls to the method expected. This is not necessary -for methods that are not mentioned at all (these are "uninteresting"), but is -useful for methods that have some expectations, but for which other calls are -ok. See -[Understanding Uninteresting vs Unexpected Calls](cook_book.md#uninteresting-vs-unexpected). - -### Ordered vs Unordered Calls {#OrderedCalls} - -By default, an expectation can match a call even though an earlier expectation -hasn't been satisfied. In other words, the calls don't have to occur in the -order the expectations are specified. - -Sometimes, you may want all the expected calls to occur in a strict order. To -say this in gMock is easy: - -```cpp -using ::testing::InSequence; -... -TEST(FooTest, DrawsLineSegment) { - ... - { - InSequence seq; - - EXPECT_CALL(turtle, PenDown()); - EXPECT_CALL(turtle, Forward(100)); - EXPECT_CALL(turtle, PenUp()); - } - Foo(); -} -``` - -By creating an object of type `InSequence`, all expectations in its scope are -put into a *sequence* and have to occur *sequentially*. Since we are just -relying on the constructor and destructor of this object to do the actual work, -its name is really irrelevant. - -In this example, we test that `Foo()` calls the three expected functions in the -order as written. If a call is made out-of-order, it will be an error. - -(What if you care about the relative order of some of the calls, but not all of -them? Can you specify an arbitrary partial order? The answer is ... yes! The -details can be found [here](cook_book.md#OrderedCalls).) - -### All Expectations Are Sticky (Unless Said Otherwise) {#StickyExpectations} - -Now let's do a quick quiz to see how well you can use this mock stuff already. -How would you test that the turtle is asked to go to the origin *exactly twice* -(you want to ignore any other instructions it receives)? - -After you've come up with your answer, take a look at ours and compare notes -(solve it yourself first - don't cheat!): - -```cpp -using ::testing::_; -using ::testing::AnyNumber; -... -EXPECT_CALL(turtle, GoTo(_, _)) // #1 - .Times(AnyNumber()); -EXPECT_CALL(turtle, GoTo(0, 0)) // #2 - .Times(2); -``` - -Suppose `turtle.GoTo(0, 0)` is called three times. In the third time, gMock will -see that the arguments match expectation #2 (remember that we always pick the -last matching expectation). Now, since we said that there should be only two -such calls, gMock will report an error immediately. This is basically what we've -told you in the [Using Multiple Expectations](#MultiExpectations) section above. - -This example shows that **expectations in gMock are "sticky" by default**, in -the sense that they remain active even after we have reached their invocation -upper bounds. This is an important rule to remember, as it affects the meaning -of the spec, and is **different** to how it's done in many other mocking -frameworks (Why'd we do that? Because we think our rule makes the common cases -easier to express and understand.). - -Simple? Let's see if you've really understood it: what does the following code -say? - -```cpp -using ::testing::Return; -... -for (int i = n; i > 0; i--) { - EXPECT_CALL(turtle, GetX()) - .WillOnce(Return(10*i)); -} -``` - -If you think it says that `turtle.GetX()` will be called `n` times and will -return 10, 20, 30, ..., consecutively, think twice! The problem is that, as we -said, expectations are sticky. So, the second time `turtle.GetX()` is called, -the last (latest) `EXPECT_CALL()` statement will match, and will immediately -lead to an "upper bound violated" error - this piece of code is not very useful! - -One correct way of saying that `turtle.GetX()` will return 10, 20, 30, ..., is -to explicitly say that the expectations are *not* sticky. In other words, they -should *retire* as soon as they are saturated: - -```cpp -using ::testing::Return; -... -for (int i = n; i > 0; i--) { - EXPECT_CALL(turtle, GetX()) - .WillOnce(Return(10*i)) - .RetiresOnSaturation(); -} -``` - -And, there's a better way to do it: in this case, we expect the calls to occur -in a specific order, and we line up the actions to match the order. Since the -order is important here, we should make it explicit using a sequence: - -```cpp -using ::testing::InSequence; -using ::testing::Return; -... -{ - InSequence s; - - for (int i = 1; i <= n; i++) { - EXPECT_CALL(turtle, GetX()) - .WillOnce(Return(10*i)) - .RetiresOnSaturation(); - } -} -``` - -By the way, the other situation where an expectation may *not* be sticky is when -it's in a sequence - as soon as another expectation that comes after it in the -sequence has been used, it automatically retires (and will never be used to -match any call). - -### Uninteresting Calls - -A mock object may have many methods, and not all of them are that interesting. -For example, in some tests we may not care about how many times `GetX()` and -`GetY()` get called. - -In gMock, if you are not interested in a method, just don't say anything about -it. If a call to this method occurs, you'll see a warning in the test output, -but it won't be a failure. This is called "naggy" behavior; to change, see -[The Nice, the Strict, and the Naggy](cook_book.md#NiceStrictNaggy). diff --git a/googlemock/docs/gmock_faq.md b/googlemock/docs/gmock_faq.md deleted file mode 100644 index 14acae5..0000000 --- a/googlemock/docs/gmock_faq.md +++ /dev/null @@ -1,398 +0,0 @@ -## Legacy gMock FAQ {#GMockFaq} - - - - - -### When I call a method on my mock object, the method for the real object is invoked instead. What's the problem? - -In order for a method to be mocked, it must be *virtual*, unless you use the -[high-perf dependency injection technique](cook_book.md#MockingNonVirtualMethods). - -### Can I mock a variadic function? - -You cannot mock a variadic function (i.e. a function taking ellipsis (`...`) -arguments) directly in gMock. - -The problem is that in general, there is *no way* for a mock object to know how -many arguments are passed to the variadic method, and what the arguments' types -are. Only the *author of the base class* knows the protocol, and we cannot look -into his or her head. - -Therefore, to mock such a function, the *user* must teach the mock object how to -figure out the number of arguments and their types. One way to do it is to -provide overloaded versions of the function. - -Ellipsis arguments are inherited from C and not really a C++ feature. They are -unsafe to use and don't work with arguments that have constructors or -destructors. Therefore we recommend to avoid them in C++ as much as possible. - -### MSVC gives me warning C4301 or C4373 when I define a mock method with a const parameter. Why? - -If you compile this using Microsoft Visual C++ 2005 SP1: - -```cpp -class Foo { - ... - virtual void Bar(const int i) = 0; -}; - -class MockFoo : public Foo { - ... - MOCK_METHOD(void, Bar, (const int i), (override)); -}; -``` - -You may get the following warning: - -```shell -warning C4301: 'MockFoo::Bar': overriding virtual function only differs from 'Foo::Bar' by const/volatile qualifier -``` - -This is a MSVC bug. The same code compiles fine with gcc, for example. If you -use Visual C++ 2008 SP1, you would get the warning: - -```shell -warning C4373: 'MockFoo::Bar': virtual function overrides 'Foo::Bar', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers -``` - -In C++, if you *declare* a function with a `const` parameter, the `const` -modifier is ignored. Therefore, the `Foo` base class above is equivalent to: - -```cpp -class Foo { - ... - virtual void Bar(int i) = 0; // int or const int? Makes no difference. -}; -``` - -In fact, you can *declare* `Bar()` with an `int` parameter, and define it with a -`const int` parameter. The compiler will still match them up. - -Since making a parameter `const` is meaningless in the method declaration, we -recommend to remove it in both `Foo` and `MockFoo`. That should workaround the -VC bug. - -Note that we are talking about the *top-level* `const` modifier here. If the -function parameter is passed by pointer or reference, declaring the pointee or -referee as `const` is still meaningful. For example, the following two -declarations are *not* equivalent: - -```cpp -void Bar(int* p); // Neither p nor *p is const. -void Bar(const int* p); // p is not const, but *p is. -``` - - - -### I can't figure out why gMock thinks my expectations are not satisfied. What should I do? - -You might want to run your test with `--gmock_verbose=info`. This flag lets -gMock print a trace of every mock function call it receives. By studying the -trace, you'll gain insights on why the expectations you set are not met. - -If you see the message "The mock function has no default action set, and its -return type has no default value set.", then try -[adding a default action](for_dummies.md#DefaultValue). Due to a known issue, -unexpected calls on mocks without default actions don't print out a detailed -comparison between the actual arguments and the expected arguments. - -### My program crashed and `ScopedMockLog` spit out tons of messages. Is it a gMock bug? - -gMock and `ScopedMockLog` are likely doing the right thing here. - -When a test crashes, the failure signal handler will try to log a lot of -information (the stack trace, and the address map, for example). The messages -are compounded if you have many threads with depth stacks. When `ScopedMockLog` -intercepts these messages and finds that they don't match any expectations, it -prints an error for each of them. - -You can learn to ignore the errors, or you can rewrite your expectations to make -your test more robust, for example, by adding something like: - -```cpp -using ::testing::AnyNumber; -using ::testing::Not; -... - // Ignores any log not done by us. - EXPECT_CALL(log, Log(_, Not(EndsWith("/my_file.cc")), _)) - .Times(AnyNumber()); -``` - -### How can I assert that a function is NEVER called? - -```cpp -using ::testing::_; -... - EXPECT_CALL(foo, Bar(_)) - .Times(0); -``` - - - -### I have a failed test where gMock tells me TWICE that a particular expectation is not satisfied. Isn't this redundant? - -When gMock detects a failure, it prints relevant information (the mock function -arguments, the state of relevant expectations, and etc) to help the user debug. -If another failure is detected, gMock will do the same, including printing the -state of relevant expectations. - -Sometimes an expectation's state didn't change between two failures, and you'll -see the same description of the state twice. They are however *not* redundant, -as they refer to *different points in time*. The fact they are the same *is* -interesting information. - -### I get a heapcheck failure when using a mock object, but using a real object is fine. What can be wrong? - -Does the class (hopefully a pure interface) you are mocking have a virtual -destructor? - -Whenever you derive from a base class, make sure its destructor is virtual. -Otherwise Bad Things will happen. Consider the following code: - -```cpp -class Base { - public: - // Not virtual, but should be. - ~Base() { ... } - ... -}; - -class Derived : public Base { - public: - ... - private: - std::string value_; -}; - -... - Base* p = new Derived; - ... - delete p; // Surprise! ~Base() will be called, but ~Derived() will not - // - value_ is leaked. -``` - -By changing `~Base()` to virtual, `~Derived()` will be correctly called when -`delete p` is executed, and the heap checker will be happy. - -### The "newer expectations override older ones" rule makes writing expectations awkward. Why does gMock do that? - -When people complain about this, often they are referring to code like: - -```cpp -using ::testing::Return; -... - // foo.Bar() should be called twice, return 1 the first time, and return - // 2 the second time. However, I have to write the expectations in the - // reverse order. This sucks big time!!! - EXPECT_CALL(foo, Bar()) - .WillOnce(Return(2)) - .RetiresOnSaturation(); - EXPECT_CALL(foo, Bar()) - .WillOnce(Return(1)) - .RetiresOnSaturation(); -``` - -The problem, is that they didn't pick the **best** way to express the test's -intent. - -By default, expectations don't have to be matched in *any* particular order. If -you want them to match in a certain order, you need to be explicit. This is -gMock's (and jMock's) fundamental philosophy: it's easy to accidentally -over-specify your tests, and we want to make it harder to do so. - -There are two better ways to write the test spec. You could either put the -expectations in sequence: - -```cpp -using ::testing::Return; -... - // foo.Bar() should be called twice, return 1 the first time, and return - // 2 the second time. Using a sequence, we can write the expectations - // in their natural order. - { - InSequence s; - EXPECT_CALL(foo, Bar()) - .WillOnce(Return(1)) - .RetiresOnSaturation(); - EXPECT_CALL(foo, Bar()) - .WillOnce(Return(2)) - .RetiresOnSaturation(); - } -``` - -or you can put the sequence of actions in the same expectation: - -```cpp -using ::testing::Return; -... - // foo.Bar() should be called twice, return 1 the first time, and return - // 2 the second time. - EXPECT_CALL(foo, Bar()) - .WillOnce(Return(1)) - .WillOnce(Return(2)) - .RetiresOnSaturation(); -``` - -Back to the original questions: why does gMock search the expectations (and -`ON_CALL`s) from back to front? Because this allows a user to set up a mock's -behavior for the common case early (e.g. in the mock's constructor or the test -fixture's set-up phase) and customize it with more specific rules later. If -gMock searches from front to back, this very useful pattern won't be possible. - -### gMock prints a warning when a function without EXPECT_CALL is called, even if I have set its behavior using ON_CALL. Would it be reasonable not to show the warning in this case? - -When choosing between being neat and being safe, we lean toward the latter. So -the answer is that we think it's better to show the warning. - -Often people write `ON_CALL`s in the mock object's constructor or `SetUp()`, as -the default behavior rarely changes from test to test. Then in the test body -they set the expectations, which are often different for each test. Having an -`ON_CALL` in the set-up part of a test doesn't mean that the calls are expected. -If there's no `EXPECT_CALL` and the method is called, it's possibly an error. If -we quietly let the call go through without notifying the user, bugs may creep in -unnoticed. - -If, however, you are sure that the calls are OK, you can write - -```cpp -using ::testing::_; -... - EXPECT_CALL(foo, Bar(_)) - .WillRepeatedly(...); -``` - -instead of - -```cpp -using ::testing::_; -... - ON_CALL(foo, Bar(_)) - .WillByDefault(...); -``` - -This tells gMock that you do expect the calls and no warning should be printed. - -Also, you can control the verbosity by specifying `--gmock_verbose=error`. Other -values are `info` and `warning`. If you find the output too noisy when -debugging, just choose a less verbose level. - -### How can I delete the mock function's argument in an action? - -If your mock function takes a pointer argument and you want to delete that -argument, you can use testing::DeleteArg() to delete the N'th (zero-indexed) -argument: - -```cpp -using ::testing::_; - ... - MOCK_METHOD(void, Bar, (X* x, const Y& y)); - ... - EXPECT_CALL(mock_foo_, Bar(_, _)) - .WillOnce(testing::DeleteArg<0>())); -``` - -### How can I perform an arbitrary action on a mock function's argument? - -If you find yourself needing to perform some action that's not supported by -gMock directly, remember that you can define your own actions using -[`MakeAction()`](#NewMonoActions) or -[`MakePolymorphicAction()`](#NewPolyActions), or you can write a stub function -and invoke it using [`Invoke()`](#FunctionsAsActions). - -```cpp -using ::testing::_; -using ::testing::Invoke; - ... - MOCK_METHOD(void, Bar, (X* p)); - ... - EXPECT_CALL(mock_foo_, Bar(_)) - .WillOnce(Invoke(MyAction(...))); -``` - -### My code calls a static/global function. Can I mock it? - -You can, but you need to make some changes. - -In general, if you find yourself needing to mock a static function, it's a sign -that your modules are too tightly coupled (and less flexible, less reusable, -less testable, etc). You are probably better off defining a small interface and -call the function through that interface, which then can be easily mocked. It's -a bit of work initially, but usually pays for itself quickly. - -This Google Testing Blog -[post](https://testing.googleblog.com/2008/06/defeat-static-cling.html) says it -excellently. Check it out. - -### My mock object needs to do complex stuff. It's a lot of pain to specify the actions. gMock sucks! - -I know it's not a question, but you get an answer for free any way. :-) - -With gMock, you can create mocks in C++ easily. And people might be tempted to -use them everywhere. Sometimes they work great, and sometimes you may find them, -well, a pain to use. So, what's wrong in the latter case? - -When you write a test without using mocks, you exercise the code and assert that -it returns the correct value or that the system is in an expected state. This is -sometimes called "state-based testing". - -Mocks are great for what some call "interaction-based" testing: instead of -checking the system state at the very end, mock objects verify that they are -invoked the right way and report an error as soon as it arises, giving you a -handle on the precise context in which the error was triggered. This is often -more effective and economical to do than state-based testing. - -If you are doing state-based testing and using a test double just to simulate -the real object, you are probably better off using a fake. Using a mock in this -case causes pain, as it's not a strong point for mocks to perform complex -actions. If you experience this and think that mocks suck, you are just not -using the right tool for your problem. Or, you might be trying to solve the -wrong problem. :-) - -### I got a warning "Uninteresting function call encountered - default action taken.." Should I panic? - -By all means, NO! It's just an FYI. :-) - -What it means is that you have a mock function, you haven't set any expectations -on it (by gMock's rule this means that you are not interested in calls to this -function and therefore it can be called any number of times), and it is called. -That's OK - you didn't say it's not OK to call the function! - -What if you actually meant to disallow this function to be called, but forgot to -write `EXPECT_CALL(foo, Bar()).Times(0)`? While one can argue that it's the -user's fault, gMock tries to be nice and prints you a note. - -So, when you see the message and believe that there shouldn't be any -uninteresting calls, you should investigate what's going on. To make your life -easier, gMock dumps the stack trace when an uninteresting call is encountered. -From that you can figure out which mock function it is, and how it is called. - -### I want to define a custom action. Should I use Invoke() or implement the ActionInterface interface? - -Either way is fine - you want to choose the one that's more convenient for your -circumstance. - -Usually, if your action is for a particular function type, defining it using -`Invoke()` should be easier; if your action can be used in functions of -different types (e.g. if you are defining `Return(*value*)`), -`MakePolymorphicAction()` is easiest. Sometimes you want precise control on what -types of functions the action can be used in, and implementing `ActionInterface` -is the way to go here. See the implementation of `Return()` in -`testing/base/public/gmock-actions.h` for an example. - -### I use SetArgPointee() in WillOnce(), but gcc complains about "conflicting return type specified". What does it mean? - -You got this error as gMock has no idea what value it should return when the -mock method is called. `SetArgPointee()` says what the side effect is, but -doesn't say what the return value should be. You need `DoAll()` to chain a -`SetArgPointee()` with a `Return()` that provides a value appropriate to the API -being mocked. - -See this [recipe](cook_book.md#mocking-side-effects) for more details and an -example. - -### I have a huge mock class, and Microsoft Visual C++ runs out of memory when compiling it. What can I do? - -We've noticed that when the `/clr` compiler flag is used, Visual C++ uses 5~6 -times as much memory when compiling a mock class. We suggest to avoid `/clr` -when compiling native C++ mocks. diff --git a/googlemock/docs/guide.md b/googlemock/docs/guide.md deleted file mode 100644 index 3e74594..0000000 --- a/googlemock/docs/guide.md +++ /dev/null @@ -1,49 +0,0 @@ -# googletest gMock Users Guide - -go/gmockguide - -Welcome to googletest: Google's C++ testing and mocking framework. gMock is a -mocking part of googletest. - -* [OSS Version](https://github.com/google/googletest) -* [Google3](http://google3/third_party/googletest/) - -* If you are new to gMock, start with [*gMock for Dummies*](for_dummies.md) to - learn the basic usage. - -* Read [gMock Cookbook](cook_book.md) to learn more advanced usage and useful - tips. - -* For a quick reference, check out [gMock Cheat Sheet](cheat_sheet.md). - -* If you have questions, search [gMock FAQ](#GMockFaq) and the gmock-users@ - archive before sending them to gmock-users@. - - - - - -#### Side Effects - - -| Matcher | Description | -| :--------------------------------- | :-------------------------------------- | -| `Assign(&variable, value)` | Assign `value` to variable. | -| `DeleteArg()` | Delete the `N`-th (0-based) argument, which must be a pointer. | -| `SaveArg(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. | -| `SaveArgPointee(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. | -| `SetArgReferee(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. | -| `SetArgPointee(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. | -| `SetArgumentPointee(value)` | Same as `SetArgPointee(value)`. Deprecated. Will be removed in v1.7.0. | -| `SetArrayArgument(first, last)` | Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range. | -| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. | -| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. | - - -* When compiling with exceptions in google3, it's not enough to specify - `-fexceptions` to copts in your cc_test target. That flag will not be - inherited by gmock, and various headers will be compiled both with and - without `-fexceptions` causing subtle bugs. Instead you must pass - `--copt=-fexceptions` to the blaze command so the flag gets passed to all - targets... but this is Google and we don't use exceptions so it shouldn't - really be an issue. diff --git a/googlemock/docs/index.md b/googlemock/docs/index.md deleted file mode 100644 index cc73e83..0000000 --- a/googlemock/docs/index.md +++ /dev/null @@ -1,127 +0,0 @@ -# googletest Home - -go/gmock - -Googletest is Google's C++ testing and mocking framework. Please note that there -are legacy names you may encounter "gUnit" and "gMock" - these names are now -merged into "googletest" - - - -## Testimonials - -> "I'm really enjoying trying it, and it's amazing to me how far you've taken -> this in C++. It's changed the way I program (and therefore changed my life ;), -> and one of my teams has adopted it for all/most tests (and I'm working on the -> other)." \ -> -- *Derek Thomson*, Google Mountain View - -
- -> "I started using mocks with EasyMock in Java a few years ago and found them -> **invaluable** for making unit testing as painless and effective as possible. -> I'm very glad (and amazed) to see you've managed to create something similar -> for C++. It's making the transition much more pleasant." \ -> -- *David Harkness*, Google Mountain View - -
- -> "I #included `gmock.h` and lived to tell the tale... Kept me from having to -> depend on `MockBigtable` thus far, which is **huge**." \ -> -- *Matthew Simmons*, Google NYC - -
- -> "I like the approach of `EXPECT_CALL` much more than EasyMock's mock modes -> (record, replay). It's the best way to ensure the user will never forget to -> verify the expectations: do it automatically!" \ -> -- *Tiago Silverira*, Google Brazil - -
- -> "It's by far the best mocking library for C++, by a long-shot." \ -> -- *Joe Walnes*, co-creator of jMock, Google London - -## Learning googletest mocking - -Please see the [*googletest Users Guide*](guide.md) for the combined gMock -mocking documentation. - -## Resources for Users - -* More docs: - * [Interview with gMock's Creator](http://www.corp.google.com/eng/testing/codegreen/v10/gMock.htm) - on the - [Feb 2008](http://www.corp.google.com/eng/testing/codegreen/v10/index.htm) - issue of [Code Green](http://go/codegreen) - discusses gMock's history - and philosophy. - * "Mockers of the (C++) world, delight!": TotT - [episode 66](http://big.corp.google.com/~jmcmaster/testing/2007/12/episode-68-mockers-of-c-world-delight.html) - - quick intro on gMock's benefits and usage - * "Mock logs better than gold": TotT - [episode 76](http://big.corp.google.com/~jmcmaster/testing/2008/02/episode-76-mock-logs-better-than-gold_21.html) - - how to test LOGs using gMock - * "Testing legacy code gently": TotT - [episode 84](http://big.corp.google.com/~jmcmaster/testing/2008/04/episode-84-testing-legacy-code-gently.html) - - using mock callbacks to test legacy code without a big refactoring - * "Literate testing with matchers": TotT - [episode 135](http://big.corp.google.com/~jmcmaster/testing/2009/06/episode-135-literate-testing-with_08.html) - - using matchers to get readable test code and readable test messages - * "Making a perfect matcher": TotT - [episode 139](http://big.corp.google.com/~jmcmaster/testing/2009/07/episode-139-making-perfect-matcher.html) - - defining custom matchers easily -* Talks - * "Declarative C++ Testing Using DSLs" talk (6/4/2008): - [abstract](https://wiki.corp.google.com/twiki/bin/view/Main/WanTalks#Declarative_C_Testing_Using_DSLs), - [slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0806-declarative-cpp-testing.xul#Eva) - (requires Firefox) - gMock's design and implementation tricks - * "Mocks made easy in C++ and Java" talk (4/23/2008): - [slides](http://go/MockTalk), - [fish](http://fish.corp.google.com/talks/8729/) - * "C++ mocks made easy - an introduction to gMock" talk (1/22/2008)): - [slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0801-mv-gmock.xul#eva) - (requires Firefox), - [video](https://video.google.com/a/google.com/?AuthEventSource=SSO#/Play/contentId=bd07003d4193a646) - * "A preview to gMock" talk (6/28/2007): - [PowerPoint slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0706-beijing-gmock-preview.ppt) -* Tools - * `/google/src/head/depot/google3/third_party/googletest/googlemock/scripts/generator/gmock_gen.py - *your.h ClassNames*` generates mocks for the given base classes (if no - class name is given, all classes in the file are emitted). -* Mocks - * [mock-log.h](http://s/?fileprint=//depot/google3/testing/base/public/mock-log.h) - - a sample on using gMock to create a mock class - * [gmock-sample-mock-log.cc](http://s/?fileprint=//depot/google3/testing/base/internal/gmock-sample-mock-log.cc) - - a sample on using gMock to test LOG()s -* Folks - * Meet the - [users](http://piano.kir.corp.google.com:8080/lica/?e=use%3Agmock). - * `gmock-users` list: - [subscribe](https://groups.google.com/a/google.com/group/gmock-users/topics), - [archive](https://groups.google.com/a/google.com/group/gmock-users/topics), - [smile!](http://piano.kir.corp.google.com:8080/lica/?e=gmock-users) Send - questions here if you still need help after consulting the on-line docs. - * `gmock-announce` list: - [subscribe](https://groups.google.com/a/google.com/group/gmock-announce/topics) - to this instead of `gmock-users` if you are interested in announcements - only. - -## Resources for Contributors - -* [Dashboard](http://unittest.corp.google.com/project/gunit-gmock/) -* [*gMock Design*](design.md) (go/gmockdesign) - the design doc -* `c-mock-dev` list (deprecated) - - [old archive](https://mailman.corp.google.com/pipermail/c/c-mock-dev/), - [new archive](https://g.corp.google.com/group/c-mock-dev-archive) -* `opensource-gmock` list - discussions on the development of gMock: - [subscribe](https://groups.google.com/a/google.com/group/opensource-gmock/subscribe), - [archive](https://g.corp.google.com/group/opensource-gmock-archive), - [smile!](http://piano.kir.corp.google.com:8080/lica/?e=opensource-gmock) - -## Acknowledgments - -We'd like to thank the following people for their contribution to gMock: Piotr -Kaminski, Jeffrey Yasskin (who/jyasskin), Joe Walnes, Bradford Cross, Keith Ray, -Craig Silverstein, Matthew Simmons (who/simmonmt), Hal Burch (who/hburch), Russ -Rufer, Rushabh Doshi (who/rdoshi), Gene Volovich (who/genev), Mike Bland, Neal -Norwitz (who/nnorwitz), Mark Zuber, Vadim Berman (who/vadimb). diff --git a/googlemock/docs/overview.md b/googlemock/docs/overview.md deleted file mode 100644 index 0c77dfa..0000000 --- a/googlemock/docs/overview.md +++ /dev/null @@ -1,111 +0,0 @@ -# GMock - - - -## What is gMock? - -gMock is Google's framework for creating and using C++ mock classes. It helps -you design better systems and write better tests. A mock object is an object -that you use in a test instead of a real object. A mock object implements the -same interface as a real object but lets you specify at run time how the object -will be used. When you write tests that use a mock, you define expectations -about how the mock's methods will be called. Your test then verifies how your -real code behaves when interacting with the mock. See the -[Mock Objects Best Practices Guide](http://go/mock-objects#mocks-stubs-fakes) -for a comparison of mocks with stubs, fakes, and other kinds of test doubles. - -For example, gMock provides a simple syntax for declaring "I expect the -RetryQuery method on this mock object to be called three times in the course of -this test". Your test will fail if the expectation isn't met. - -The gMock library provides a mock framework for C++ similar to jMock or -EasyMock[?](http://go/easymock-codelab) for Java. In gMock you use macros to -define methods for your mock objects and set expectations for those methods. -gMock runs on Linux, Windows, and Mac OS X. - -## What is gMock good for? - -Mocks in general are good for: - -- prototyping and designing new code and APIs. -- removing unnecessary, expensive, or unreliable dependencies from your tests. - -gMock in particular is good for writing quality C++ mocks. Without the help of a -mocking framework like gMock, good C++ mocks are hard to create. - -## What is gMock NOT good for? - -gMock is not good for testing the behavior of dependencies. The point of testing -with mocks is to test the classes that use the mocks, not the mocks themselves. -Objects that have working toy implementations are called fakes instead of mocks. -For example, you could use an in-memory file system to fake disk operations. - -Mocks aren't useful for very simple classes like -[Dumb Data Objects](http://big.corp.google.com/~jmcmaster/testing/2011/04/episode-220-blast-from-tott-past-dont.html). -If it's more trouble to use a mock than the real class, just use the real class. - -## Who uses gMock? - -There are over 30K tests using gmock. Virtually every C++ test at Google that -needs a mock object uses gMock. - -## Practical matters - -gMock is bundled with [gUnit](/third_party/googletest/googletest/docs/). To use -gMock, -[include a dependency](/third_party/googletest/googletest/docs/howto_cpp#LinuxTarget) -on `//testing/base/public:gunit` in the BUILD rule for your mocks, and use the -following include statement in the file that defines your mock class: - -``` -#include "gmock/gmock.h" -``` - -  |   ---------------------------- | ------------------------------------------ -**Implementation language** | C++ -**Code location** | google3/third_party/googletest/googlemock/ -**Build target** | //testing/base/public:gunit - -## Best practices - -Use [dependency injection](http://en.wikipedia.org/wiki/Dependency_injection) to -enable easy mocking. If you define dependencies as interfaces rather than -concrete classes, you can swap out the production version of a class for a mock -during testing. - -You can also use gMock during the design phase for your system. By sketching -your architecture using mocks rather than full implementations, you can evolve -your design more quickly. - -## History and evolution - -In January 2007 Zhanyong Wan and the Testing Technology team met with -experienced C++ engineers to find out about C++ testing needs. The team learned -that creating mocks in C++ was a major pain point. They looked around for -existing frameworks but didn't find anything satisfactory. So Zhanyong Wan -tackled the problem of creating a usable C++ mocking framework. - -C++ posed a unique problem for mocking: while -[reflection](http://en.wikipedia.org/wiki/Reflection_\(computer_programming\)) -in Java and Python make it easy to generate a mock implementation of any -interface, C++ does not have reflection. Wan hit on macros as a way to simplify -mock writing in C++, and gMock was born. - -## Who to contact - -- g/gmock-users -- g/gmock-announce - -## Additional resources - -- [gMock](http://go/gmock) - homepage -- [GMock for Dummies](http://) - gets you started with gMock - quickly -- [GMock Cookbook](http://) - recipes for common scenarios; covers - advanced usage. -- [GMock Cheat Sheet](http://) - a quick reference -- [GMock FAQ](http://) - frequently asked questions -- [gUnit GDH page](http://go/gunit-overview) -- [gUnit User's Guide](http://goto.corp.google.com/gunit) - gets you started - with gUnit, which is closely related to gMock diff --git a/googlemock/docs/pump_manual.md b/googlemock/docs/pump_manual.md deleted file mode 100644 index 17fb370..0000000 --- a/googlemock/docs/pump_manual.md +++ /dev/null @@ -1,189 +0,0 @@ -Pump is Useful for Meta Programming. - - - -# The Problem - -Template and macro libraries often need to define many classes, functions, or -macros that vary only (or almost only) in the number of arguments they take. -It's a lot of repetitive, mechanical, and error-prone work. - -Our experience is that it's tedious to write custom scripts, which tend to -reflect the structure of the generated code poorly and are often hard to read -and edit. For example, a small change needed in the generated code may require -some non-intuitive, non-trivial changes in the script. This is especially -painful when experimenting with the code. - -This script may be useful for generating meta code, for example a series of -macros of FOO1, FOO2, etc. Nevertheless, please make it your last resort -technique by favouring C++ template metaprogramming or variadic macros. - -# Our Solution - -Pump (for Pump is Useful for Meta Programming, Pretty Useful for Meta -Programming, or Practical Utility for Meta Programming, whichever you prefer) is -a simple meta-programming tool for C++. The idea is that a programmer writes a -`foo.pump` file which contains C++ code plus meta code that manipulates the C++ -code. The meta code can handle iterations over a range, nested iterations, local -meta variable definitions, simple arithmetic, and conditional expressions. You -can view it as a small Domain-Specific Language. The meta language is designed -to be non-intrusive (s.t. it won't confuse Emacs' C++ mode, for example) and -concise, making Pump code intuitive and easy to maintain. - -## Highlights - -* The implementation is in a single Python script and thus ultra portable: no - build or installation is needed and it works cross platforms. -* Pump tries to be smart with respect to - [Google's style guide](https://github.com/google/styleguide): it breaks long - lines (easy to have when they are generated) at acceptable places to fit - within 80 columns and indent the continuation lines correctly. -* The format is human-readable and more concise than XML. -* The format works relatively well with Emacs' C++ mode. - -## Examples - -The following Pump code (where meta keywords start with `$`, `[[` and `]]` are -meta brackets, and `$$` starts a meta comment that ends with the line): - -``` -$var n = 3 $$ Defines a meta variable n. -$range i 0..n $$ Declares the range of meta iterator i (inclusive). -$for i [[ - $$ Meta loop. -// Foo$i does blah for $i-ary predicates. -$range j 1..i -template -class Foo$i { -$if i == 0 [[ - blah a; -]] $elif i <= 2 [[ - blah b; -]] $else [[ - blah c; -]] -}; - -]] -``` - -will be translated by the Pump compiler to: - -```cpp -// Foo0 does blah for 0-ary predicates. -template -class Foo0 { - blah a; -}; - -// Foo1 does blah for 1-ary predicates. -template -class Foo1 { - blah b; -}; - -// Foo2 does blah for 2-ary predicates. -template -class Foo2 { - blah b; -}; - -// Foo3 does blah for 3-ary predicates. -template -class Foo3 { - blah c; -}; -``` - -In another example, - -``` -$range i 1..n -Func($for i + [[a$i]]); -$$ The text between i and [[ is the separator between iterations. -``` - -will generate one of the following lines (without the comments), depending on -the value of `n`: - -```cpp -Func(); // If n is 0. -Func(a1); // If n is 1. -Func(a1 + a2); // If n is 2. -Func(a1 + a2 + a3); // If n is 3. -// And so on... -``` - -## Constructs - -We support the following meta programming constructs: - -| `$var id = exp` | Defines a named constant value. `$id` is | -: : valid until the end of the current meta : -: : lexical block. : -| :------------------------------- | :--------------------------------------- | -| `$range id exp..exp` | Sets the range of an iteration variable, | -: : which can be reused in multiple loops : -: : later. : -| `$for id sep [[ code ]]` | Iteration. The range of `id` must have | -: : been defined earlier. `$id` is valid in : -: : `code`. : -| `$($)` | Generates a single `$` character. | -| `$id` | Value of the named constant or iteration | -: : variable. : -| `$(exp)` | Value of the expression. | -| `$if exp [[ code ]] else_branch` | Conditional. | -| `[[ code ]]` | Meta lexical block. | -| `cpp_code` | Raw C++ code. | -| `$$ comment` | Meta comment. | - -**Note:** To give the user some freedom in formatting the Pump source code, Pump -ignores a new-line character if it's right after `$for foo` or next to `[[` or -`]]`. Without this rule you'll often be forced to write very long lines to get -the desired output. Therefore sometimes you may need to insert an extra new-line -in such places for a new-line to show up in your output. - -## Grammar - -```ebnf -code ::= atomic_code* -atomic_code ::= $var id = exp - | $var id = [[ code ]] - | $range id exp..exp - | $for id sep [[ code ]] - | $($) - | $id - | $(exp) - | $if exp [[ code ]] else_branch - | [[ code ]] - | cpp_code -sep ::= cpp_code | empty_string -else_branch ::= $else [[ code ]] - | $elif exp [[ code ]] else_branch - | empty_string -exp ::= simple_expression_in_Python_syntax -``` - -## Code - -You can find the source code of Pump in [scripts/pump.py](../scripts/pump.py). -It is still very unpolished and lacks automated tests, although it has been -successfully used many times. If you find a chance to use it in your project, -please let us know what you think! We also welcome help on improving Pump. - -## Real Examples - -You can find real-world applications of Pump in -[Google Test](https://github.com/google/googletest/tree/master/googletest) and -[Google Mock](https://github.com/google/googletest/tree/master/googlemock). The -source file `foo.h.pump` generates `foo.h`. - -## Tips - -* If a meta variable is followed by a letter or digit, you can separate them - using `[[]]`, which inserts an empty string. For example `Foo$j[[]]Helper` - generate `Foo1Helper` when `j` is 1. -* To avoid extra-long Pump source lines, you can break a line anywhere you - want by inserting `[[]]` followed by a new line. Since any new-line - character next to `[[` or `]]` is ignored, the generated code won't contain - this new line. diff --git a/googlemock/docs/sitemap.md b/googlemock/docs/sitemap.md deleted file mode 100644 index 78f2d1f..0000000 --- a/googlemock/docs/sitemap.md +++ /dev/null @@ -1,11 +0,0 @@ -Googletest Mocking (gMock) - -* [Home](index.md) -* [Overview](overview.md) -* [User's Guide](guide.md) -* [gMock For Dummies](for_dummies.md) -* [gMock Cookbook](cook_book.md) -* [gMock Cheat Sheet](cheat_sheet.md) -* [Design](design.md) -* [How To Contribute](contribute.md) -* [gMock FAQ](gmock_faq.md) diff --git a/googlemock/docs/under-construction-banner.md b/googlemock/docs/under-construction-banner.md deleted file mode 100644 index 2ee59f9..0000000 --- a/googlemock/docs/under-construction-banner.md +++ /dev/null @@ -1,4 +0,0 @@ -**WARNING:** This document was recently migrated from -[Goowiki](http://wtf/goowiki) (b/35424903) and may still require additional -updates or formatting. You can still access the original document on Goowiki -until the cleanup is complete: diff --git a/googlemock/g3doc/includes/g3_BUILD_rule.md b/googlemock/g3doc/includes/g3_BUILD_rule.md deleted file mode 100644 index 82e2ca7..0000000 --- a/googlemock/g3doc/includes/g3_BUILD_rule.md +++ /dev/null @@ -1,17 +0,0 @@ -## BUILD Rule - -Add *one* of the following to your `deps`: - -```build -"//testing/base/public:gunit", -"//testing/base/public:gtest_main", -``` - -Add this to your `.cc` file: - -```cpp -#include "gmock/gmock.h" -``` - -Unless noted, *all functions and classes* are defined in the `::testing` -namespace. diff --git a/googlemock/g3doc/includes/g3_absl_status_matcher.md b/googlemock/g3doc/includes/g3_absl_status_matcher.md deleted file mode 100644 index 93e1738..0000000 --- a/googlemock/g3doc/includes/g3_absl_status_matcher.md +++ /dev/null @@ -1,54 +0,0 @@ -### absl::Status - -In namespace `testing::status`: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
`IsOk()` `argument` is a `absl::Status` or `absl::StatusOr` whose status is OK.
`IsOkAndHolds(m)` - `argument` is an `absl::StatusOr` whose status is OK and whose inner value matches matcher `m`. - See also [`ASSERT_OK_AND_ASSIGN`](http://google3/testing/base/public/gmock_utils/status-matchers.h?q=symbol:ASSERT_OK_AND_ASSIGN). -
`StatusHasPayload()` `argument` is a `absl::Status` or `absl::StatusOr` whose status is not OK and which has any payload.
`StatusHasPayload()` `argument` is a `absl::Status` or `absl::StatusOr` whose status is not OK and which has a payload of type `ProtoType`.
`StatusHasPayload(m)` `argument` is a `absl::Status` or `absl::StatusOr` whose status is not OK and which has a payload of type `ProtoType` that matches `m`.
`StatusIs(s, c, m)` `argument` is a `absl::Status` or `absl::StatusOr` where: the error space matches `s`, the status code matches `c`, and the error message matches `m`.
`StatusIs(c, m)` `argument` is a `absl::Status` or `absl::StatusOr` where: the error space is canonical, the status code matches `c`, and the error message matches `m`.
`StatusIs(c)` `argument` is a `absl::Status` or `absl::StatusOr` where: the error space is canonical, and the status code matches `c`.
`CanonicalStatusIs(c, m)` `argument` is a `absl::Status` or `absl::StatusOr` where: the canonical status code matches `c`, and the error message matches `m`.
`CanonicalStatusIs(c)` `argument` is a `absl::Status` or `absl::StatusOr` where: the canonical status code matches `c`.
- -The two- and one-argument version of StatusIs use util::GetErrorSpaceForEnum to -determine the error space. If the error code matcher is not an enum with an -associated ErrorSpace, then the canonical space will be used. diff --git a/googlemock/g3doc/includes/g3_callback_snippet.md b/googlemock/g3doc/includes/g3_callback_snippet.md deleted file mode 100644 index a849e9b..0000000 --- a/googlemock/g3doc/includes/g3_callback_snippet.md +++ /dev/null @@ -1,3 +0,0 @@ -You can also use `google3` permanent callback as an action. Note that `Callback` -or member function must be wrapped with `Invoke()`, whereas lambdas and functors -will work by themselves. diff --git a/googlemock/g3doc/includes/g3_callbacks_as_matchers.md b/googlemock/g3doc/includes/g3_callbacks_as_matchers.md deleted file mode 100644 index f0a99da..0000000 --- a/googlemock/g3doc/includes/g3_callbacks_as_matchers.md +++ /dev/null @@ -1,22 +0,0 @@ -#### Using Callbacks as Matchers - -Callbacks are widely used in `google3`. Conceptually, a `ResultCallback1` is just a predicate on argument of type `T`. Naturally, we sometimes would -want to use such a callback as a matcher. - -gMock gives you two function templates in namespace `testing` to turn callbacks -into matchers. - -The first is `Truly(callback)`. It matches `argument` iff -`callback->Run(argument)` returns `true`. - -The second is `AddressSatisfies(callback)`, which matches `argument` whenever -`callback->Run(&argument)` returns `true`. - -The callbacks used in `Truly()` and `AddressSatisfies()` must be permanent (e.g. -those returned by `NewPermanentCallback()`), or you'll get a run-time error. The -matcher takes ownership of the callback, so you don't need to worry about -deleting it. - -For examples, see -google3/testing/base/internal/gmock_utils/callback-matchers_test.cc. diff --git a/googlemock/g3doc/includes/g3_content.md b/googlemock/g3doc/includes/g3_content.md deleted file mode 100644 index 22299c0..0000000 --- a/googlemock/g3doc/includes/g3_content.md +++ /dev/null @@ -1,134 +0,0 @@ -#### Mock(able) Files {#MockableFile} - -Don't use Mockable Files except to simulate errors on File. For general testing -of File, see go/file-testing. - -google3/file/testing/mockablefile/mockablefile.h defines a `MockableFile` class. -It wraps an arbitrary `File` object and makes its virtual methods "mockable", -meaning that by default they'll delegate to the underlying `File` while you have -the option to call `ON_CALL` or `EXPECT_CALL` to set expectations on them and/or -change their behavior. This gives you the best part of both a mock and a real -object: - -* The methods all have a working, default implementation. This can greatly - reduce the amount of work needed to set up the mock object. -* By setting expectations on the methods using `EXPECT_CALL`, you can easily - test how your code uses the `File`. -* By changing the methods' behavior (using `ON_CALL`), you can easily simulate - file errors and thus test your error handling code. - -`mockablefile.h` contains copious comments on the usage, and -[`mockablefile_test.cc`](http://google3/file/testing/mockablefile/mockablefile_test.cc) -in the same directory contains some complete examples. Here's one of them, -showing how to simulate `Write()` errors: - -```cpp -#include "file/base/path.h" -#include "file/testing/mockablefile/mockablefile.h" - -using ::file::testing::MockableFile; -using ::testing::_; -using ::testing::DoDefault; -using ::testing::Return; - -// This test demonstrates using MockableFile to test code that handles -// File operation errors. We want to test that WriteToFile() returns -// false when there is a Write() failure. It's hard to cause such an -// error using a real File object, but easy to make MockableFile -// simulate it. -TEST(SampleTest, SimulateFileError) { - // Creates a mockable_file object from a real File object. The real - // file is a local file in this example, but can also be any other - // type of File. - MockableFile* const mockable_file = new MockableFile( - File::Create(file::JoinPath(FLAGS_test_tmpdir, "/test"), "w")); - - // Tells the mockable file to start failing from the second Write() - // operation on. - EXPECT_CALL(*mockable_file, Write) - // By default, calls are delegated to the real File object. - .WillOnce(DoDefault()) - // Simulates a write error from the second time on. - .WillRepeatedly(Return(util::UnknownError("message"))); - - // Exercises the code we want to test, letting it talk to the - // MockableFile object instead of a real one. - EXPECT_FALSE(WriteToFile(mockable_file)); -} -``` - -`mockablefile.h` also defines a `MockableFileSystem` class that allows you to -register mockable files in the file system under the `/mockable` mount point, -which can then be opened by your code by name. Since `MockableFile` can wrap -**any** type of file, this means you can inject **any** type of file into the -file system for testing. For example, `google3/file/memfile/memfile.h` defines a -convenient in-memory file type `MutableStringFile`. Now, you can wrap a -`MutableStringFile` in a `MockableFile` and inject it using `MockableFileSystem` -in order to test error handling of File operations that want to open a file -themselves. - -```cpp -#include "file/memfile/memfile.h" // you also need to depend on //file/memfile:memfile in your BUILD file -#include "file/testing/mockablefile/mockablefile.h" - -using ::file::testing::MockableFile; -using ::file::testing::MockableFileSystem; -using ::testing::_; -using ::testing::DoDefault; -using ::testing::Return; - -// This test demonstrates registering a MockableFile with (a.k.a. -// injecting it into) the file system and opening it by name later. -// We want to test that WriteToFileByName() returns false when there -// is a Write() failure. -TEST(SampleTest, RegisterMockableFile) { - // Creates a mockable_file from a MutableStringFile. - MockableFile* const mockable_file = new MockableFile( - MutableStringFile("/foo/bar", new string, - TAKE_OWNERSHIP, DO_NOT_ALLOW_MMAP)); - - // Creates a mockable file system so that we can inject - // mockable_file into it. - MockableFileSystem fs; - - // Injects mockable_file as "/mockable/foo/bar". - const string kPath = "/mockable/foo/bar"; - EXPECT_CALL(fs, CreateFile(kPath, "w", _, _, _)) - .WillOnce(Return(mockable_file)); - - // Tells the mockable file to start failing from the second Write() - // operation on. - EXPECT_CALL(*mockable_file, Write) - // By default, calls are delegated to the real File object. - .WillOnce(DoDefault()) - // Simulates a write error from the second time on. - .WillRepeatedly(Return(util::error::UNKNOWN)); - - // Exercises the code we want to test, letting it talk to the - // MockableFile object instead of a real one. - EXPECT_FALSE(WriteToFileByName(kPath)); -} -``` - -#### Mock Network System Calls - -Gary Morain (gmorain@) implemented mock network system calls such that you can -use gMock to control their behavior when testing code that invokes network -system calls. You can find the code here: - -* google3/net/util/network_system_call_interface.h - the interface. -* google3/net/util/network_system_call.h - the real implementation. -* google3/net/util/network_system_call_mock.h - the mock implementation. -* google3/net/util/network_system_call_unittest.cc - the unit test and demo. - -#### Mock Bigtable - -Please see the -[Svala](https://sites.google.com/a/google.com/te-zrh/tools--technologies/gmock-bigtable) -project for a gMock-based Bigtable implementation. - -#### Add Yours Here - -Don't be shy! If you've created a mock class using gMock and think it would be -useful to other Googlers, write an entry about it on this wiki page so that -people can learn about it. diff --git a/googlemock/g3doc/includes/g3_matching_proto_buffers_cookbook_recipe.md b/googlemock/g3doc/includes/g3_matching_proto_buffers_cookbook_recipe.md deleted file mode 100644 index 885741d..0000000 --- a/googlemock/g3doc/includes/g3_matching_proto_buffers_cookbook_recipe.md +++ /dev/null @@ -1,36 +0,0 @@ -#### Matching Protocol Buffers - -Many Google APIs pass protocol buffers around. gMock provides some matchers for -protocol buffers. You can use them to specify that an argument must be equal (or -equivalent) to a given protocol buffer. - -`EqualsProto(proto_buffer)` matches an argument iff it's equal to -`proto_buffer`, as determined by the `Equals()` method of the argument. The -argument must be a protocol buffer; pointers must be dereferenced. - -Sometimes we want to test for equivalence instead of equality, i.e. we want to -use the `Equivalent()` method to compare two protocol buffers. For this we can -use `EquivToProto(proto_buffer)`. - -It's worth noting that all of the matchers we mention here make a copy of -`proto_buffer`. This means that you can use a matcher even if the original -protocol buffer used for creating the matcher has been destroyed. Just one less -thing for you to worry about! - -Note that `EqualsProto` and `EquivToProto` work for both proto1 and proto2. They -are declared in `gmock.h`, so you do not have to include other files. See -go/protomatchers for more proto buffer matching goodies. - -In addition: One application of `Property()` is testing protocol buffers: - - - - - - - - - - - -
`Property(&MyProto::has_size, true)` Matches `proto` where `proto.has_size()` returns `true`.
`Property(&MyProto::size, Gt(5))` Matches `proto` where `proto.size()` is greater than 5.
diff --git a/googlemock/g3doc/includes/g3_mock_a_stubby_server.md b/googlemock/g3doc/includes/g3_mock_a_stubby_server.md deleted file mode 100644 index 749f624..0000000 --- a/googlemock/g3doc/includes/g3_mock_a_stubby_server.md +++ /dev/null @@ -1,37 +0,0 @@ -### I need to mock a Stubby server. Should I use gMock or the service mocker? {#GMockVsServiceMocker} - -To quote PiotrKaminski, the author of the service mocker: - -You can find an introduction to the service mocker -[here](http://go/stubby-codelab#test-client), and detailed documentation in -net/rpc/testing/public/servicemocker.h. As I'm the author of the framework my -opinion on it can hardly be objective, but here are the main advantages it has -over gMock when it comes to mocking Stubby services: - -* Services are mocked dynamically so there's no need to manually write mock - service implementations. -* The client's calls go through a real Stubby channel, which will catch some - errors that calling a service implementation directly would miss. -* The service mocker is aware of sync/async client distinctions and common - Stubby threading strategies, and in general allows you to exert more control - over when the callback is made. -* The base syntax and semantics are very similar to gMock, but Stubby-specific - matchers and actions make the testing code more compact. -* A powerful expectation grouping mechanism allows expressing complicated - async call ordering constraints in a readable fashion. -* By the end of the week, there'll be built-in support for testing call - cancellation. - -Some disadvantages: - -* The service mocker documentation is not as good as gMock's. -* The error messages are probably not as good as gMock's either. -* You can only mock services, not arbitrary classes. Expectations do not - interact with gMock's. -* Slightly different expectation matching semantics in corner cases, which - could get confusing if you're using gMock as well. - -In my biased opinion, if you only need to mock out Stubby services, you should -look at the service mocker first. If you need to mock out other classes too, and -especially if you need to express relationships between service and other -expectations, you're probably better off with gMock. diff --git a/googlemock/g3doc/includes/g3_mock_callbacks.md b/googlemock/g3doc/includes/g3_mock_callbacks.md deleted file mode 100644 index 1198a0c..0000000 --- a/googlemock/g3doc/includes/g3_mock_callbacks.md +++ /dev/null @@ -1,95 +0,0 @@ -#### Mock Callbacks - -Callbacks (`"base/callback.h"`) are widely used in `google3` to package data and -logic together. Sometimes you want to test how your code invokes callbacks (with -what arguments, how many times, in which order, and etc). This is a job cut out -for mock callbacks. - -`"testing/base/public/mock-callback.h"` defines a class template to mock -callbacks. Given arbitrary types `R`, `T1`, ..., and `Tn`, class -**`MockCallback`** mocks a callback that takes arguments of type -`T1`, ..., and `Tn`, and returns type `R`, which can be `void`. This class is -derived from its corresponding abstract callback classed defined in -`"base/callback.h"`, for example: - -* `MockCallback` inherits from `Closure`, -* `MockCallback` inherits from `Callback2`, -* `MockCallback` derives from `ResultCallback`, and -* `MockCallback` derives from `ResultCallback1`. - -Compared with the various classes in `"base/callback.h"`, the mock classes share -the same name and only differ in the template arguments, so you will never have -trouble remembering which is called what. - -Like a real callback, a mock callback can be either *single-use* or *permanent*. -A single-use mock callback will delete itself when invoked. A permanent mock -callback will not and thus can be invoked many times - you have to make sure it -is deleted somehow. - -Since a mock object verifies all expectations on its mock methods in the -destructor, please link with `//base:heapcheck` (it is already linked -automatically if you link with `//testing/base/public:gtest_main`) to make sure -all mock callbacks - -are properly deleted. - -`MockCallback` has a mock method `OnRun()` with the signature: - -```cpp - R OnRun(T1, ..., Tn); -``` - -`OnRun()` will be called whenever the mock callback is invoked. Note that we -don't name it `Run()` to match the method in the base class, as doing so will -interfere with mocking single-use callbacks. - -Finally, `"mock-callback.h"` is a header-only library, so just include it and -go. Here's a complete example on how you use it: - -```cpp -#include "testing/base/public/mock-callback.h" - -// 1. Import the necessary names from the testing name space. -using ::testing::_; -using ::testing::MockCallback; -using ::testing::NotNull; -using ::testing::NewMockCallback; -using ::testing::NewPermanentMockCallback; -using ::testing::SetArgPointee; - -TEST(FooTest, DoesBar) { - // 2. Create a single-use mock callback using NewMockCallback(), or - // a permanent mock callback using NewPermanentMockCallback(). - MockCallback* show_int = NewMockCallback(); - std::unique_ptr > get_count( - NewPermanentMockCallback()); - - // 3. Set expectations on the OnRun() method of the mock callbacks. - EXPECT_CALL(*show_int, OnRun(5, true)) - .WillOnce(Return("+5")); - EXPECT_CALL(*get_count, OnRun(NotNull())) - .WillOnce(SetArgPointee<0>(1)) - .WillOnce(SetArgPointee<0>(2)); - - // 4. Exercise code that uses the mock callbacks. The single-use - // mock callback show_int will be verified and deleted when it's - // called. Link with //base:heapcheck to make sure it is not - // leaked. - Foo(5, show_int, get_count.get()); - // Foo()'s signature: - // void Foo(int n, ResultCallback2* show_int, - // Callback1* get_count); - - // 5. The permanent mock callback will be verified and deleted here, - // thanks to the std::unique_ptr. -} -``` - -Did you notice that you don't specify the types when calling `NewMockCallback()` -and `NewPermanentMockCallback()`? Apparently they can read your mind and know -the type of the mock callback you want. :-) - -(Seriously, these functions figure out their return types from the -left-hand-side of the assignment or the initialization, with the help of some -template tricks. But you don't need to understand how they work in order to use -mock callbacks.) diff --git a/googlemock/g3doc/includes/g3_mock_multithreaded.md b/googlemock/g3doc/includes/g3_mock_multithreaded.md deleted file mode 100644 index d8d9370..0000000 --- a/googlemock/g3doc/includes/g3_mock_multithreaded.md +++ /dev/null @@ -1,9 +0,0 @@ -### Can I use gMock in multi-threaded programs? - -googletest was designed with thread-safety in mind. It uses synchronization -primitives from `google3` to be thread-safe. If you work in `google3`, you can -use gMock in multiple threads safely. If you work outside of `google3` and need -gMock to be thread-safe, please let us know. - -For more details on how to use gMock with threads, read this -[recipe](#UsingThreads). diff --git a/googlemock/g3doc/includes/g3_proto_matchers.md b/googlemock/g3doc/includes/g3_proto_matchers.md deleted file mode 100644 index b929653..0000000 --- a/googlemock/g3doc/includes/g3_proto_matchers.md +++ /dev/null @@ -1,148 +0,0 @@ -### Protocol Buffer Matchers {#ProtoMatchers} - -(go/protomatchers) - -In the following, `argument` can be either a protocol buffer (version 1 or -version 2) or a pointer to it, and `proto` can be either a protocol buffer or a -human-readable ASCII string representing it (e.g. `"foo: 5"`). If you need help -writing the ASCII string, read go/textformat. "Fully-initialized" below means -all `required` fields are set. - - - - - - - - - - - - - - - - - - - - - - - -
`EqualsInitializedProto(proto)` `argument` is fully-initialized and equal to `proto`.
`EqualsProto(proto)` `argument` is equal to `proto`. Can also be used as a multi-argument matcher; see below.
`EquivToInitializedProto(proto)` `argument` is fully-initialized and equivalent to `proto`.
`EquivToProto(proto)` `argument` is equivalent to `proto`. Can also be used as a multi-argument matcher; see below.
`IsInitializedProto()` `argument` is a fully-initialized protocol buffer.
- -Both Equiv and Equal matchers checks that two protocol buffers have identical -values, however only Equal matchers ensure that the protocol buffers fields were -set the same way (explicitly or through their default value). - -When these matchers are given a string parameter, they *optionally* accept the -type of the protocol buffer as a template argument, e.g. -`EqualsProto("bar: 'xyz'")`. - -The following *protocol buffer matcher transformers* in namespace -`::testing::proto` change the behavior of a matcher: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
`Approximately(proto_matcher)` The same as `proto_matcher` except that it compares floating-point fields approximately.
`Approximately(proto_matcher, margin)` The same as `Approximately(proto_matcher)` except that two floating-point fields are considered equal if their absolute difference is <= `margin`.
`Approximately(proto_matcher, margin, fraction)` The same as `Approximately(proto_matcher)` except that two floating-point fields are considered equal if their absolute difference is <= `margin` or their fractional difference is <= `fraction`.
`TreatingNaNsAsEqual(proto_matcher)` The same as `proto_matcher` except that two floating-point fields are considered equal if both are NaN, matching the behavior of `NanSensitiveDoubleEq()`.
`IgnoringRepeatedFieldOrdering(proto_matcher)` The same as `proto_matcher` except that it ignores ordering of elements within repeated fields (see `proto2::MessageDifferencer::TreatAsSet()` for more details).
`IgnoringFieldPaths({"some_field.subfield"}, proto_matcher)` The same as `proto_matcher` except that it ignores the value of field `subfield` in field `some_field`.
`Partially(proto_matcher)` The same as `proto_matcher` except that only fields present in the expected protocol buffer are considered.
`WhenDeserialized(typed_proto_matcher)` `argument` is a string in the protocol buffer binary format that can be deserialized to a protocol buffer matching `typed_proto_matcher`.
`WhenDeserializedAs(matcher)` `argument` is a string in the protocol buffer binary format that can be deserialized to a protocol buffer of type `PB` that matches `matcher`.
`WhenParsedFromProtoText(typed_proto_matcher)` `argument` is a string in the protocol buffer text format that can be parsed to a protocol buffer matching `typed_proto_matcher`.
`WhenParsedFromProtoTextAs(matcher)` `argument` is a string in the protocol buffer text format that can be parsed to a protocol buffer of type `PB` that matches `matcher`.
`WhenUnpacked(typed_proto_matcher)` `argument` is a `google.protobuf.Any` that can be unpacked into a protocol buffer of the type of `typed_proto_matcher` that matches that matcher.
`WhenUnpackedTo(matcher)` `argument` is a `google.protobuf.Any` that can be unpacked into a protocol buffer of type `PB` that matches `matcher`.
- -where: - -* `proto_matcher` can be any of the `Equals*` and `EquivTo*` protocol buffer - matchers above, -* `typed_proto_matcher` can be an `Equals*` or `EquivTo*` protocol buffer - matcher where the type of the expected protocol buffer is known at run time - (e.g. `EqualsProto(expected_pb)` or `EqualsProto("bar: 'xyz'")`). -* `matcher` can be any matcher that can be used to match a `PB` value, e.g. - `EqualsProto("bar: 'xyz'")`, `Not(EqualsProto(my_pb))`. - -`Approximately()`, `Partially()`, and `TreatingNaNsAsEqual()` can be combined, -e.g. `Partially(Approximately(EqualsProto(foo)))`. - -Note that `EqualsProto()` and `EquivToProto()` can be used as multi-argument -matchers that match a 2-tuple of protos. The following example shows how to -compare two vectors of protos. - -```cpp -vector actual; -vector expected; -... // Fill vectors with data -EXPECT_THAT(actual, Pointwise(EqualsProto(), expected)); -``` - -Similarly, they can be used to compare a vector of protos against a vector of -strings. - -```cpp -vector actual; -... // Fill 'actual' with data -vector expected {"foo:", "foo:"}; -EXPECT_THAT(actual, Pointwise(EqualsProto(), expected)); -// Or, concisely: -EXPECT_THAT(actual, Pointwise(EqualsProto(), {"foo:", "foo:"})); -``` - - - - - - - - - - - -
`EqualsProto()` `x.Equals(y)`
`EquivToProto()` `x.Equivalent(y)`
diff --git a/googlemock/g3doc/includes/g3_stubby_actions.md b/googlemock/g3doc/includes/g3_stubby_actions.md deleted file mode 100644 index 0976a60..0000000 --- a/googlemock/g3doc/includes/g3_stubby_actions.md +++ /dev/null @@ -1,31 +0,0 @@ -### Stubby Actions - -gMock has the following actions to provide limited support for mocking Stubby -(go/stubby) services. You can use them to return a canned answer from a Stubby -call, which has the signature `void Method(RPC*, const Request*, Response* -response, Closure* done)`. You should consider using Service Mocker -(go/servicemocker) instead if your need is more complex. - - - - - - - - - - - - - - - - - - - - - - - -
`BeDone()` Calls the `done` closure.
`FailWith(status)` Fails the RPC with the given RPC status code.
`FailWithUtilStatus(util_status)` Fails the RPC with the given util::Status error code.
`RespondWith(proto)` Sets the `response` argument to the given protocol buffer, and calls the `done` closure.
`RespondWith(proto_string)` Sets the `response` argument to the protocol buffer parsed from the given ASCII string, and calls the `done` closure.
diff --git a/googlemock/g3doc/includes/g3_testing_LOGs.md b/googlemock/g3doc/includes/g3_testing_LOGs.md deleted file mode 100644 index 6a86086..0000000 --- a/googlemock/g3doc/includes/g3_testing_LOGs.md +++ /dev/null @@ -1,185 +0,0 @@ -#### Testing LOG()s {#TestingLogs} - -LOG()s are widely used in `google3` programs. They make it possible to diagnose -a server crash when you don't have the luxury of reproducing the bug. They are -also great as a [tool for refactoring](http://go/log-pin). - -Often we need to test how a piece of code calls LOG()s. Traditionally, this has -been done using [golden files](http://go/log-pin), which is tedious to set up -and brittle (what if a library you depend on starts to generate its own logs?). -The [`ScopedMemoryLog`](http://go/gunit-faq-scoped-mock-log) class was created -to allow writing robust LOG tests, but using it beyond the most basic scenario -can be awkward. - -With gMock we have a better solution. `testing/base/public/mock-log.h` defines a -mock log sink class `ScopedMockLog`. A `ScopedMockLog` object intercepts all -LOG()s (except `LOG(FATAL)`) while it is alive. This object has a mock method of -this signature: - -```cpp - void Log(LogSeverity severity, const string& path, const string& message); -``` - -This file comes with gUnit and gMock, so there is no need to add any dependency -to your `BUILD` rule in order to use it. - -Here are some ideas on how to make use of it: - -To test that the code generates exactly one warning message (and nothing else): - -```cpp -using ::testing::_; -using ::testing::kDoNotCaptureLogsYet; -using ::testing::ScopedMockLog; -... - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log(WARNING, _, "Expected warning.")); - log.StartCapturingLogs(); - ... code that LOG()s ... -``` - -To test that a particular message is logged exactly once (but there can be other -log messages with different contents): - -```cpp -using ::testing::_; -using ::testing::kDoNotCaptureLogsYet; -using ::testing::AnyNumber; -using ::testing::ScopedMockLog; -... - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log).Times(AnyNumber()); - EXPECT_CALL(log, Log(INFO, _, "Expected message")); - log.StartCapturingLogs(); - ... code that LOG()s ... -``` - -To test that no `ERROR` is logged (but there can be other log messages with -different severities): - -```cpp -using ::testing::_; -using ::testing::kDoNotCaptureLogsYet; -using ::testing::AnyNumber; -using ::testing::ScopedMockLog; -... - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log).Times(AnyNumber()); - EXPECT_CALL(log, Log(ERROR, _, _)) - .Times(0); - log.StartCapturingLogs(); - ... code that LOG()s ... -``` - -To test that a particular message is logged at least once (and there can be -other log messages): - -```cpp -using ::testing::_; -using ::testing::kDoNotCaptureLogsYet; -using ::testing::AnyNumber; -using ::testing::AtLeast; -using ::testing::ScopedMockLog; -... - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log).Times(AnyNumber()); - EXPECT_CALL(log, Log(INFO, _, "Expected message")) - .Times(AtLeast(1)); - log.StartCapturingLogs(); - ... code that LOG()s ... -``` - -To test that three LOG()s occur sequentially: - -```cpp -using ::testing::_; -using ::testing::kDoNotCaptureLogsYet; -using ::testing::InSequence; -using ::testing::ScopedMockLog; -... - ScopedMockLog log(kDoNotCaptureLogsYet); - { - InSequence s; - EXPECT_CALL(log, Log(INFO, _, "Log #1")); - EXPECT_CALL(log, Log(WARNING, _, "Log #2")); - EXPECT_CALL(log, Log(INFO, _, "Log #3")); - } - log.StartCapturingLogs(); - ... code that LOG()s ... -``` - -To test that the log message contains a certain sub-string: - -```cpp -using ::testing::_; -using ::testing::kDoNotCaptureLogsYet; -using ::testing::HasSubstr; -using ::testing::ScopedMockLog; -... - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log(WARNING, _, HasSubstr("needle"))); - log.StartCapturingLogs(); - ... code that LOG()s ... -``` - -To test that a given module generates a specific log: - -```cpp -using ::testing::kDoNotCaptureLogsYet; -using ::testing::ScopedMockLog; -... - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log(WARNING, "path/to/my_module.cc", "Expected warning.")); - log.StartCapturingLogs(); - ... code that LOG()s ... -``` - -To test that code doesn't log anything at all: - -```cpp -using ::testing::_; -using ::testing::kDoNotCaptureLogsYet; -using ::testing::ScopedMockLog; -... - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log).Times(0); - log.StartCapturingLogs(); - ... code that does not LOG() ... -``` - -**Warning:** For robust tests, either ignore unexpected logs (loose), or ignore -logs in other modules (tight), otherwise your test may break if their logging -changes. - -```cpp -using ::testing::_; -using ::testing::AnyNumber; -using ::testing::kDoNotCaptureLogsYet; -using ::testing::Not; -using ::testing::ScopedMockLog; - -// ... - -// Simple robust setup, ignores unexpected logs. - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log).Times(AnyNumber()); // Ignore unexpected logs. - EXPECT_CALL(log, Log(ERROR, "path/to/my_file.cc", _)) - .Times(3); // Verifies logs from my_file.cc. - log.StartCapturingLogs(); - // ... code that LOG()s ... - -// ... - -// Tighter alternative. - ScopedMockLog log(kDoNotCaptureLogsYet); - EXPECT_CALL(log, Log(_, Not("path/to/my_file.cc"), _)) - .Times(AnyNumber()); // Ignores other modules. - EXPECT_CALL(log, Log(ERROR, "path/to/my_file.cc", _)) - .Times(3); // Verifies logs from my_file.cc. - log.StartCapturingLogs(); - // ... code that LOG()s ... -``` - -To test `LOG(DFATAL)`, use -[`EXPECT_DFATAL`](/third_party/googletest/googletest/docs/google3_faq#testing-death-in-debug-mode) -instead. diff --git a/googlemock/g3doc/includes/g3_testing_code_stubby_server.md b/googlemock/g3doc/includes/g3_testing_code_stubby_server.md deleted file mode 100644 index 22d7926..0000000 --- a/googlemock/g3doc/includes/g3_testing_code_stubby_server.md +++ /dev/null @@ -1,77 +0,0 @@ -#### Testing Code that Uses a Stubby Server - -(Contributed by JonWray on 2008/3/11; updated by ZhanyongWan later.) - -I'm testing a C++ frontend that calls several different backends, but I'll just -include an example for one to keep this relatively short. This example is -mocking a `CacheServer` backend. An explanation follows the code. - -```cpp -using ::testing::_; -using ::testing::BeDone; -using ::testing::EqualsProto; -using ::testing::RespondWith; - -class MockCacheServer : public CacheServerRPC { - public: - MockCacheServer(HTTPServer *hs) { - rpc2::EnableRPC2(this, rpc2::ServiceParameters()); - CacheServerRPC::ExportService(hs); - ON_CALL(*this, Insert).WillByDefault(BeDone()); - ON_CALL(*this, Lookup).WillByDefault(BeDone()); - } - - MOCK_METHOD(void, Insert, - (RPC*, const CacheInsertCommandProto*, CacheInsertResultsProto*, - Closure*), - (override)); - MOCK_METHOD(void, Lookup, - (RPC*, const CacheLookupCommandProto*, CacheLookupResultsProto*, - Closure*), - (override)); -}; -... - // This is in the test fixture. - MockCacheServer cacheserver_; -... - // Now the code that uses it: - CacheLookupCommandProto command; - // Init command - CacheLookupResultsProto results; - // Init results - - EXPECT_CALL(cacheserver_, Lookup(_, EqualsProto(command), _, _)) - .WillOnce(RespondWith(results)); -``` - -In the success case, the command matches the `EXPECT_CALL`, so results is set -and the callback is called. - -In the failure case, the command matches the default `ON_CALL`, the results are -not set, and the done closure is called (don't want the test to hang). - -So it's a bit ugly, but given that I need to mock five backends, I think it's -better than doing this manually. The best part is the nicely formatted error -messages when the expected call is incorrect. Once all this scaffolding is in -place, it's easy to churn out test suites. - -**Discussions:** - -* ZhanyongWan: `StubbySimulator` by Mike Bland might also be useful: - google3/testing/lib/net/rpc/stubby_simulator.h. -* JonWray: This is turning a mock into a fake, isn't it? All requests are - accepted, and you can write logic to set the reply conditionally on the - request. The interesting thing is the logic moves from the mock class into - the test suite. -* MikeBland: It's sort of a Frankenstein, but it works well for my purposes. - It collaborates with a mock Stubby server, which sets the expectation and - does the actual intercepting of the args, and then gives you the freedom to - fiddle with the results while the RPC is conceptually "in flight". This is - especially handy for "pausing" the RPC and having it return a state other - than `RPC::OK`. This sort of approach to splitting RPC calls into separate - objects from ControlFlows was first explored in - [TotT Episode 46](http://tott/2007/06/episode-46-encapsulated-rpcs-or.html). -* PiotrKaminski: The [Service Mocker](http://go/servicemocker) is a gMock-like - framework that specializes in mocking Stubby services. It allows for small, - in-process tests, doesn't require manually writing a service mock, and can - deal with async clients, streaming and testing for cancellations. diff --git a/googlemock/g3doc/includes/g3_useful_matchers_outsidegmock.md b/googlemock/g3doc/includes/g3_useful_matchers_outsidegmock.md deleted file mode 100644 index 5061681..0000000 --- a/googlemock/g3doc/includes/g3_useful_matchers_outsidegmock.md +++ /dev/null @@ -1,109 +0,0 @@ -### Useful Matchers Defined Outside of gMock - -#### std::tuple - -**deps:** `"//util/tuple:matchers"`
-`#include "util/tuple/matchers.h"`
-In namespace `util::tuple::testing`: - - - - - - - - - - - -
`Tuple(m0, m1, ..., mn)` `argument` is a `std::tuple` const reference with `n + 1` elements, where the i-th element matches `std::get*(argument)`
`FieldPairsAre(m0, m1, ..., mn)` matches a pair (2-tuple) of tuples where matcher `mi` matches the i-th fields of the tuples; usually for use inside `Pointwise()` or `UnorderedPointwise()`
- -#### Web - -**deps:** `"//webutil/url:test_utils"`
-`#include "webutil/url/test_utils.h"` - - - - - - - - - - - - - - - - - - - -
`webutil_url::testing::HasUrlArg(key)` `argument` is a URL string that has a query argument whose name is `key`. E.g. `http://foo.com/bar?key=value`
`webutil_url::testing::HasUrlArg(key, m)` `argument` is a URL string that has a query argument whose name is `key` and whose value matches `m`.
`webutil_url::testing::HasUrlPathParam(key)` `argument` is a URL string that has a path parameter whose name is `key`. E.g. `http://foo.com/bar;key=value`
`webutil_url::testing::HasUrlPathParam(key, m)` `argument` is a URL string that has a path parameter whose name is `key` and whose value matches `m`.
- -**deps:** `"//third_party/jsoncpp:testing"`
-`#include "third_party/jsoncpp/testing.h"` - - - - - - - -
`Json::testing::EqualsJson(json)` `argument` is a string that represents the same Json value as the `json` string does.
- -#### Encoding - -**deps:** `"//testing/lib/util/coding:varint"`
-`#include "testing/lib/util/coding/varint.h"` - - - - - - - -
`testing_lib_util_coding::EncodesVarint64(n)` `argument` is a string that represents a Varint encoding of `n`, a `uint64` value.
- -#### XPath - -**deps:** `"//template/prototemplate/testing:xpath_matcher"`
-`#include "template/prototemplate/testing/xpath_matcher.h"` - - - - - - - -
`prototemplate::testing::MatchesXPath(str)` `argument` is a well-formed HTML/XML string that matches the given [XPath](http://www.w3.org/TR/xpath/#contents) expression.
- -#### Flume - -**deps:** `"//pipeline/flume/contrib:matchers"`
-`#include "pipeline/flume/contrib/matchers.h"` - - - - - - - -
`flume::testing::Kv(key_matcher, value_matcher)` `argument` is a `KV` where the key matches `key_matcher` and the value matches `value_matcher`.
- -#### i18n strings - -**deps:** `"///i18n/testing/public:expecti18n"`
-`#include "google3/i18n/testing/public/expecti18n.h"` - - - - - - - -
`i18n_testing::I18nEq(utf8)` `argument` is a `absl::string_view` whose content matches `utf8` allowing for locale data changes. - In case it does not match, the error message contains both a readable version of both strings and the list of - decoded codepoints.
diff --git a/googlemock/g3doc/includes/g3_wrap_external_api_snippet.md b/googlemock/g3doc/includes/g3_wrap_external_api_snippet.md deleted file mode 100644 index 4c3771a..0000000 --- a/googlemock/g3doc/includes/g3_wrap_external_api_snippet.md +++ /dev/null @@ -1,3 +0,0 @@ -See also the [Wrap External APIs](http://go/d4tg/wrap-external.html) chapter of -the -*[Design for Testability Guide](http://www.corp.google.com/eng/howto/testing/testability_guide/)*. diff --git a/googletest/docs/README.md b/googletest/docs/README.md new file mode 100644 index 0000000..1bc57b7 --- /dev/null +++ b/googletest/docs/README.md @@ -0,0 +1,4 @@ +# Content Moved + +We are working on updates to the GoogleTest documentation, which has moved to +the top-level [docs](../../docs) directory. diff --git a/googletest/docs/advanced.md b/googletest/docs/advanced.md deleted file mode 100644 index 7ac5a53..0000000 --- a/googletest/docs/advanced.md +++ /dev/null @@ -1,2640 +0,0 @@ -# Advanced googletest Topics - - - - - -## Introduction - -Now that you have read the [googletest Primer](primer.md) and learned how to -write tests using googletest, it's time to learn some new tricks. This document -will show you more assertions as well as how to construct complex failure -messages, propagate fatal failures, reuse and speed up your test fixtures, and -use various flags with your tests. - -## More Assertions - -This section covers some less frequently used, but still significant, -assertions. - -### Explicit Success and Failure - -These three assertions do not actually test a value or expression. Instead, they -generate a success or failure directly. Like the macros that actually perform a -test, you may stream a custom failure message into them. - -```c++ -SUCCEED(); -``` - -Generates a success. This does **NOT** make the overall test succeed. A test is -considered successful only if none of its assertions fail during its execution. - -NOTE: `SUCCEED()` is purely documentary and currently doesn't generate any -user-visible output. However, we may add `SUCCEED()` messages to googletest's -output in the future. - -```c++ -FAIL(); -ADD_FAILURE(); -ADD_FAILURE_AT("file_path", line_number); -``` - -`FAIL()` generates a fatal failure, while `ADD_FAILURE()` and `ADD_FAILURE_AT()` -generate a nonfatal failure. These are useful when control flow, rather than a -Boolean expression, determines the test's success or failure. For example, you -might want to write something like: - -```c++ -switch(expression) { - case 1: - ... some checks ... - case 2: - ... some other checks ... - default: - FAIL() << "We shouldn't get here."; -} -``` - -NOTE: you can only use `FAIL()` in functions that return `void`. See the -[Assertion Placement section](#assertion-placement) for more information. - -### Exception Assertions - -These are for verifying that a piece of code throws (or does not throw) an -exception of the given type: - -Fatal assertion | Nonfatal assertion | Verifies ------------------------------------------- | ------------------------------------------ | -------- -`ASSERT_THROW(statement, exception_type);` | `EXPECT_THROW(statement, exception_type);` | `statement` throws an exception of the given type -`ASSERT_ANY_THROW(statement);` | `EXPECT_ANY_THROW(statement);` | `statement` throws an exception of any type -`ASSERT_NO_THROW(statement);` | `EXPECT_NO_THROW(statement);` | `statement` doesn't throw any exception - -Examples: - -```c++ -ASSERT_THROW(Foo(5), bar_exception); - -EXPECT_NO_THROW({ - int n = 5; - Bar(&n); -}); -``` - -**Availability**: requires exceptions to be enabled in the build environment - -### Predicate Assertions for Better Error Messages - -Even though googletest has a rich set of assertions, they can never be complete, -as it's impossible (nor a good idea) to anticipate all scenarios a user might -run into. Therefore, sometimes a user has to use `EXPECT_TRUE()` to check a -complex expression, for lack of a better macro. This has the problem of not -showing you the values of the parts of the expression, making it hard to -understand what went wrong. As a workaround, some users choose to construct the -failure message by themselves, streaming it into `EXPECT_TRUE()`. However, this -is awkward especially when the expression has side-effects or is expensive to -evaluate. - -googletest gives you three different options to solve this problem: - -#### Using an Existing Boolean Function - -If you already have a function or functor that returns `bool` (or a type that -can be implicitly converted to `bool`), you can use it in a *predicate -assertion* to get the function arguments printed for free: - - - -| Fatal assertion | Nonfatal assertion | Verifies | -| --------------------------------- | --------------------------------- | --------------------------- | -| `ASSERT_PRED1(pred1, val1)` | `EXPECT_PRED1(pred1, val1)` | `pred1(val1)` is true | -| `ASSERT_PRED2(pred2, val1, val2)` | `EXPECT_PRED2(pred2, val1, val2)` | `pred2(val1, val2)` is true | -| `...` | `...` | `...` | - - -In the above, `predn` is an `n`-ary predicate function or functor, where `val1`, -`val2`, ..., and `valn` are its arguments. The assertion succeeds if the -predicate returns `true` when applied to the given arguments, and fails -otherwise. When the assertion fails, it prints the value of each argument. In -either case, the arguments are evaluated exactly once. - -Here's an example. Given - -```c++ -// Returns true if m and n have no common divisors except 1. -bool MutuallyPrime(int m, int n) { ... } - -const int a = 3; -const int b = 4; -const int c = 10; -``` - -the assertion - -```c++ - EXPECT_PRED2(MutuallyPrime, a, b); -``` - -will succeed, while the assertion - -```c++ - EXPECT_PRED2(MutuallyPrime, b, c); -``` - -will fail with the message - -```none -MutuallyPrime(b, c) is false, where -b is 4 -c is 10 -``` - -> NOTE: -> -> 1. If you see a compiler error "no matching function to call" when using -> `ASSERT_PRED*` or `EXPECT_PRED*`, please see -> [this](faq.md#the-compiler-complains-no-matching-function-to-call-when-i-use-assert-pred-how-do-i-fix-it) -> for how to resolve it. - -#### Using a Function That Returns an AssertionResult - -While `EXPECT_PRED*()` and friends are handy for a quick job, the syntax is not -satisfactory: you have to use different macros for different arities, and it -feels more like Lisp than C++. The `::testing::AssertionResult` class solves -this problem. - -An `AssertionResult` object represents the result of an assertion (whether it's -a success or a failure, and an associated message). You can create an -`AssertionResult` using one of these factory functions: - -```c++ -namespace testing { - -// Returns an AssertionResult object to indicate that an assertion has -// succeeded. -AssertionResult AssertionSuccess(); - -// Returns an AssertionResult object to indicate that an assertion has -// failed. -AssertionResult AssertionFailure(); - -} -``` - -You can then use the `<<` operator to stream messages to the `AssertionResult` -object. - -To provide more readable messages in Boolean assertions (e.g. `EXPECT_TRUE()`), -write a predicate function that returns `AssertionResult` instead of `bool`. For -example, if you define `IsEven()` as: - -```c++ -testing::AssertionResult IsEven(int n) { - if ((n % 2) == 0) - return testing::AssertionSuccess(); - else - return testing::AssertionFailure() << n << " is odd"; -} -``` - -instead of: - -```c++ -bool IsEven(int n) { - return (n % 2) == 0; -} -``` - -the failed assertion `EXPECT_TRUE(IsEven(Fib(4)))` will print: - -```none -Value of: IsEven(Fib(4)) - Actual: false (3 is odd) -Expected: true -``` - -instead of a more opaque - -```none -Value of: IsEven(Fib(4)) - Actual: false -Expected: true -``` - -If you want informative messages in `EXPECT_FALSE` and `ASSERT_FALSE` as well -(one third of Boolean assertions in the Google code base are negative ones), and -are fine with making the predicate slower in the success case, you can supply a -success message: - -```c++ -testing::AssertionResult IsEven(int n) { - if ((n % 2) == 0) - return testing::AssertionSuccess() << n << " is even"; - else - return testing::AssertionFailure() << n << " is odd"; -} -``` - -Then the statement `EXPECT_FALSE(IsEven(Fib(6)))` will print - -```none - Value of: IsEven(Fib(6)) - Actual: true (8 is even) - Expected: false -``` - -#### Using a Predicate-Formatter - -If you find the default message generated by `(ASSERT|EXPECT)_PRED*` and -`(ASSERT|EXPECT)_(TRUE|FALSE)` unsatisfactory, or some arguments to your -predicate do not support streaming to `ostream`, you can instead use the -following *predicate-formatter assertions* to *fully* customize how the message -is formatted: - -Fatal assertion | Nonfatal assertion | Verifies ------------------------------------------------- | ------------------------------------------------ | -------- -`ASSERT_PRED_FORMAT1(pred_format1, val1);` | `EXPECT_PRED_FORMAT1(pred_format1, val1);` | `pred_format1(val1)` is successful -`ASSERT_PRED_FORMAT2(pred_format2, val1, val2);` | `EXPECT_PRED_FORMAT2(pred_format2, val1, val2);` | `pred_format2(val1, val2)` is successful -`...` | `...` | ... - -The difference between this and the previous group of macros is that instead of -a predicate, `(ASSERT|EXPECT)_PRED_FORMAT*` take a *predicate-formatter* -(`pred_formatn`), which is a function or functor with the signature: - -```c++ -testing::AssertionResult PredicateFormattern(const char* expr1, - const char* expr2, - ... - const char* exprn, - T1 val1, - T2 val2, - ... - Tn valn); -``` - -where `val1`, `val2`, ..., and `valn` are the values of the predicate arguments, -and `expr1`, `expr2`, ..., and `exprn` are the corresponding expressions as they -appear in the source code. The types `T1`, `T2`, ..., and `Tn` can be either -value types or reference types. For example, if an argument has type `Foo`, you -can declare it as either `Foo` or `const Foo&`, whichever is appropriate. - -As an example, let's improve the failure message in `MutuallyPrime()`, which was -used with `EXPECT_PRED2()`: - -```c++ -// Returns the smallest prime common divisor of m and n, -// or 1 when m and n are mutually prime. -int SmallestPrimeCommonDivisor(int m, int n) { ... } - -// A predicate-formatter for asserting that two integers are mutually prime. -testing::AssertionResult AssertMutuallyPrime(const char* m_expr, - const char* n_expr, - int m, - int n) { - if (MutuallyPrime(m, n)) return testing::AssertionSuccess(); - - return testing::AssertionFailure() << m_expr << " and " << n_expr - << " (" << m << " and " << n << ") are not mutually prime, " - << "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n); -} -``` - -With this predicate-formatter, we can use - -```c++ - EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c); -``` - -to generate the message - -```none -b and c (4 and 10) are not mutually prime, as they have a common divisor 2. -``` - -As you may have realized, many of the built-in assertions we introduced earlier -are special cases of `(EXPECT|ASSERT)_PRED_FORMAT*`. In fact, most of them are -indeed defined using `(EXPECT|ASSERT)_PRED_FORMAT*`. - -### Floating-Point Comparison - -Comparing floating-point numbers is tricky. Due to round-off errors, it is very -unlikely that two floating-points will match exactly. Therefore, `ASSERT_EQ` 's -naive comparison usually doesn't work. And since floating-points can have a wide -value range, no single fixed error bound works. It's better to compare by a -fixed relative error bound, except for values close to 0 due to the loss of -precision there. - -In general, for floating-point comparison to make sense, the user needs to -carefully choose the error bound. If they don't want or care to, comparing in -terms of Units in the Last Place (ULPs) is a good default, and googletest -provides assertions to do this. Full details about ULPs are quite long; if you -want to learn more, see -[here](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/). - -#### Floating-Point Macros - - - -| Fatal assertion | Nonfatal assertion | Verifies | -| ------------------------------- | ------------------------------- | ---------------------------------------- | -| `ASSERT_FLOAT_EQ(val1, val2);` | `EXPECT_FLOAT_EQ(val1, val2);` | the two `float` values are almost equal | -| `ASSERT_DOUBLE_EQ(val1, val2);` | `EXPECT_DOUBLE_EQ(val1, val2);` | the two `double` values are almost equal | - - - -By "almost equal" we mean the values are within 4 ULP's from each other. - -The following assertions allow you to choose the acceptable error bound: - - - -| Fatal assertion | Nonfatal assertion | Verifies | -| ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- | -| `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 | - - - -#### Floating-Point Predicate-Format Functions - -Some floating-point operations are useful, but not that often used. In order to -avoid an explosion of new macros, we provide them as predicate-format functions -that can be used in predicate assertion macros (e.g. `EXPECT_PRED_FORMAT2`, -etc). - -```c++ -EXPECT_PRED_FORMAT2(testing::FloatLE, val1, val2); -EXPECT_PRED_FORMAT2(testing::DoubleLE, val1, val2); -``` - -Verifies that `val1` is less than, or almost equal to, `val2`. You can replace -`EXPECT_PRED_FORMAT2` in the above table with `ASSERT_PRED_FORMAT2`. - -### Asserting Using gMock Matchers - -[gMock](../../googlemock) comes with -[a library of matchers](../../googlemock/docs/cheat_sheet.md#MatcherList) for -validating arguments passed to mock objects. A gMock *matcher* is basically a -predicate that knows how to describe itself. It can be used in these assertion -macros: - - - -| Fatal assertion | Nonfatal assertion | Verifies | -| ------------------------------ | ------------------------------ | --------------------- | -| `ASSERT_THAT(value, matcher);` | `EXPECT_THAT(value, matcher);` | value matches matcher | - - - -For example, `StartsWith(prefix)` is a matcher that matches a string starting -with `prefix`, and you can write: - -```c++ -using ::testing::StartsWith; -... - // Verifies that Foo() returns a string starting with "Hello". - EXPECT_THAT(Foo(), StartsWith("Hello")); -``` - -Read this -[recipe](../../googlemock/docs/cook_book.md#using-matchers-in-googletest-assertions) -in the gMock Cookbook for more details. - -gMock has a rich set of matchers. You can do many things googletest cannot do -alone with them. For a list of matchers gMock provides, read -[this](../../googlemock/docs/cook_book.md##using-matchers). It's easy to write -your [own matchers](../../googlemock/docs/cook_book.md#NewMatchers) too. - -gMock is bundled with googletest, so you don't need to add any build dependency -in order to take advantage of this. Just include `"gmock/gmock.h"` -and you're ready to go. - -### More String Assertions - -(Please read the [previous](#asserting-using-gmock-matchers) section first if -you haven't.) - -You can use the gMock -[string matchers](../../googlemock/docs/cheat_sheet.md#string-matchers) with -`EXPECT_THAT()` or `ASSERT_THAT()` to do more string comparison tricks -(sub-string, prefix, suffix, regular expression, and etc). For example, - -```c++ -using ::testing::HasSubstr; -using ::testing::MatchesRegex; -... - ASSERT_THAT(foo_string, HasSubstr("needle")); - EXPECT_THAT(bar_string, MatchesRegex("\\w*\\d+")); -``` - -If the string contains a well-formed HTML or XML document, you can check whether -its DOM tree matches an -[XPath expression](http://www.w3.org/TR/xpath/#contents): - -```c++ -// Currently still in //template/prototemplate/testing:xpath_matcher -#include "template/prototemplate/testing/xpath_matcher.h" -using ::prototemplate::testing::MatchesXPath; -EXPECT_THAT(html_string, MatchesXPath("//a[text()='click here']")); -``` - -### Windows HRESULT assertions - -These assertions test for `HRESULT` success or failure. - -Fatal assertion | Nonfatal assertion | Verifies --------------------------------------- | -------------------------------------- | -------- -`ASSERT_HRESULT_SUCCEEDED(expression)` | `EXPECT_HRESULT_SUCCEEDED(expression)` | `expression` is a success `HRESULT` -`ASSERT_HRESULT_FAILED(expression)` | `EXPECT_HRESULT_FAILED(expression)` | `expression` is a failure `HRESULT` - -The generated output contains the human-readable error message associated with -the `HRESULT` code returned by `expression`. - -You might use them like this: - -```c++ -CComPtr shell; -ASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application")); -CComVariant empty; -ASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty)); -``` - -### Type Assertions - -You can call the function - -```c++ -::testing::StaticAssertTypeEq(); -``` - -to assert that types `T1` and `T2` are the same. The function does nothing if -the assertion is satisfied. If the types are different, the function call will -fail to compile, the compiler error message will say that -`T1 and T2 are not the same type` and most likely (depending on the compiler) -show you the actual values of `T1` and `T2`. This is mainly useful inside -template code. - -**Caveat**: When used inside a member function of a class template or a function -template, `StaticAssertTypeEq()` is effective only if the function is -instantiated. For example, given: - -```c++ -template class Foo { - public: - void Bar() { testing::StaticAssertTypeEq(); } -}; -``` - -the code: - -```c++ -void Test1() { Foo foo; } -``` - -will not generate a compiler error, as `Foo::Bar()` is never actually -instantiated. Instead, you need: - -```c++ -void Test2() { Foo foo; foo.Bar(); } -``` - -to cause a compiler error. - -### Assertion Placement - -You can use assertions in any C++ function. In particular, it doesn't have to be -a method of the test fixture class. The one constraint is that assertions that -generate a fatal failure (`FAIL*` and `ASSERT_*`) can only be used in -void-returning functions. This is a consequence of Google's not using -exceptions. By placing it in a non-void function you'll get a confusing compile -error like `"error: void value not ignored as it ought to be"` or `"cannot -initialize return object of type 'bool' with an rvalue of type 'void'"` or -`"error: no viable conversion from 'void' to 'string'"`. - -If you need to use fatal assertions in a function that returns non-void, one -option is to make the function return the value in an out parameter instead. For -example, you can rewrite `T2 Foo(T1 x)` to `void Foo(T1 x, T2* result)`. You -need to make sure that `*result` contains some sensible value even when the -function returns prematurely. As the function now returns `void`, you can use -any assertion inside of it. - -If changing the function's type is not an option, you should just use assertions -that generate non-fatal failures, such as `ADD_FAILURE*` and `EXPECT_*`. - -NOTE: Constructors and destructors are not considered void-returning functions, -according to the C++ language specification, and so you may not use fatal -assertions in them; you'll get a compilation error if you try. Instead, either -call `abort` and crash the entire test executable, or put the fatal assertion in -a `SetUp`/`TearDown` function; see -[constructor/destructor vs. `SetUp`/`TearDown`](faq.md#CtorVsSetUp) - -WARNING: A fatal assertion in a helper function (private void-returning method) -called from a constructor or destructor does not terminate the current test, as -your intuition might suggest: it merely returns from the constructor or -destructor early, possibly leaving your object in a partially-constructed or -partially-destructed state! You almost certainly want to `abort` or use -`SetUp`/`TearDown` instead. - -## Teaching googletest How to Print Your Values - -When a test assertion such as `EXPECT_EQ` fails, googletest prints the argument -values to help you debug. It does this using a user-extensible value printer. - -This printer knows how to print built-in C++ types, native arrays, STL -containers, and any type that supports the `<<` operator. For other types, it -prints the raw bytes in the value and hopes that you the user can figure it out. - -As mentioned earlier, the printer is *extensible*. That means you can teach it -to do a better job at printing your particular type than to dump the bytes. To -do that, define `<<` for your type: - -```c++ -#include - -namespace foo { - -class Bar { // We want googletest to be able to print instances of this. -... - // Create a free inline friend function. - friend std::ostream& operator<<(std::ostream& os, const Bar& bar) { - return os << bar.DebugString(); // whatever needed to print bar to os - } -}; - -// If you can't declare the function in the class it's important that the -// << operator is defined in the SAME namespace that defines Bar. C++'s look-up -// rules rely on that. -std::ostream& operator<<(std::ostream& os, const Bar& bar) { - return os << bar.DebugString(); // whatever needed to print bar to os -} - -} // namespace foo -``` - -Sometimes, this might not be an option: your team may consider it bad style to -have a `<<` operator for `Bar`, or `Bar` may already have a `<<` operator that -doesn't do what you want (and you cannot change it). If so, you can instead -define a `PrintTo()` function like this: - -```c++ -#include - -namespace foo { - -class Bar { - ... - friend void PrintTo(const Bar& bar, std::ostream* os) { - *os << bar.DebugString(); // whatever needed to print bar to os - } -}; - -// If you can't declare the function in the class it's important that PrintTo() -// is defined in the SAME namespace that defines Bar. C++'s look-up rules rely -// on that. -void PrintTo(const Bar& bar, std::ostream* os) { - *os << bar.DebugString(); // whatever needed to print bar to os -} - -} // namespace foo -``` - -If you have defined both `<<` and `PrintTo()`, the latter will be used when -googletest is concerned. This allows you to customize how the value appears in -googletest's output without affecting code that relies on the behavior of its -`<<` operator. - -If you want to print a value `x` using googletest's value printer yourself, just -call `::testing::PrintToString(x)`, which returns an `std::string`: - -```c++ -vector > bar_ints = GetBarIntVector(); - -EXPECT_TRUE(IsCorrectBarIntVector(bar_ints)) - << "bar_ints = " << testing::PrintToString(bar_ints); -``` - -## Death Tests - -In many applications, there are assertions that can cause application failure if -a condition is not met. These sanity checks, which ensure that the program is in -a known good state, are there to fail at the earliest possible time after some -program state is corrupted. If the assertion checks the wrong condition, then -the program may proceed in an erroneous state, which could lead to memory -corruption, security holes, or worse. Hence it is vitally important to test that -such assertion statements work as expected. - -Since these precondition checks cause the processes to die, we call such tests -_death tests_. More generally, any test that checks that a program terminates -(except by throwing an exception) in an expected fashion is also a death test. - -Note that if a piece of code throws an exception, we don't consider it "death" -for the purpose of death tests, as the caller of the code could catch the -exception and avoid the crash. If you want to verify exceptions thrown by your -code, see [Exception Assertions](#ExceptionAssertions). - -If you want to test `EXPECT_*()/ASSERT_*()` failures in your test code, see -Catching Failures - -### How to Write a Death Test - -googletest has the following macros to support death tests: - -Fatal assertion | Nonfatal assertion | Verifies ------------------------------------------------- | ------------------------------------------------ | -------- -`ASSERT_DEATH(statement, matcher);` | `EXPECT_DEATH(statement, matcher);` | `statement` crashes with the given error -`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 -`ASSERT_DEBUG_DEATH(statement, matcher);` | `EXPECT_DEBUG_DEATH(statement, matcher);` | `statement` crashes with the given error **in debug mode**. When not in debug (i.e. `NDEBUG` is defined), this just executes `statement` -`ASSERT_EXIT(statement, predicate, matcher);` | `EXPECT_EXIT(statement, predicate, matcher);` | `statement` exits with the given error, and its exit code matches `predicate` - -where `statement` is a statement that is expected to cause the process to die, -`predicate` is a function or function object that evaluates an integer exit -status, and `matcher` is either a gMock matcher matching a `const std::string&` -or a (Perl) regular expression - either of which is matched against the stderr -output of `statement`. For legacy reasons, a bare string (i.e. with no matcher) -is interpreted as `ContainsRegex(str)`, **not** `Eq(str)`. Note that `statement` -can be *any valid statement* (including *compound statement*) and doesn't have -to be an expression. - -As usual, the `ASSERT` variants abort the current test function, while the -`EXPECT` variants do not. - -> NOTE: We use the word "crash" here to mean that the process terminates with a -> *non-zero* exit status code. There are two possibilities: either the process -> has called `exit()` or `_exit()` with a non-zero value, or it may be killed by -> a signal. -> -> This means that if *`statement`* terminates the process with a 0 exit code, it -> is *not* considered a crash by `EXPECT_DEATH`. Use `EXPECT_EXIT` instead if -> this is the case, or if you want to restrict the exit code more precisely. - -A predicate here must accept an `int` and return a `bool`. The death test -succeeds only if the predicate returns `true`. googletest defines a few -predicates that handle the most common cases: - -```c++ -::testing::ExitedWithCode(exit_code) -``` - -This expression is `true` if the program exited normally with the given exit -code. - -```c++ -testing::KilledBySignal(signal_number) // Not available on Windows. -``` - -This expression is `true` if the program was killed by the given signal. - -The `*_DEATH` macros are convenient wrappers for `*_EXIT` that use a predicate -that verifies the process' exit code is non-zero. - -Note that a death test only cares about three things: - -1. does `statement` abort or exit the process? -2. (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 -3. does the stderr output match `matcher`? - -In particular, if `statement` generates an `ASSERT_*` or `EXPECT_*` failure, it -will **not** cause the death test to fail, as googletest assertions don't abort -the process. - -To write a death test, simply use one of the above macros inside your test -function. For example, - -```c++ -TEST(MyDeathTest, Foo) { - // This death test uses a compound statement. - ASSERT_DEATH({ - int n = 5; - Foo(&n); - }, "Error on line .* of Foo()"); -} - -TEST(MyDeathTest, NormalExit) { - EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success"); -} - -TEST(MyDeathTest, KillMyself) { - EXPECT_EXIT(KillMyself(), testing::KilledBySignal(SIGKILL), - "Sending myself unblockable signal"); -} -``` - -verifies that: - -* calling `Foo(5)` causes the process to die with the given error message, -* calling `NormalExit()` causes the process to print `"Success"` to stderr and - exit with exit code 0, and -* calling `KillMyself()` kills the process with signal `SIGKILL`. - -The test function body may contain other assertions and statements as well, if -necessary. - -### Death Test Naming - -IMPORTANT: We strongly recommend you to follow the convention of naming your -**test suite** (not test) `*DeathTest` when it contains a death test, as -demonstrated in the above example. The -[Death Tests And Threads](#death-tests-and-threads) section below explains why. - -If a test fixture class is shared by normal tests and death tests, you can use -`using` or `typedef` to introduce an alias for the fixture class and avoid -duplicating its code: - -```c++ -class FooTest : public testing::Test { ... }; - -using FooDeathTest = FooTest; - -TEST_F(FooTest, DoesThis) { - // normal test -} - -TEST_F(FooDeathTest, DoesThat) { - // death test -} -``` - -### Regular Expression Syntax - -On POSIX systems (e.g. Linux, Cygwin, and Mac), googletest uses the -[POSIX extended regular expression](http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04) -syntax. To learn about this syntax, you may want to read this -[Wikipedia entry](http://en.wikipedia.org/wiki/Regular_expression#POSIX_Extended_Regular_Expressions). - -On Windows, googletest uses its own simple regular expression implementation. It -lacks many features. For example, we don't support union (`"x|y"`), grouping -(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among -others. Below is what we do support (`A` denotes a literal character, period -(`.`), or a single `\\ ` escape sequence; `x` and `y` denote regular -expressions.): - -Expression | Meaning ----------- | -------------------------------------------------------------- -`c` | matches any literal character `c` -`\\d` | matches any decimal digit -`\\D` | matches any character that's not a decimal digit -`\\f` | matches `\f` -`\\n` | matches `\n` -`\\r` | matches `\r` -`\\s` | matches any ASCII whitespace, including `\n` -`\\S` | matches any character that's not a whitespace -`\\t` | matches `\t` -`\\v` | matches `\v` -`\\w` | matches any letter, `_`, or decimal digit -`\\W` | matches any character that `\\w` doesn't match -`\\c` | matches any literal character `c`, which must be a punctuation -`.` | matches any single character except `\n` -`A?` | matches 0 or 1 occurrences of `A` -`A*` | matches 0 or many occurrences of `A` -`A+` | matches 1 or many occurrences of `A` -`^` | matches the beginning of a string (not that of each line) -`$` | matches the end of a string (not that of each line) -`xy` | matches `x` followed by `y` - -To help you determine which capability is available on your system, googletest -defines macros to govern which regular expression it is using. The macros are: -`GTEST_USES_SIMPLE_RE=1` or `GTEST_USES_POSIX_RE=1`. If you want your death -tests to work in all cases, you can either `#if` on these macros or use the more -limited syntax only. - -### How It Works - -Under the hood, `ASSERT_EXIT()` spawns a new process and executes the death test -statement in that process. The details of how precisely that happens depend on -the platform and the variable `::testing::GTEST_FLAG(death_test_style)` (which is -initialized from the command-line flag `--gtest_death_test_style`). - -* On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the - child, after which: - * If the variable's value is `"fast"`, the death test statement is - immediately executed. - * 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. -* 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. - -Other values for the variable are illegal and will cause the death test to fail. -Currently, the flag's default value is **"fast"** - -1. the child's exit status satisfies the predicate, and -2. the child's stderr matches the regular expression. - -If the death test statement runs to completion without dying, the child process -will nonetheless terminate, and the assertion fails. - -### Death Tests And Threads - -The reason for the two death test styles has to do with thread safety. Due to -well-known problems with forking in the presence of threads, death tests should -be run in a single-threaded context. Sometimes, however, it isn't feasible to -arrange that kind of environment. For example, statically-initialized modules -may start threads before main is ever reached. Once threads have been created, -it may be difficult or impossible to clean them up. - -googletest has three features intended to raise awareness of threading issues. - -1. A warning is emitted if multiple threads are running when a death test is - encountered. -2. Test suites with a name ending in "DeathTest" are run before all other - tests. -3. 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. - -It's perfectly fine to create threads inside a death test statement; they are -executed in a separate process and cannot affect the parent. - -### Death Test Styles - -The "threadsafe" death test style was introduced in order to help mitigate the -risks of testing in a possibly multithreaded environment. It trades increased -test execution time (potentially dramatically so) for improved thread safety. - -The automated testing framework does not set the style flag. You can choose a -particular style of death tests by setting the flag programmatically: - -```c++ -testing::FLAGS_gtest_death_test_style="threadsafe" -``` - -You can do this in `main()` to set the style for all death tests in the binary, -or in individual tests. Recall that flags are saved before running each test and -restored afterwards, so you need not do that yourself. For example: - -```c++ -int main(int argc, char** argv) { - testing::InitGoogleTest(&argc, argv); - testing::FLAGS_gtest_death_test_style = "fast"; - return RUN_ALL_TESTS(); -} - -TEST(MyDeathTest, TestOne) { - testing::FLAGS_gtest_death_test_style = "threadsafe"; - // This test is run in the "threadsafe" style: - ASSERT_DEATH(ThisShouldDie(), ""); -} - -TEST(MyDeathTest, TestTwo) { - // This test is run in the "fast" style: - ASSERT_DEATH(ThisShouldDie(), ""); -} -``` - -### Caveats - -The `statement` argument of `ASSERT_EXIT()` can be any valid C++ statement. If -it leaves the current function via a `return` statement or by throwing an -exception, the death test is considered to have failed. Some googletest macros -may return from the current function (e.g. `ASSERT_TRUE()`), so be sure to avoid -them in `statement`. - -Since `statement` runs in the child process, any in-memory side effect (e.g. -modifying a variable, releasing memory, etc) it causes will *not* be observable -in the parent process. In particular, if you release memory in a death test, -your program will fail the heap check as the parent process will never see the -memory reclaimed. To solve this problem, you can - -1. try not to free memory in a death test; -2. free the memory again in the parent process; or -3. do not use the heap checker in your program. - -Due to an implementation detail, you cannot place multiple death test assertions -on the same line; otherwise, compilation will fail with an unobvious error -message. - -Despite the improved thread safety afforded by the "threadsafe" style of death -test, thread problems such as deadlock are still possible in the presence of -handlers registered with `pthread_atfork(3)`. - - -## Using Assertions in Sub-routines - -Note: If you want to put a series of test assertions in a subroutine to check -for a complex condition, consider using -[a custom GMock matcher](../../googlemock/docs/cook_book.md#NewMatchers) -instead. This lets you provide a more readable error message in case of failure -and avoid all of the issues described below. - -### Adding Traces to Assertions - -If a test sub-routine is called from several places, when an assertion inside it -fails, it can be hard to tell which invocation of the sub-routine the failure is -from. You can alleviate this problem using extra logging or custom failure -messages, but that usually clutters up your tests. A better solution is to use -the `SCOPED_TRACE` macro or the `ScopedTrace` utility: - -```c++ -SCOPED_TRACE(message); -``` -```c++ -ScopedTrace trace("file_path", line_number, message); -``` - -where `message` can be anything streamable to `std::ostream`. `SCOPED_TRACE` -macro will cause the current file name, line number, and the given message to be -added in every failure message. `ScopedTrace` accepts explicit file name and -line number in arguments, which is useful for writing test helpers. The effect -will be undone when the control leaves the current lexical scope. - -For example, - -```c++ -10: void Sub1(int n) { -11: EXPECT_EQ(Bar(n), 1); -12: EXPECT_EQ(Bar(n + 1), 2); -13: } -14: -15: TEST(FooTest, Bar) { -16: { -17: SCOPED_TRACE("A"); // This trace point will be included in -18: // every failure in this scope. -19: Sub1(1); -20: } -21: // Now it won't. -22: Sub1(9); -23: } -``` - -could result in messages like these: - -```none -path/to/foo_test.cc:11: Failure -Value of: Bar(n) -Expected: 1 - Actual: 2 -Google Test trace: -path/to/foo_test.cc:17: A - -path/to/foo_test.cc:12: Failure -Value of: Bar(n + 1) -Expected: 2 - Actual: 3 -``` - -Without the trace, it would've been difficult to know which invocation of -`Sub1()` the two failures come from respectively. (You could add an extra -message to each assertion in `Sub1()` to indicate the value of `n`, but that's -tedious.) - -Some tips on using `SCOPED_TRACE`: - -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. -2. 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. -3. 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 `""`. -4. 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. -5. The trace dump is clickable in Emacs - hit `return` on a line number and - you'll be taken to that line in the source file! - -### Propagating Fatal Failures - -A common pitfall when using `ASSERT_*` and `FAIL*` is not understanding that -when they fail they only abort the _current function_, not the entire test. For -example, the following test will segfault: - -```c++ -void Subroutine() { - // Generates a fatal failure and aborts the current function. - ASSERT_EQ(1, 2); - - // The following won't be executed. - ... -} - -TEST(FooTest, Bar) { - Subroutine(); // The intended behavior is for the fatal failure - // in Subroutine() to abort the entire test. - - // The actual behavior: the function goes on after Subroutine() returns. - int* p = nullptr; - *p = 3; // Segfault! -} -``` - -To alleviate this, googletest provides three different solutions. You could use -either exceptions, the `(ASSERT|EXPECT)_NO_FATAL_FAILURE` assertions or the -`HasFatalFailure()` function. They are described in the following two -subsections. - -#### Asserting on Subroutines with an exception - -The following code can turn ASSERT-failure into an exception: - -```c++ -class ThrowListener : public testing::EmptyTestEventListener { - void OnTestPartResult(const testing::TestPartResult& result) override { - if (result.type() == testing::TestPartResult::kFatalFailure) { - throw testing::AssertionException(result); - } - } -}; -int main(int argc, char** argv) { - ... - testing::UnitTest::GetInstance()->listeners().Append(new ThrowListener); - return RUN_ALL_TESTS(); -} -``` - -This listener should be added after other listeners if you have any, otherwise -they won't see failed `OnTestPartResult`. - -#### Asserting on Subroutines - -As shown above, if your test calls a subroutine that has an `ASSERT_*` failure -in it, the test will continue after the subroutine returns. This may not be what -you want. - -Often people want fatal failures to propagate like exceptions. For that -googletest offers the following macros: - -Fatal assertion | Nonfatal assertion | Verifies -------------------------------------- | ------------------------------------- | -------- -`ASSERT_NO_FATAL_FAILURE(statement);` | `EXPECT_NO_FATAL_FAILURE(statement);` | `statement` doesn't generate any new fatal failures in the current thread. - -Only failures in the thread that executes the assertion are checked to determine -the result of this type of assertions. If `statement` creates new threads, -failures in these threads are ignored. - -Examples: - -```c++ -ASSERT_NO_FATAL_FAILURE(Foo()); - -int i; -EXPECT_NO_FATAL_FAILURE({ - i = Bar(); -}); -``` - -Assertions from multiple threads are currently not supported on Windows. - -#### Checking for Failures in the Current Test - -`HasFatalFailure()` in the `::testing::Test` class returns `true` if an -assertion in the current test has suffered a fatal failure. This allows -functions to catch fatal failures in a sub-routine and return early. - -```c++ -class Test { - public: - ... - static bool HasFatalFailure(); -}; -``` - -The typical usage, which basically simulates the behavior of a thrown exception, -is: - -```c++ -TEST(FooTest, Bar) { - Subroutine(); - // Aborts if Subroutine() had a fatal failure. - if (HasFatalFailure()) return; - - // The following won't be executed. - ... -} -``` - -If `HasFatalFailure()` is used outside of `TEST()` , `TEST_F()` , or a test -fixture, you must add the `::testing::Test::` prefix, as in: - -```c++ -if (testing::Test::HasFatalFailure()) return; -``` - -Similarly, `HasNonfatalFailure()` returns `true` if the current test has at -least one non-fatal failure, and `HasFailure()` returns `true` if the current -test has at least one failure of either kind. - -## Logging Additional Information - -In your test code, you can call `RecordProperty("key", value)` to log additional -information, where `value` can be either a string or an `int`. The *last* value -recorded for a key will be emitted to the -[XML output](#generating-an-xml-report) if you specify one. For example, the -test - -```c++ -TEST_F(WidgetUsageTest, MinAndMaxWidgets) { - RecordProperty("MaximumWidgets", ComputeMaxUsage()); - RecordProperty("MinimumWidgets", ComputeMinUsage()); -} -``` - -will output XML like this: - -```xml - ... - - ... -``` - -> NOTE: -> -> * `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. -> * *`key`* must be a valid XML attribute name, and cannot conflict with the -> ones already used by googletest (`name`, `status`, `time`, `classname`, -> `type_param`, and `value_param`). -> * Calling `RecordProperty()` outside of the lifespan of a test is allowed. -> If it's called outside of a test but between a test suite's -> `SetUpTestSuite()` and `TearDownTestSuite()` methods, it will be -> attributed to the XML element for the test suite. If it's called outside -> of all test suites (e.g. in a test environment), it will be attributed to -> the top-level XML element. - -## Sharing Resources Between Tests in the Same Test Suite - -googletest creates a new test fixture object for each test in order to make -tests independent and easier to debug. However, sometimes tests use resources -that are expensive to set up, making the one-copy-per-test model prohibitively -expensive. - -If the tests don't change the resource, there's no harm in their sharing a -single resource copy. So, in addition to per-test set-up/tear-down, googletest -also supports per-test-suite set-up/tear-down. To use it: - -1. In your test fixture class (say `FooTest` ), declare as `static` some member - variables to hold the shared resources. -2. Outside your test fixture class (typically just below it), define those - member variables, optionally giving them initial values. -3. In the same test fixture class, define a `static void SetUpTestSuite()` - function (remember not to spell it as **`SetupTestSuite`** with a small - `u`!) to set up the shared resources and a `static void TearDownTestSuite()` - function to tear them down. - -That's it! googletest automatically calls `SetUpTestSuite()` before running the -*first test* in the `FooTest` test suite (i.e. before creating the first -`FooTest` object), and calls `TearDownTestSuite()` after running the *last test* -in it (i.e. after deleting the last `FooTest` object). In between, the tests can -use the shared resources. - -Remember that the test order is undefined, so your code can't depend on a test -preceding or following another. Also, the tests must either not modify the state -of any shared resource, or, if they do modify the state, they must restore the -state to its original value before passing control to the next test. - -Here's an example of per-test-suite set-up and tear-down: - -```c++ -class FooTest : public testing::Test { - protected: - // Per-test-suite set-up. - // Called before the first test in this test suite. - // Can be omitted if not needed. - static void SetUpTestSuite() { - shared_resource_ = new ...; - } - - // Per-test-suite tear-down. - // Called after the last test in this test suite. - // Can be omitted if not needed. - static void TearDownTestSuite() { - delete shared_resource_; - shared_resource_ = nullptr; - } - - // You can define per-test set-up logic as usual. - virtual void SetUp() { ... } - - // You can define per-test tear-down logic as usual. - virtual void TearDown() { ... } - - // Some expensive resource shared by all tests. - static T* shared_resource_; -}; - -T* FooTest::shared_resource_ = nullptr; - -TEST_F(FooTest, Test1) { - ... you can refer to shared_resource_ here ... -} - -TEST_F(FooTest, Test2) { - ... you can refer to shared_resource_ here ... -} -``` - -NOTE: Though the above code declares `SetUpTestSuite()` protected, it may -sometimes be necessary to declare it public, such as when using it with -`TEST_P`. - -## Global Set-Up and Tear-Down - -Just as you can do set-up and tear-down at the test level and the test suite -level, you can also do it at the test program level. Here's how. - -First, you subclass the `::testing::Environment` class to define a test -environment, which knows how to set-up and tear-down: - -```c++ -class Environment : public testing::Environment { - public: - ~Environment() override {} - - // Override this to define how to set up the environment. - void SetUp() override {} - - // Override this to define how to tear down the environment. - void TearDown() override {} -}; -``` - -Then, you register an instance of your environment class with googletest by -calling the `::testing::AddGlobalTestEnvironment()` function: - -```c++ -Environment* AddGlobalTestEnvironment(Environment* env); -``` - -Now, when `RUN_ALL_TESTS()` is called, it first calls the `SetUp()` method of -each environment object, then runs the tests if none of the environments -reported fatal failures and `GTEST_SKIP()` was not called. `RUN_ALL_TESTS()` -always calls `TearDown()` with each environment object, regardless of whether or -not the tests were run. - -It's OK to register multiple environment objects. In this suite, their `SetUp()` -will be called in the order they are registered, and their `TearDown()` will be -called in the reverse order. - -Note that googletest takes ownership of the registered environment objects. -Therefore **do not delete them** by yourself. - -You should call `AddGlobalTestEnvironment()` before `RUN_ALL_TESTS()` is called, -probably in `main()`. If you use `gtest_main`, you need to call this before -`main()` starts for it to take effect. One way to do this is to define a global -variable like this: - -```c++ -testing::Environment* const foo_env = - testing::AddGlobalTestEnvironment(new FooEnvironment); -``` - -However, we strongly recommend you to write your own `main()` and call -`AddGlobalTestEnvironment()` there, as relying on initialization of global -variables makes the code harder to read and may cause problems when you register -multiple environments from different translation units and the environments have -dependencies among them (remember that the compiler doesn't guarantee the order -in which global variables from different translation units are initialized). - -## Value-Parameterized Tests - -*Value-parameterized tests* allow you to test your code with different -parameters without writing multiple copies of the same test. This is useful in a -number of situations, for example: - -* You have a piece of code whose behavior is affected by one or more - command-line flags. You want to make sure your code performs correctly for - various values of those flags. -* You want to test different implementations of an OO interface. -* 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! - -### How to Write Value-Parameterized Tests - -To write value-parameterized tests, first you should define a fixture class. It -must be derived from both `testing::Test` and `testing::WithParamInterface` -(the latter is a pure interface), where `T` is the type of your parameter -values. For convenience, you can just derive the fixture class from -`testing::TestWithParam`, which itself is derived from both `testing::Test` -and `testing::WithParamInterface`. `T` can be any copyable type. If it's a -raw pointer, you are responsible for managing the lifespan of the pointed -values. - -NOTE: If your test fixture defines `SetUpTestSuite()` or `TearDownTestSuite()` -they must be declared **public** rather than **protected** in order to use -`TEST_P`. - -```c++ -class FooTest : - public testing::TestWithParam { - // You can implement all the usual fixture class members here. - // To access the test parameter, call GetParam() from class - // TestWithParam. -}; - -// Or, when you want to add parameters to a pre-existing fixture class: -class BaseTest : public testing::Test { - ... -}; -class BarTest : public BaseTest, - public testing::WithParamInterface { - ... -}; -``` - -Then, use the `TEST_P` macro to define as many test patterns using this fixture -as you want. The `_P` suffix is for "parameterized" or "pattern", whichever you -prefer to think. - -```c++ -TEST_P(FooTest, DoesBlah) { - // Inside a test, access the test parameter with the GetParam() method - // of the TestWithParam class: - EXPECT_TRUE(foo.Blah(GetParam())); - ... -} - -TEST_P(FooTest, HasBlahBlah) { - ... -} -``` - -Finally, you can use `INSTANTIATE_TEST_SUITE_P` to instantiate the test suite -with any set of parameters you want. googletest defines a number of functions -for generating test parameters. They return what we call (surprise!) *parameter -generators*. Here is a summary of them, which are all in the `testing` -namespace: - - - -| Parameter Generator | Behavior | -| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -| `Range(begin, end [, step])` | Yields values `{begin, begin+step, begin+step+step, ...}`. The values do not include `end`. `step` defaults to 1. | -| `Values(v1, v2, ..., vN)` | Yields values `{v1, v2, ..., vN}`. | -| `ValuesIn(container)` and `ValuesIn(begin,end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)` | -| `Bool()` | Yields sequence `{false, true}`. | -| `Combine(g1, g2, ..., gN)` | Yields all combinations (Cartesian product) as std\:\:tuples of the values generated by the `N` generators. | - - - -For more details, see the comments at the definitions of these functions. - -The following statement will instantiate tests from the `FooTest` test suite -each with parameter values `"meeny"`, `"miny"`, and `"moe"`. - -```c++ -INSTANTIATE_TEST_SUITE_P(InstantiationName, - FooTest, - testing::Values("meeny", "miny", "moe")); -``` - -NOTE: The code above must be placed at global or namespace scope, not at -function scope. - -Per default, every `TEST_P` without a corresponding `INSTANTIATE_TEST_SUITE_P` -causes a failing test in test suite `GoogleTestVerification`. If you have a test -suite where that omission is not an error, for example it is in a library that -may be linked in for other reason or where the list of test cases is dynamic and -may be empty, then this check can be suppressed by tagging the test suite: - -```c++ -GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST(FooTest); -``` - -To distinguish different instances of the pattern (yes, you can instantiate it -more than once), the first argument to `INSTANTIATE_TEST_SUITE_P` is a prefix -that will be added to the actual test suite name. Remember to pick unique -prefixes for different instantiations. The tests from the instantiation above -will have these names: - -* `InstantiationName/FooTest.DoesBlah/0` for `"meeny"` -* `InstantiationName/FooTest.DoesBlah/1` for `"miny"` -* `InstantiationName/FooTest.DoesBlah/2` for `"moe"` -* `InstantiationName/FooTest.HasBlahBlah/0` for `"meeny"` -* `InstantiationName/FooTest.HasBlahBlah/1` for `"miny"` -* `InstantiationName/FooTest.HasBlahBlah/2` for `"moe"` - -You can use these names in [`--gtest_filter`](#running-a-subset-of-the-tests). - -This statement will instantiate all tests from `FooTest` again, each with -parameter values `"cat"` and `"dog"`: - -```c++ -const char* pets[] = {"cat", "dog"}; -INSTANTIATE_TEST_SUITE_P(AnotherInstantiationName, FooTest, - testing::ValuesIn(pets)); -``` - -The tests from the instantiation above will have these names: - -* `AnotherInstantiationName/FooTest.DoesBlah/0` for `"cat"` -* `AnotherInstantiationName/FooTest.DoesBlah/1` for `"dog"` -* `AnotherInstantiationName/FooTest.HasBlahBlah/0` for `"cat"` -* `AnotherInstantiationName/FooTest.HasBlahBlah/1` for `"dog"` - -Please note that `INSTANTIATE_TEST_SUITE_P` will instantiate *all* tests in the -given test suite, whether their definitions come before or *after* the -`INSTANTIATE_TEST_SUITE_P` statement. - -You can see [sample7_unittest.cc] and [sample8_unittest.cc] for more examples. - -[sample7_unittest.cc]: ../googletest/samples/sample7_unittest.cc "Parameterized Test example" -[sample8_unittest.cc]: ../googletest/samples/sample8_unittest.cc "Parameterized Test example with multiple parameters" - -### Creating Value-Parameterized Abstract Tests - -In the above, we define and instantiate `FooTest` in the *same* source file. -Sometimes you may want to define value-parameterized tests in a library and let -other people instantiate them later. This pattern is known as *abstract tests*. -As an example of its application, when you are designing an interface you can -write a standard suite of abstract tests (perhaps using a factory function as -the test parameter) that all implementations of the interface are expected to -pass. When someone implements the interface, they can instantiate your suite to -get all the interface-conformance tests for free. - -To define abstract tests, you should organize your code like this: - -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. -2. Put the `TEST_P` definitions in `foo_param_test.cc`, which includes - `foo_param_test.h`. Think of this as *implementing* your abstract tests. - -Once they are defined, you can instantiate them by including `foo_param_test.h`, -invoking `INSTANTIATE_TEST_SUITE_P()`, and depending on the library target that -contains `foo_param_test.cc`. You can instantiate the same abstract test suite -multiple times, possibly in different source files. - -### Specifying Names for Value-Parameterized Test Parameters - -The optional last argument to `INSTANTIATE_TEST_SUITE_P()` allows the user to -specify a function or functor that generates custom test name suffixes based on -the test parameters. The function should accept one argument of type -`testing::TestParamInfo`, and return `std::string`. - -`testing::PrintToStringParamName` is a builtin test suffix generator that -returns the value of `testing::PrintToString(GetParam())`. It does not work for -`std::string` or C strings. - -NOTE: test names must be non-empty, unique, and may only contain ASCII -alphanumeric characters. In particular, they -[should not contain underscores](faq.md#why-should-test-suite-names-and-test-names-not-contain-underscore) - -```c++ -class MyTestSuite : public testing::TestWithParam {}; - -TEST_P(MyTestSuite, MyTest) -{ - std::cout << "Example Test Param: " << GetParam() << std::endl; -} - -INSTANTIATE_TEST_SUITE_P(MyGroup, MyTestSuite, testing::Range(0, 10), - testing::PrintToStringParamName()); -``` - -Providing a custom functor allows for more control over test parameter name -generation, especially for types where the automatic conversion does not -generate helpful parameter names (e.g. strings as demonstrated above). The -following example illustrates this for multiple parameters, an enumeration type -and a string, and also demonstrates how to combine generators. It uses a lambda -for conciseness: - -```c++ -enum class MyType { MY_FOO = 0, MY_BAR = 1 }; - -class MyTestSuite : public testing::TestWithParam> { -}; - -INSTANTIATE_TEST_SUITE_P( - MyGroup, MyTestSuite, - testing::Combine( - testing::Values(MyType::VALUE_0, MyType::VALUE_1), - testing::ValuesIn("", "")), - [](const testing::TestParamInfo& info) { - std::string name = absl::StrCat( - std::get<0>(info.param) == MY_FOO ? "Foo" : "Bar", "_", - std::get<1>(info.param)); - absl::c_replace_if(name, [](char c) { return !std::isalnum(c); }, '_'); - return name; - }); -``` - -## Typed Tests - -Suppose you have multiple implementations of the same interface and want to make -sure that all of them satisfy some common requirements. Or, you may have defined -several types that are supposed to conform to the same "concept" and you want to -verify it. In both cases, you want the same test logic repeated for different -types. - -While you can write one `TEST` or `TEST_F` for each type you want to test (and -you may even factor the test logic into a function template that you invoke from -the `TEST`), it's tedious and doesn't scale: if you want `m` tests over `n` -types, you'll end up writing `m*n` `TEST`s. - -*Typed tests* allow you to repeat the same test logic over a list of types. You -only need to write the test logic once, although you must know the type list -when writing typed tests. Here's how you do it: - -First, define a fixture class template. It should be parameterized by a type. -Remember to derive it from `::testing::Test`: - -```c++ -template -class FooTest : public testing::Test { - public: - ... - using List = std::list; - static T shared_; - T value_; -}; -``` - -Next, associate a list of types with the test suite, which will be repeated for -each type in the list: - -```c++ -using MyTypes = ::testing::Types; -TYPED_TEST_SUITE(FooTest, MyTypes); -``` - -The type alias (`using` or `typedef`) is necessary for the `TYPED_TEST_SUITE` -macro to parse correctly. Otherwise the compiler will think that each comma in -the type list introduces a new macro argument. - -Then, use `TYPED_TEST()` instead of `TEST_F()` to define a typed test for this -test suite. You can repeat this as many times as you want: - -```c++ -TYPED_TEST(FooTest, DoesBlah) { - // Inside a test, refer to the special name TypeParam to get the type - // parameter. Since we are inside a derived class template, C++ requires - // us to visit the members of FooTest via 'this'. - TypeParam n = this->value_; - - // To visit static members of the fixture, add the 'TestFixture::' - // prefix. - n += TestFixture::shared_; - - // To refer to typedefs in the fixture, add the 'typename TestFixture::' - // prefix. The 'typename' is required to satisfy the compiler. - typename TestFixture::List values; - - values.push_back(n); - ... -} - -TYPED_TEST(FooTest, HasPropertyA) { ... } -``` - -You can see [sample6_unittest.cc] for a complete example. - -[sample6_unittest.cc]: ../googletest/samples/sample6_unittest.cc "Typed Test example" - -## Type-Parameterized Tests - -*Type-parameterized tests* are like typed tests, except that they don't require -you to know the list of types ahead of time. Instead, you can define the test -logic first and instantiate it with different type lists later. You can even -instantiate it more than once in the same program. - -If you are designing an interface or concept, you can define a suite of -type-parameterized tests to verify properties that any valid implementation of -the interface/concept should have. Then, the author of each implementation can -just instantiate the test suite with their type to verify that it conforms to -the requirements, without having to write similar tests repeatedly. Here's an -example: - -First, define a fixture class template, as we did with typed tests: - -```c++ -template -class FooTest : public testing::Test { - ... -}; -``` - -Next, declare that you will define a type-parameterized test suite: - -```c++ -TYPED_TEST_SUITE_P(FooTest); -``` - -Then, use `TYPED_TEST_P()` to define a type-parameterized test. You can repeat -this as many times as you want: - -```c++ -TYPED_TEST_P(FooTest, DoesBlah) { - // Inside a test, refer to TypeParam to get the type parameter. - TypeParam n = 0; - ... -} - -TYPED_TEST_P(FooTest, HasPropertyA) { ... } -``` - -Now the tricky part: you need to register all test patterns using the -`REGISTER_TYPED_TEST_SUITE_P` macro before you can instantiate them. The first -argument of the macro is the test suite name; the rest are the names of the -tests in this test suite: - -```c++ -REGISTER_TYPED_TEST_SUITE_P(FooTest, - DoesBlah, HasPropertyA); -``` - -Finally, you are free to instantiate the pattern with the types you want. If you -put the above code in a header file, you can `#include` it in multiple C++ -source files and instantiate it multiple times. - -```c++ -using MyTypes = ::testing::Types; -INSTANTIATE_TYPED_TEST_SUITE_P(My, FooTest, MyTypes); -``` - -To distinguish different instances of the pattern, the first argument to the -`INSTANTIATE_TYPED_TEST_SUITE_P` macro is a prefix that will be added to the -actual test suite name. Remember to pick unique prefixes for different -instances. - -In the special case where the type list contains only one type, you can write -that type directly without `::testing::Types<...>`, like this: - -```c++ -INSTANTIATE_TYPED_TEST_SUITE_P(My, FooTest, int); -``` - -You can see [sample6_unittest.cc] for a complete example. - -## Testing Private Code - -If you change your software's internal implementation, your tests should not -break as long as the change is not observable by users. Therefore, **per the -black-box testing principle, most of the time you should test your code through -its public interfaces.** - -**If you still find yourself needing to test internal implementation code, -consider if there's a better design.** The desire to test internal -implementation is often a sign that the class is doing too much. Consider -extracting an implementation class, and testing it. Then use that implementation -class in the original class. - -If you absolutely have to test non-public interface code though, you can. There -are two cases to consider: - -* Static functions ( *not* the same as static member functions!) or unnamed - namespaces, and -* Private or protected class members - -To test them, we use the following special techniques: - -* Both static functions and definitions/declarations in an unnamed namespace - are only visible within the same translation unit. To test them, you can - `#include` the entire `.cc` file being tested in your `*_test.cc` file. - (#including `.cc` files is not a good way to reuse code - you should not do - this in production code!) - - However, a better approach is to move the private code into the - `foo::internal` namespace, where `foo` is the namespace your project - normally uses, and put the private declarations in a `*-internal.h` file. - Your production `.cc` files and your tests are allowed to include this - internal header, but your clients are not. This way, you can fully test your - internal implementation without leaking it to your clients. - -* Private class members are only accessible from within the class or by - friends. To access a class' private members, you can declare your test - fixture as a friend to the class and define accessors in your fixture. Tests - using the fixture can then access the private members of your production - class via the accessors in the fixture. Note that even though your fixture - is a friend to your production class, your tests are not automatically - friends to it, as they are technically defined in sub-classes of the - fixture. - - Another way to test private members is to refactor them into an - implementation class, which is then declared in a `*-internal.h` file. Your - clients aren't allowed to include this header but your tests can. Such is - called the - [Pimpl](https://www.gamedev.net/articles/programming/general-and-gameplay-programming/the-c-pimpl-r1794/) - (Private Implementation) idiom. - - Or, you can declare an individual test as a friend of your class by adding - this line in the class body: - - ```c++ - FRIEND_TEST(TestSuiteName, TestName); - ``` - - For example, - - ```c++ - // foo.h - class Foo { - ... - private: - FRIEND_TEST(FooTest, BarReturnsZeroOnNull); - - int Bar(void* x); - }; - - // foo_test.cc - ... - TEST(FooTest, BarReturnsZeroOnNull) { - Foo foo; - EXPECT_EQ(foo.Bar(NULL), 0); // Uses Foo's private member Bar(). - } - ``` - - Pay special attention when your class is defined in a namespace, as you - should define your test fixtures and tests in the same namespace if you want - them to be friends of your class. For example, if the code to be tested - looks like: - - ```c++ - namespace my_namespace { - - class Foo { - friend class FooTest; - FRIEND_TEST(FooTest, Bar); - FRIEND_TEST(FooTest, Baz); - ... definition of the class Foo ... - }; - - } // namespace my_namespace - ``` - - Your test code should be something like: - - ```c++ - namespace my_namespace { - - class FooTest : public testing::Test { - protected: - ... - }; - - TEST_F(FooTest, Bar) { ... } - TEST_F(FooTest, Baz) { ... } - - } // namespace my_namespace - ``` - -## "Catching" Failures - -If you are building a testing utility on top of googletest, you'll want to test -your utility. What framework would you use to test it? googletest, of course. - -The challenge is to verify that your testing utility reports failures correctly. -In frameworks that report a failure by throwing an exception, you could catch -the exception and assert on it. But googletest doesn't use exceptions, so how do -we test that a piece of code generates an expected failure? - -`"gtest/gtest-spi.h"` contains some constructs to do this. After #including this header, -you can use - -```c++ - EXPECT_FATAL_FAILURE(statement, substring); -``` - -to assert that `statement` generates a fatal (e.g. `ASSERT_*`) failure in the -current thread whose message contains the given `substring`, or use - -```c++ - EXPECT_NONFATAL_FAILURE(statement, substring); -``` - -if you are expecting a non-fatal (e.g. `EXPECT_*`) failure. - -Only failures in the current thread are checked to determine the result of this -type of expectations. If `statement` creates new threads, failures in these -threads are also ignored. If you want to catch failures in other threads as -well, use one of the following macros instead: - -```c++ - EXPECT_FATAL_FAILURE_ON_ALL_THREADS(statement, substring); - EXPECT_NONFATAL_FAILURE_ON_ALL_THREADS(statement, substring); -``` - -NOTE: Assertions from multiple threads are currently not supported on Windows. - -For technical reasons, there are some caveats: - -1. You cannot stream a failure message to either macro. - -2. `statement` in `EXPECT_FATAL_FAILURE{_ON_ALL_THREADS}()` cannot reference - local non-static variables or non-static members of `this` object. - -3. `statement` in `EXPECT_FATAL_FAILURE{_ON_ALL_THREADS}()` cannot return a - value. - -## Registering tests programmatically - -The `TEST` macros handle the vast majority of all use cases, but there are few -where runtime registration logic is required. For those cases, the framework -provides the `::testing::RegisterTest` that allows callers to register arbitrary -tests dynamically. - -This is an advanced API only to be used when the `TEST` macros are insufficient. -The macros should be preferred when possible, as they avoid most of the -complexity of calling this function. - -It provides the following signature: - -```c++ -template -TestInfo* RegisterTest(const char* test_suite_name, const char* test_name, - const char* type_param, const char* value_param, - const char* file, int line, Factory factory); -``` - -The `factory` argument is a factory callable (move-constructible) object or -function pointer that creates a new instance of the Test object. It handles -ownership to the caller. The signature of the callable is `Fixture*()`, where -`Fixture` is the test fixture class for the test. All tests registered with the -same `test_suite_name` must return the same fixture type. This is checked at -runtime. - -The framework will infer the fixture class from the factory and will call the -`SetUpTestSuite` and `TearDownTestSuite` for it. - -Must be called before `RUN_ALL_TESTS()` is invoked, otherwise behavior is -undefined. - -Use case example: - -```c++ -class MyFixture : public testing::Test { - public: - // All of these optional, just like in regular macro usage. - static void SetUpTestSuite() { ... } - static void TearDownTestSuite() { ... } - void SetUp() override { ... } - void TearDown() override { ... } -}; - -class MyTest : public MyFixture { - public: - explicit MyTest(int data) : data_(data) {} - void TestBody() override { ... } - - private: - int data_; -}; - -void RegisterMyTests(const std::vector& values) { - for (int v : values) { - testing::RegisterTest( - "MyFixture", ("Test" + std::to_string(v)).c_str(), nullptr, - std::to_string(v).c_str(), - __FILE__, __LINE__, - // Important to use the fixture type as the return type here. - [=]() -> MyFixture* { return new MyTest(v); }); - } -} -... -int main(int argc, char** argv) { - std::vector values_to_test = LoadValuesFromConfig(); - RegisterMyTests(values_to_test); - ... - return RUN_ALL_TESTS(); -} -``` -## Getting the Current Test's Name - -Sometimes a function may need to know the name of the currently running test. -For example, you may be using the `SetUp()` method of your test fixture to set -the golden file name based on which test is running. The `::testing::TestInfo` -class has this information: - -```c++ -namespace testing { - -class TestInfo { - public: - // Returns the test suite name and the test name, respectively. - // - // Do NOT delete or free the return value - it's managed by the - // TestInfo class. - const char* test_suite_name() const; - const char* name() const; -}; - -} -``` - -To obtain a `TestInfo` object for the currently running test, call -`current_test_info()` on the `UnitTest` singleton object: - -```c++ - // Gets information about the currently running test. - // Do NOT delete the returned object - it's managed by the UnitTest class. - const testing::TestInfo* const test_info = - testing::UnitTest::GetInstance()->current_test_info(); - - printf("We are in test %s of test suite %s.\n", - test_info->name(), - test_info->test_suite_name()); -``` - -`current_test_info()` returns a null pointer if no test is running. In -particular, you cannot find the test suite name in `SetUpTestSuite()`, -`TearDownTestSuite()` (where you know the test suite name implicitly), or -functions called from them. - -## Extending googletest by Handling Test Events - -googletest provides an **event listener API** to let you receive notifications -about the progress of a test program and test failures. The events you can -listen to include the start and end of the test program, a test suite, or a test -method, among others. You may use this API to augment or replace the standard -console output, replace the XML output, or provide a completely different form -of output, such as a GUI or a database. You can also use test events as -checkpoints to implement a resource leak checker, for example. - -### Defining Event Listeners - -To define a event listener, you subclass either testing::TestEventListener or -testing::EmptyTestEventListener The former is an (abstract) interface, where -*each pure virtual method can be overridden to handle a test event* (For -example, when a test starts, the `OnTestStart()` method will be called.). The -latter provides an empty implementation of all methods in the interface, such -that a subclass only needs to override the methods it cares about. - -When an event is fired, its context is passed to the handler function as an -argument. The following argument types are used: - -* UnitTest reflects the state of the entire test program, -* TestSuite has information about a test suite, which can contain one or more - tests, -* TestInfo contains the state of a test, and -* TestPartResult represents the result of a test assertion. - -An event handler function can examine the argument it receives to find out -interesting information about the event and the test program's state. - -Here's an example: - -```c++ - class MinimalistPrinter : public testing::EmptyTestEventListener { - // Called before a test starts. - virtual void OnTestStart(const testing::TestInfo& test_info) { - printf("*** Test %s.%s starting.\n", - test_info.test_suite_name(), test_info.name()); - } - - // Called after a failed assertion or a SUCCESS(). - virtual void OnTestPartResult(const testing::TestPartResult& test_part_result) { - printf("%s in %s:%d\n%s\n", - test_part_result.failed() ? "*** Failure" : "Success", - test_part_result.file_name(), - test_part_result.line_number(), - test_part_result.summary()); - } - - // Called after a test ends. - virtual void OnTestEnd(const testing::TestInfo& test_info) { - printf("*** Test %s.%s ending.\n", - test_info.test_suite_name(), test_info.name()); - } - }; -``` - -### Using Event Listeners - -To use the event listener you have defined, add an instance of it to the -googletest event listener list (represented by class TestEventListeners - note -the "s" at the end of the name) in your `main()` function, before calling -`RUN_ALL_TESTS()`: - -```c++ -int main(int argc, char** argv) { - testing::InitGoogleTest(&argc, argv); - // Gets hold of the event listener list. - testing::TestEventListeners& listeners = - testing::UnitTest::GetInstance()->listeners(); - // Adds a listener to the end. googletest takes the ownership. - listeners.Append(new MinimalistPrinter); - return RUN_ALL_TESTS(); -} -``` - -There's only one problem: the default test result printer is still in effect, so -its output will mingle with the output from your minimalist printer. To suppress -the default printer, just release it from the event listener list and delete it. -You can do so by adding one line: - -```c++ - ... - delete listeners.Release(listeners.default_result_printer()); - listeners.Append(new MinimalistPrinter); - return RUN_ALL_TESTS(); -``` - -Now, sit back and enjoy a completely different output from your tests. For more -details, see [sample9_unittest.cc]. - -[sample9_unittest.cc]: ../googletest/samples/sample9_unittest.cc "Event listener example" - -You may append more than one listener to the list. When an `On*Start()` or -`OnTestPartResult()` event is fired, the listeners will receive it in the order -they appear in the list (since new listeners are added to the end of the list, -the default text printer and the default XML generator will receive the event -first). An `On*End()` event will be received by the listeners in the *reverse* -order. This allows output by listeners added later to be framed by output from -listeners added earlier. - -### Generating Failures in Listeners - -You may use failure-raising macros (`EXPECT_*()`, `ASSERT_*()`, `FAIL()`, etc) -when processing an event. There are some restrictions: - -1. You cannot generate any failure in `OnTestPartResult()` (otherwise it will - cause `OnTestPartResult()` to be called recursively). -2. A listener that handles `OnTestPartResult()` is not allowed to generate any - failure. - -When you add listeners to the listener list, you should put listeners that -handle `OnTestPartResult()` *before* listeners that can generate failures. This -ensures that failures generated by the latter are attributed to the right test -by the former. - -See [sample10_unittest.cc] for an example of a failure-raising listener. - -[sample10_unittest.cc]: ../googletest/samples/sample10_unittest.cc "Failure-raising listener example" - -## Running Test Programs: Advanced Options - -googletest test programs are ordinary executables. Once built, you can run them -directly and affect their behavior via the following environment variables -and/or command line flags. For the flags to work, your programs must call -`::testing::InitGoogleTest()` before calling `RUN_ALL_TESTS()`. - -To see a list of supported flags and their usage, please run your test program -with the `--help` flag. You can also use `-h`, `-?`, or `/?` for short. - -If an option is specified both by an environment variable and by a flag, the -latter takes precedence. - -### Selecting Tests - -#### Listing Test Names - -Sometimes it is necessary to list the available tests in a program before -running them so that a filter may be applied if needed. Including the flag -`--gtest_list_tests` overrides all other flags and lists tests in the following -format: - -```none -TestSuite1. - TestName1 - TestName2 -TestSuite2. - TestName -``` - -None of the tests listed are actually run if the flag is provided. There is no -corresponding environment variable for this flag. - -#### Running a Subset of the Tests - -By default, a googletest program runs all tests the user has defined. Sometimes, -you want to run only a subset of the tests (e.g. for debugging or quickly -verifying a change). If you set the `GTEST_FILTER` environment variable or the -`--gtest_filter` flag to a filter string, googletest will only run the tests -whose full names (in the form of `TestSuiteName.TestName`) match the filter. - -The format of a filter is a '`:`'-separated list of wildcard patterns (called -the *positive patterns*) optionally followed by a '`-`' and another -'`:`'-separated pattern list (called the *negative patterns*). A test matches -the filter if and only if it matches any of the positive patterns but does not -match any of the negative patterns. - -A pattern may contain `'*'` (matches any string) or `'?'` (matches any single -character). For convenience, the filter `'*-NegativePatterns'` can be also -written as `'-NegativePatterns'`. - -For example: - -* `./foo_test` Has no flag, and thus runs all its tests. -* `./foo_test --gtest_filter=*` Also runs everything, due to the single - match-everything `*` value. -* `./foo_test --gtest_filter=FooTest.*` Runs everything in test suite - `FooTest` . -* `./foo_test --gtest_filter=*Null*:*Constructor*` Runs any test whose full - name contains either `"Null"` or `"Constructor"` . -* `./foo_test --gtest_filter=-*DeathTest.*` Runs all non-death tests. -* `./foo_test --gtest_filter=FooTest.*-FooTest.Bar` Runs everything in test - suite `FooTest` except `FooTest.Bar`. -* `./foo_test --gtest_filter=FooTest.*:BarTest.*-FooTest.Bar:BarTest.Foo` Runs - everything in test suite `FooTest` except `FooTest.Bar` and everything in - test suite `BarTest` except `BarTest.Foo`. - -#### Stop test execution upon first failure - -By default, a googletest program runs all tests the user has defined. In some -cases (e.g. iterative test development & execution) it may be desirable stop -test execution upon first failure (trading improved latency for completeness). -If `GTEST_FAIL_FAST` environment variable or `--gtest_fail_fast` flag is set, -the test runner will stop execution as soon as the first test failure is -found. - -#### Temporarily Disabling Tests - -If you have a broken test that you cannot fix right away, you can add the -`DISABLED_` prefix to its name. This will exclude it from execution. This is -better than commenting out the code or using `#if 0`, as disabled tests are -still compiled (and thus won't rot). - -If you need to disable all tests in a test suite, you can either add `DISABLED_` -to the front of the name of each test, or alternatively add it to the front of -the test suite name. - -For example, the following tests won't be run by googletest, even though they -will still be compiled: - -```c++ -// Tests that Foo does Abc. -TEST(FooTest, DISABLED_DoesAbc) { ... } - -class DISABLED_BarTest : public testing::Test { ... }; - -// Tests that Bar does Xyz. -TEST_F(DISABLED_BarTest, DoesXyz) { ... } -``` - -NOTE: This feature should only be used for temporary pain-relief. You still have -to fix the disabled tests at a later date. As a reminder, googletest will print -a banner warning you if a test program contains any disabled tests. - -TIP: You can easily count the number of disabled tests you have using `gsearch` -and/or `grep`. This number can be used as a metric for improving your test -quality. - -#### Temporarily Enabling Disabled Tests - -To include disabled tests in test execution, just invoke the test program with -the `--gtest_also_run_disabled_tests` flag or set the -`GTEST_ALSO_RUN_DISABLED_TESTS` environment variable to a value other than `0`. -You can combine this with the `--gtest_filter` flag to further select which -disabled tests to run. - -### Repeating the Tests - -Once in a while you'll run into a test whose result is hit-or-miss. Perhaps it -will fail only 1% of the time, making it rather hard to reproduce the bug under -a debugger. This can be a major source of frustration. - -The `--gtest_repeat` flag allows you to repeat all (or selected) test methods in -a program many times. Hopefully, a flaky test will eventually fail and give you -a chance to debug. Here's how to use it: - -```none -$ foo_test --gtest_repeat=1000 -Repeat foo_test 1000 times and don't stop at failures. - -$ foo_test --gtest_repeat=-1 -A negative count means repeating forever. - -$ 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 test -fails, it will drop into the debugger and you can then inspect -variables and stacks. - -$ foo_test --gtest_repeat=1000 --gtest_filter=FooBar.* -Repeat the tests whose name matches the filter 1000 times. -``` - -If your test program contains -[global set-up/tear-down](#global-set-up-and-tear-down) code, it will be -repeated in each iteration as well, as the flakiness may be in it. You can also -specify the repeat count by setting the `GTEST_REPEAT` environment variable. - -### Shuffling the Tests - -You can specify the `--gtest_shuffle` flag (or set the `GTEST_SHUFFLE` -environment variable to `1`) to run the tests in a program in a random order. -This helps to reveal bad dependencies between tests. - -By default, googletest uses a random seed calculated from the current time. -Therefore you'll get a different order every time. The console output includes -the random seed value, such that you can reproduce an order-related test failure -later. To specify the random seed explicitly, use the `--gtest_random_seed=SEED` -flag (or set the `GTEST_RANDOM_SEED` environment variable), where `SEED` is an -integer in the range [0, 99999]. The seed value 0 is special: it tells -googletest to do the default behavior of calculating the seed from the current -time. - -If you combine this with `--gtest_repeat=N`, googletest will pick a different -random seed and re-shuffle the tests in each iteration. - -### Controlling Test Output - -#### Colored Terminal Output - -googletest can use colors in its terminal output to make it easier to spot the -important information: - - -...
- [----------] 1 test from - FooTest
- [ RUN      ] - FooTest.DoesAbc
- [       OK ] - FooTest.DoesAbc
- [----------] - 2 tests from BarTest
- [ RUN      ] - BarTest.HasXyzProperty
- [       OK ] - BarTest.HasXyzProperty
- [ RUN      ] - BarTest.ReturnsTrueOnSuccess ... some error messages ...
- [   FAILED ] - BarTest.ReturnsTrueOnSuccess ...
- [==========] - 30 tests from 14 test suites ran.
- [   PASSED ] - 28 tests.
- [   FAILED ] - 2 tests, listed below:
- [   FAILED ] - BarTest.ReturnsTrueOnSuccess
- [   FAILED ] - AnotherTest.DoesXyz
-
- 2 FAILED TESTS - - - -You can set the `GTEST_COLOR` environment variable or the `--gtest_color` -command line flag to `yes`, `no`, or `auto` (the default) to enable colors, -disable colors, or let googletest decide. When the value is `auto`, googletest -will use colors if and only if the output goes to a terminal and (on non-Windows -platforms) the `TERM` environment variable is set to `xterm` or `xterm-color`. - -#### Suppressing test passes - -By default, googletest prints 1 line of output for each test, indicating if it -passed or failed. To show only test failures, run the test program with -`--gtest_brief=1`, or set the GTEST_BRIEF environment variable to `1`. - -#### Suppressing the Elapsed Time - -By default, googletest prints the time it takes to run each test. To disable -that, run the test program with the `--gtest_print_time=0` command line flag, or -set the GTEST_PRINT_TIME environment variable to `0`. - -#### Suppressing UTF-8 Text Output - -In case of assertion failures, googletest prints expected and actual values of -type `string` both as hex-encoded strings as well as in readable UTF-8 text if -they contain valid non-ASCII UTF-8 characters. If you want to suppress the UTF-8 -text because, for example, you don't have an UTF-8 compatible output medium, run -the test program with `--gtest_print_utf8=0` or set the `GTEST_PRINT_UTF8` -environment variable to `0`. - - - -#### Generating an XML Report - -googletest can emit a detailed XML report to a file in addition to its normal -textual output. The report contains the duration of each test, and thus can help -you identify slow tests. - -To generate the XML report, set the `GTEST_OUTPUT` environment variable or the -`--gtest_output` flag to the string `"xml:path_to_output_file"`, which will -create the file at the given location. You can also just use the string `"xml"`, -in which case the output can be found in the `test_detail.xml` file in the -current directory. - -If you specify a directory (for example, `"xml:output/directory/"` on Linux or -`"xml:output\directory\"` on Windows), googletest will create the XML file in -that directory, named after the test executable (e.g. `foo_test.xml` for test -program `foo_test` or `foo_test.exe`). If the file already exists (perhaps left -over from a previous run), googletest will pick a different name (e.g. -`foo_test_1.xml`) to avoid overwriting it. - -The report is based on the `junitreport` Ant task. Since that format was -originally intended for Java, a little interpretation is required to make it -apply to googletest tests, as shown here: - -```xml - - - - - - - - - -``` - -* The root `` element corresponds to the entire test program. -* `` elements correspond to googletest test suites. -* `` elements correspond to googletest test functions. - -For instance, the following program - -```c++ -TEST(MathTest, Addition) { ... } -TEST(MathTest, Subtraction) { ... } -TEST(LogicTest, NonContradiction) { ... } -``` - -could generate this report: - -```xml - - - - - ... - ... - - - - - - - - - -``` - -Things to note: - -* The `tests` attribute of a `` or `` element tells how - many test functions the googletest program or test suite contains, while the - `failures` attribute tells how many of them failed. - -* The `time` attribute expresses the duration of the test, test suite, or - entire test program in seconds. - -* The `timestamp` attribute records the local date and time of the test - execution. - -* Each `` element corresponds to a single failed googletest - assertion. - -#### Generating a JSON Report - -googletest can also emit a JSON report as an alternative format to XML. To -generate the JSON report, set the `GTEST_OUTPUT` environment variable or the -`--gtest_output` flag to the string `"json:path_to_output_file"`, which will -create the file at the given location. You can also just use the string -`"json"`, in which case the output can be found in the `test_detail.json` file -in the current directory. - -The report format conforms to the following JSON Schema: - -```json -{ - "$schema": "http://json-schema.org/schema#", - "type": "object", - "definitions": { - "TestCase": { - "type": "object", - "properties": { - "name": { "type": "string" }, - "tests": { "type": "integer" }, - "failures": { "type": "integer" }, - "disabled": { "type": "integer" }, - "time": { "type": "string" }, - "testsuite": { - "type": "array", - "items": { - "$ref": "#/definitions/TestInfo" - } - } - } - }, - "TestInfo": { - "type": "object", - "properties": { - "name": { "type": "string" }, - "status": { - "type": "string", - "enum": ["RUN", "NOTRUN"] - }, - "time": { "type": "string" }, - "classname": { "type": "string" }, - "failures": { - "type": "array", - "items": { - "$ref": "#/definitions/Failure" - } - } - } - }, - "Failure": { - "type": "object", - "properties": { - "failures": { "type": "string" }, - "type": { "type": "string" } - } - } - }, - "properties": { - "tests": { "type": "integer" }, - "failures": { "type": "integer" }, - "disabled": { "type": "integer" }, - "errors": { "type": "integer" }, - "timestamp": { - "type": "string", - "format": "date-time" - }, - "time": { "type": "string" }, - "name": { "type": "string" }, - "testsuites": { - "type": "array", - "items": { - "$ref": "#/definitions/TestCase" - } - } - } -} -``` - -The report uses the format that conforms to the following Proto3 using the -[JSON encoding](https://developers.google.com/protocol-buffers/docs/proto3#json): - -```proto -syntax = "proto3"; - -package googletest; - -import "google/protobuf/timestamp.proto"; -import "google/protobuf/duration.proto"; - -message UnitTest { - int32 tests = 1; - int32 failures = 2; - int32 disabled = 3; - int32 errors = 4; - google.protobuf.Timestamp timestamp = 5; - google.protobuf.Duration time = 6; - string name = 7; - repeated TestCase testsuites = 8; -} - -message TestCase { - string name = 1; - int32 tests = 2; - int32 failures = 3; - int32 disabled = 4; - int32 errors = 5; - google.protobuf.Duration time = 6; - repeated TestInfo testsuite = 7; -} - -message TestInfo { - string name = 1; - enum Status { - RUN = 0; - NOTRUN = 1; - } - Status status = 2; - google.protobuf.Duration time = 3; - string classname = 4; - message Failure { - string failures = 1; - string type = 2; - } - repeated Failure failures = 5; -} -``` - -For instance, the following program - -```c++ -TEST(MathTest, Addition) { ... } -TEST(MathTest, Subtraction) { ... } -TEST(LogicTest, NonContradiction) { ... } -``` - -could generate this report: - -```json -{ - "tests": 3, - "failures": 1, - "errors": 0, - "time": "0.035s", - "timestamp": "2011-10-31T18:52:42Z", - "name": "AllTests", - "testsuites": [ - { - "name": "MathTest", - "tests": 2, - "failures": 1, - "errors": 0, - "time": "0.015s", - "testsuite": [ - { - "name": "Addition", - "status": "RUN", - "time": "0.007s", - "classname": "", - "failures": [ - { - "message": "Value of: add(1, 1)\n Actual: 3\nExpected: 2", - "type": "" - }, - { - "message": "Value of: add(1, -1)\n Actual: 1\nExpected: 0", - "type": "" - } - ] - }, - { - "name": "Subtraction", - "status": "RUN", - "time": "0.005s", - "classname": "" - } - ] - }, - { - "name": "LogicTest", - "tests": 1, - "failures": 0, - "errors": 0, - "time": "0.005s", - "testsuite": [ - { - "name": "NonContradiction", - "status": "RUN", - "time": "0.005s", - "classname": "" - } - ] - } - ] -} -``` - -IMPORTANT: The exact format of the JSON document is subject to change. - -### Controlling How Failures Are Reported - -#### Detecting Test Premature Exit - -Google Test implements the _premature-exit-file_ protocol for test runners -to catch any kind of unexpected exits of test programs. Upon start, -Google Test creates the file which will be automatically deleted after -all work has been finished. Then, the test runner can check if this file -exists. In case the file remains undeleted, the inspected test has exited -prematurely. - -This feature is enabled only if the `TEST_PREMATURE_EXIT_FILE` environment -variable has been set. - -#### Turning Assertion Failures into Break-Points - -When running test programs under a debugger, it's very convenient if the -debugger can catch an assertion failure and automatically drop into interactive -mode. googletest's *break-on-failure* mode supports this behavior. - -To enable it, set the `GTEST_BREAK_ON_FAILURE` environment variable to a value -other than `0`. Alternatively, you can use the `--gtest_break_on_failure` -command line flag. - -#### Disabling Catching Test-Thrown Exceptions - -googletest can be used either with or without exceptions enabled. If a test -throws a C++ exception or (on Windows) a structured exception (SEH), by default -googletest catches it, reports it as a test failure, and continues with the next -test method. This maximizes the coverage of a test run. Also, on Windows an -uncaught exception will cause a pop-up window, so catching the exceptions allows -you to run the tests automatically. - -When debugging the test failures, however, you may instead want the exceptions -to be handled by the debugger, such that you can examine the call stack when an -exception is thrown. To achieve that, set the `GTEST_CATCH_EXCEPTIONS` -environment variable to `0`, or use the `--gtest_catch_exceptions=0` flag when -running the tests. - -### Sanitizer Integration - -The -[Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html), -[Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer), -and -[Thread Sanitizer](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual) -all provide weak functions that you can override to trigger explicit failures -when they detect sanitizer errors, such as creating a reference from `nullptr`. -To override these functions, place definitions for them in a source file that -you compile as part of your main binary: - -``` -extern "C" { -void __ubsan_on_report() { - FAIL() << "Encountered an undefined behavior sanitizer error"; -} -void __asan_on_error() { - FAIL() << "Encountered an address sanitizer error"; -} -void __tsan_on_report() { - FAIL() << "Encountered a thread sanitizer error"; -} -} // extern "C" -``` - -After compiling your project with one of the sanitizers enabled, if a particular -test triggers a sanitizer error, googletest will report that it failed. diff --git a/googletest/docs/faq.md b/googletest/docs/faq.md deleted file mode 100644 index d91bd4d..0000000 --- a/googletest/docs/faq.md +++ /dev/null @@ -1,771 +0,0 @@ -# Googletest FAQ - - - - - -## Why should test suite names and test names not contain underscore? - -Note: Googletest reserves underscore (`_`) for special purpose keywords, such as -[the `DISABLED_` prefix](advanced.md#temporarily-disabling-tests), in addition -to the following rationale. - -Underscore (`_`) is special, as C++ reserves the following to be used by the -compiler and the standard library: - -1. any identifier that starts with an `_` followed by an upper-case letter, and -2. any identifier that contains two consecutive underscores (i.e. `__`) - *anywhere* in its name. - -User code is *prohibited* from using such identifiers. - -Now let's look at what this means for `TEST` and `TEST_F`. - -Currently `TEST(TestSuiteName, TestName)` generates a class named -`TestSuiteName_TestName_Test`. What happens if `TestSuiteName` or `TestName` -contains `_`? - -1. If `TestSuiteName` starts with an `_` followed by an upper-case letter (say, - `_Foo`), we end up with `_Foo_TestName_Test`, which is reserved and thus - invalid. -2. If `TestSuiteName` ends with an `_` (say, `Foo_`), we get - `Foo__TestName_Test`, which is invalid. -3. If `TestName` starts with an `_` (say, `_Bar`), we get - `TestSuiteName__Bar_Test`, which is invalid. -4. If `TestName` ends with an `_` (say, `Bar_`), we get - `TestSuiteName_Bar__Test`, which is invalid. - -So clearly `TestSuiteName` and `TestName` cannot start or end with `_` -(Actually, `TestSuiteName` can start with `_` -- as long as the `_` isn't -followed by an upper-case letter. But that's getting complicated. So for -simplicity we just say that it cannot start with `_`.). - -It may seem fine for `TestSuiteName` and `TestName` to contain `_` in the -middle. However, consider this: - -```c++ -TEST(Time, Flies_Like_An_Arrow) { ... } -TEST(Time_Flies, Like_An_Arrow) { ... } -``` - -Now, the two `TEST`s will both generate the same class -(`Time_Flies_Like_An_Arrow_Test`). That's not good. - -So for simplicity, we just ask the users to avoid `_` in `TestSuiteName` and -`TestName`. The rule is more constraining than necessary, but it's simple and -easy to remember. It also gives googletest some wiggle room in case its -implementation needs to change in the future. - -If you violate the rule, there may not be immediate consequences, but your test -may (just may) break with a new compiler (or a new version of the compiler you -are using) or with a new version of googletest. Therefore it's best to follow -the rule. - -## Why does googletest support `EXPECT_EQ(NULL, ptr)` and `ASSERT_EQ(NULL, ptr)` but not `EXPECT_NE(NULL, ptr)` and `ASSERT_NE(NULL, ptr)`? - -First of all you can use `EXPECT_NE(nullptr, ptr)` and `ASSERT_NE(nullptr, -ptr)`. This is the preferred syntax in the style guide because nullptr does not -have the type problems that NULL does. Which is why NULL does not work. - -Due to some peculiarity of C++, it requires some non-trivial template meta -programming tricks to support using `NULL` as an argument of the `EXPECT_XX()` -and `ASSERT_XX()` macros. Therefore we only do it where it's most needed -(otherwise we make the implementation of googletest harder to maintain and more -error-prone than necessary). - -The `EXPECT_EQ()` macro takes the *expected* value as its first argument and the -*actual* value as the second. It's reasonable that someone wants to write -`EXPECT_EQ(NULL, some_expression)`, and this indeed was requested several times. -Therefore we implemented it. - -The need for `EXPECT_NE(NULL, ptr)` isn't nearly as strong. When the assertion -fails, you already know that `ptr` must be `NULL`, so it doesn't add any -information to print `ptr` in this case. That means `EXPECT_TRUE(ptr != NULL)` -works just as well. - -If we were to support `EXPECT_NE(NULL, ptr)`, for consistency we'll have to -support `EXPECT_NE(ptr, NULL)` as well, as unlike `EXPECT_EQ`, we don't have a -convention on the order of the two arguments for `EXPECT_NE`. This means using -the template meta programming tricks twice in the implementation, making it even -harder to understand and maintain. We believe the benefit doesn't justify the -cost. - -Finally, with the growth of the gMock matcher library, we are encouraging people -to use the unified `EXPECT_THAT(value, matcher)` syntax more often in tests. One -significant advantage of the matcher approach is that matchers can be easily -combined to form new matchers, while the `EXPECT_NE`, etc, macros cannot be -easily combined. Therefore we want to invest more in the matchers than in the -`EXPECT_XX()` macros. - -## I need to test that different implementations of an interface satisfy some common requirements. Should I use typed tests or value-parameterized tests? - -For testing various implementations of the same interface, either typed tests or -value-parameterized tests can get it done. It's really up to you the user to -decide which is more convenient for you, depending on your particular case. Some -rough guidelines: - -* Typed tests can be easier to write if instances of the different - implementations can be created the same way, modulo the type. For example, - if all these implementations have a public default constructor (such that - you can write `new TypeParam`), or if their factory functions have the same - form (e.g. `CreateInstance()`). -* Value-parameterized tests can be easier to write if you need different code - patterns to create different implementations' instances, e.g. `new Foo` vs - `new Bar(5)`. To accommodate for the differences, you can write factory - function wrappers and pass these function pointers to the tests as their - parameters. -* When a typed test fails, the default output includes the name of the type, - which can help you quickly identify which implementation is wrong. - Value-parameterized tests only show the number of the failed iteration by - default. You will need to define a function that returns the iteration name - and pass it as the third parameter to INSTANTIATE_TEST_SUITE_P to have more - useful output. -* When using typed tests, you need to make sure you are testing against the - interface type, not the concrete types (in other words, you want to make - sure `implicit_cast(my_concrete_impl)` works, not just that - `my_concrete_impl` works). It's less likely to make mistakes in this area - when using value-parameterized tests. - -I hope I didn't confuse you more. :-) If you don't mind, I'd suggest you to give -both approaches a try. Practice is a much better way to grasp the subtle -differences between the two tools. Once you have some concrete experience, you -can much more easily decide which one to use the next time. - -## I got some run-time errors about invalid proto descriptors when using `ProtocolMessageEquals`. Help! - -**Note:** `ProtocolMessageEquals` and `ProtocolMessageEquiv` are *deprecated* -now. Please use `EqualsProto`, etc instead. - -`ProtocolMessageEquals` and `ProtocolMessageEquiv` were redefined recently and -are now less tolerant of invalid protocol buffer definitions. In particular, if -you have a `foo.proto` that doesn't fully qualify the type of a protocol message -it references (e.g. `message` where it should be `message`), you -will now get run-time errors like: - -``` -... descriptor.cc:...] Invalid proto descriptor for file "path/to/foo.proto": -... descriptor.cc:...] blah.MyMessage.my_field: ".Bar" is not defined. -``` - -If you see this, your `.proto` file is broken and needs to be fixed by making -the types fully qualified. The new definition of `ProtocolMessageEquals` and -`ProtocolMessageEquiv` just happen to reveal your bug. - -## My death test modifies some state, but the change seems lost after the death test finishes. Why? - -Death tests (`EXPECT_DEATH`, etc) are executed in a sub-process s.t. the -expected crash won't kill the test program (i.e. the parent process). As a -result, any in-memory side effects they incur are observable in their respective -sub-processes, but not in the parent process. You can think of them as running -in a parallel universe, more or less. - -In particular, if you use mocking and the death test statement invokes some mock -methods, the parent process will think the calls have never occurred. Therefore, -you may want to move your `EXPECT_CALL` statements inside the `EXPECT_DEATH` -macro. - -## EXPECT_EQ(htonl(blah), blah_blah) generates weird compiler errors in opt mode. Is this a googletest bug? - -Actually, the bug is in `htonl()`. - -According to `'man htonl'`, `htonl()` is a *function*, which means it's valid to -use `htonl` as a function pointer. However, in opt mode `htonl()` is defined as -a *macro*, which breaks this usage. - -Worse, the macro definition of `htonl()` uses a `gcc` extension and is *not* -standard C++. That hacky implementation has some ad hoc limitations. In -particular, it prevents you from writing `Foo()`, where `Foo` -is a template that has an integral argument. - -The implementation of `EXPECT_EQ(a, b)` uses `sizeof(... a ...)` inside a -template argument, and thus doesn't compile in opt mode when `a` contains a call -to `htonl()`. It is difficult to make `EXPECT_EQ` bypass the `htonl()` bug, as -the solution must work with different compilers on various platforms. - -`htonl()` has some other problems as described in `//util/endian/endian.h`, -which defines `ghtonl()` to replace it. `ghtonl()` does the same thing `htonl()` -does, only without its problems. We suggest you to use `ghtonl()` instead of -`htonl()`, both in your tests and production code. - -`//util/endian/endian.h` also defines `ghtons()`, which solves similar problems -in `htons()`. - -Don't forget to add `//util/endian` to the list of dependencies in the `BUILD` -file wherever `ghtonl()` and `ghtons()` are used. The library consists of a -single header file and will not bloat your binary. - -## The compiler complains about "undefined references" to some static const member variables, but I did define them in the class body. What's wrong? - -If your class has a static data member: - -```c++ -// foo.h -class Foo { - ... - static const int kBar = 100; -}; -``` - -You also need to define it *outside* of the class body in `foo.cc`: - -```c++ -const int Foo::kBar; // No initializer here. -``` - -Otherwise your code is **invalid C++**, and may break in unexpected ways. In -particular, using it in googletest comparison assertions (`EXPECT_EQ`, etc) will -generate an "undefined reference" linker error. The fact that "it used to work" -doesn't mean it's valid. It just means that you were lucky. :-) - -If the declaration of the static data member is `constexpr` then it is -implicitly an `inline` definition, and a separate definition in `foo.cc` is not -needed: - -```c++ -// foo.h -class Foo { - ... - static constexpr int kBar = 100; // Defines kBar, no need to do it in foo.cc. -}; -``` - -## Can I derive a test fixture from another? - -Yes. - -Each test fixture has a corresponding and same named test suite. This means only -one test suite can use a particular fixture. Sometimes, however, multiple test -cases may want to use the same or slightly different fixtures. For example, you -may want to make sure that all of a GUI library's test suites don't leak -important system resources like fonts and brushes. - -In googletest, you share a fixture among test suites by putting the shared logic -in a base test fixture, then deriving from that base a separate fixture for each -test suite that wants to use this common logic. You then use `TEST_F()` to write -tests using each derived fixture. - -Typically, your code looks like this: - -```c++ -// Defines a base test fixture. -class BaseTest : public ::testing::Test { - protected: - ... -}; - -// Derives a fixture FooTest from BaseTest. -class FooTest : public BaseTest { - protected: - void SetUp() override { - BaseTest::SetUp(); // Sets up the base fixture first. - ... additional set-up work ... - } - - void TearDown() override { - ... clean-up work for FooTest ... - BaseTest::TearDown(); // Remember to tear down the base fixture - // after cleaning up FooTest! - } - - ... functions and variables for FooTest ... -}; - -// Tests that use the fixture FooTest. -TEST_F(FooTest, Bar) { ... } -TEST_F(FooTest, Baz) { ... } - -... additional fixtures derived from BaseTest ... -``` - -If necessary, you can continue to derive test fixtures from a derived fixture. -googletest has no limit on how deep the hierarchy can be. - -For a complete example using derived test fixtures, see -[sample5_unittest.cc](../googletest/samples/sample5_unittest.cc). - -## My compiler complains "void value not ignored as it ought to be." What does this mean? - -You're probably using an `ASSERT_*()` in a function that doesn't return `void`. -`ASSERT_*()` can only be used in `void` functions, due to exceptions being -disabled by our build system. Please see more details -[here](advanced.md#assertion-placement). - -## My death test hangs (or seg-faults). How do I fix it? - -In googletest, death tests are run in a child process and the way they work is -delicate. To write death tests you really need to understand how they work. -Please make sure you have read [this](advanced.md#how-it-works). - -In particular, death tests don't like having multiple threads in the parent -process. So the first thing you can try is to eliminate creating threads outside -of `EXPECT_DEATH()`. For example, you may want to use mocks or fake objects -instead of real ones in your tests. - -Sometimes this is impossible as some library you must use may be creating -threads before `main()` is even reached. In this case, you can try to minimize -the chance of conflicts by either moving as many activities as possible inside -`EXPECT_DEATH()` (in the extreme case, you want to move everything inside), or -leaving as few things as possible in it. Also, you can try to set the death test -style to `"threadsafe"`, which is safer but slower, and see if it helps. - -If you go with thread-safe death tests, remember that they rerun the test -program from the beginning in the child process. Therefore make sure your -program can run side-by-side with itself and is deterministic. - -In the end, this boils down to good concurrent programming. You have to make -sure that there are no race conditions or deadlocks in your program. No silver -bullet - sorry! - -## Should I use the constructor/destructor of the test fixture or SetUp()/TearDown()? {#CtorVsSetUp} - -The first thing to remember is that googletest does **not** reuse the same test -fixture object across multiple tests. For each `TEST_F`, googletest will create -a **fresh** test fixture object, immediately call `SetUp()`, run the test body, -call `TearDown()`, and then delete the test fixture object. - -When you need to write per-test set-up and tear-down logic, you have the choice -between using the test fixture constructor/destructor or `SetUp()/TearDown()`. -The former is usually preferred, as it has the following benefits: - -* By initializing a member variable in the constructor, we have the option to - make it `const`, which helps prevent accidental changes to its value and - makes the tests more obviously correct. -* In case we need to subclass the test fixture class, the subclass' - constructor is guaranteed to call the base class' constructor *first*, and - the subclass' destructor is guaranteed to call the base class' destructor - *afterward*. With `SetUp()/TearDown()`, a subclass may make the mistake of - forgetting to call the base class' `SetUp()/TearDown()` or call them at the - wrong time. - -You may still want to use `SetUp()/TearDown()` in the following cases: - -* C++ does not allow virtual function calls in constructors and destructors. - You can call a method declared as virtual, but it will not use dynamic - dispatch, it will use the definition from the class the constructor of which - is currently executing. This is because calling a virtual method before the - derived class constructor has a chance to run is very dangerous - the - virtual method might operate on uninitialized data. Therefore, if you need - to call a method that will be overridden in a derived class, you have to use - `SetUp()/TearDown()`. -* In the body of a constructor (or destructor), it's not possible to use the - `ASSERT_xx` macros. Therefore, if the set-up operation could cause a fatal - test failure that should prevent the test from running, it's necessary to - use `abort` and abort the whole test executable, - or to use `SetUp()` instead of a constructor. -* If the tear-down operation could throw an exception, you must use - `TearDown()` as opposed to the destructor, as throwing in a destructor leads - to undefined behavior and usually will kill your program right away. Note - that many standard libraries (like STL) may throw when exceptions are - enabled in the compiler. Therefore you should prefer `TearDown()` if you - want to write portable tests that work with or without exceptions. -* The googletest team is considering making the assertion macros throw on - platforms where exceptions are enabled (e.g. Windows, Mac OS, and Linux - client-side), which will eliminate the need for the user to propagate - failures from a subroutine to its caller. Therefore, you shouldn't use - googletest assertions in a destructor if your code could run on such a - platform. - -## The compiler complains "no matching function to call" when I use ASSERT_PRED*. How do I fix it? - -If the predicate function you use in `ASSERT_PRED*` or `EXPECT_PRED*` is -overloaded or a template, the compiler will have trouble figuring out which -overloaded version it should use. `ASSERT_PRED_FORMAT*` and -`EXPECT_PRED_FORMAT*` don't have this problem. - -If you see this error, you might want to switch to -`(ASSERT|EXPECT)_PRED_FORMAT*`, which will also give you a better failure -message. If, however, that is not an option, you can resolve the problem by -explicitly telling the compiler which version to pick. - -For example, suppose you have - -```c++ -bool IsPositive(int n) { - return n > 0; -} - -bool IsPositive(double x) { - return x > 0; -} -``` - -you will get a compiler error if you write - -```c++ -EXPECT_PRED1(IsPositive, 5); -``` - -However, this will work: - -```c++ -EXPECT_PRED1(static_cast(IsPositive), 5); -``` - -(The stuff inside the angled brackets for the `static_cast` operator is the type -of the function pointer for the `int`-version of `IsPositive()`.) - -As another example, when you have a template function - -```c++ -template -bool IsNegative(T x) { - return x < 0; -} -``` - -you can use it in a predicate assertion like this: - -```c++ -ASSERT_PRED1(IsNegative, -5); -``` - -Things are more interesting if your template has more than one parameter. The -following won't compile: - -```c++ -ASSERT_PRED2(GreaterThan, 5, 0); -``` - -as the C++ pre-processor thinks you are giving `ASSERT_PRED2` 4 arguments, which -is one more than expected. The workaround is to wrap the predicate function in -parentheses: - -```c++ -ASSERT_PRED2((GreaterThan), 5, 0); -``` - -## My compiler complains about "ignoring return value" when I call RUN_ALL_TESTS(). Why? - -Some people had been ignoring the return value of `RUN_ALL_TESTS()`. That is, -instead of - -```c++ - return RUN_ALL_TESTS(); -``` - -they write - -```c++ - RUN_ALL_TESTS(); -``` - -This is **wrong and dangerous**. The testing services needs to see the return -value of `RUN_ALL_TESTS()` in order to determine if a test has passed. If your -`main()` function ignores it, your test will be considered successful even if it -has a googletest assertion failure. Very bad. - -We have decided to fix this (thanks to Michael Chastain for the idea). Now, your -code will no longer be able to ignore `RUN_ALL_TESTS()` when compiled with -`gcc`. If you do so, you'll get a compiler error. - -If you see the compiler complaining about you ignoring the return value of -`RUN_ALL_TESTS()`, the fix is simple: just make sure its value is used as the -return value of `main()`. - -But how could we introduce a change that breaks existing tests? Well, in this -case, the code was already broken in the first place, so we didn't break it. :-) - -## My compiler complains that a constructor (or destructor) cannot return a value. What's going on? - -Due to a peculiarity of C++, in order to support the syntax for streaming -messages to an `ASSERT_*`, e.g. - -```c++ - ASSERT_EQ(1, Foo()) << "blah blah" << foo; -``` - -we had to give up using `ASSERT*` and `FAIL*` (but not `EXPECT*` and -`ADD_FAILURE*`) in constructors and destructors. The workaround is to move the -content of your constructor/destructor to a private void member function, or -switch to `EXPECT_*()` if that works. This -[section](advanced.md#assertion-placement) in the user's guide explains it. - -## My SetUp() function is not called. Why? - -C++ is case-sensitive. Did you spell it as `Setup()`? - -Similarly, sometimes people spell `SetUpTestSuite()` as `SetupTestSuite()` and -wonder why it's never called. - - -## I have several test suites which share the same test fixture logic, do I have to define a new test fixture class for each of them? This seems pretty tedious. - -You don't have to. Instead of - -```c++ -class FooTest : public BaseTest {}; - -TEST_F(FooTest, Abc) { ... } -TEST_F(FooTest, Def) { ... } - -class BarTest : public BaseTest {}; - -TEST_F(BarTest, Abc) { ... } -TEST_F(BarTest, Def) { ... } -``` - -you can simply `typedef` the test fixtures: - -```c++ -typedef BaseTest FooTest; - -TEST_F(FooTest, Abc) { ... } -TEST_F(FooTest, Def) { ... } - -typedef BaseTest BarTest; - -TEST_F(BarTest, Abc) { ... } -TEST_F(BarTest, Def) { ... } -``` - -## googletest output is buried in a whole bunch of LOG messages. What do I do? - -The googletest output is meant to be a concise and human-friendly report. If -your test generates textual output itself, it will mix with the googletest -output, making it hard to read. However, there is an easy solution to this -problem. - -Since `LOG` messages go to stderr, we decided to let googletest output go to -stdout. This way, you can easily separate the two using redirection. For -example: - -```shell -$ ./my_test > gtest_output.txt -``` - -## Why should I prefer test fixtures over global variables? - -There are several good reasons: - -1. It's likely your test needs to change the states of its global variables. - This makes it difficult to keep side effects from escaping one test and - contaminating others, making debugging difficult. By using fixtures, each - test has a fresh set of variables that's different (but with the same - names). Thus, tests are kept independent of each other. -2. Global variables pollute the global namespace. -3. Test fixtures can be reused via subclassing, which cannot be done easily - with global variables. This is useful if many test suites have something in - common. - -## What can the statement argument in ASSERT_DEATH() be? - -`ASSERT_DEATH(statement, matcher)` (or any death assertion macro) can be used -wherever *`statement`* is valid. So basically *`statement`* can be any C++ -statement that makes sense in the current context. In particular, it can -reference global and/or local variables, and can be: - -* a simple function call (often the case), -* a complex expression, or -* a compound statement. - -Some examples are shown here: - -```c++ -// A death test can be a simple function call. -TEST(MyDeathTest, FunctionCall) { - ASSERT_DEATH(Xyz(5), "Xyz failed"); -} - -// Or a complex expression that references variables and functions. -TEST(MyDeathTest, ComplexExpression) { - const bool c = Condition(); - ASSERT_DEATH((c ? Func1(0) : object2.Method("test")), - "(Func1|Method) failed"); -} - -// Death assertions can be used anywhere in a function. In -// particular, they can be inside a loop. -TEST(MyDeathTest, InsideLoop) { - // Verifies that Foo(0), Foo(1), ..., and Foo(4) all die. - for (int i = 0; i < 5; i++) { - EXPECT_DEATH_M(Foo(i), "Foo has \\d+ errors", - ::testing::Message() << "where i is " << i); - } -} - -// A death assertion can contain a compound statement. -TEST(MyDeathTest, CompoundStatement) { - // Verifies that at lease one of Bar(0), Bar(1), ..., and - // Bar(4) dies. - ASSERT_DEATH({ - for (int i = 0; i < 5; i++) { - Bar(i); - } - }, - "Bar has \\d+ errors"); -} -``` - -gtest-death-test_test.cc contains more examples if you are interested. - -## I have a fixture class `FooTest`, but `TEST_F(FooTest, Bar)` gives me error ``"no matching function for call to `FooTest::FooTest()'"``. Why? - -Googletest needs to be able to create objects of your test fixture class, so it -must have a default constructor. Normally the compiler will define one for you. -However, there are cases where you have to define your own: - -* If you explicitly declare a non-default constructor for class `FooTest` - (`DISALLOW_EVIL_CONSTRUCTORS()` does this), then you need to define a - default constructor, even if it would be empty. -* If `FooTest` has a const non-static data member, then you have to define the - default constructor *and* initialize the const member in the initializer - list of the constructor. (Early versions of `gcc` doesn't force you to - initialize the const member. It's a bug that has been fixed in `gcc 4`.) - -## Why does ASSERT_DEATH complain about previous threads that were already joined? - -With the Linux pthread library, there is no turning back once you cross the line -from a single thread to multiple threads. The first time you create a thread, a -manager thread is created in addition, so you get 3, not 2, threads. Later when -the thread you create joins the main thread, the thread count decrements by 1, -but the manager thread will never be killed, so you still have 2 threads, which -means you cannot safely run a death test. - -The new NPTL thread library doesn't suffer from this problem, as it doesn't -create a manager thread. However, if you don't control which machine your test -runs on, you shouldn't depend on this. - -## Why does googletest require the entire test suite, instead of individual tests, to be named *DeathTest when it uses ASSERT_DEATH? - -googletest does not interleave tests from different test suites. That is, it -runs all tests in one test suite first, and then runs all tests in the next test -suite, and so on. googletest does this because it needs to set up a test suite -before the first test in it is run, and tear it down afterwards. Splitting up -the test case would require multiple set-up and tear-down processes, which is -inefficient and makes the semantics unclean. - -If we were to determine the order of tests based on test name instead of test -case name, then we would have a problem with the following situation: - -```c++ -TEST_F(FooTest, AbcDeathTest) { ... } -TEST_F(FooTest, Uvw) { ... } - -TEST_F(BarTest, DefDeathTest) { ... } -TEST_F(BarTest, Xyz) { ... } -``` - -Since `FooTest.AbcDeathTest` needs to run before `BarTest.Xyz`, and we don't -interleave tests from different test suites, we need to run all tests in the -`FooTest` case before running any test in the `BarTest` case. This contradicts -with the requirement to run `BarTest.DefDeathTest` before `FooTest.Uvw`. - -## But I don't like calling my entire test suite \*DeathTest when it contains both death tests and non-death tests. What do I do? - -You don't have to, but if you like, you may split up the test suite into -`FooTest` and `FooDeathTest`, where the names make it clear that they are -related: - -```c++ -class FooTest : public ::testing::Test { ... }; - -TEST_F(FooTest, Abc) { ... } -TEST_F(FooTest, Def) { ... } - -using FooDeathTest = FooTest; - -TEST_F(FooDeathTest, Uvw) { ... EXPECT_DEATH(...) ... } -TEST_F(FooDeathTest, Xyz) { ... ASSERT_DEATH(...) ... } -``` - -## googletest prints the LOG messages in a death test's child process only when the test fails. How can I see the LOG messages when the death test succeeds? - -Printing the LOG messages generated by the statement inside `EXPECT_DEATH()` -makes it harder to search for real problems in the parent's log. Therefore, -googletest only prints them when the death test has failed. - -If you really need to see such LOG messages, a workaround is to temporarily -break the death test (e.g. by changing the regex pattern it is expected to -match). Admittedly, this is a hack. We'll consider a more permanent solution -after the fork-and-exec-style death tests are implemented. - -## The compiler complains about "no match for 'operator<<'" when I use an assertion. What gives? - -If you use a user-defined type `FooType` in an assertion, you must make sure -there is an `std::ostream& operator<<(std::ostream&, const FooType&)` function -defined such that we can print a value of `FooType`. - -In addition, if `FooType` is declared in a name space, the `<<` operator also -needs to be defined in the *same* name space. See https://abseil.io/tips/49 for details. - -## How do I suppress the memory leak messages on Windows? - -Since the statically initialized googletest singleton requires allocations on -the heap, the Visual C++ memory leak detector will report memory leaks at the -end of the program run. The easiest way to avoid this is to use the -`_CrtMemCheckpoint` and `_CrtMemDumpAllObjectsSince` calls to not report any -statically initialized heap objects. See MSDN for more details and additional -heap check/debug routines. - -## How can my code detect if it is running in a test? - -If you write code that sniffs whether it's running in a test and does different -things accordingly, you are leaking test-only logic into production code and -there is no easy way to ensure that the test-only code paths aren't run by -mistake in production. Such cleverness also leads to -[Heisenbugs](https://en.wikipedia.org/wiki/Heisenbug). Therefore we strongly -advise against the practice, and googletest doesn't provide a way to do it. - -In general, the recommended way to cause the code to behave differently under -test is [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection). You can inject -different functionality from the test and from the production code. Since your -production code doesn't link in the for-test logic at all (the -[`testonly`](https://docs.bazel.build/versions/master/be/common-definitions.html#common.testonly) attribute for BUILD targets helps to ensure -that), there is no danger in accidentally running it. - -However, if you *really*, *really*, *really* have no choice, and if you follow -the rule of ending your test program names with `_test`, you can use the -*horrible* hack of sniffing your executable name (`argv[0]` in `main()`) to know -whether the code is under test. - -## How do I temporarily disable a test? - -If you have a broken test that you cannot fix right away, you can add the -DISABLED_ prefix to its name. This will exclude it from execution. This is -better than commenting out the code or using #if 0, as disabled tests are still -compiled (and thus won't rot). - -To include disabled tests in test execution, just invoke the test program with -the --gtest_also_run_disabled_tests flag. - -## Is it OK if I have two separate `TEST(Foo, Bar)` test methods defined in different namespaces? - -Yes. - -The rule is **all test methods in the same test suite must use the same fixture -class.** This means that the following is **allowed** because both tests use the -same fixture class (`::testing::Test`). - -```c++ -namespace foo { -TEST(CoolTest, DoSomething) { - SUCCEED(); -} -} // namespace foo - -namespace bar { -TEST(CoolTest, DoSomething) { - SUCCEED(); -} -} // namespace bar -``` - -However, the following code is **not allowed** and will produce a runtime error -from googletest because the test methods are using different test fixture -classes with the same test suite name. - -```c++ -namespace foo { -class CoolTest : public ::testing::Test {}; // Fixture foo::CoolTest -TEST_F(CoolTest, DoSomething) { - SUCCEED(); -} -} // namespace foo - -namespace bar { -class CoolTest : public ::testing::Test {}; // Fixture: bar::CoolTest -TEST_F(CoolTest, DoSomething) { - SUCCEED(); -} -} // namespace bar -``` diff --git a/googletest/docs/pkgconfig.md b/googletest/docs/pkgconfig.md deleted file mode 100644 index aed4ad4..0000000 --- a/googletest/docs/pkgconfig.md +++ /dev/null @@ -1,150 +0,0 @@ -## Using GoogleTest from various build systems - - - -GoogleTest comes with pkg-config files that can be used to determine all -necessary flags for compiling and linking to GoogleTest (and GoogleMock). -Pkg-config is a standardised plain-text format containing - -* the includedir (-I) path -* necessary macro (-D) definitions -* further required flags (-pthread) -* the library (-L) path -* the library (-l) to link to - -All current build systems support pkg-config in one way or another. For all -examples here we assume you want to compile the sample -`samples/sample3_unittest.cc`. - -### CMake - -Using `pkg-config` in CMake is fairly easy: - -```cmake -cmake_minimum_required(VERSION 3.0) - -cmake_policy(SET CMP0048 NEW) -project(my_gtest_pkgconfig VERSION 0.0.1 LANGUAGES CXX) - -find_package(PkgConfig) -pkg_search_module(GTEST REQUIRED gtest_main) - -add_executable(testapp samples/sample3_unittest.cc) -target_link_libraries(testapp ${GTEST_LDFLAGS}) -target_compile_options(testapp PUBLIC ${GTEST_CFLAGS}) - -include(CTest) -add_test(first_and_only_test testapp) -``` - -It is generally recommended that you use `target_compile_options` + `_CFLAGS` -over `target_include_directories` + `_INCLUDE_DIRS` as the former includes not -just -I flags (GoogleTest might require a macro indicating to internal headers -that all libraries have been compiled with threading enabled. In addition, -GoogleTest might also require `-pthread` in the compiling step, and as such -splitting the pkg-config `Cflags` variable into include dirs and macros for -`target_compile_definitions()` might still miss this). The same recommendation -goes for using `_LDFLAGS` over the more commonplace `_LIBRARIES`, which happens -to discard `-L` flags and `-pthread`. - -### Help! pkg-config can't find GoogleTest! - -Let's say you have a `CMakeLists.txt` along the lines of the one in this -tutorial and you try to run `cmake`. It is very possible that you get a failure -along the lines of: - -``` --- Checking for one of the modules 'gtest_main' -CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:640 (message): - None of the required 'gtest_main' found -``` - -These failures are common if you installed GoogleTest yourself and have not -sourced it from a distro or other package manager. If so, you need to tell -pkg-config where it can find the `.pc` files containing the information. Say you -installed GoogleTest to `/usr/local`, then it might be that the `.pc` files are -installed under `/usr/local/lib64/pkgconfig`. If you set - -``` -export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig -``` - -pkg-config will also try to look in `PKG_CONFIG_PATH` to find `gtest_main.pc`. - -### Using pkg-config in a cross-compilation setting - -Pkg-config can be used in a cross-compilation setting too. To do this, let's -assume the final prefix of the cross-compiled installation will be `/usr`, and -your sysroot is `/home/MYUSER/sysroot`. Configure and install GTest using - -``` -mkdir build && cmake -DCMAKE_INSTALL_PREFIX=/usr .. -``` - -Install into the sysroot using `DESTDIR`: - -``` -make -j install DESTDIR=/home/MYUSER/sysroot -``` - -Before we continue, it is recommended to **always** define the following two -variables for pkg-config in a cross-compilation setting: - -``` -export PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=yes -export PKG_CONFIG_ALLOW_SYSTEM_LIBS=yes -``` - -otherwise `pkg-config` will filter `-I` and `-L` flags against standard prefixes -such as `/usr` (see https://bugs.freedesktop.org/show_bug.cgi?id=28264#c3 for -reasons why this stripping needs to occur usually). - -If you look at the generated pkg-config file, it will look something like - -``` -libdir=/usr/lib64 -includedir=/usr/include - -Name: gtest -Description: GoogleTest (without main() function) -Version: 1.10.0 -URL: https://github.com/google/googletest -Libs: -L${libdir} -lgtest -lpthread -Cflags: -I${includedir} -DGTEST_HAS_PTHREAD=1 -lpthread -``` - -Notice that the sysroot is not included in `libdir` and `includedir`! If you try -to run `pkg-config` with the correct -`PKG_CONFIG_LIBDIR=/home/MYUSER/sysroot/usr/lib64/pkgconfig` against this `.pc` -file, you will get - -``` -$ pkg-config --cflags gtest --DGTEST_HAS_PTHREAD=1 -lpthread -I/usr/include -$ pkg-config --libs gtest --L/usr/lib64 -lgtest -lpthread -``` - -which is obviously wrong and points to the `CBUILD` and not `CHOST` root. In -order to use this in a cross-compilation setting, we need to tell pkg-config to -inject the actual sysroot into `-I` and `-L` variables. Let us now tell -pkg-config about the actual sysroot - -``` -export PKG_CONFIG_DIR= -export PKG_CONFIG_SYSROOT_DIR=/home/MYUSER/sysroot -export PKG_CONFIG_LIBDIR=${PKG_CONFIG_SYSROOT_DIR}/usr/lib64/pkgconfig -``` - -and running `pkg-config` again we get - -``` -$ pkg-config --cflags gtest --DGTEST_HAS_PTHREAD=1 -lpthread -I/home/MYUSER/sysroot/usr/include -$ pkg-config --libs gtest --L/home/MYUSER/sysroot/usr/lib64 -lgtest -lpthread -``` - -which contains the correct sysroot now. For a more comprehensive guide to also -including `${CHOST}` in build system calls, see the excellent tutorial by Diego -Elio Pettenò: https://autotools.io/pkgconfig/cross-compiling.html diff --git a/googletest/docs/primer.md b/googletest/docs/primer.md deleted file mode 100644 index 28c1691..0000000 --- a/googletest/docs/primer.md +++ /dev/null @@ -1,583 +0,0 @@ -# Googletest Primer - - - - - -## Introduction: Why googletest? - -*googletest* helps you write better C++ tests. - -googletest is a testing framework developed by the Testing Technology team with -Google's specific requirements and constraints in mind. Whether you work on -Linux, Windows, or a Mac, if you write C++ code, googletest can help you. And it -supports *any* kind of tests, not just unit tests. - -So what makes a good test, and how does googletest fit in? We believe: - -1. Tests should be *independent* and *repeatable*. It's a pain to debug a test - that succeeds or fails as a result of other tests. googletest isolates the - tests by running each of them on a different object. When a test fails, - googletest allows you to run it in isolation for quick debugging. -2. Tests should be well *organized* and reflect the structure of the tested - code. googletest groups related tests into test suites that can share data - and subroutines. This common pattern is easy to recognize and makes tests - easy to maintain. Such consistency is especially helpful when people switch - projects and start to work on a new code base. -3. Tests should be *portable* and *reusable*. Google has a lot of code that is - platform-neutral; its tests should also be platform-neutral. googletest - works on different OSes, with different compilers, with or without - exceptions, so googletest tests can work with a variety of configurations. -4. When tests fail, they should provide as much *information* about the problem - as possible. googletest doesn't stop at the first test failure. Instead, it - only stops the current test and continues with the next. You can also set up - tests that report non-fatal failures after which the current test continues. - Thus, you can detect and fix multiple bugs in a single run-edit-compile - cycle. -5. The testing framework should liberate test writers from housekeeping chores - and let them focus on the test *content*. googletest automatically keeps - track of all tests defined, and doesn't require the user to enumerate them - in order to run them. -6. Tests should be *fast*. With googletest, you can reuse shared resources - across tests and pay for the set-up/tear-down only once, without making - tests depend on each other. - -Since googletest is based on the popular xUnit architecture, you'll feel right -at home if you've used JUnit or PyUnit before. If not, it will take you about 10 -minutes to learn the basics and get started. So let's go! - -## Beware of the nomenclature - -_Note:_ There might be some confusion arising from different definitions of the -terms _Test_, _Test Case_ and _Test Suite_, so beware of misunderstanding these. - -Historically, googletest started to use the term _Test Case_ for grouping -related tests, whereas current publications, including International Software -Testing Qualifications Board ([ISTQB](http://www.istqb.org/)) materials and -various textbooks on software quality, use the term -_[Test Suite][istqb test suite]_ for this. - -The related term _Test_, as it is used in googletest, corresponds to the term -_[Test Case][istqb test case]_ of ISTQB and others. - -The term _Test_ is commonly of broad enough sense, including ISTQB's definition -of _Test Case_, so it's not much of a problem here. But the term _Test Case_ as -was used in Google Test is of contradictory sense and thus confusing. - -googletest recently started replacing the term _Test Case_ with _Test Suite_. -The preferred API is *TestSuite*. The older TestCase API is being slowly -deprecated and refactored away. - -So please be aware of the different definitions of the terms: - - - -Meaning | googletest Term | [ISTQB](http://www.istqb.org/) Term -:----------------------------------------------------------------------------------- | :---------------------- | :---------------------------------- -Exercise a particular program path with specific input values and verify the results | [TEST()](#simple-tests) | [Test Case][istqb test case] - - - -[istqb test case]: http://glossary.istqb.org/en/search/test%20case -[istqb test suite]: http://glossary.istqb.org/en/search/test%20suite - -## Basic Concepts - -When using googletest, you start by writing *assertions*, which are statements -that check whether a condition is true. An assertion's result can be *success*, -*nonfatal failure*, or *fatal failure*. If a fatal failure occurs, it aborts the -current function; otherwise the program continues normally. - -*Tests* use assertions to verify the tested code's behavior. If a test crashes -or has a failed assertion, then it *fails*; otherwise it *succeeds*. - -A *test suite* contains one or many tests. You should group your tests into test -suites that reflect the structure of the tested code. When multiple tests in a -test suite need to share common objects and subroutines, you can put them into a -*test fixture* class. - -A *test program* can contain multiple test suites. - -We'll now explain how to write a test program, starting at the individual -assertion level and building up to tests and test suites. - -## Assertions - -googletest assertions are macros that resemble function calls. You test a class -or function by making assertions about its behavior. When an assertion fails, -googletest prints the assertion's source file and line number location, along -with a failure message. You may also supply a custom failure message which will -be appended to googletest's message. - -The assertions come in pairs that test the same thing but have different effects -on the current function. `ASSERT_*` versions generate fatal failures when they -fail, and **abort the current function**. `EXPECT_*` versions generate nonfatal -failures, which don't abort the current function. Usually `EXPECT_*` are -preferred, as they allow more than one failure to be reported in a test. -However, you should use `ASSERT_*` if it doesn't make sense to continue when the -assertion in question fails. - -Since a failed `ASSERT_*` returns from the current function immediately, -possibly skipping clean-up code that comes after it, it may cause a space leak. -Depending on the nature of the leak, it may or may not be worth fixing - so keep -this in mind if you get a heap checker error in addition to assertion errors. - -To provide a custom failure message, simply stream it into the macro using the -`<<` operator or a sequence of such operators. An example: - -```c++ -ASSERT_EQ(x.size(), y.size()) << "Vectors x and y are of unequal length"; - -for (int i = 0; i < x.size(); ++i) { - EXPECT_EQ(x[i], y[i]) << "Vectors x and y differ at index " << i; -} -``` - -Anything that can be streamed to an `ostream` can be streamed to an assertion -macro--in particular, C strings and `string` objects. If a wide string -(`wchar_t*`, `TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is -streamed to an assertion, it will be translated to UTF-8 when printed. - -### Basic Assertions - -These assertions do basic true/false condition testing. - -Fatal assertion | Nonfatal assertion | Verifies --------------------------- | -------------------------- | -------------------- -`ASSERT_TRUE(condition);` | `EXPECT_TRUE(condition);` | `condition` is true -`ASSERT_FALSE(condition);` | `EXPECT_FALSE(condition);` | `condition` is false - -Remember, when they fail, `ASSERT_*` yields a fatal failure and returns from the -current function, while `EXPECT_*` yields a nonfatal failure, allowing the -function to continue running. In either case, an assertion failure means its -containing test fails. - -**Availability**: Linux, Windows, Mac. - -### Binary Comparison - -This section describes assertions that compare two values. - -Fatal assertion | Nonfatal assertion | Verifies ------------------------- | ------------------------ | -------------- -`ASSERT_EQ(val1, val2);` | `EXPECT_EQ(val1, val2);` | `val1 == val2` -`ASSERT_NE(val1, val2);` | `EXPECT_NE(val1, val2);` | `val1 != val2` -`ASSERT_LT(val1, val2);` | `EXPECT_LT(val1, val2);` | `val1 < val2` -`ASSERT_LE(val1, val2);` | `EXPECT_LE(val1, val2);` | `val1 <= val2` -`ASSERT_GT(val1, val2);` | `EXPECT_GT(val1, val2);` | `val1 > val2` -`ASSERT_GE(val1, val2);` | `EXPECT_GE(val1, val2);` | `val1 >= val2` - -Value arguments must be comparable by the assertion's comparison operator or -you'll get a compiler error. We used to require the arguments to support the -`<<` operator for streaming to an `ostream`, but this is no longer necessary. If -`<<` is supported, it will be called to print the arguments when the assertion -fails; otherwise googletest will attempt to print them in the best way it can. -For more details and how to customize the printing of the arguments, see the -[documentation](./advanced.md#teaching-googletest-how-to-print-your-values). - -These assertions can work with a user-defined type, but only if you define the -corresponding comparison operator (e.g., `==` or `<`). Since this is discouraged -by the Google -[C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Operator_Overloading), -you may need to use `ASSERT_TRUE()` or `EXPECT_TRUE()` to assert the equality of -two objects of a user-defined type. - -However, when possible, `ASSERT_EQ(actual, expected)` is preferred to -`ASSERT_TRUE(actual == expected)`, since it tells you `actual` and `expected`'s -values on failure. - -Arguments are always evaluated exactly once. Therefore, it's OK for the -arguments to have side effects. However, as with any ordinary C/C++ function, -the arguments' evaluation order is undefined (i.e., the compiler is free to -choose any order), and your code should not depend on any particular argument -evaluation order. - -`ASSERT_EQ()` does pointer equality on pointers. If used on two C strings, it -tests if they are in the same memory location, not if they have the same value. -Therefore, if you want to compare C strings (e.g. `const char*`) by value, use -`ASSERT_STREQ()`, which will be described later on. In particular, to assert -that a C string is `NULL`, use `ASSERT_STREQ(c_string, NULL)`. Consider using -`ASSERT_EQ(c_string, nullptr)` if c++11 is supported. To compare two `string` -objects, you should use `ASSERT_EQ`. - -When doing pointer comparisons use `*_EQ(ptr, nullptr)` and `*_NE(ptr, nullptr)` -instead of `*_EQ(ptr, NULL)` and `*_NE(ptr, NULL)`. This is because `nullptr` is -typed, while `NULL` is not. See the [FAQ](faq.md) for more details. - -If you're working with floating point numbers, you may want to use the floating -point variations of some of these macros in order to avoid problems caused by -rounding. See [Advanced googletest Topics](advanced.md) for details. - -Macros in this section work with both narrow and wide string objects (`string` -and `wstring`). - -**Availability**: Linux, Windows, Mac. - -**Historical note**: Before February 2016 `*_EQ` had a convention of calling it -as `ASSERT_EQ(expected, actual)`, so lots of existing code uses this order. Now -`*_EQ` treats both parameters in the same way. - -### String Comparison - -The assertions in this group compare two **C strings**. If you want to compare -two `string` objects, use `EXPECT_EQ`, `EXPECT_NE`, and etc instead. - - - -| Fatal assertion | Nonfatal assertion | Verifies | -| -------------------------- | ------------------------------ | -------------------------------------------------------- | -| `ASSERT_STREQ(str1,str2);` | `EXPECT_STREQ(str1,str2);` | the two C strings have the same content | -| `ASSERT_STRNE(str1,str2);` | `EXPECT_STRNE(str1,str2);` | the two C strings have different contents | -| `ASSERT_STRCASEEQ(str1,str2);` | `EXPECT_STRCASEEQ(str1,str2);` | the two C strings have the same content, ignoring case | -| `ASSERT_STRCASENE(str1,str2);` | `EXPECT_STRCASENE(str1,str2);` | the two C strings have different contents, ignoring case | - - - -Note that "CASE" in an assertion name means that case is ignored. A `NULL` -pointer and an empty string are considered *different*. - -`*STREQ*` and `*STRNE*` also accept wide C strings (`wchar_t*`). If a comparison -of two wide strings fails, their values will be printed as UTF-8 narrow strings. - -**Availability**: Linux, Windows, Mac. - -**See also**: For more string comparison tricks (substring, prefix, suffix, and -regular expression matching, for example), see [this](advanced.md) in the -Advanced googletest Guide. - -## Simple Tests - -To create a test: - -1. Use the `TEST()` macro to define and name a test function. These are - ordinary C++ functions that don't return a value. -2. In this function, along with any valid C++ statements you want to include, - use the various googletest assertions to check values. -3. The test's result is determined by the assertions; if any assertion in the - test fails (either fatally or non-fatally), or if the test crashes, the - entire test fails. Otherwise, it succeeds. - -```c++ -TEST(TestSuiteName, TestName) { - ... test body ... -} -``` - -`TEST()` arguments go from general to specific. The *first* argument is the name -of the test suite, and the *second* argument is the test's name within the test -suite. Both names must be valid C++ identifiers, and they should not contain -any underscores (`_`). A test's *full name* consists of its containing test suite and -its individual name. Tests from different test suites can have the same -individual name. - -For example, let's take a simple integer function: - -```c++ -int Factorial(int n); // Returns the factorial of n -``` - -A test suite for this function might look like: - -```c++ -// Tests factorial of 0. -TEST(FactorialTest, HandlesZeroInput) { - EXPECT_EQ(Factorial(0), 1); -} - -// Tests factorial of positive numbers. -TEST(FactorialTest, HandlesPositiveInput) { - EXPECT_EQ(Factorial(1), 1); - EXPECT_EQ(Factorial(2), 2); - EXPECT_EQ(Factorial(3), 6); - EXPECT_EQ(Factorial(8), 40320); -} -``` - -googletest groups the test results by test suites, so logically related tests -should be in the same test suite; in other words, the first argument to their -`TEST()` should be the same. In the above example, we have two tests, -`HandlesZeroInput` and `HandlesPositiveInput`, that belong to the same test -suite `FactorialTest`. - -When naming your test suites and tests, you should follow the same convention as -for -[naming functions and classes](https://google.github.io/styleguide/cppguide.html#Function_Names). - -**Availability**: Linux, Windows, Mac. - -## Test Fixtures: Using the Same Data Configuration for Multiple Tests {#same-data-multiple-tests} - -If you find yourself writing two or more tests that operate on similar data, you -can use a *test fixture*. This allows you to reuse the same configuration of -objects for several different tests. - -To create a fixture: - -1. Derive a class from `::testing::Test` . Start its body with `protected:`, as - we'll want to access fixture members from sub-classes. -2. Inside the class, declare any objects you plan to use. -3. If necessary, write a default constructor or `SetUp()` function to prepare - the objects for each test. A common mistake is to spell `SetUp()` as - **`Setup()`** with a small `u` - Use `override` in C++11 to make sure you - spelled it correctly. -4. If necessary, write a destructor or `TearDown()` function to release any - resources you allocated in `SetUp()` . To learn when you should use the - constructor/destructor and when you should use `SetUp()/TearDown()`, read - the [FAQ](faq.md#CtorVsSetUp). -5. If needed, define subroutines for your tests to share. - -When using a fixture, use `TEST_F()` instead of `TEST()` as it allows you to -access objects and subroutines in the test fixture: - -```c++ -TEST_F(TestFixtureName, TestName) { - ... test body ... -} -``` - -Like `TEST()`, the first argument is the test suite name, but for `TEST_F()` -this must be the name of the test fixture class. You've probably guessed: `_F` -is for fixture. - -Unfortunately, the C++ macro system does not allow us to create a single macro -that can handle both types of tests. Using the wrong macro causes a compiler -error. - -Also, you must first define a test fixture class before using it in a -`TEST_F()`, or you'll get the compiler error "`virtual outside class -declaration`". - -For each test defined with `TEST_F()`, googletest will create a *fresh* test -fixture at runtime, immediately initialize it via `SetUp()`, run the test, -clean up by calling `TearDown()`, and then delete the test fixture. Note that -different tests in the same test suite have different test fixture objects, and -googletest always deletes a test fixture before it creates the next one. -googletest does **not** reuse the same test fixture for multiple tests. Any -changes one test makes to the fixture do not affect other tests. - -As an example, let's write tests for a FIFO queue class named `Queue`, which has -the following interface: - -```c++ -template // E is the element type. -class Queue { - public: - Queue(); - void Enqueue(const E& element); - E* Dequeue(); // Returns NULL if the queue is empty. - size_t size() const; - ... -}; -``` - -First, define a fixture class. By convention, you should give it the name -`FooTest` where `Foo` is the class being tested. - -```c++ -class QueueTest : public ::testing::Test { - protected: - void SetUp() override { - q1_.Enqueue(1); - q2_.Enqueue(2); - q2_.Enqueue(3); - } - - // void TearDown() override {} - - Queue q0_; - Queue q1_; - Queue q2_; -}; -``` - -In this case, `TearDown()` is not needed since we don't have to clean up after -each test, other than what's already done by the destructor. - -Now we'll write tests using `TEST_F()` and this fixture. - -```c++ -TEST_F(QueueTest, IsEmptyInitially) { - EXPECT_EQ(q0_.size(), 0); -} - -TEST_F(QueueTest, DequeueWorks) { - int* n = q0_.Dequeue(); - EXPECT_EQ(n, nullptr); - - n = q1_.Dequeue(); - ASSERT_NE(n, nullptr); - EXPECT_EQ(*n, 1); - EXPECT_EQ(q1_.size(), 0); - delete n; - - n = q2_.Dequeue(); - ASSERT_NE(n, nullptr); - EXPECT_EQ(*n, 2); - EXPECT_EQ(q2_.size(), 1); - delete n; -} -``` - -The above uses both `ASSERT_*` and `EXPECT_*` assertions. The rule of thumb is -to use `EXPECT_*` when you want the test to continue to reveal more errors after -the assertion failure, and use `ASSERT_*` when continuing after failure doesn't -make sense. For example, the second assertion in the `Dequeue` test is -`ASSERT_NE(nullptr, n)`, as we need to dereference the pointer `n` later, which -would lead to a segfault when `n` is `NULL`. - -When these tests run, the following happens: - -1. googletest constructs a `QueueTest` object (let's call it `t1`). -2. `t1.SetUp()` initializes `t1`. -3. The first test (`IsEmptyInitially`) runs on `t1`. -4. `t1.TearDown()` cleans up after the test finishes. -5. `t1` is destructed. -6. The above steps are repeated on another `QueueTest` object, this time - running the `DequeueWorks` test. - -**Availability**: Linux, Windows, Mac. - -## Invoking the Tests - -`TEST()` and `TEST_F()` implicitly register their tests with googletest. So, -unlike with many other C++ testing frameworks, you don't have to re-list all -your defined tests in order to run them. - -After defining your tests, you can run them with `RUN_ALL_TESTS()`, which -returns `0` if all the tests are successful, or `1` otherwise. Note that -`RUN_ALL_TESTS()` runs *all tests* in your link unit--they can be from -different test suites, or even different source files. - -When invoked, the `RUN_ALL_TESTS()` macro: - -* Saves the state of all googletest flags. - -* Creates a test fixture object for the first test. - -* Initializes it via `SetUp()`. - -* Runs the test on the fixture object. - -* Cleans up the fixture via `TearDown()`. - -* Deletes the fixture. - -* Restores the state of all googletest flags. - -* Repeats the above steps for the next test, until all tests have run. - -If a fatal failure happens the subsequent steps will be skipped. - -> IMPORTANT: You must **not** ignore the return value of `RUN_ALL_TESTS()`, or -> you will get a compiler error. The rationale for this design is that the -> automated testing service determines whether a test has passed based on its -> exit code, not on its stdout/stderr output; thus your `main()` function must -> return the value of `RUN_ALL_TESTS()`. -> -> Also, you should call `RUN_ALL_TESTS()` only **once**. Calling it more than -> once conflicts with some advanced googletest features (e.g., thread-safe -> [death tests](advanced.md#death-tests)) and thus is not supported. - -**Availability**: Linux, Windows, Mac. - -## Writing the main() Function - -Most users should _not_ need to write their own `main` function and instead link -with `gtest_main` (as opposed to with `gtest`), which defines a suitable entry -point. See the end of this section for details. The remainder of this section -should only apply when you need to do something custom before the tests run that -cannot be expressed within the framework of fixtures and test suites. - -If you write your own `main` function, it should return the value of -`RUN_ALL_TESTS()`. - -You can start from this boilerplate: - -```c++ -#include "this/package/foo.h" - -#include "gtest/gtest.h" - -namespace my { -namespace project { -namespace { - -// The fixture for testing class Foo. -class FooTest : public ::testing::Test { - protected: - // You can remove any or all of the following functions if their bodies would - // be empty. - - FooTest() { - // You can do set-up work for each test here. - } - - ~FooTest() override { - // You can do clean-up work that doesn't throw exceptions here. - } - - // If the constructor and destructor are not enough for setting up - // and cleaning up each test, you can define the following methods: - - void SetUp() override { - // Code here will be called immediately after the constructor (right - // before each test). - } - - void TearDown() override { - // Code here will be called immediately after each test (right - // before the destructor). - } - - // Class members declared here can be used by all tests in the test suite - // for Foo. -}; - -// Tests that the Foo::Bar() method does Abc. -TEST_F(FooTest, MethodBarDoesAbc) { - const std::string input_filepath = "this/package/testdata/myinputfile.dat"; - const std::string output_filepath = "this/package/testdata/myoutputfile.dat"; - Foo f; - EXPECT_EQ(f.Bar(input_filepath, output_filepath), 0); -} - -// Tests that Foo does Xyz. -TEST_F(FooTest, DoesXyz) { - // Exercises the Xyz feature of Foo. -} - -} // namespace -} // namespace project -} // namespace my - -int main(int argc, char **argv) { - ::testing::InitGoogleTest(&argc, argv); - return RUN_ALL_TESTS(); -} -``` - -The `::testing::InitGoogleTest()` function parses the command line for -googletest flags, and removes all recognized flags. This allows the user to -control a test program's behavior via various flags, which we'll cover in -the [AdvancedGuide](advanced.md). You **must** call this function before calling -`RUN_ALL_TESTS()`, or the flags won't be properly initialized. - -On Windows, `InitGoogleTest()` also works with wide strings, so it can be used -in programs compiled in `UNICODE` mode as well. - -But maybe you think that writing all those `main` functions is too much work? We -agree with you completely, and that's why Google Test provides a basic -implementation of main(). If it fits your needs, then just link your test with -the `gtest_main` library and you are good to go. - -NOTE: `ParseGUnitFlags()` is deprecated in favor of `InitGoogleTest()`. - -## Known Limitations - -* Google Test is designed to be thread-safe. The implementation is thread-safe - on systems where the `pthreads` library is available. It is currently - _unsafe_ to use Google Test assertions from two threads concurrently on - other systems (e.g. Windows). In most tests this is not an issue as usually - the assertions are done in the main thread. If you want to help, you can - volunteer to implement the necessary synchronization primitives in - `gtest-port.h` for your platform. diff --git a/googletest/docs/samples.md b/googletest/docs/samples.md deleted file mode 100644 index aaa5883..0000000 --- a/googletest/docs/samples.md +++ /dev/null @@ -1,22 +0,0 @@ -# Googletest Samples {#samples} - -If you're like us, you'd like to look at -[googletest samples.](https://github.com/google/googletest/tree/master/googletest/samples) -The sample directory has a number of well-commented samples showing how to use a -variety of googletest features. - -* Sample #1 shows the basic steps of using googletest to test C++ functions. -* Sample #2 shows a more complex unit test for a class with multiple member - functions. -* Sample #3 uses a test fixture. -* Sample #4 teaches you how to use googletest and `googletest.h` together to - get the best of both libraries. -* Sample #5 puts shared testing logic in a base test fixture, and reuses it in - derived fixtures. -* Sample #6 demonstrates type-parameterized tests. -* Sample #7 teaches the basics of value-parameterized tests. -* Sample #8 shows using `Combine()` in value-parameterized tests. -* Sample #9 shows use of the listener API to modify Google Test's console - output and the use of its reflection API to inspect test results. -* Sample #10 shows use of the listener API to implement a primitive memory - leak checker. -- cgit v0.12