diff options
Diffstat (limited to 'googlemock/docs/ForDummies.md')
| -rw-r--r-- | googlemock/docs/ForDummies.md | 72 |
1 files changed, 40 insertions, 32 deletions
diff --git a/googlemock/docs/ForDummies.md b/googlemock/docs/ForDummies.md index 0da4cbe..e2a430f 100644 --- a/googlemock/docs/ForDummies.md +++ b/googlemock/docs/ForDummies.md @@ -23,8 +23,8 @@ Using Google Mock involves three basic steps: # Why Google Mock? # 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. + * Someone has to implement the mocks. The job is usually tedious and error-prone. No wonder people go great distances 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. In contrast, Java and Python programmers have some fine mock frameworks, 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. @@ -49,7 +49,7 @@ Using Google Mock is easy! Inside your C++ source file, just `#include` `"gtest/ # A Case for Mock Turtles # Let's look at an example. Suppose you are developing a graphics program that relies on a LOGO-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 and know the right thing to do: instead of having your application talk to the drawing API directly, wrap the API in an interface (say, `Turtle`) and code to that interface: -``` +```cpp class Turtle { ... virtual ~Turtle() {} @@ -83,7 +83,7 @@ Using the `Turtle` interface as example, here are the simple steps you need to f After the process, you should have something like: -``` +```cpp #include "gmock/gmock.h" // Brings in Google Mock. class MockTurtle : public Turtle { public: @@ -125,7 +125,7 @@ Once you have a mock class, using it is easy. The typical work flow is: Here's an example: -``` +```cpp #include "path/to/mock-turtle.h" #include "gmock/gmock.h" #include "gtest/gtest.h" @@ -170,8 +170,8 @@ Admittedly, this test is contrived and doesn't do much. You can easily achieve t ## Using Google Mock with Any Testing Framework ## If you want to use something other than Google Test (e.g. [CppUnit](http://sourceforge.net/projects/cppunit/) or -[CxxTest](http://cxxtest.tigris.org/)) as your testing framework, just change the `main()` function in the previous section to: -``` +[CxxTest](https://cxxtest.com/)) as your testing framework, just change the `main()` function in the previous section to: +```cpp int main(int argc, char** argv) { // The following line causes Google Mock to throw an exception on failure, // which will be interpreted by your testing framework as a test failure. @@ -187,7 +187,7 @@ sometimes causes the test program to crash. You'll still be able to notice that the test has failed, but it's not a graceful failure. A better solution is to use Google Test's -[event listener API](../../googletest/docs/AdvancedGuide.md#extending-google-test-by-handling-test-events) +[event listener API](../../googletest/docs/advanced.md#extending-googletest-by-handling-test-events) to report a test failure to your testing framework properly. You'll need to implement the `OnTestPartResult()` method of the event listener interface, but it should be straightforward. @@ -203,7 +203,7 @@ The key to using a mock object successfully is to set the _right expectations_ o ## General Syntax ## In Google Mock 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) @@ -216,8 +216,9 @@ The macro can be followed by some optional _clauses_ that provide more informati This syntax is designed to make an expectation read like English. For example, you can probably guess that -``` -using ::testing::Return;... +```cpp +using ::testing::Return; +... EXPECT_CALL(turtle, GetX()) .Times(5) .WillOnce(Return(100)) @@ -232,14 +233,14 @@ says that the `turtle` object's `GetX()` method will be called five times, it wi ## Matchers: What Arguments Do We Expect? ## When a mock function takes arguments, we must specify what arguments we are expecting; for example: -``` +```cpp // Expects the turtle to move forward by 100 units. EXPECT_CALL(turtle, Forward(100)); ``` Sometimes you may 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 care to check that `Forward()` will be called but aren't interested in its actual argument, write `_` as the argument, which means "anything goes": -``` +```cpp using ::testing::_; ... // Expects the turtle to move forward. @@ -250,8 +251,9 @@ EXPECT_CALL(turtle, Forward(_)); A list of built-in matchers can be found in the [CheatSheet](CheatSheet.md). For example, here's the `Ge` (greater than or equal) matcher: -``` -using ::testing::Ge;... +```cpp +using ::testing::Ge; +... EXPECT_CALL(turtle, Forward(Ge(100))); ``` @@ -279,8 +281,9 @@ First, if the return type of a mock function is a built-in type or a pointer, th 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, -``` -using ::testing::Return;... +```cpp +using ::testing::Return; +... EXPECT_CALL(turtle, GetX()) .WillOnce(Return(100)) .WillOnce(Return(200)) @@ -289,8 +292,9 @@ EXPECT_CALL(turtle, GetX()) This says that `turtle.GetX()` will be called _exactly three times_ (Google Mock 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. -``` -using ::testing::Return;... +```cpp +using ::testing::Return; +... EXPECT_CALL(turtle, GetY()) .WillOnce(Return(100)) .WillOnce(Return(200)) @@ -305,7 +309,7 @@ What can we do inside `WillOnce()` besides `Return()`? You can return a referenc **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 int n = 100; EXPECT_CALL(turtle, GetX()) .Times(4) @@ -316,8 +320,9 @@ Instead of returning 100, 101, 102, ..., consecutively, this mock function will Time for another quiz! What do you think the following means? -``` -using ::testing::Return;... +```cpp +using ::testing::Return; +... EXPECT_CALL(turtle, GetY()) .Times(4) .WillOnce(Return(100)); @@ -330,8 +335,9 @@ So far we've only shown examples where you have a single expectation. More reali By default, when a mock method is invoked, Google Mock 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: -``` -using ::testing::_;... +```cpp +using ::testing::_; +... EXPECT_CALL(turtle, Forward(_)); // #1 EXPECT_CALL(turtle, Forward(10)) // #2 .Times(2); @@ -346,8 +352,9 @@ By default, an expectation can match a call even though an earlier expectation h Sometimes, you may want all the expected calls to occur in a strict order. To say this in Google Mock is easy: -``` -using ::testing::InSequence;... +```cpp +using ::testing::InSequence; +... TEST(FooTest, DrawsLineSegment) { ... { @@ -365,15 +372,16 @@ By creating an object of type `InSequence`, all expectations in its scope are pu 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 in the [CookBook](CookBook#Expecting_Partially_Ordered_Calls.md).) +(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 in the [CookBook](CookBook.md#expecting-partially-ordered-calls).) ## All Expectations Are Sticky (Unless Said Otherwise) ## 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!): -``` -using ::testing::_;... +```cpp +using ::testing::_; +... EXPECT_CALL(turtle, GoTo(_, _)) // #1 .Times(AnyNumber()); EXPECT_CALL(turtle, GoTo(0, 0)) // #2 @@ -386,7 +394,7 @@ This example shows that **expectations in Google Mock are "sticky" by default**, 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--) { @@ -399,7 +407,7 @@ If you think it says that `turtle.GetX()` will be called `n` times and will retu 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--) { @@ -411,7 +419,7 @@ for (int i = n; i > 0; i--) { 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; ... |