googleMock/README

   1 Google C++ Mocking Framework
   2 ============================
   3
   4 http://code.google.com/p/googlemock/
   5
   6 Overview
   7 --------
   8
   9 Google's framework for writing and using C++ mock classes on a variety
  10 of platforms (Linux, Mac OS X, Windows, Windows CE, Symbian, etc).
  11 Inspired by jMock, EasyMock, and Hamcrest, and designed with C++'s
  12 specifics in mind, it can help you derive better designs of your
  13 system and write better tests.
  14
  15 Google Mock:
  16
  17 - provides a declarative syntax for defining mocks,
  18 - can easily define partial (hybrid) mocks, which are a cross of real
  19   and mock objects,
  20 - handles functions of arbitrary types and overloaded functions,
  21 - comes with a rich set of matchers for validating function arguments,
  22 - uses an intuitive syntax for controlling the behavior of a mock,
  23 - does automatic verification of expectations (no record-and-replay
  24   needed),
  25 - allows arbitrary (partial) ordering constraints on
  26   function calls to be expressed,
  27 - lets a user extend it by defining new matchers and actions.
  28 - does not use exceptions, and
  29 - is easy to learn and use.
  30
  31 Please see the project page above for more information as well as the
  32 mailing list for questions, discussions, and development.  There is
  33 also an IRC channel on OFTC (irc.oftc.net) #gtest available.  Please
  34 join us!
  35
  36 Please note that code under scripts/generator/ is from the cppclean
  37 project (http://code.google.com/p/cppclean/) and under the Apache
  38 License, which is different from Google Mock's license.
  39
  40 Requirements for End Users
  41 --------------------------
  42
  43 Google Mock is implemented on top of the Google Test C++ testing
  44 framework (http://code.google.com/p/googletest/), and includes the
  45 latter as part of the SVN repositary and distribution package.  You
  46 must use the bundled version of Google Test when using Google Mock, or
  47 you may get compiler/linker errors.
  48
  49 You can also easily configure Google Mock to work with another testing
  50 framework of your choice; although it will still need Google Test as
  51 an internal dependency.  Please read
  52 http://code.google.com/p/googlemock/wiki/ForDummies#Using_Google_Mock_with_Any_Testing_Framework
  53 for how to do it.
  54
  55 Google Mock depends on advanced C++ features and thus requires a more
  56 modern compiler.  The following are needed to use Google Mock:
  57
  58 ### Linux Requirements ###
  59
  60 These are the base requirements to build and use Google Mock from a source
  61 package (as described below):
  62
  63   * GNU-compatible Make or "gmake"
  64   * POSIX-standard shell
  65   * POSIX(-2) Regular Expressions (regex.h)
  66   * C++98-standard-compliant compiler (e.g. GCC 3.4 or newer)
  67
  68 ### Windows Requirements ###
  69
  70   * Microsoft Visual C++ 8.0 SP1 or newer
  71
  72 ### Mac OS X Requirements ###
  73
  74   * Mac OS X 10.4 Tiger or newer
  75   * Developer Tools Installed
  76
  77 Requirements for Contributors
  78 -----------------------------
  79
  80 We welcome patches.  If you plan to contribute a patch, you need to
  81 build Google Mock and its own tests from an SVN checkout (described
  82 below), which has further requirements:
  83
  84   * Automake version 1.9 or newer
  85   * Autoconf version 2.59 or newer
  86   * Libtool / Libtoolize
  87   * Python version 2.3 or newer (for running some of the tests and
  88     re-generating certain source files from templates)
  89
  90 Getting the Source
  91 ------------------
  92
  93 There are two primary ways of getting Google Mock's source code: you
  94 can download a stable source release in your preferred archive format,
  95 or directly check out the source from our Subversion (SVN) repositary.
  96 The SVN checkout requires a few extra steps and some extra software
  97 packages on your system, but lets you track development and make
  98 patches much more easily, so we highly encourage it.
  99
 100 ### Source Package ###
 101
 102 Google Mock is released in versioned source packages which can be
 103 downloaded from the download page [1].  Several different archive
 104 formats are provided, but the only difference is the tools needed to
 105 extract their contents, and the size of the resulting file.  Download
 106 whichever you are most comfortable with.
 107
 108   [1] http://code.google.com/p/googlemock/downloads/list
 109
 110 Once downloaded expand the archive using whichever tools you prefer
 111 for that type.  This will always result in a new directory with the
 112 name "gmock-X.Y.Z" which contains all of the source code.  Here are
 113 some examples on Linux:
 114
 115   tar -xvzf gmock-X.Y.Z.tar.gz
 116   tar -xvjf gmock-X.Y.Z.tar.bz2
 117   unzip gmock-X.Y.Z.zip
 118
 119 ### SVN Checkout ###
 120
 121 To check out the main branch (also known as the "trunk") of Google
 122 Mock, run the following Subversion command:
 123
 124   svn checkout http://googlemock.googlecode.com/svn/trunk/ gmock-svn
 125
 126 If you are using a *nix system and plan to use the GNU Autotools build
 127 system to build Google Mock (described below), you'll need to
 128 configure it now.  Otherwise you are done with getting the source
 129 files.
 130
 131 To prepare the Autotools build system, enter the target directory of
 132 the checkout command you used ('gmock-svn') and proceed with the
 133 following command:
 134
 135   autoreconf -fvi
 136
 137 Once you have completed this step, you are ready to build the library.
 138 Note that you should only need to complete this step once.  The
 139 subsequent 'make' invocations will automatically re-generate the bits
 140 of the build system that need to be changed.
 141
 142 If your system uses older versions of the autotools, the above command
 143 will fail.  You may need to explicitly specify a version to use.  For
 144 instance, if you have both GNU Automake 1.4 and 1.9 installed and
 145 'automake' would invoke the 1.4, use instead:
 146
 147   AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf -fvi
 148
 149 Make sure you're using the same version of automake and aclocal.
 150
 151 Setting up the Build
 152 --------------------
 153
 154 To build Google Mock and your tests that use it, you need to tell your
 155 build system where to find its headers and source files.  The exact
 156 way to do it depends on which build system you use, and is usually
 157 straightforward.
 158
 159 ### Generic Build Instructions ###
 160
 161 This section shows how you can integrate Google Mock into your
 162 existing build system.
 163
 164 Suppose you put Google Mock in directory ${GMOCK_DIR} and Google Test
 165 in ${GTEST_DIR} (the latter is ${GMOCK_DIR}/gtest by default).  To
 166 build Google Mock, create a library build target (or a project as
 167 called by Visual Studio and Xcode) to compile
 168
 169   ${GTEST_DIR}/src/gtest-all.cc and ${GMOCK_DIR}/src/gmock-all.cc
 170
 171 with
 172
 173   ${GTEST_DIR}/include, ${GTEST_DIR}, ${GMOCK_DIR}/include, and ${GMOCK_DIR}
 174
 175 in the header search path.  Assuming a Linux-like system and gcc,
 176 something like the following will do:
 177
 178   g++ -I${GTEST_DIR}/include -I${GTEST_DIR} -I${GMOCK_DIR}/include \
 179       -I${GMOCK_DIR} -c ${GTEST_DIR}/src/gtest-all.cc
 180   g++ -I${GTEST_DIR}/include -I${GTEST_DIR} -I${GMOCK_DIR}/include \
 181       -I${GMOCK_DIR} -c ${GMOCK_DIR}/src/gmock-all.cc
 182   ar -rv libgmock.a gtest-all.o gmock-all.o
 183
 184 Next, you should compile your test source file with
 185 ${GTEST_DIR}/include and ${GMOCK_DIR}/include in the header search
 186 path, and link it with gmock and any other necessary libraries:
 187
 188   g++ -I${GTEST_DIR}/include -I${GMOCK_DIR}/include \
 189       path/to/your_test.cc libgmock.a -o your_test
 190
 191 As an example, the make/ directory contains a Makefile that you can
 192 use to build Google Mock on systems where GNU make is available
 193 (e.g. Linux, Mac OS X, and Cygwin).  It doesn't try to build Google
 194 Mock's own tests.  Instead, it just builds the Google Mock library and
 195 a sample test.  You can use it as a starting point for your own build
 196 script.
 197
 198 If the default settings are correct for your environment, the
 199 following commands should succeed:
 200
 201   cd ${GMOCK_DIR}/make
 202   make
 203   ./gmock_test
 204
 205 If you see errors, try to tweak the contents of make/Makefile to make
 206 them go away.  There are instructions in make/Makefile on how to do
 207 it.
 208
 209 ### Windows ###
 210
 211 The msvc/2005 directory contains VC++ 2005 projects and the msvc/2010
 212 directory contains VC++ 2010 projects for building Google Mock and
 213 selected tests.
 214
 215 Change to the appropriate directory and run "msbuild gmock.sln" to
 216 build the library and tests (or open the gmock.sln in the MSVC IDE).
 217 If you want to create your own project to use with Google Mock, you'll
 218 have to configure it to use the gmock_config propety sheet.  For that:
 219
 220  * Open the Property Manager window (View | Other Windows | Property Manager)
 221  * Right-click on your project and select "Add Existing Property Sheet..."
 222  * Navigate to gmock_config.vsprops or gmock_config.props and select it.
 223  * In Project Properties | Configuration Properties | General | Additional
 224    Include Directories, type <path to Google Mock>/include.
 225
 226 Tweaking Google Mock
 227 --------------------
 228
 229 Google Mock can be used in diverse environments.  The default
 230 configuration may not work (or may not work well) out of the box in
 231 some environments.  However, you can easily tweak Google Mock by
 232 defining control macros on the compiler command line.  Generally,
 233 these macros are named like GTEST_XYZ and you define them to either 1
 234 or 0 to enable or disable a certain feature.
 235
 236 We list the most frequently used macros below.  For a complete list,
 237 see file ${GTEST_DIR}/include/gtest/internal/gtest-port.h.
 238
 239 ### Choosing a TR1 Tuple Library ###
 240
 241 Google Mock uses the C++ Technical Report 1 (TR1) tuple library
 242 heavily.  Unfortunately TR1 tuple is not yet widely available with all
 243 compilers.  The good news is that Google Test 1.4.0+ implements a
 244 subset of TR1 tuple that's enough for Google Mock's need.  Google Mock
 245 will automatically use that implementation when the compiler doesn't
 246 provide TR1 tuple.
 247
 248 Usually you don't need to care about which tuple library Google Test
 249 and Google Mock use.  However, if your project already uses TR1 tuple,
 250 you need to tell Google Test and Google Mock to use the same TR1 tuple
 251 library the rest of your project uses, or the two tuple
 252 implementations will clash.  To do that, add
 253
 254   -DGTEST_USE_OWN_TR1_TUPLE=0
 255
 256 to the compiler flags while compiling Google Test, Google Mock, and
 257 your tests.  If you want to force Google Test and Google Mock to use
 258 their own tuple library, just add
 259
 260   -DGTEST_USE_OWN_TR1_TUPLE=1
 261
 262 to the compiler flags instead.
 263
 264 If you want to use Boost's TR1 tuple library with Google Mock, please
 265 refer to the Boost website (http://www.boost.org/) for how to obtain
 266 it and set it up.
 267
 268 ### Tweaking Google Test ###
 269
 270 Most of Google Test's control macros apply to Google Mock as well.
 271 Please see file ${GTEST_DIR}/README for how to tweak them.
 272
 273 Upgrading from an Earlier Version
 274 ---------------------------------
 275
 276 We strive to keep Google Mock releases backward compatible.
 277 Sometimes, though, we have to make some breaking changes for the
 278 users' long-term benefits.  This section describes what you'll need to
 279 do if you are upgrading from an earlier version of Google Mock.
 280
 281 ### Upgrading from 1.1.0 or Earlier ###
 282
 283 You may need to explicitly enable or disable Google Test's own TR1
 284 tuple library.  See the instructions in section "Choosing a TR1 Tuple
 285 Library".
 286
 287 ### Upgrading from 1.4.0 or Earlier ###
 288
 289 On platforms where the pthread library is available, Google Test and
 290 Google Mock use it in order to be thread-safe.  For this to work, you
 291 may need to tweak your compiler and/or linker flags.  Please see the
 292 "Multi-threaded Tests" section in file ${GTEST_DIR}/README for what
 293 you may need to do.
 294
 295 If you have custom matchers defined using MatcherInterface or
 296 MakePolymorphicMatcher(), you'll need to update their definitions to
 297 use the new matcher API [2].  Matchers defined using MATCHER() or
 298 MATCHER_P*() aren't affected.
 299
 300   [2] http://code.google.com/p/googlemock/wiki/CookBook#Writing_New_Monomorphic_Matchers,
 301       http://code.google.com/p/googlemock/wiki/CookBook#Writing_New_Polymorphic_Matchers
 302
 303 Developing Google Mock
 304 ----------------------
 305
 306 This section discusses how to make your own changes to Google Mock.
 307
 308 ### Testing Google Mock Itself ###
 309
 310 To make sure your changes work as intended and don't break existing
 311 functionality, you'll want to compile and run Google Test's own tests.
 312 For that you'll need Autotools.  First, make sure you have followed
 313 the instructions in section "SVN Checkout" to configure Google Mock.
 314 Then, create a build output directory and enter it.  Next,
 315
 316   ${GMOCK_DIR}/configure  # Standard GNU configure script, --help for more info
 317
 318 Once you have successfully configured Google Mock, the build steps are
 319 standard for GNU-style OSS packages.
 320
 321   make        # Standard makefile following GNU conventions
 322   make check  # Builds and runs all tests - all should pass.
 323
 324 Note that when building your project against Google Mock, you are building
 325 against Google Test as well.  There is no need to configure Google Test
 326 separately.
 327
 328 ### Regenerating Source Files ###
 329
 330 Some of Google Mock's source files are generated from templates (not
 331 in the C++ sense) using a script.  A template file is named FOO.pump,
 332 where FOO is the name of the file it will generate.  For example, the
 333 file include/gmock/gmock-generated-actions.h.pump is used to generate
 334 gmock-generated-actions.h in the same directory.
 335
 336 Normally you don't need to worry about regenerating the source files,
 337 unless you need to modify them.  In that case, you should modify the
 338 corresponding .pump files instead and run the 'pump' script (for Pump
 339 is Useful for Meta Programming) to regenerate them.  You can find
 340 pump.py in the ${GTEST_DIR}/scripts/ directory.  Read the Pump manual
 341 [3] for how to use it.
 342
 343   [3] http://code.google.com/p/googletest/wiki/PumpManual.
 344
 345 ### Contributing a Patch ###
 346
 347 We welcome patches.  Please read the Google Mock developer's guide [4]
 348 for how you can contribute.  In particular, make sure you have signed
 349 the Contributor License Agreement, or we won't be able to accept the
 350 patch.
 351
 352   [4] http://code.google.com/p/googlemock/wiki/DevGuide
 353
 354 Happy testing!