1 |
2 |
jamieiles |
## Google Mock ##
|
2 |
|
|
|
3 |
|
|
The Google C++ mocking framework.
|
4 |
|
|
|
5 |
|
|
### Overview ###
|
6 |
|
|
|
7 |
|
|
Google's framework for writing and using C++ mock classes.
|
8 |
|
|
It can help you derive better designs of your system and write better tests.
|
9 |
|
|
|
10 |
|
|
It is inspired by:
|
11 |
|
|
|
12 |
|
|
* [jMock](http://www.jmock.org/),
|
13 |
|
|
* [EasyMock](http://www.easymock.org/), and
|
14 |
|
|
* [Hamcrest](http://code.google.com/p/hamcrest/),
|
15 |
|
|
|
16 |
|
|
and designed with C++'s specifics in mind.
|
17 |
|
|
|
18 |
|
|
Google mock:
|
19 |
|
|
|
20 |
|
|
* lets you create mock classes trivially using simple macros.
|
21 |
|
|
* supports a rich set of matchers and actions.
|
22 |
|
|
* handles unordered, partially ordered, or completely ordered expectations.
|
23 |
|
|
* is extensible by users.
|
24 |
|
|
|
25 |
|
|
We hope you find it useful!
|
26 |
|
|
|
27 |
|
|
### Features ###
|
28 |
|
|
|
29 |
|
|
* Provides a declarative syntax for defining mocks.
|
30 |
|
|
* Can easily define partial (hybrid) mocks, which are a cross of real
|
31 |
|
|
and mock objects.
|
32 |
|
|
* Handles functions of arbitrary types and overloaded functions.
|
33 |
|
|
* Comes with a rich set of matchers for validating function arguments.
|
34 |
|
|
* Uses an intuitive syntax for controlling the behavior of a mock.
|
35 |
|
|
* Does automatic verification of expectations (no record-and-replay needed).
|
36 |
|
|
* Allows arbitrary (partial) ordering constraints on
|
37 |
|
|
function calls to be expressed,.
|
38 |
|
|
* Lets a user extend it by defining new matchers and actions.
|
39 |
|
|
* Does not use exceptions.
|
40 |
|
|
* Is easy to learn and use.
|
41 |
|
|
|
42 |
|
|
Please see the project page above for more information as well as the
|
43 |
|
|
mailing list for questions, discussions, and development. There is
|
44 |
|
|
also an IRC channel on OFTC (irc.oftc.net) #gtest available. Please
|
45 |
|
|
join us!
|
46 |
|
|
|
47 |
|
|
Please note that code under [scripts/generator](scripts/generator/) is
|
48 |
|
|
from [cppclean](http://code.google.com/p/cppclean/) and released under
|
49 |
|
|
the Apache License, which is different from Google Mock's license.
|
50 |
|
|
|
51 |
|
|
## Getting Started ##
|
52 |
|
|
|
53 |
|
|
If you are new to the project, we suggest that you read the user
|
54 |
|
|
documentation in the following order:
|
55 |
|
|
|
56 |
|
|
* Learn the [basics](../googletest/docs/Primer.md) of
|
57 |
|
|
Google Test, if you choose to use Google Mock with it (recommended).
|
58 |
|
|
* Read [Google Mock for Dummies](docs/ForDummies.md).
|
59 |
|
|
* Read the instructions below on how to build Google Mock.
|
60 |
|
|
|
61 |
|
|
You can also watch Zhanyong's [talk](http://www.youtube.com/watch?v=sYpCyLI47rM) on Google Mock's usage and implementation.
|
62 |
|
|
|
63 |
|
|
Once you understand the basics, check out the rest of the docs:
|
64 |
|
|
|
65 |
|
|
* [CheatSheet](docs/CheatSheet.md) - all the commonly used stuff
|
66 |
|
|
at a glance.
|
67 |
|
|
* [CookBook](docs/CookBook.md) - recipes for getting things done,
|
68 |
|
|
including advanced techniques.
|
69 |
|
|
|
70 |
|
|
If you need help, please check the
|
71 |
|
|
[KnownIssues](docs/KnownIssues.md) and
|
72 |
|
|
[FrequentlyAskedQuestions](docs/FrequentlyAskedQuestions.md) before
|
73 |
|
|
posting a question on the
|
74 |
|
|
[discussion group](http://groups.google.com/group/googlemock).
|
75 |
|
|
|
76 |
|
|
|
77 |
|
|
### Using Google Mock Without Google Test ###
|
78 |
|
|
|
79 |
|
|
Google Mock is not a testing framework itself. Instead, it needs a
|
80 |
|
|
testing framework for writing tests. Google Mock works seamlessly
|
81 |
|
|
with [Google Test](http://code.google.com/p/googletest/), but
|
82 |
|
|
you can also use it with [any C++ testing framework](googlemock/ForDummies.md#Using_Google_Mock_with_Any_Testing_Framework).
|
83 |
|
|
|
84 |
|
|
### Requirements for End Users ###
|
85 |
|
|
|
86 |
|
|
Google Mock is implemented on top of [Google Test](
|
87 |
|
|
http://github.com/google/googletest/), and depends on it.
|
88 |
|
|
You must use the bundled version of Google Test when using Google Mock.
|
89 |
|
|
|
90 |
|
|
You can also easily configure Google Mock to work with another testing
|
91 |
|
|
framework, although it will still need Google Test. Please read
|
92 |
|
|
["Using_Google_Mock_with_Any_Testing_Framework"](
|
93 |
|
|
docs/ForDummies.md#Using_Google_Mock_with_Any_Testing_Framework)
|
94 |
|
|
for instructions.
|
95 |
|
|
|
96 |
|
|
Google Mock depends on advanced C++ features and thus requires a more
|
97 |
|
|
modern compiler. The following are needed to use Google Mock:
|
98 |
|
|
|
99 |
|
|
#### Linux Requirements ####
|
100 |
|
|
|
101 |
|
|
* GNU-compatible Make or "gmake"
|
102 |
|
|
* POSIX-standard shell
|
103 |
|
|
* POSIX(-2) Regular Expressions (regex.h)
|
104 |
|
|
* C++98-standard-compliant compiler (e.g. GCC 3.4 or newer)
|
105 |
|
|
|
106 |
|
|
#### Windows Requirements ####
|
107 |
|
|
|
108 |
|
|
* Microsoft Visual C++ 8.0 SP1 or newer
|
109 |
|
|
|
110 |
|
|
#### Mac OS X Requirements ####
|
111 |
|
|
|
112 |
|
|
* Mac OS X 10.4 Tiger or newer
|
113 |
|
|
* Developer Tools Installed
|
114 |
|
|
|
115 |
|
|
### Requirements for Contributors ###
|
116 |
|
|
|
117 |
|
|
We welcome patches. If you plan to contribute a patch, you need to
|
118 |
|
|
build Google Mock and its tests, which has further requirements:
|
119 |
|
|
|
120 |
|
|
* Automake version 1.9 or newer
|
121 |
|
|
* Autoconf version 2.59 or newer
|
122 |
|
|
* Libtool / Libtoolize
|
123 |
|
|
* Python version 2.3 or newer (for running some of the tests and
|
124 |
|
|
re-generating certain source files from templates)
|
125 |
|
|
|
126 |
|
|
### Building Google Mock ###
|
127 |
|
|
|
128 |
|
|
#### Preparing to Build (Unix only) ####
|
129 |
|
|
|
130 |
|
|
If you are using a Unix system and plan to use the GNU Autotools build
|
131 |
|
|
system to build Google Mock (described below), you'll need to
|
132 |
|
|
configure it now.
|
133 |
|
|
|
134 |
|
|
To prepare the Autotools build system:
|
135 |
|
|
|
136 |
|
|
cd googlemock
|
137 |
|
|
autoreconf -fvi
|
138 |
|
|
|
139 |
|
|
To build Google Mock and your tests that use it, you need to tell your
|
140 |
|
|
build system where to find its headers and source files. The exact
|
141 |
|
|
way to do it depends on which build system you use, and is usually
|
142 |
|
|
straightforward.
|
143 |
|
|
|
144 |
|
|
This section shows how you can integrate Google Mock into your
|
145 |
|
|
existing build system.
|
146 |
|
|
|
147 |
|
|
Suppose you put Google Mock in directory `${GMOCK_DIR}` and Google Test
|
148 |
|
|
in `${GTEST_DIR}` (the latter is `${GMOCK_DIR}/gtest` by default). To
|
149 |
|
|
build Google Mock, create a library build target (or a project as
|
150 |
|
|
called by Visual Studio and Xcode) to compile
|
151 |
|
|
|
152 |
|
|
${GTEST_DIR}/src/gtest-all.cc and ${GMOCK_DIR}/src/gmock-all.cc
|
153 |
|
|
|
154 |
|
|
with
|
155 |
|
|
|
156 |
|
|
${GTEST_DIR}/include and ${GMOCK_DIR}/include
|
157 |
|
|
|
158 |
|
|
in the system header search path, and
|
159 |
|
|
|
160 |
|
|
${GTEST_DIR} and ${GMOCK_DIR}
|
161 |
|
|
|
162 |
|
|
in the normal header search path. Assuming a Linux-like system and gcc,
|
163 |
|
|
something like the following will do:
|
164 |
|
|
|
165 |
|
|
g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
|
166 |
|
|
-isystem ${GMOCK_DIR}/include -I${GMOCK_DIR} \
|
167 |
|
|
-pthread -c ${GTEST_DIR}/src/gtest-all.cc
|
168 |
|
|
g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
|
169 |
|
|
-isystem ${GMOCK_DIR}/include -I${GMOCK_DIR} \
|
170 |
|
|
-pthread -c ${GMOCK_DIR}/src/gmock-all.cc
|
171 |
|
|
ar -rv libgmock.a gtest-all.o gmock-all.o
|
172 |
|
|
|
173 |
|
|
(We need -pthread as Google Test and Google Mock use threads.)
|
174 |
|
|
|
175 |
|
|
Next, you should compile your test source file with
|
176 |
|
|
${GTEST\_DIR}/include and ${GMOCK\_DIR}/include in the header search
|
177 |
|
|
path, and link it with gmock and any other necessary libraries:
|
178 |
|
|
|
179 |
|
|
g++ -isystem ${GTEST_DIR}/include -isystem ${GMOCK_DIR}/include \
|
180 |
|
|
-pthread path/to/your_test.cc libgmock.a -o your_test
|
181 |
|
|
|
182 |
|
|
As an example, the make/ directory contains a Makefile that you can
|
183 |
|
|
use to build Google Mock on systems where GNU make is available
|
184 |
|
|
(e.g. Linux, Mac OS X, and Cygwin). It doesn't try to build Google
|
185 |
|
|
Mock's own tests. Instead, it just builds the Google Mock library and
|
186 |
|
|
a sample test. You can use it as a starting point for your own build
|
187 |
|
|
script.
|
188 |
|
|
|
189 |
|
|
If the default settings are correct for your environment, the
|
190 |
|
|
following commands should succeed:
|
191 |
|
|
|
192 |
|
|
cd ${GMOCK_DIR}/make
|
193 |
|
|
make
|
194 |
|
|
./gmock_test
|
195 |
|
|
|
196 |
|
|
If you see errors, try to tweak the contents of
|
197 |
|
|
[make/Makefile](make/Makefile) to make them go away.
|
198 |
|
|
|
199 |
|
|
### Windows ###
|
200 |
|
|
|
201 |
|
|
The msvc/2005 directory contains VC++ 2005 projects and the msvc/2010
|
202 |
|
|
directory contains VC++ 2010 projects for building Google Mock and
|
203 |
|
|
selected tests.
|
204 |
|
|
|
205 |
|
|
Change to the appropriate directory and run "msbuild gmock.sln" to
|
206 |
|
|
build the library and tests (or open the gmock.sln in the MSVC IDE).
|
207 |
|
|
If you want to create your own project to use with Google Mock, you'll
|
208 |
|
|
have to configure it to use the `gmock_config` propety sheet. For that:
|
209 |
|
|
|
210 |
|
|
* Open the Property Manager window (View | Other Windows | Property Manager)
|
211 |
|
|
* Right-click on your project and select "Add Existing Property Sheet..."
|
212 |
|
|
* Navigate to `gmock_config.vsprops` or `gmock_config.props` and select it.
|
213 |
|
|
* In Project Properties | Configuration Properties | General | Additional
|
214 |
|
|
Include Directories, type /include.
|
215 |
|
|
|
216 |
|
|
### Tweaking Google Mock ###
|
217 |
|
|
|
218 |
|
|
Google Mock can be used in diverse environments. The default
|
219 |
|
|
configuration may not work (or may not work well) out of the box in
|
220 |
|
|
some environments. However, you can easily tweak Google Mock by
|
221 |
|
|
defining control macros on the compiler command line. Generally,
|
222 |
|
|
these macros are named like `GTEST_XYZ` and you define them to either 1
|
223 |
|
|
or 0 to enable or disable a certain feature.
|
224 |
|
|
|
225 |
|
|
We list the most frequently used macros below. For a complete list,
|
226 |
|
|
see file [${GTEST\_DIR}/include/gtest/internal/gtest-port.h](
|
227 |
|
|
../googletest/include/gtest/internal/gtest-port.h).
|
228 |
|
|
|
229 |
|
|
### Choosing a TR1 Tuple Library ###
|
230 |
|
|
|
231 |
|
|
Google Mock uses the C++ Technical Report 1 (TR1) tuple library
|
232 |
|
|
heavily. Unfortunately TR1 tuple is not yet widely available with all
|
233 |
|
|
compilers. The good news is that Google Test 1.4.0+ implements a
|
234 |
|
|
subset of TR1 tuple that's enough for Google Mock's need. Google Mock
|
235 |
|
|
will automatically use that implementation when the compiler doesn't
|
236 |
|
|
provide TR1 tuple.
|
237 |
|
|
|
238 |
|
|
Usually you don't need to care about which tuple library Google Test
|
239 |
|
|
and Google Mock use. However, if your project already uses TR1 tuple,
|
240 |
|
|
you need to tell Google Test and Google Mock to use the same TR1 tuple
|
241 |
|
|
library the rest of your project uses, or the two tuple
|
242 |
|
|
implementations will clash. To do that, add
|
243 |
|
|
|
244 |
|
|
-DGTEST_USE_OWN_TR1_TUPLE=0
|
245 |
|
|
|
246 |
|
|
to the compiler flags while compiling Google Test, Google Mock, and
|
247 |
|
|
your tests. If you want to force Google Test and Google Mock to use
|
248 |
|
|
their own tuple library, just add
|
249 |
|
|
|
250 |
|
|
-DGTEST_USE_OWN_TR1_TUPLE=1
|
251 |
|
|
|
252 |
|
|
to the compiler flags instead.
|
253 |
|
|
|
254 |
|
|
If you want to use Boost's TR1 tuple library with Google Mock, please
|
255 |
|
|
refer to the Boost website (http://www.boost.org/) for how to obtain
|
256 |
|
|
it and set it up.
|
257 |
|
|
|
258 |
|
|
### As a Shared Library (DLL) ###
|
259 |
|
|
|
260 |
|
|
Google Mock is compact, so most users can build and link it as a static
|
261 |
|
|
library for the simplicity. Google Mock can be used as a DLL, but the
|
262 |
|
|
same DLL must contain Google Test as well. See
|
263 |
|
|
[Google Test's README][gtest_readme]
|
264 |
|
|
for instructions on how to set up necessary compiler settings.
|
265 |
|
|
|
266 |
|
|
### Tweaking Google Mock ###
|
267 |
|
|
|
268 |
|
|
Most of Google Test's control macros apply to Google Mock as well.
|
269 |
|
|
Please see [Google Test's README][gtest_readme] for how to tweak them.
|
270 |
|
|
|
271 |
|
|
### Upgrading from an Earlier Version ###
|
272 |
|
|
|
273 |
|
|
We strive to keep Google Mock releases backward compatible.
|
274 |
|
|
Sometimes, though, we have to make some breaking changes for the
|
275 |
|
|
users' long-term benefits. This section describes what you'll need to
|
276 |
|
|
do if you are upgrading from an earlier version of Google Mock.
|
277 |
|
|
|
278 |
|
|
#### Upgrading from 1.1.0 or Earlier ####
|
279 |
|
|
|
280 |
|
|
You may need to explicitly enable or disable Google Test's own TR1
|
281 |
|
|
tuple library. See the instructions in section "[Choosing a TR1 Tuple
|
282 |
|
|
Library](../googletest/#choosing-a-tr1-tuple-library)".
|
283 |
|
|
|
284 |
|
|
#### Upgrading from 1.4.0 or Earlier ####
|
285 |
|
|
|
286 |
|
|
On platforms where the pthread library is available, Google Test and
|
287 |
|
|
Google Mock use it in order to be thread-safe. For this to work, you
|
288 |
|
|
may need to tweak your compiler and/or linker flags. Please see the
|
289 |
|
|
"[Multi-threaded Tests](../googletest#multi-threaded-tests
|
290 |
|
|
)" section in file Google Test's README for what you may need to do.
|
291 |
|
|
|
292 |
|
|
If you have custom matchers defined using `MatcherInterface` or
|
293 |
|
|
`MakePolymorphicMatcher()`, you'll need to update their definitions to
|
294 |
|
|
use the new matcher API (
|
295 |
|
|
[monomorphic](http://code.google.com/p/googlemock/wiki/CookBook#Writing_New_Monomorphic_Matchers),
|
296 |
|
|
[polymorphic](http://code.google.com/p/googlemock/wiki/CookBook#Writing_New_Polymorphic_Matchers)).
|
297 |
|
|
Matchers defined using `MATCHER()` or `MATCHER_P*()` aren't affected.
|
298 |
|
|
|
299 |
|
|
### Developing Google Mock ###
|
300 |
|
|
|
301 |
|
|
This section discusses how to make your own changes to Google Mock.
|
302 |
|
|
|
303 |
|
|
#### Testing Google Mock Itself ####
|
304 |
|
|
|
305 |
|
|
To make sure your changes work as intended and don't break existing
|
306 |
|
|
functionality, you'll want to compile and run Google Test's own tests.
|
307 |
|
|
For that you'll need Autotools. First, make sure you have followed
|
308 |
|
|
the instructions above to configure Google Mock.
|
309 |
|
|
Then, create a build output directory and enter it. Next,
|
310 |
|
|
|
311 |
|
|
${GMOCK_DIR}/configure # try --help for more info
|
312 |
|
|
|
313 |
|
|
Once you have successfully configured Google Mock, the build steps are
|
314 |
|
|
standard for GNU-style OSS packages.
|
315 |
|
|
|
316 |
|
|
make # Standard makefile following GNU conventions
|
317 |
|
|
make check # Builds and runs all tests - all should pass.
|
318 |
|
|
|
319 |
|
|
Note that when building your project against Google Mock, you are building
|
320 |
|
|
against Google Test as well. There is no need to configure Google Test
|
321 |
|
|
separately.
|
322 |
|
|
|
323 |
|
|
#### Contributing a Patch ####
|
324 |
|
|
|
325 |
|
|
We welcome patches.
|
326 |
|
|
Please read the [Developer's Guide](docs/DevGuide.md)
|
327 |
|
|
for how you can contribute. In particular, make sure you have signed
|
328 |
|
|
the Contributor License Agreement, or we won't be able to accept the
|
329 |
|
|
patch.
|
330 |
|
|
|
331 |
|
|
Happy testing!
|
332 |
|
|
|
333 |
|
|
[gtest_readme]: ../googletest/README.md "googletest"
|