]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ## 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 <path to Google Mock>/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" |