diff options
Diffstat (limited to 'chromium/third_party/googletest/src/docs/gmock_cook_book.md')
| -rw-r--r-- | chromium/third_party/googletest/src/docs/gmock_cook_book.md | 111 |
1 files changed, 30 insertions, 81 deletions
diff --git a/chromium/third_party/googletest/src/docs/gmock_cook_book.md b/chromium/third_party/googletest/src/docs/gmock_cook_book.md index c6a99912397..c08958eb16a 100644 --- a/chromium/third_party/googletest/src/docs/gmock_cook_book.md +++ b/chromium/third_party/googletest/src/docs/gmock_cook_book.md @@ -1088,7 +1088,8 @@ 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 +including the `Lt()` matcher above. See +[Multi-argument Matchers](reference/matchers.md#MultiArgMatchers) for the complete list. Note that if you want to pass the arguments to a predicate of your own (e.g. @@ -1136,59 +1137,17 @@ 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. +See [`EXPECT_THAT`](reference/assertions.md#EXPECT_THAT) in the Assertions +Reference. ### 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: +gMock provides a set of built-in matchers for matching arguments with expected +values—see the [Matchers Reference](reference/matchers.md) for more information. +In case you find the built-in set 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; @@ -1752,7 +1711,7 @@ 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`. +[`After` clause](reference/mocking.md#EXPECT_CALL.After) 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 @@ -3015,31 +2974,21 @@ 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} +Do not set new expectations after verifying and clearing a mock after its use. +Setting expectations after code that exercises the mock has undefined behavior. +See [Using Mocks in Tests](gmock_for_dummies.md#using-mocks-in-tests) for more +information. -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. +### Using Checkpoints {#UsingCheckPoints} -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. +Sometimes you might want to test a mock object's behavior in phases whose sizes +are each manageable, or you might want to set more detailed expectations about +which API calls invoke which mock functions. -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: +A technique you can use is to put the expectations in a sequence and insert +calls to a dummy "checkpoint" 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 the code: ```cpp Foo(1); @@ -3048,7 +2997,7 @@ time. For example, if you are exercising code: ``` 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: +`Foo(2)` doesn't invoke anything, you can write: ```cpp using ::testing::MockFunction; @@ -3074,10 +3023,10 @@ TEST(FooTest, InvokesBarCorrectly) { } ``` -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()`. +The expectation spec says that the first `Bar("a")` call must happen before +checkpoint "1", the second `Bar("a")` call must happen after checkpoint "2", and +nothing should happen between the two checkpoints. The explicit checkpoints make +it clear which `Bar("a")` is called by which call to `Foo()`. ### Mocking Destructors @@ -3371,7 +3320,7 @@ or, ```cpp using ::testing::Not; ... - // Verifies that two values are divisible by 7. + // Verifies that a value is divisible by 7 and the other is not. EXPECT_THAT(some_expression, IsDivisibleBy7()); EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7())); ``` @@ -3696,7 +3645,7 @@ class NotNullMatcher { } // Describes the property of a value matching this matcher. - void DescribeTo(std::ostream& os) const { *os << "is not NULL"; } + 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"; } |