diff options
Diffstat (limited to 'testing/gmock/README')
| -rw-r--r-- | testing/gmock/README | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/testing/gmock/README b/testing/gmock/README new file mode 100644 index 0000000..f14279c --- /dev/null +++ b/testing/gmock/README @@ -0,0 +1,345 @@ +Google C++ Mocking Framework +============================ +http://code.google.com/p/googlemock/ + +Overview +-------- +Google's framework for writing and using C++ mock classes on Linux, +Mac OS X, and Windows. 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. + +Google Mock: + +- 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, and +- is easy to learn and use. + +Please see the project page above for more information as well as mailing lists +for questions, discussions, and development. There is also an IRC channel on +OFTC (irc.oftc.net) #gtest available. Please join us! + +Please note that code under scripts/generator/ is from the cppclean +project (http://code.google.com/p/cppclean/) and under the Apache +License, which is different from Google Mock's license. + +Requirements +------------ +Google Mock is not a testing framework itself. Instead, it needs a +testing framework for writing tests. It works with Google Test +(http://code.google.com/p/googletest/) out of the box. You can use +either the copy of Google Test that comes with Google Mock, or a +compatible version you already have. This version of Google Mock +requires Google Test 1.3.0. + +You can also easily configure Google Mock to work with another testing +framework of your choice; although it will still need Google Test as +an internal dependency. Please read +http://code.google.com/p/googlemock/wiki/ForDummies#Using_Google_Mock_with_Any_Testing_Framework +for how to do it. + +Google Mock depends on advanced C++ features and thus requires a more +modern compiler. The following are needed to use Google Mock: + +### Linux Requirements ### +These are the base requirements to build and use Google Mock from a source +package (as described below): + * GNU-compatible Make or "gmake" + * POSIX-standard shell + * POSIX(-2) Regular Expressions (regex.h) + * gcc 4.0 or newer, or gcc 3.4 or newer with the tr1 tuple library + (from Boost or other vendors). + +Furthermore, if you are building Google Mock from a VCS Checkout (also +described below), there are further requirements: + * Automake version 1.9 or newer + * Autoconf version 2.59 or newer + * Libtool / Libtoolize + * Python version 2.3 or newer + +### Windows Requirements ### + * Microsoft Visual C++ 8.0 SP1 or newer + * An implementation of the tr1 tuple C++ library (You can get it for + free from http://www.boost.org/. We have verified that version + 1.36.0 works. One caveat is this implementation exposes a bug in + Visual C++'s <type_info> header when exceptions are disabled. + Therefore your project must enable exceptions for this + configuration to work.) + +### Mac OS X Requirements ### + * Mac OS X 10.4 Tiger or newer + * Developer Tools Installed + +Getting the Source +------------------ +There are two primary ways of getting Google Mock's source code: you can +download a source release in your preferred archive format, or directly check +out the source from a Version Control System (VCS, we use Google Code's +Subversion hosting). The VCS checkout requires a few extra steps and some extra +software packages on your system, but lets you track development, and make +patches to contribute much more easily, so we highly encourage it. + +### VCS Checkout: ### +The first step is to select whether you want to check out the main line of +development on Google Mock, or one of the released branches. The former will be +much more active and have the latest features, but the latter provides much +more stability and predictability. Choose whichever fits your needs best, and +proceed with the following Subversion commands: + + svn checkout http://googlemock.googlecode.com/svn/trunk/ gmock-svn + +or for a release version X.Y.*'s branch: + + svn checkout http://googlemock.googlecode.com/svn/branches/release-X.Y/ \ + gmock-X.Y-svn + +Next you will need to prepare the GNU Autotools build system, if you +are using Linux or Mac OS X. Enter the target directory of the +checkout command you used ('gmock-svn' or 'gmock-X.Y-svn' above) and +proceed with the following command: + + autoreconf -fvi + +Once you have completed this step, you are ready to build the library. Note +that you should only need to complete this step once. The subsequent `make' +invocations will automatically re-generate the bits of the build system that +need to be changed. + +If your system uses older versions of the autotools, the above command will +fail. You may need to explicitly specify a version to use. For instance, if you +have both GNU Automake 1.4 and 1.9 installed and `automake' would invoke the +1.4, use instead: + + AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf -fvi + +Make sure you're using the same version of automake and aclocal. + +### Source Package: ### +Google Mock is also released in source packages which can be downloaded from +its Google Code download page[1]. Several different archive formats are +provided, but the only difference is the tools needed to extract their +contents, and the size of the resulting file. Download whichever you are most +comfortable with. + + [1] Google Mock Downloads: http://code.google.com/p/googlemock/downloads/list + +Once downloaded expand the archive using whichever tools you prefer for that +type. This will always result in a new directory with the name "gmock-X.Y.Z" +which contains all of the source code. Here are some examples in Linux: + + tar -xvzf gmock-X.Y.Z.tar.gz + tar -xvjf gmock-X.Y.Z.tar.bz2 + unzip gmock-X.Y.Z.zip + +Building the Source +------------------- +### Linux and Mac OS X (without Xcode) ### +There are two primary options for building the source at this point: build it +inside the source code tree, or in a separate directory. We recommend building +in a separate directory as that tends to produce both more consistent results +and be easier to clean up should anything go wrong, but both patterns are +supported. The only hard restriction is that while the build directory can be +a subdirectory of the source directory, the opposite is not possible and will +result in errors. Once you have selected where you wish to build Google Mock, +create the directory if necessary, and enter it. The following steps apply for +either approach by simply substituting the shell variable SRCDIR with "." for +building inside the source directory, and the relative path to the source +directory otherwise. + + ${SRCDIR}/configure # Standard GNU configure script, --help for more info + +The default behavior of the configure script with respect to locating and using +Google Test is to first search for a 'gtest-config' in the system path, and +lacking this, build an internal copy of Google Test. You may optionally specify +a custom Google Test you wish to build Google Mock against, provided it is +a new enough version. + + # Configure against an installation in '/opt' with '/opt/bin/gtest-config'. + ${SRCDIR}/configure --with-gtest=/opt + +This can also be used to specify a Google Test which hasn't yet been installed. +However, it must have been configured and built as described in the Google Test +README before you configure Google Mock. To enable this feature, simply pass +the directory where you configured and built Google Test (which is not +necessarily its source directory) to Google Mock's configure script. + + # Configure against a build of Google Test in an arbitrary directory. + ${SRCDIR}/configure --with-gtest=../../my_gtest_build + +Finally, if you have a version of Google Test installed but for some reason +wish to forcibly prevent it from being used, we provide a special option. +Typically this is not needed as we fall back to the internal Google Test +packaged with Google Mock if an installed version is either unavailable or too +old to build Google Mock. When using the internally packaged Google Test, the +user does *not* need to configure or build it, that is automatically handled by +Google Mock's build system. + + # Force the use of the internally packaged Google Test, despite + # 'gtest-config' being in your PATH. + ${SRCDIR}/configure --disable-external-gtest + +Once you have successfully configured Google Mock, the build steps are standard +for GNU-style OSS packages. + + make # Standard makefile following GNU conventions + make check # Builds and runs all tests - all should pass + +Other programs will only be able to use Google Mock's functionality if you +install it in a location which they can access, in Linux this is typically +under '/usr/local'. The following command will install all of the Google Mock +libraries, public headers, and utilities necessary for other programs and +libraries to leverage it. Note that if Google Mock was unable to find an +external Google Test to build against, it will also install the internally +packaged Google Test in order to allow the installed Google Mock to function +properly. This Google Test install will be fully functional, and if installed +will also be uninstalled by uninstalling Google Mock. + + sudo make install # Not necessary, but allows use by other programs + +Should you need to remove Google Mock from your system after having installed +it, run the following command, and it will back out its changes. However, note +carefully that you must run this command on the *same* Google Mock build that +you ran the install from, or the results are not predictable. If you install +Google Mock on your system, and are working from a VCS checkout, make sure you +run this *before* updating your checkout of the source in order to uninstall +the same version which you installed. + + sudo make uninstall # Must be run against the exact same build as "install" + +Your project can build against Google Mock and Google Test simply by leveraging +the 'gmock-config' script. This script can be invoked directly out of the +'scripts' subdirectory of the build tree, and it will be installed in the +binary directory specified during the 'configure'. Here are some examples of +its use, see 'gmock-config --help' for more detailed information. + + gmock-config --min-version=1.0 || echo "Insufficient Google Mock version." + + g++ $(gmock-config --cppflags --cxxflags) -o foo.o -c foo.cpp + g++ $(gmock-config --ldflags --libs) -o foo foo.o + + # When using a built but not installed Google Mock: + g++ $(../../my_gmock_build/scripts/gmock-config ...) ... + +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. + +### Windows ### +The msvc/ directory contains VC++ 2005 projects for building Google +Mock and selected tests. In order to build Google Mock you must have +an implementation of TR1 tuple. One library that provides such +implementation is Boost. If you choose to use Boost, download it from +www.boost.org and install it on your system. Note that Boost TR1 tuple +is a header-only library, so the installation only involves unpacking +it to a suitable location - you don't need to compile it or download a +pre-compiled Boost binary. + +Since Boost is quite large, you may prefer to only install the files +actually needed by Google Mock. If so, you can download TR1 tuple +without other parts of Boost from +http://code.google.com/p/googlemock/downloads/list. + +After that you have two options: either set up Boost globally or +modify the Google Mock project to point to your copy of Boost. The +former will let all your tests use the same Boost library while the +latter will allow each of your projects use its own copy. You can also +use a hybrid solution: your project settings will override the +system-wide one. + +For example, if you unpacked boost v1.36.0 into C:\boost: +To set up Boost such that all projects can use it: + * Assuming you are using the Visual Studio 2005 IDE, select Tools | + Options | Projects And Solutions | VC++ Directories. + * In the "Show directories for" drop-down select Include Files. Add + C:\boost\boost_1_36_0\boost\tr1\tr1 and C:\boost\boost_1_36_0 to the + list of directories. + +To configure your project to point to that version of Boost, replace +the value of the BoostDir user macro with C:\boost\boost_1_36_0 in the +msvc/gmock_config.vsprops file. You can use any text editor to edit +that file. + +If you want to use a version of Google Test other then the one bundled with +Google Mock, change the value of the GTestDir macro in gmock_config.vsprop +to point to the new location. + +After configuring Boost, just open msvc/gmock.sln and build the library and +tests. If you want to create your own project to use with Google Mock, you'll +have to configure it to use the gmock_config propety sheet. For that: + * Open the Property Manager window (View | Other Windows | Property Manager) + * Right-click on your project and select "Add Existing Property Sheet..." + * Navigate to gmock_config.vsprops and select it. + * In Project Properties | Configuration Properties | General | Additional + Include Directories, type <path to Google Mock>/include. + +TODO(wan@google.com): update the .vsprops and .vcproj files such that the +last step is unnecessary. + +### Using GNU Make ### +The make/ directory contains a Makefile that you can use to build +Google Mock on systems where GNU make is available (e.g. Linux and Mac +OS X). It doesn't try to build Google Mock's own tests. Instead, it +just builds the Google Mock libraries and some sample tests. You can +use it as a starting point for your own Makefile. + +If the default settings are correct for your environment, the +following commands should succeed: + + cd ${SRCDIR}/make + make + ./gmock_test + +If you see errors, try to tweak the contents of make/Makefile to make +them go away. There are instructions in make/Makefile on how to do +it. + +### Using Your Own Build System ### +If none of the build solutions we provide works for you, or if you +prefer your own build system, you just need to compile +${GTEST_SRCDIR}/src/gtest-all.cc (where GTEST_SRCDIR is the root of +the Google Test source tree) and src/gmock-all.cc into a library and +link your tests with it. Assuming a Linux-like system and gcc, +something like the following will do: + + cd ${SRCDIR} + g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \ + -c {GTEST_SRCDIR}/src/gtest-all.cc + g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \ + -c src/gmock-all.cc + ar -rv libgmock.a gtest-all.o gmock-all.o + g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \ + path/to/your_test.cc libgmock.a -o your_test + +On Windows, you'll also need to add the include path for the boost +headers to the compiler command line. See +http://www.boost.org/doc/libs/1_36_0/doc/html/boost_tr1/usage.html for +how to do it. + +Regenerating Source Files +------------------------- +Some of Google Mock's source files are generated from templates (not +in the C++ sense) using a script. A template file is named FOO.pump, +where FOO is the name of the file it will generate. For example, the +file include/gmock/gmock-generated-actions.h.pump is used to generate +gmock-generated-actions.h in the same directory. + +Normally you don't need to worry about regenerating the source files, +unless you need to modify them (e.g. if you are working on a patch for +Google Mock). In that case, you should modify the corresponding .pump +files instead and run the 'pump' script (for Pump is Useful for Meta +Programming) to regenerate them. We are still working on releasing +the script and its documentation. If you need it now, please email +googlemock@googlegroups.com such that we know to make it happen +sooner. + +Happy testing! |