README.md 10.8 KB
Newer Older
Billy Donahue's avatar
Billy Donahue committed
1
## Google C++ Mocking Framework ##
2

Billy Donahue's avatar
Billy Donahue committed
3
<http://github.com/google/googlemock/>
4

Billy Donahue's avatar
Billy Donahue committed
5
### Overview ###
6
7
8
9
10
11

Google's framework for writing and using C++ mock classes on a variety
of platforms (Linux, Mac OS X, Windows, Windows CE, Symbian, etc).
Inspired by jMock, EasyMock, and Hamcrest, and designed with C++'s
specifics in mind, it can help you derive better designs of your
system and write better tests.
12

Billy Donahue's avatar
Billy Donahue committed
13
14
15
16
17
18
19
20
21
22
23
24
25
26
### Features ###

  * Provides a declarative syntax for defining mocks.
  * Can easily define partial (hybrid) mocks, which are a cross of real
    and mock objects.
  * Handles functions of arbitrary types and overloaded functions.
  * Comes with a rich set of matchers for validating function arguments.
  * Uses an intuitive syntax for controlling the behavior of a mock.
  * Does automatic verification of expectations (no record-and-replay needed).
  * Allows arbitrary (partial) ordering constraints on
    function calls to be expressed,.
  * Lets a user extend it by defining new matchers and actions.
  * Does not use exceptions.
  * Is easy to learn and use.
27

28
29
30
31
Please see the project page above for more information as well as the
mailing list for questions, discussions, and development.  There is
also an IRC channel on OFTC (irc.oftc.net) #gtest available.  Please
join us!
32

