Merge pull request #3189 from ellert:gtest-help-test-GNU/kFreeBSD

PiperOrigin-RevId: 349349288

googlemock/docs/contribute.md

@@ -0,0 +1,5 @@
+# How to Contribute
+
+googletest development is Piper-First. Just create a regular Piper CL. When the
+CL is accepted and submitted, it will make its way to OSS via regular releasing
+process.

googlemock/docs/guide.md

@@ -0,0 +1,49 @@
+# googletest gMock Users Guide
+
+go/gmockguide
+
+Welcome to googletest: Google's C++ testing and mocking framework. gMock is a
+mocking part of googletest.
+
+*   [OSS Version](https://github.com/google/googletest)
+*   [Google3](http://google3/third_party/googletest/)
+
+*   If you are new to gMock, start with [*gMock for Dummies*](for_dummies.md) to
+    learn the basic usage.
+
+*   Read [gMock Cookbook](cook_book.md) to learn more advanced usage and useful
+    tips.
+
+*   For a quick reference, check out [gMock Cheat Sheet](cheat_sheet.md).
+
+*   If you have questions, search [gMock FAQ](#GMockFaq) and the gmock-users@
+    archive before sending them to gmock-users@.
+
+<!-- GOOGLETEST_CM0035 DO NOT DELETE -->
+
+<!--#include file="for_dummies.md"-->
+
+#### Side Effects
+
+<!-- mdformat off(github rendering does not support multiline tables) -->
+| Matcher                            | Description                             |
+| :--------------------------------- | :-------------------------------------- |
+| `Assign(&variable, value)` | Assign `value` to variable. |
+| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. |
+| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. |
+| `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. |
+| `SetArgReferee<N>(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. |
+| `SetArgPointee<N>(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. |
+| `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0. |
+| `SetArrayArgument<N>(first, last)` | Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range. |
+| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. |
+| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. |
+<!-- mdformat on -->
+
+*   When compiling with exceptions in google3, it's not enough to specify
+    `-fexceptions` to copts in your cc_test target. That flag will not be
+    inherited by gmock, and various headers will be compiled both with and
+    without `-fexceptions` causing subtle bugs. Instead you must pass
+    `--copt=-fexceptions` to the blaze command so the flag gets passed to all
+    targets... but this is Google and we don't use exceptions so it shouldn't
+    really be an issue.

googlemock/docs/index.md

@@ -0,0 +1,127 @@
+# googletest Home
+
+go/gmock
+
+Googletest is Google's C++ testing and mocking framework. Please note that there
+are legacy names you may encounter "gUnit" and "gMock" - these names are now
+merged into "googletest"
+
+<!-- GOOGLETEST_CM0035 DO NOT DELETE -->
+
+## Testimonials
+
+> "I'm really enjoying trying it, and it's amazing to me how far you've taken
+> this in C++. It's changed the way I program (and therefore changed my life ;),
+> and one of my teams has adopted it for all/most tests (and I'm working on the
+> other)." \
+> -- *Derek Thomson*, Google Mountain View
+
+<section></section>
+
+> "I started using mocks with EasyMock in Java a few years ago and found them
+> **invaluable** for making unit testing as painless and effective as possible.
+> I'm very glad (and amazed) to see you've managed to create something similar
+> for C++. It's making the transition much more pleasant." \
+> -- *David Harkness*, Google Mountain View
+
+<section></section>
+
+> "I #included `gmock.h` and lived to tell the tale... Kept me from having to
+> depend on `MockBigtable` thus far, which is **huge**." \
+> -- *Matthew Simmons*, Google NYC
+
+<section></section>
+
+> "I like the approach of `EXPECT_CALL` much more than EasyMock's mock modes
+> (record, replay). It's the best way to ensure the user will never forget to
+> verify the expectations: do it automatically!" \
+> -- *Tiago Silverira*, Google Brazil
+
+<section></section>
+
+> "It's by far the best mocking library for C++, by a long-shot." \
+> -- *Joe Walnes*, co-creator of jMock, Google London
+
+## Learning googletest mocking
+
+Please see the [*googletest Users Guide*](guide.md) for the combined gMock
+mocking documentation.
+
+## Resources for Users
+
+*   More docs:
+    *   [Interview with gMock's Creator](http://www.corp.google.com/eng/testing/codegreen/v10/gMock.htm)
+        on the
+        [Feb 2008](http://www.corp.google.com/eng/testing/codegreen/v10/index.htm)
+        issue of [Code Green](http://go/codegreen) - discusses gMock's history
+        and philosophy.
+    *   "Mockers of the (C++) world, delight!": TotT
+        [episode 66](http://big.corp.google.com/~jmcmaster/testing/2007/12/episode-68-mockers-of-c-world-delight.html) -
+        quick intro on gMock's benefits and usage
+    *   "Mock logs better than gold": TotT
+        [episode 76](http://big.corp.google.com/~jmcmaster/testing/2008/02/episode-76-mock-logs-better-than-gold_21.html) -
+        how to test LOGs using gMock
+    *   "Testing legacy code gently": TotT
+        [episode 84](http://big.corp.google.com/~jmcmaster/testing/2008/04/episode-84-testing-legacy-code-gently.html) -
+        using mock callbacks to test legacy code without a big refactoring
+    *   "Literate testing with matchers": TotT
+        [episode 135](http://big.corp.google.com/~jmcmaster/testing/2009/06/episode-135-literate-testing-with_08.html) -
+        using matchers to get readable test code and readable test messages
+    *   "Making a perfect matcher": TotT
+        [episode 139](http://big.corp.google.com/~jmcmaster/testing/2009/07/episode-139-making-perfect-matcher.html) -
+        defining custom matchers easily
+*   Talks
+    *   "Declarative C++ Testing Using DSLs" talk (6/4/2008):
+        [abstract](https://wiki.corp.google.com/twiki/bin/view/Main/WanTalks#Declarative_C_Testing_Using_DSLs),
+        [slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0806-declarative-cpp-testing.xul#Eva)
+        (requires Firefox) - gMock's design and implementation tricks
+    *   "Mocks made easy in C++ and Java" talk (4/23/2008):
+        [slides](http://go/MockTalk),
+        [fish](http://fish.corp.google.com/talks/8729/)
+    *   "C++ mocks made easy - an introduction to gMock" talk (1/22/2008)):
+        [slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0801-mv-gmock.xul#eva)
+        (requires Firefox),
+        [video](https://video.google.com/a/google.com/?AuthEventSource=SSO#/Play/contentId=bd07003d4193a646)
+    *   "A preview to gMock" talk (6/28/2007):
+        [PowerPoint slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0706-beijing-gmock-preview.ppt)
+*   Tools
+    *   `/google/src/head/depot/google3/third_party/googletest/googlemock/scripts/generator/gmock_gen.py
+        *your.h ClassNames*` generates mocks for the given base classes (if no
+        class name is given, all classes in the file are emitted).
+*   Mocks
+    *   [mock-log.h](http://s/?fileprint=//depot/google3/testing/base/public/mock-log.h) -
+        a sample on using gMock to create a mock class
+    *   [gmock-sample-mock-log.cc](http://s/?fileprint=//depot/google3/testing/base/internal/gmock-sample-mock-log.cc) -
+        a sample on using gMock to test LOG()s
+*   Folks
+    *   Meet the
+        [users](http://piano.kir.corp.google.com:8080/lica/?e=use%3Agmock).
+    *   `gmock-users` list:
+        [subscribe](https://groups.google.com/a/google.com/group/gmock-users/topics),
+        [archive](https://groups.google.com/a/google.com/group/gmock-users/topics),
+        [smile!](http://piano.kir.corp.google.com:8080/lica/?e=gmock-users) Send
+        questions here if you still need help after consulting the on-line docs.
+    *   `gmock-announce` list:
+        [subscribe](https://groups.google.com/a/google.com/group/gmock-announce/topics)
+        to this instead of `gmock-users` if you are interested in announcements
+        only.
+
+## Resources for Contributors
+
+*   [Dashboard](http://unittest.corp.google.com/project/gunit-gmock/)
+*   [*gMock Design*](design.md) (go/gmockdesign) - the design doc
+*   `c-mock-dev` list (deprecated) -
+    [old archive](https://mailman.corp.google.com/pipermail/c/c-mock-dev/),
+    [new archive](https://g.corp.google.com/group/c-mock-dev-archive)
+*   `opensource-gmock` list - discussions on the development of gMock:
+    [subscribe](https://groups.google.com/a/google.com/group/opensource-gmock/subscribe),
+    [archive](https://g.corp.google.com/group/opensource-gmock-archive),
+    [smile!](http://piano.kir.corp.google.com:8080/lica/?e=opensource-gmock)
+
+## Acknowledgments
+
+We'd like to thank the following people for their contribution to gMock: Piotr
+Kaminski, Jeffrey Yasskin (who/jyasskin), Joe Walnes, Bradford Cross, Keith Ray,
+Craig Silverstein, Matthew Simmons (who/simmonmt), Hal Burch (who/hburch), Russ
+Rufer, Rushabh Doshi (who/rdoshi), Gene Volovich (who/genev), Mike Bland, Neal
+Norwitz (who/nnorwitz), Mark Zuber, Vadim Berman (who/vadimb).

googlemock/docs/overview.md

@@ -0,0 +1,111 @@
+# GMock
+
+<!-- GOOGLETEST_CM0035 DO NOT DELETE -->
+
+## What is gMock?
+
+gMock is Google's framework for creating and using C++ mock classes. It helps
+you design better systems and write better tests. A mock object is an object
+that you use in a test instead of a real object. A mock object implements the
+same interface as a real object but lets you specify at run time how the object
+will be used. When you write tests that use a mock, you define expectations
+about how the mock's methods will be called. Your test then verifies how your
+real code behaves when interacting with the mock. See the
+[Mock Objects Best Practices Guide](http://go/mock-objects#mocks-stubs-fakes)
+for a comparison of mocks with stubs, fakes, and other kinds of test doubles.
+
+For example, gMock provides a simple syntax for declaring "I expect the
+RetryQuery method on this mock object to be called three times in the course of
+this test". Your test will fail if the expectation isn't met.
+
+The gMock library provides a mock framework for C++ similar to jMock or
+EasyMock[?](http://go/easymock-codelab) for Java. In gMock you use macros to
+define methods for your mock objects and set expectations for those methods.
+gMock runs on Linux, Windows, and Mac OS X.
+
+## What is gMock good for?
+
+Mocks in general are good for:
+
+-   prototyping and designing new code and APIs.
+-   removing unnecessary, expensive, or unreliable dependencies from your tests.
+
+gMock in particular is good for writing quality C++ mocks. Without the help of a
+mocking framework like gMock, good C++ mocks are hard to create.
+
+## What is gMock NOT good for?
+
+gMock is not good for testing the behavior of dependencies. The point of testing
+with mocks is to test the classes that use the mocks, not the mocks themselves.
+Objects that have working toy implementations are called fakes instead of mocks.
+For example, you could use an in-memory file system to fake disk operations.
+
+Mocks aren't useful for very simple classes like
+[Dumb Data Objects](http://big.corp.google.com/~jmcmaster/testing/2011/04/episode-220-blast-from-tott-past-dont.html).
+If it's more trouble to use a mock than the real class, just use the real class.
+
+## Who uses gMock?
+
+There are over 30K tests using gmock. Virtually every C++ test at Google that
+needs a mock object uses gMock.
+
+## Practical matters
+
+gMock is bundled with [gUnit](/third_party/googletest/googletest/docs/). To use
+gMock,
+[include a dependency](/third_party/googletest/googletest/docs/howto_cpp#LinuxTarget)
+on `//testing/base/public:gunit` in the BUILD rule for your mocks, and use the
+following include statement in the file that defines your mock class:
+
+```
+#include "gmock/gmock.h"
+```
+
+&nbsp;                      | &nbsp;
+--------------------------- | ------------------------------------------
+**Implementation language** | C++
+**Code location**           | google3/third_party/googletest/googlemock/
+**Build target**            | //testing/base/public:gunit
+
+## Best practices
+
+Use [dependency injection](http://en.wikipedia.org/wiki/Dependency_injection) to
+enable easy mocking. If you define dependencies as interfaces rather than
+concrete classes, you can swap out the production version of a class for a mock
+during testing.
+
+You can also use gMock during the design phase for your system. By sketching
+your architecture using mocks rather than full implementations, you can evolve
+your design more quickly.
+
+## History and evolution
+
+In January 2007 Zhanyong Wan and the Testing Technology team met with
+experienced C++ engineers to find out about C++ testing needs. The team learned
+that creating mocks in C++ was a major pain point. They looked around for
+existing frameworks but didn't find anything satisfactory. So Zhanyong Wan
+tackled the problem of creating a usable C++ mocking framework.
+
+C++ posed a unique problem for mocking: while
+[reflection](http://en.wikipedia.org/wiki/Reflection_\(computer_programming\))
+in Java and Python make it easy to generate a mock implementation of any
+interface, C++ does not have reflection. Wan hit on macros as a way to simplify
+mock writing in C++, and gMock was born.
+
+## Who to contact
+
+-   g/gmock-users
+-   g/gmock-announce
+
+## Additional resources
+
+-   [gMock](http://go/gmock) - homepage
+-   [GMock for Dummies](http://<!-- GOOGLETEST_CM0013 DO NOT DELETE -->) - gets you started with gMock
+    quickly
+-   [GMock Cookbook](http://<!-- GOOGLETEST_CM0012 DO NOT DELETE -->) - recipes for common scenarios; covers
+    advanced usage.
+-   [GMock Cheat Sheet](http://<!-- GOOGLETEST_CM0020 DO NOT DELETE -->) - a quick reference
+-   [GMock FAQ](http://<!-- GOOGLETEST_CM0021 DO NOT DELETE -->) - frequently asked questions
+-   [gUnit GDH page](http://go/gunit-overview)
+-   [gUnit User's Guide](http://goto.corp.google.com/gunit) - gets you started
+    with gUnit, which is closely related to gMock

googlemock/docs/sitemap.md

@@ -0,0 +1,11 @@
+Googletest Mocking (gMock)
+
+*   [Home](index.md)
+*   [Overview](overview.md)
+*   [User's Guide](guide.md)
+*   [gMock For Dummies](for_dummies.md)
+*   [gMock Cookbook](cook_book.md)
+*   [gMock Cheat Sheet](cheat_sheet.md)
+*   [Design](design.md)
+*   [How To Contribute](contribute.md)
+*   [gMock FAQ](gmock_faq.md)

googlemock/docs/under-construction-banner.md

@@ -0,0 +1,4 @@
+**WARNING:** This document was recently migrated from
+[Goowiki](http://wtf/goowiki) (b/35424903) and may still require additional
+updates or formatting. You can still access the original document on Goowiki
+until the cleanup is complete:

googlemock/g3doc/includes/g3_BUILD_rule.md

@@ -0,0 +1,17 @@
+## BUILD Rule
+
+Add *one* of the following to your `deps`:
+
+```build
+"//testing/base/public:gunit",
+"//testing/base/public:gtest_main",
+```
+
+Add this to your `.cc` file:
+
+```cpp
+#include "gmock/gmock.h"
+```
+
+Unless noted, *all functions and classes* are defined in the `::testing`
+namespace.

googlemock/g3doc/includes/g3_absl_status_matcher.md

@@ -0,0 +1,54 @@
+### absl::Status
+
+In namespace `testing::status`:
+
+<a name="table22"></a>
+<table border="1" cellspacing="0" cellpadding="1">
+  <tr>
+    <td> `IsOk()` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` whose status is OK. </td>
+  </tr>
+  <tr>
+    <td> `IsOkAndHolds(m)` </td>
+    <td>
+      `argument` is an `absl::StatusOr<T>` whose status is OK and whose inner value matches matcher `m`.
+      See also [`ASSERT_OK_AND_ASSIGN`](http://google3/testing/base/public/gmock_utils/status-matchers.h?q=symbol:ASSERT_OK_AND_ASSIGN).
+    </td>
+  </tr>
+  <tr>
+    <td> `StatusHasPayload()` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` whose status is not OK and which has any payload. </td>
+  </tr>
+  <tr>
+    <td> `StatusHasPayload<ProtoType>()` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` whose status is not OK and which has a payload of type `ProtoType`. </td>
+  </tr>
+  <tr>
+    <td> `StatusHasPayload<ProtoType>(m)` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` whose status is not OK and which has a payload of type `ProtoType` that matches `m`. </td>
+  </tr>
+  <tr>
+    <td> `StatusIs(s, c, m)` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` where: the error space matches `s`, the status code matches `c`, and the error message matches `m`. </td>
+  </tr>
+  <tr>
+    <td> `StatusIs(c, m)` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` where: the error space is canonical, the status code matches `c`, and the error message matches `m`. </td>
+  </tr>
+  <tr>
+    <td> `StatusIs(c)` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` where: the error space is canonical, and the status code matches `c`. </td>
+  </tr>
+  <tr>
+    <td> `CanonicalStatusIs(c, m)` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` where: the canonical status code matches `c`, and the error message matches `m`. </td>
+  </tr>
+  <tr>
+    <td> `CanonicalStatusIs(c)` </td>
+    <td> `argument` is a `absl::Status` or `absl::StatusOr<T>` where: the canonical status code matches `c`. </td>
+  </tr>
+</table>
+
+The two- and one-argument version of StatusIs use util::GetErrorSpaceForEnum to
+determine the error space. If the error code matcher is not an enum with an
+associated ErrorSpace, then the canonical space will be used.

googlemock/g3doc/includes/g3_callback_snippet.md

@@ -0,0 +1,3 @@
+You can also use `google3` permanent callback as an action. Note that `Callback`
+or member function must be wrapped with `Invoke()`, whereas lambdas and functors
+will work by themselves.