diff options
| -rw-r--r-- | CONTRIBUTING.md | 2 | ||||
| -rw-r--r-- | README.md | 5 | ||||
| -rw-r--r-- | googlemock/CMakeLists.txt | 4 | ||||
| -rw-r--r-- | googlemock/docs/cheat_sheet.md | 81 | ||||
| -rw-r--r-- | googlemock/docs/cook_book.md | 71 | ||||
| -rw-r--r-- | googlemock/docs/for_dummies.md | 8 | ||||
| -rw-r--r-- | googlemock/docs/gmock_faq.md | 4 | ||||
| -rw-r--r-- | googletest/CMakeLists.txt | 2 | ||||
| -rw-r--r-- | googletest/docs/advanced.md | 6 | ||||
| -rw-r--r-- | googletest/docs/primer.md | 4 |
10 files changed, 142 insertions, 45 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2924e0fa..2fe4ff54 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -131,7 +131,7 @@ gtest-type-util.h in the same directory. You don't need to worry about regenerating the source files unless you need to modify them. You would then modify the corresponding `.pump` files and run the '[pump.py](googletest/scripts/pump.py)' generator script. See the -[Pump Manual](googletest/g3doc/PumpManual.md). +[Pump Manual](googletest/docs/PumpManual.md). ## Developing Google Mock @@ -5,11 +5,6 @@ [](https://travis-ci.org/google/googletest) [](https://ci.appveyor.com/project/GoogleTestAppVeyor/googletest/branch/master) -### Summer Vacation - -June 26, 2019 - July 20 2019 due to summer vacations there will be much reduced -activity on Pull Requests and issues from the maintainers. - ### Future Plans #### 1.8.x Release: diff --git a/googlemock/CMakeLists.txt b/googlemock/CMakeLists.txt index c204f271..f75ec45d 100644 --- a/googlemock/CMakeLists.txt +++ b/googlemock/CMakeLists.txt @@ -142,7 +142,7 @@ if (gmock_build_tests) "$project_bin = \"${CMAKE_BINARY_DIR}/bin/$<CONFIG>\" $env:Path = \"$project_bin;$env:Path\" & $args") - elseif (MINGW) + elseif (MINGW OR CYGWIN) file(GENERATE OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/RunTest.ps1" CONTENT "$project_bin = (cygpath --windows ${CMAKE_BINARY_DIR}/bin) @@ -162,7 +162,7 @@ $env:Path = \"$project_bin;$env:Path\" cxx_test(gmock-generated-matchers_test gmock_main) cxx_test(gmock-internal-utils_test gmock_main) cxx_test(gmock-matchers_test gmock_main) - if (MINGW) + if (MINGW OR CYGWIN) target_compile_options(gmock-matchers_test PRIVATE "-Wa,-mbig-obj") endif() cxx_test(gmock-more-actions_test gmock_main) diff --git a/googlemock/docs/cheat_sheet.md b/googlemock/docs/cheat_sheet.md index 633fda06..6170965f 100644 --- a/googlemock/docs/cheat_sheet.md +++ b/googlemock/docs/cheat_sheet.md @@ -2,6 +2,8 @@ <!-- GOOGLETEST_CM0019 DO NOT DELETE --> +<!-- GOOGLETEST_CM0033 DO NOT DELETE --> + ### Defining a Mock Class #### Mocking a Normal Class {#MockClass} @@ -232,7 +234,7 @@ A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or Built-in matchers (where `argument` is the function argument) are divided into several categories: -## Wildcard +#### Wildcard Matcher | Description :-------------------------- | :----------------------------------------------- @@ -495,6 +497,10 @@ messages, you can use: | `WhenDynamicCastTo<T>(m)` | when `argument` is passed through | : : `dynamic_cast<T>()`, it matches matcher `m`. : +<!-- GOOGLETEST_CM0026 DO NOT DELETE --> + +<!-- GOOGLETEST_CM0027 DO NOT DELETE --> + #### Multi-argument Matchers {#MultiArgMatchers} Technically, all matchers match a *single* value. A "multi-argument" matcher is @@ -525,13 +531,25 @@ reorder them) to participate in the matching: 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`. : -| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers | -: : `m1` to `mn`. : -| `Not(m)` | `argument` doesn't match matcher `m`. | +| Matcher | Description | +| :------------------------------- | :-------------------------------------- | +| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers | +: : `m1` to `mn`. : +| `AllOfArray({m0, m1, ..., mn})`, | The same as `AllOf()` except that the | +: `AllOfArray(a_container)`, : matchers come from an initializer list, : +: `AllOfArray(begin, end)`, : STL-style container, iterator range, or : +: `AllOfArray(array)`, or : C-style array. : +: `AllOfArray(array, count)` : : +| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the | +: : matchers `m1` to `mn`. : +| `AnyOfArray({m0, m1, ..., mn})`, | The same as `AnyOf()` except that the | +: `AnyOfArray(a_container)`, : matchers come from an initializer list, : +: `AnyOfArray(begin, end)`, : STL-style container, iterator range, or : +: `AnyOfArray(array)`, or : C-style array. : +: `AnyOfArray(array, count)` : : +| `Not(m)` | `argument` doesn't match matcher `m`. | + +<!-- GOOGLETEST_CM0028 DO NOT DELETE --> #### Adapters for Matchers @@ -550,7 +568,7 @@ You can make a matcher from one or more other matchers: `AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`, which must be a permanent callback. -#### Matchers as Predicates {#MatchersAsPredicatesCheat} +#### Using Matchers as Predicates {#MatchersAsPredicatesCheat} | Matcher | Description | | :---------------------------- | :------------------------------------------ | @@ -587,20 +605,13 @@ which must be a permanent callback. 3. You can use `PrintToString(x)` to convert a value `x` of any type to a string. -## Matchers as Test Assertions - -Matcher | Description -:--------------------------- | :---------- -`ASSERT_THAT(expression, m)` | Generates a [fatal failure](../../googletest/docs/primer.md#assertions) if the value of `expression` doesn't match matcher `m`. -`EXPECT_THAT(expression, m)` | Generates a non-fatal failure if the value of `expression` doesn't match matcher `m`. - ### Actions {#ActionList} **Actions** specify what a mock function should do when invoked. #### Returning a Value -| Matcher | Description | +| | | | :-------------------------- | :-------------------------------------------- | | `Return()` | Return from a `void` mock function. | | `Return(value)` | Return `value`. If the type of `value` is | @@ -619,7 +630,7 @@ Matcher | Description #### Side Effects -| Matcher | Description | +| | | | :--------------------------------- | :-------------------------------------- | | `Assign(&variable, value)` | Assign `value` to variable. | | `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, | @@ -652,8 +663,11 @@ Matcher | Description In the following, by "callable" we mean a free function, `std::function`, functor, lambda, or `google3`-style permanent callback. -| Matcher | Description | +| | | | :---------------------------------- | :------------------------------------- | +| `f` | Invoke f with the arguments passed to | +: : the mock function, where f is a : +: : callable (except of google3 callback). : | `Invoke(f)` | Invoke `f` with the arguments passed | : : to the mock function, where `f` can be : : : a global/static function or a functor. : @@ -708,7 +722,7 @@ InvokeArgument<2>(5, string("Hi"), ByRef(foo)) calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by value, and `foo` by reference. -## Default Action +#### Default Action | Matcher | Description | | :------------ | :----------------------------------------------------- | @@ -718,9 +732,11 @@ value, and `foo` by reference. **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 +<!-- GOOGLETEST_CM0032 DO NOT DELETE --> -| Matcher | Description | +#### Composite Actions + +| | | | :----------------------------- | :------------------------------------------ | | `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the | : : result of `an` in each invocation. The : @@ -734,9 +750,22 @@ composite action - trying to do so will result in a run-time error. : : it. : | `WithoutArgs(a)` | Perform action `a` without any arguments. | -## Defining Actions - -| Matcher | Description | +#### Defining Actions + +<table border="1" cellspacing="0" cellpadding="1"> + <tr> + <td>`struct SumAction {` <br> +  `template <typename T>` <br> +  `T operator()(T x, Ty) { return x + y; }` <br> + `};` + </td> + <td> Defines a generic functor that can be used as an action summing its + arguments. </td> </tr> + <tr> + </tr> +</table> + +| | | | :--------------------------------- | :-------------------------------------- | | `ACTION(Sum) { return arg0 + arg1; | Defines an action `Sum()` to return the | : }` : sum of the mock function's argument #0 : @@ -755,7 +784,7 @@ The `ACTION*` macros cannot be used inside a function or class. These are used in `Times()` to specify how many times a mock function will be called: -| Matcher | Description | +| | | | :---------------- | :----------------------------------------------------- | | `AnyNumber()` | The function can be called any number of times. | | `AtLeast(n)` | The call is expected at least `n` times. | diff --git a/googlemock/docs/cook_book.md b/googlemock/docs/cook_book.md index a858cd1f..17c26459 100644 --- a/googlemock/docs/cook_book.md +++ b/googlemock/docs/cook_book.md @@ -1,4 +1,4 @@ -## Googletest Mocking (gMock) Cookbook +## gMock Cookbook <!-- GOOGLETEST_CM0012 DO NOT DELETE --> @@ -824,6 +824,7 @@ A frequently used matcher is `_`, which matches anything: ```cpp EXPECT_CALL(foo, DoThat(_, NotNull())); ``` +<!-- GOOGLETEST_CM0022 DO NOT DELETE --> #### Combining Matchers {#CombiningMatchers} @@ -1138,6 +1139,8 @@ 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) ...`. +<!-- GOOGLETEST_CM0023 DO NOT DELETE --> + #### Matching Arguments that Are Not Copyable When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of @@ -2147,7 +2150,11 @@ 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 +(function, `std::function`, method, functor, lambda as an action. + +<!-- GOOGLETEST_CM0024 DO NOT DELETE --> + +```cpp using ::testing::_; using ::testing::Invoke; class MockFoo : public Foo { @@ -3239,6 +3246,8 @@ 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. +<!-- GOOGLETEST_CM0025 DO NOT DELETE --> + #### Running Tests in Emacs If you build and run your tests in Emacs using the `M-x google-compile` command @@ -4175,3 +4184,61 @@ 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 + +<!--#include file="includes/g3_testing_LOGs.md"--> +<!--#include file="includes/g3_mock_callbacks.md"--> + +#### 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<R(T1, ..., Tn)>` 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<R(T1, ..., Tn)> 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<int(string)> 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<int(string)>& fun); + // void Foo(std::function<int(string)> 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. :-) + +<!-- GOOGLETEST_CM0034 DO NOT DELETE --> diff --git a/googlemock/docs/for_dummies.md b/googlemock/docs/for_dummies.md index 5433e8b3..5551cd8b 100644 --- a/googlemock/docs/for_dummies.md +++ b/googlemock/docs/for_dummies.md @@ -1,4 +1,4 @@ -## Googletest Mocking (gMock) for Dummies {#GMockForDummies} +## gMock for Dummies {#GMockForDummies} <!-- GOOGLETEST_CM0013 DO NOT DELETE --> @@ -206,6 +206,8 @@ 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. +<!-- GOOGLETEST_CM0029 DO NOT DELETE --> + ### Using Mocks in Tests Once you have a mock class, using it is easy. The typical work flow is: @@ -593,8 +595,8 @@ 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! If you -are impatient, the details can be found [here](#PartialOrder).) +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} diff --git a/googlemock/docs/gmock_faq.md b/googlemock/docs/gmock_faq.md index 184c501f..8bc45b18 100644 --- a/googlemock/docs/gmock_faq.md +++ b/googlemock/docs/gmock_faq.md @@ -81,6 +81,8 @@ void Bar(int* p); // Neither p nor *p is const. void Bar(const int* p); // p is not const, but *p is. ``` +<<!-- GOOGLETEST_CM0030 DO NOT DELETE --> + ### 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 @@ -124,6 +126,8 @@ using ::testing::_; .Times(0); ``` +<!-- GOOGLETEST_CM0031 DO NOT DELETE --> + ### 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 diff --git a/googletest/CMakeLists.txt b/googletest/CMakeLists.txt index 52a615d5..db292946 100644 --- a/googletest/CMakeLists.txt +++ b/googletest/CMakeLists.txt @@ -188,7 +188,7 @@ if (gtest_build_tests) "$project_bin = \"${CMAKE_BINARY_DIR}/bin/$<CONFIG>\" $env:Path = \"$project_bin;$env:Path\" & $args") - elseif (MINGW) + elseif (MINGW OR CYGWIN) file(GENERATE OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/RunTest.ps1" CONTENT "$project_bin = (cygpath --windows ${CMAKE_BINARY_DIR}/bin) diff --git a/googletest/docs/advanced.md b/googletest/docs/advanced.md index 08db2e4e..f8624c0e 100644 --- a/googletest/docs/advanced.md +++ b/googletest/docs/advanced.md @@ -1222,15 +1222,15 @@ First, you subclass the `::testing::Environment` class to define a test environment, which knows how to set-up and tear-down: ```c++ -class Environment { +class Environment : public ::testing::Environment { public: virtual ~Environment() {} // Override this to define how to set up the environment. - virtual void SetUp() {} + void SetUp() override {} // Override this to define how to tear down the environment. - virtual void TearDown() {} + void TearDown() override {} }; ``` diff --git a/googletest/docs/primer.md b/googletest/docs/primer.md index e441ceb8..27598209 100644 --- a/googletest/docs/primer.md +++ b/googletest/docs/primer.md @@ -193,7 +193,7 @@ 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 [FAQ](faq.md)for more details. +typed while `NULL` is not. See [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 @@ -456,7 +456,7 @@ When invoked, the `RUN_ALL_TESTS()` macro: * Deletes the fixture. -* Restores the state of all all googletest flags +* Restores the state of all googletest flags * Repeats the above steps for the next test, until all tests have run. |