Billy Donahue's avatar
Billy Donahue committed
33
34
35
Please note that code under [scripts/generator](scripts/generator/) is
from [cppclean](http://code.google.com/p/cppclean/) and released under
the Apache License, which is different from Google Mock's license.
36

Billy Donahue's avatar
Billy Donahue committed
37
### Requirements for End Users ###
38

Billy Donahue's avatar
Billy Donahue committed
39
Google Mock is implemented on top of [Google Test](
Billy Donahue's avatar
Billy Donahue committed
40
http://github.com/google/googletest/), and depends on it.
Billy Donahue's avatar
Billy Donahue committed
41
You must use the bundled version of Google Test when using Google Mock.
42

43
You can also easily configure Google Mock to work with another testing
Billy Donahue's avatar
Billy Donahue committed
44
45
46
47
framework, although it will still need Google Test.  Please read
["Using_Google_Mock_with_Any_Testing_Framework"](
    docs/ForDummies.md#Using_Google_Mock_with_Any_Testing_Framework)
for instructions.
48

49
Google Mock depends on advanced C++ features and thus requires a more
Billy Donahue's avatar
Billy Donahue committed
50
modern compiler. The following are needed to use Google Mock:
51

Billy Donahue's avatar
Billy Donahue committed
52
#### Linux Requirements ####
53

54
55
56
  * GNU-compatible Make or "gmake"
  * POSIX-standard shell
  * POSIX(-2) Regular Expressions (regex.h)
57
  * C++98-standard-compliant compiler (e.g. GCC 3.4 or newer)
58

Billy Donahue's avatar
Billy Donahue committed
59
#### Windows Requirements ####
60

61
62
  * Microsoft Visual C++ 8.0 SP1 or newer

Billy Donahue's avatar
Billy Donahue committed
63
#### Mac OS X Requirements ####
64

65
66
67
  * Mac OS X 10.4 Tiger or newer
  * Developer Tools Installed

Billy Donahue's avatar
Billy Donahue committed
68
### Requirements for Contributors ###
69

Billy Donahue's avatar
Billy Donahue committed
70
71
We welcome patches. If you plan to contribute a patch, you need to
build Google Mock and its tests, which has further requirements:
72
73
74
75
76
77
78

  * Automake version 1.9 or newer
  * Autoconf version 2.59 or newer
  * Libtool / Libtoolize
  * Python version 2.3 or newer (for running some of the tests and
    re-generating certain source files from templates)

Billy Donahue's avatar
Billy Donahue committed
79
### Building Google Mock ###
80

Billy Donahue's avatar
Billy Donahue committed
81
#### Preparing to Build (Unix only) ####
82

Billy Donahue's avatar
Billy Donahue committed
83
If you are using a Unix system and plan to use the GNU Autotools build
84
system to build Google Mock (described below), you'll need to
Billy Donahue's avatar
Billy Donahue committed
85
configure it now.
86

Billy Donahue's avatar
Billy Donahue committed
87
To prepare the Autotools build system:
shiqian's avatar
shiqian committed
88

Billy Donahue's avatar
Billy Donahue committed
89
    cd googlemock
Billy Donahue's avatar
Billy Donahue committed
90
    autoreconf -fvi
shiqian's avatar
shiqian committed
91

92
93
94
95
To build Google Mock and your tests that use it, you need to tell your
build system where to find its headers and source files.  The exact
way to do it depends on which build system you use, and is usually
straightforward.
96

97
98
99
This section shows how you can integrate Google Mock into your
existing build system.

Billy Donahue's avatar
Billy Donahue committed
100
101
Suppose you put Google Mock in directory `${GMOCK_DIR}` and Google Test
in `${GTEST_DIR}` (the latter is `${GMOCK_DIR}/gtest` by default).  To
102
103
104
build Google Mock, create a library build target (or a project as
called by Visual Studio and Xcode) to compile

Billy Donahue's avatar
Billy Donahue committed
105
    ${GTEST_DIR}/src/gtest-all.cc and ${GMOCK_DIR}/src/gmock-all.cc
106
107
108

with

Billy Donahue's avatar
Billy Donahue committed
109
    ${GTEST_DIR}/include and ${GMOCK_DIR}/include
110

111
112
in the system header search path, and

Billy Donahue's avatar
Billy Donahue committed
113
    ${GTEST_DIR} and ${GMOCK_DIR}
114
115

in the normal header search path.  Assuming a Linux-like system and gcc,
116
117
something like the following will do:

Billy Donahue's avatar
Billy Donahue committed
118
119
120
121
122
123
124
    g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
        -isystem ${GMOCK_DIR}/include -I${GMOCK_DIR} \
        -pthread -c ${GTEST_DIR}/src/gtest-all.cc
    g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
        -isystem ${GMOCK_DIR}/include -I${GMOCK_DIR} \
        -pthread -c ${GMOCK_DIR}/src/gmock-all.cc
    ar -rv libgmock.a gtest-all.o gmock-all.o
125

126
127
(We need -pthread as Google Test and Google Mock use threads.)

128
Next, you should compile your test source file with
Billy Donahue's avatar
Billy Donahue committed
129
${GTEST\_DIR}/include and ${GMOCK\_DIR}/include in the header search
130
131
path, and link it with gmock and any other necessary libraries:

Billy Donahue's avatar
Billy Donahue committed
132
133
    g++ -isystem ${GTEST_DIR}/include -isystem ${GMOCK_DIR}/include \
        -pthread path/to/your_test.cc libgmock.a -o your_test
134
135
136
137
138
139
140
141
142
143
144

As an example, the make/ directory contains a Makefile that you can
use to build Google Mock on systems where GNU make is available
(e.g. Linux, Mac OS X, and Cygwin).  It doesn't try to build Google
Mock's own tests.  Instead, it just builds the Google Mock library and
a sample test.  You can use it as a starting point for your own build
script.

If the default settings are correct for your environment, the
following commands should succeed:

Billy Donahue's avatar
Billy Donahue committed
145
146
147
    cd ${GMOCK_DIR}/make
    make
    ./gmock_test
148

Billy Donahue's avatar
Billy Donahue committed
149
150
If you see errors, try to tweak the contents of
[make/Makefile](make/Makefile) to make them go away.
151
152
153

### Windows ###

154
155
156
The msvc/2005 directory contains VC++ 2005 projects and the msvc/2010
directory contains VC++ 2010 projects for building Google Mock and
selected tests.
157

158
159
160
Change to the appropriate directory and run "msbuild gmock.sln" to
build the library and tests (or open the gmock.sln in the MSVC IDE).
If you want to create your own project to use with Google Mock, you'll
Billy Donahue's avatar
Billy Donahue committed
161
have to configure it to use the `gmock_config` propety sheet.  For that:
162
163
164

 * Open the Property Manager window (View | Other Windows | Property Manager)
 * Right-click on your project and select "Add Existing Property Sheet..."
Billy Donahue's avatar
Billy Donahue committed
165
 * Navigate to `gmock_config.vsprops` or `gmock_config.props` and select it.
166
167
168
 * In Project Properties | Configuration Properties | General | Additional
   Include Directories, type <path to Google Mock>/include.

Billy Donahue's avatar
Billy Donahue committed
169
### Tweaking Google Mock ###
170
171
172
173
174

Google Mock can be used in diverse environments.  The default
configuration may not work (or may not work well) out of the box in
some environments.  However, you can easily tweak Google Mock by
defining control macros on the compiler command line.  Generally,
Billy Donahue's avatar
Billy Donahue committed
175
these macros are named like `GTEST_XYZ` and you define them to either 1
176
177
178
or 0 to enable or disable a certain feature.

We list the most frequently used macros below.  For a complete list,
Billy Donahue's avatar
Billy Donahue committed
179
180
see file [${GTEST\_DIR}/include/gtest/internal/gtest-port.h](
../googletest/include/gtest/internal/gtest-port.h).
181
182

### Choosing a TR1 Tuple Library ###
183

184
185
186
187
188
189
190
191
192
193
Google Mock uses the C++ Technical Report 1 (TR1) tuple library
heavily.  Unfortunately TR1 tuple is not yet widely available with all
compilers.  The good news is that Google Test 1.4.0+ implements a
subset of TR1 tuple that's enough for Google Mock's need.  Google Mock
will automatically use that implementation when the compiler doesn't
provide TR1 tuple.

Usually you don't need to care about which tuple library Google Test
and Google Mock use.  However, if your project already uses TR1 tuple,
you need to tell Google Test and Google Mock to use the same TR1 tuple
194
library the rest of your project uses, or the two tuple
195
196
implementations will clash.  To do that, add

Billy Donahue's avatar
Billy Donahue committed
197
    -DGTEST_USE_OWN_TR1_TUPLE=0
198
199

to the compiler flags while compiling Google Test, Google Mock, and
200
201
202
your tests.  If you want to force Google Test and Google Mock to use
their own tuple library, just add

Billy Donahue's avatar
Billy Donahue committed
203
    -DGTEST_USE_OWN_TR1_TUPLE=1
204
205

to the compiler flags instead.
206
207
208
209
210

If you want to use Boost's TR1 tuple library with Google Mock, please
refer to the Boost website (http://www.boost.org/) for how to obtain
it and set it up.

211
212
213
214
### As a Shared Library (DLL) ###

Google Mock is compact, so most users can build and link it as a static
library for the simplicity.  Google Mock can be used as a DLL, but the
Billy Donahue's avatar
Billy Donahue committed
215
216
217
same DLL must contain Google Test as well.  See
[Google Test's README][gtest_readme]
for instructions on how to set up necessary compiler settings.
218
219

### Tweaking Google Mock ###
220

221
Most of Google Test's control macros apply to Google Mock as well.
Billy Donahue's avatar
Billy Donahue committed
222
Please see [Google Test's README][gtest_readme] for how to tweak them.
223

Billy Donahue's avatar
Billy Donahue committed
224
### Upgrading from an Earlier Version ###
225

226
227
228
229
We strive to keep Google Mock releases backward compatible.
Sometimes, though, we have to make some breaking changes for the
users' long-term benefits.  This section describes what you'll need to
do if you are upgrading from an earlier version of Google Mock.
230

Billy Donahue's avatar
Billy Donahue committed
231
#### Upgrading from 1.1.0 or Earlier ####
shiqian's avatar
shiqian committed
232

233
You may need to explicitly enable or disable Google Test's own TR1
Billy Donahue's avatar
Billy Donahue committed
234
235
tuple library.  See the instructions in section "[Choosing a TR1 Tuple
Library](../googletest/#choosing-a-tr1-tuple-library)".
236

Billy Donahue's avatar
Billy Donahue committed
237
#### Upgrading from 1.4.0 or Earlier ####
238

239
240
241
On platforms where the pthread library is available, Google Test and
Google Mock use it in order to be thread-safe.  For this to work, you
may need to tweak your compiler and/or linker flags.  Please see the
Billy Donahue's avatar
Billy Donahue committed
242
243
"[Multi-threaded Tests](../googletest#multi-threaded-tests
)" section in file Google Test's README for what you may need to do.
244

Billy Donahue's avatar
Billy Donahue committed
245
246
247
248
249
250
If you have custom matchers defined using `MatcherInterface` or
`MakePolymorphicMatcher()`, you'll need to update their definitions to
use the new matcher API (
[monomorphic](http://code.google.com/p/googlemock/wiki/CookBook#Writing_New_Monomorphic_Matchers),
[polymorphic](http://code.google.com/p/googlemock/wiki/CookBook#Writing_New_Polymorphic_Matchers)).
Matchers defined using `MATCHER()` or `MATCHER_P*()` aren't affected.
251

Billy Donahue's avatar
Billy Donahue committed
252
### Developing Google Mock ###
253

254
255
This section discusses how to make your own changes to Google Mock.

Billy Donahue's avatar
Billy Donahue committed
256
#### Testing Google Mock Itself ####
257
258
259
260

To make sure your changes work as intended and don't break existing
functionality, you'll want to compile and run Google Test's own tests.
For that you'll need Autotools.  First, make sure you have followed
Billy Donahue's avatar
Billy Donahue committed
261
the instructions above to configure Google Mock.
262
263
Then, create a build output directory and enter it.  Next,

Billy Donahue's avatar
Billy Donahue committed
264
    ${GMOCK_DIR}/configure  # try --help for more info
265
266
267
268

Once you have successfully configured Google Mock, the build steps are
standard for GNU-style OSS packages.

Billy Donahue's avatar
Billy Donahue committed
269
270
    make        # Standard makefile following GNU conventions
    make check  # Builds and runs all tests - all should pass.
271
272
273
274
275

Note that when building your project against Google Mock, you are building
against Google Test as well.  There is no need to configure Google Test
separately.

Billy Donahue's avatar
Billy Donahue committed
276
#### Contributing a Patch ####
277

Billy Donahue's avatar
Billy Donahue committed
278
279
280
We welcome patches.
Please read the [Developer's Guide](docs/DevGuide.md)
for how you can contribute. In particular, make sure you have signed
281
282
283
the Contributor License Agreement, or we won't be able to accept the
patch.

284
Happy testing!
Billy Donahue's avatar
Billy Donahue committed
285

Billy Donahue's avatar
Billy Donahue committed
286
[gtest_readme]: ../googletest/README.md "googletest"