-description: Let us know that something does not work as expected.
-title: "[Bug]: Please title this bug report"
-body:
- - type: textarea
- id: what-happened
- attributes:
- label: Describe the issue
- description: What happened, and what did you expect to happen?
- validations:
- required: true
- - type: textarea
- id: steps
- attributes:
- label: Steps to reproduce the problem
- description: It is important that we are able to reproduce the problem that you are experiencing. Please provide all code and relevant steps to reproduce the problem, including your `BUILD`/`CMakeLists.txt` file and build commands. Links to a GitHub branch or [godbolt.org](https://godbolt.org/) that demonstrate the problem are also helpful.
- validations:
- required: true
- - type: textarea
- id: version
- attributes:
- label: What version of GoogleTest are you using?
- description: Please include the output of `git rev-parse HEAD` or the GoogleTest release version number that you are using.
- validations:
- required: true
- - type: textarea
- id: os
- attributes:
- label: What operating system and version are you using?
- description: If you are using a Linux distribution please include the name and version of the distribution as well.
- validations:
- required: true
- - type: textarea
- id: compiler
- attributes:
- label: What compiler and version are you using?
- description: Please include the output of `gcc -v` or `clang -v`, or the equivalent for your compiler.
- validations:
- required: true
- - type: textarea
- id: buildsystem
- attributes:
- label: What build system are you using?
- description: Please include the output of `bazel --version` or `cmake --version`, or the equivalent for your build system.
- validations:
- required: true
- - type: textarea
- id: additional
- attributes:
- label: Additional context
- description: Add any other context about the problem here.
-[Abseil Live at Head philosophy](https://abseil.io/about/philosophy#upgrade-support).
-We recommend
-[updating to the latest commit in the `main` branch as often as possible](https://github.com/abseil/abseil-cpp/blob/master/FAQ.md#what-is-live-at-head-and-how-do-i-do-it).
-
-#### Documentation Updates
-
-Our documentation is now live on GitHub Pages at
-https://google.github.io/googletest/. We recommend browsing the documentation on
-GitHub Pages rather than directly in the repository.
-`ASSERT_NO_FATAL_FAILURE(statement);` | `EXPECT_NO_FATAL_FAILURE(statement);` | `statement` doesn't generate any new fatal failures in the current thread.
-
-Only failures in the thread that executes the assertion are checked to determine
-the result of this type of assertions. If `statement` creates new threads,
-failures in these threads are ignored.
-
-Examples:
-
-```c++
-ASSERT_NO_FATAL_FAILURE(Foo());
-
-int i;
-EXPECT_NO_FATAL_FAILURE({
- i = Bar();
-});
-```
-
-Assertions from multiple threads are currently not supported on Windows.
-
-#### Checking for Failures in the Current Test
-
-`HasFatalFailure()` in the `::testing::Test` class returns `true` if an
-assertion in the current test has suffered a fatal failure. This allows
-functions to catch fatal failures in a sub-routine and return early.
-
-```c++
-class Test {
- public:
- ...
- static bool HasFatalFailure();
-};
-```
-
-The typical usage, which basically simulates the behavior of a thrown exception,
-is:
-
-```c++
-TEST(FooTest, Bar) {
- Subroutine();
- // Aborts if Subroutine() had a fatal failure.
- if (HasFatalFailure()) return;
-
- // The following won't be executed.
- ...
-}
-```
-
-If `HasFatalFailure()` is used outside of `TEST()` , `TEST_F()` , or a test
-fixture, you must add the `::testing::Test::` prefix, as in:
-
-```c++
-if (testing::Test::HasFatalFailure()) return;
-```
-
-Similarly, `HasNonfatalFailure()` returns `true` if the current test has at
-least one non-fatal failure, and `HasFailure()` returns `true` if the current
-test has at least one failure of either kind.
-
-## Logging Additional Information
-
-In your test code, you can call `RecordProperty("key", value)` to log additional
-information, where `value` can be either a string or an `int`. The *last* value
-recorded for a key will be emitted to the
-[XML output](#generating-an-xml-report) if you specify one. For example, the
-You can see [sample7_unittest.cc] and [sample8_unittest.cc] for more examples.
-
-[sample7_unittest.cc]: https://github.com/google/googletest/blob/main/googletest/samples/sample7_unittest.cc "Parameterized Test example"
-[sample8_unittest.cc]: https://github.com/google/googletest/blob/main/googletest/samples/sample8_unittest.cc "Parameterized Test example with multiple parameters"
-
-### Creating Value-Parameterized Abstract Tests
-
-In the above, we define and instantiate `FooTest` in the *same* source file.
-Sometimes you may want to define value-parameterized tests in a library and let
-other people instantiate them later. This pattern is known as *abstract tests*.
-As an example of its application, when you are designing an interface you can
-write a standard suite of abstract tests (perhaps using a factory function as
-the test parameter) that all implementations of the interface are expected to
-pass. When someone implements the interface, they can instantiate your suite to
-get all the interface-conformance tests for free.
-
-To define abstract tests, you should organize your code like this:
-
-1. Put the definition of the parameterized test fixture class (e.g. `FooTest`)
- in a header file, say `foo_param_test.h`. Think of this as *declaring* your
- abstract tests.
-2. Put the `TEST_P` definitions in `foo_param_test.cc`, which includes
- `foo_param_test.h`. Think of this as *implementing* your abstract tests.
-
-Once they are defined, you can instantiate them by including `foo_param_test.h`,
-invoking `INSTANTIATE_TEST_SUITE_P()`, and depending on the library target that
-contains `foo_param_test.cc`. You can instantiate the same abstract test suite
-multiple times, possibly in different source files.
-
-### Specifying Names for Value-Parameterized Test Parameters
-
-The optional last argument to `INSTANTIATE_TEST_SUITE_P()` allows the user to
-specify a function or functor that generates custom test name suffixes based on
-the test parameters. The function should accept one argument of type
-`testing::TestParamInfo<class ParamType>`, and return `std::string`.
-
-`testing::PrintToStringParamName` is a builtin test suffix generator that
-returns the value of `testing::PrintToString(GetParam())`. It does not work for
-`std::string` or C strings.
-
-{: .callout .note}
-NOTE: test names must be non-empty, unique, and may only contain ASCII
-alphanumeric characters. In particular, they
-[should not contain underscores](faq.md#why-should-test-suite-names-and-test-names-not-contain-underscore)
-
-```c++
-class MyTestSuite : public testing::TestWithParam<int> {};
-`ASSERT_NE(ptr, nullptr)`. This is the preferred syntax in the style guide
-because `nullptr` does not have the type problems that `NULL` does.
-
-Due to some peculiarity of C++, it requires some non-trivial template meta
-programming tricks to support using `NULL` as an argument of the `EXPECT_XX()`
-and `ASSERT_XX()` macros. Therefore we only do it where it's most needed
-(otherwise we make the implementation of GoogleTest harder to maintain and more
-error-prone than necessary).
-
-Historically, the `EXPECT_EQ()` macro took the *expected* value as its first
-argument and the *actual* value as the second, though this argument order is now
-discouraged. It was reasonable that someone wanted
-to write `EXPECT_EQ(NULL, some_expression)`, and this indeed was requested
-several times. Therefore we implemented it.
-
-The need for `EXPECT_NE(NULL, ptr)` wasn't nearly as strong. When the assertion
-fails, you already know that `ptr` must be `NULL`, so it doesn't add any
-information to print `ptr` in this case. That means `EXPECT_TRUE(ptr != NULL)`
-works just as well.
-
-If we were to support `EXPECT_NE(NULL, ptr)`, for consistency we'd have to
-support `EXPECT_NE(ptr, NULL)` as well. This means using the template meta
-programming tricks twice in the implementation, making it even harder to
-understand and maintain. We believe the benefit doesn't justify the cost.
-
-Finally, with the growth of the gMock matcher library, we are encouraging people
-to use the unified `EXPECT_THAT(value, matcher)` syntax more often in tests. One
-significant advantage of the matcher approach is that matchers can be easily
-combined to form new matchers, while the `EXPECT_NE`, etc, macros cannot be
-easily combined. Therefore we want to invest more in the matchers than in the
-`EXPECT_XX()` macros.
-
-## I need to test that different implementations of an interface satisfy some common requirements. Should I use typed tests or value-parameterized tests?
-
-For testing various implementations of the same interface, either typed tests or
-value-parameterized tests can get it done. It's really up to you the user to
-decide which is more convenient for you, depending on your particular case. Some
-rough guidelines:
-
-* Typed tests can be easier to write if instances of the different
- implementations can be created the same way, modulo the type. For example,
- if all these implementations have a public default constructor (such that
- you can write `new TypeParam`), or if their factory functions have the same
- form (e.g. `CreateInstance<TypeParam>()`).
-* Value-parameterized tests can be easier to write if you need different code
- patterns to create different implementations' instances, e.g. `new Foo` vs
- `new Bar(5)`. To accommodate for the differences, you can write factory
- function wrappers and pass these function pointers to the tests as their
- parameters.
-* When a typed test fails, the default output includes the name of the type,
- which can help you quickly identify which implementation is wrong.
- Value-parameterized tests only show the number of the failed iteration by
- default. You will need to define a function that returns the iteration name
- and pass it as the third parameter to INSTANTIATE_TEST_SUITE_P to have more
- useful output.
-* When using typed tests, you need to make sure you are testing against the
- interface type, not the concrete types (in other words, you want to make
- sure `implicit_cast<MyInterface*>(my_concrete_impl)` works, not just that
- `my_concrete_impl` works). It's less likely to make mistakes in this area
- when using value-parameterized tests.
-
-I hope I didn't confuse you more. :-) If you don't mind, I'd suggest you to give
-both approaches a try. Practice is a much better way to grasp the subtle
-differences between the two tools. Once you have some concrete experience, you
-can much more easily decide which one to use the next time.
-
-## I got some run-time errors about invalid proto descriptors when using `ProtocolMessageEquals`. Help!
-
-{: .callout .note}
-**Note:** `ProtocolMessageEquals` and `ProtocolMessageEquiv` are *deprecated*
-now. Please use `EqualsProto`, etc instead.
-
-`ProtocolMessageEquals` and `ProtocolMessageEquiv` were redefined recently and
-are now less tolerant of invalid protocol buffer definitions. In particular, if
-you have a `foo.proto` that doesn't fully qualify the type of a protocol message
-it references (e.g. `message<Bar>` where it should be `message<blah.Bar>`), you
-will now get run-time errors like:
-
-```
-... descriptor.cc:...] Invalid proto descriptor for file "path/to/foo.proto":
-... descriptor.cc:...] blah.MyMessage.my_field: ".Bar" is not defined.
-```
-
-If you see this, your `.proto` file is broken and needs to be fixed by making
-the types fully qualified. The new definition of `ProtocolMessageEquals` and
-`ProtocolMessageEquiv` just happen to reveal your bug.
-
-## My death test modifies some state, but the change seems lost after the death test finishes. Why?
-
-Death tests (`EXPECT_DEATH`, etc) are executed in a sub-process s.t. the
-expected crash won't kill the test program (i.e. the parent process). As a
-result, any in-memory side effects they incur are observable in their respective
-sub-processes, but not in the parent process. You can think of them as running
-in a parallel universe, more or less.
-
-In particular, if you use mocking and the death test statement invokes some mock
-methods, the parent process will think the calls have never occurred. Therefore,
-you may want to move your `EXPECT_CALL` statements inside the `EXPECT_DEATH`
-macro.
-
-## EXPECT_EQ(htonl(blah), blah_blah) generates weird compiler errors in opt mode. Is this a GoogleTest bug?
-
-Actually, the bug is in `htonl()`.
-
-According to `'man htonl'`, `htonl()` is a *function*, which means it's valid to
-use `htonl` as a function pointer. However, in opt mode `htonl()` is defined as
-a *macro*, which breaks this usage.
-
-Worse, the macro definition of `htonl()` uses a `gcc` extension and is *not*
-standard C++. That hacky implementation has some ad hoc limitations. In
-particular, it prevents you from writing `Foo<sizeof(htonl(x))>()`, where `Foo`
-is a template that has an integral argument.
-
-The implementation of `EXPECT_EQ(a, b)` uses `sizeof(... a ...)` inside a
-template argument, and thus doesn't compile in opt mode when `a` contains a call
-to `htonl()`. It is difficult to make `EXPECT_EQ` bypass the `htonl()` bug, as
-the solution must work with different compilers on various platforms.
-
-## The compiler complains about "undefined references" to some static const member variables, but I did define them in the class body. What's wrong?
-
-If your class has a static data member:
-
-```c++
-// foo.h
-class Foo {
- ...
- static const int kBar = 100;
-};
-```
-
-You also need to define it *outside* of the class body in `foo.cc`:
-
-```c++
-const int Foo::kBar; // No initializer here.
-```
-
-Otherwise your code is **invalid C++**, and may break in unexpected ways. In
-particular, using it in GoogleTest comparison assertions (`EXPECT_EQ`, etc) will
-generate an "undefined reference" linker error. The fact that "it used to work"
-doesn't mean it's valid. It just means that you were lucky. :-)
-
-If the declaration of the static data member is `constexpr` then it is
-implicitly an `inline` definition, and a separate definition in `foo.cc` is not
-needed:
-
-```c++
-// foo.h
-class Foo {
- ...
- static constexpr int kBar = 100; // Defines kBar, no need to do it in foo.cc.
-};
-```
-
-## Can I derive a test fixture from another?
-
-Yes.
-
-Each test fixture has a corresponding and same named test suite. This means only
-one test suite can use a particular fixture. Sometimes, however, multiple test
-cases may want to use the same or slightly different fixtures. For example, you
-may want to make sure that all of a GUI library's test suites don't leak
-important system resources like fonts and brushes.
-
-In GoogleTest, you share a fixture among test suites by putting the shared logic
-in a base test fixture, then deriving from that base a separate fixture for each
-test suite that wants to use this common logic. You then use `TEST_F()` to write
-tests using each derived fixture.
-
-Typically, your code looks like this:
-
-```c++
-// Defines a base test fixture.
-class BaseTest : public ::testing::Test {
- protected:
- ...
-};
-
-// Derives a fixture FooTest from BaseTest.
-class FooTest : public BaseTest {
- protected:
- void SetUp() override {
- BaseTest::SetUp(); // Sets up the base fixture first.
- ... additional set-up work ...
- }
-
- void TearDown() override {
- ... clean-up work for FooTest ...
- BaseTest::TearDown(); // Remember to tear down the base fixture
- // after cleaning up FooTest!
- }
-
- ... functions and variables for FooTest ...
-};
-
-// Tests that use the fixture FooTest.
-TEST_F(FooTest, Bar) { ... }
-TEST_F(FooTest, Baz) { ... }
-
-... additional fixtures derived from BaseTest ...
-```
-
-If necessary, you can continue to derive test fixtures from a derived fixture.
-GoogleTest has no limit on how deep the hierarchy can be.
-
-For a complete example using derived test fixtures, see
-## My compiler complains "void value not ignored as it ought to be." What does this mean?
-
-You're probably using an `ASSERT_*()` in a function that doesn't return `void`.
-`ASSERT_*()` can only be used in `void` functions, due to exceptions being
-disabled by our build system. Please see more details
-[here](advanced.md#assertion-placement).
-
-## My death test hangs (or seg-faults). How do I fix it?
-
-In GoogleTest, death tests are run in a child process and the way they work is
-delicate. To write death tests you really need to understand how they work—see
-the details at [Death Assertions](reference/assertions.md#death) in the
-Assertions Reference.
-
-In particular, death tests don't like having multiple threads in the parent
-process. So the first thing you can try is to eliminate creating threads outside
-of `EXPECT_DEATH()`. For example, you may want to use mocks or fake objects
-instead of real ones in your tests.
-
-Sometimes this is impossible as some library you must use may be creating
-threads before `main()` is even reached. In this case, you can try to minimize
-the chance of conflicts by either moving as many activities as possible inside
-`EXPECT_DEATH()` (in the extreme case, you want to move everything inside), or
-leaving as few things as possible in it. Also, you can try to set the death test
-style to `"threadsafe"`, which is safer but slower, and see if it helps.
-
-If you go with thread-safe death tests, remember that they rerun the test
-program from the beginning in the child process. Therefore make sure your
-program can run side-by-side with itself and is deterministic.
-
-In the end, this boils down to good concurrent programming. You have to make
-sure that there are no race conditions or deadlocks in your program. No silver
-bullet - sorry!
-
-## Should I use the constructor/destructor of the test fixture or SetUp()/TearDown()? {#CtorVsSetUp}
-
-The first thing to remember is that GoogleTest does **not** reuse the same test
-fixture object across multiple tests. For each `TEST_F`, GoogleTest will create
-a **fresh** test fixture object, immediately call `SetUp()`, run the test body,
-call `TearDown()`, and then delete the test fixture object.
-
-When you need to write per-test set-up and tear-down logic, you have the choice
-between using the test fixture constructor/destructor or `SetUp()/TearDown()`.
-The former is usually preferred, as it has the following benefits:
-
-* By initializing a member variable in the constructor, we have the option to
- make it `const`, which helps prevent accidental changes to its value and
- makes the tests more obviously correct.
-* In case we need to subclass the test fixture class, the subclass'
- constructor is guaranteed to call the base class' constructor *first*, and
- the subclass' destructor is guaranteed to call the base class' destructor
- *afterward*. With `SetUp()/TearDown()`, a subclass may make the mistake of
- forgetting to call the base class' `SetUp()/TearDown()` or call them at the
- wrong time.
-
-You may still want to use `SetUp()/TearDown()` in the following cases:
-
-* C++ does not allow virtual function calls in constructors and destructors.
- You can call a method declared as virtual, but it will not use dynamic
- dispatch. It will use the definition from the class the constructor of which
- is currently executing. This is because calling a virtual method before the
- derived class constructor has a chance to run is very dangerous - the
- virtual method might operate on uninitialized data. Therefore, if you need
- to call a method that will be overridden in a derived class, you have to use
- `SetUp()/TearDown()`.
-* In the body of a constructor (or destructor), it's not possible to use the
- `ASSERT_xx` macros. Therefore, if the set-up operation could cause a fatal
- test failure that should prevent the test from running, it's necessary to
- use `abort` and abort the whole test
- executable, or to use `SetUp()` instead of a constructor.
-* If the tear-down operation could throw an exception, you must use
- `TearDown()` as opposed to the destructor, as throwing in a destructor leads
- to undefined behavior and usually will kill your program right away. Note
- that many standard libraries (like STL) may throw when exceptions are
- enabled in the compiler. Therefore you should prefer `TearDown()` if you
- want to write portable tests that work with or without exceptions.
-* The GoogleTest team is considering making the assertion macros throw on
- platforms where exceptions are enabled (e.g. Windows, Mac OS, and Linux
- client-side), which will eliminate the need for the user to propagate
- failures from a subroutine to its caller. Therefore, you shouldn't use
- GoogleTest assertions in a destructor if your code could run on such a
- platform.
-
-## The compiler complains "no matching function to call" when I use ASSERT_PRED*. How do I fix it?
-
-See details for [`EXPECT_PRED*`](reference/assertions.md#EXPECT_PRED) in the
-Assertions Reference.
-
-## My compiler complains about "ignoring return value" when I call RUN_ALL_TESTS(). Why?
-
-Some people had been ignoring the return value of `RUN_ALL_TESTS()`. That is,
-instead of
-
-```c++
- return RUN_ALL_TESTS();
-```
-
-they write
-
-```c++
- RUN_ALL_TESTS();
-```
-
-This is **wrong and dangerous**. The testing services needs to see the return
-value of `RUN_ALL_TESTS()` in order to determine if a test has passed. If your
-`main()` function ignores it, your test will be considered successful even if it
-has a GoogleTest assertion failure. Very bad.
-
-We have decided to fix this (thanks to Michael Chastain for the idea). Now, your
-code will no longer be able to ignore `RUN_ALL_TESTS()` when compiled with
-`gcc`. If you do so, you'll get a compiler error.
-
-If you see the compiler complaining about you ignoring the return value of
-`RUN_ALL_TESTS()`, the fix is simple: just make sure its value is used as the
-return value of `main()`.
-
-But how could we introduce a change that breaks existing tests? Well, in this
-case, the code was already broken in the first place, so we didn't break it. :-)
-
-## My compiler complains that a constructor (or destructor) cannot return a value. What's going on?
-
-Due to a peculiarity of C++, in order to support the syntax for streaming
-messages to an `ASSERT_*`, e.g.
-
-```c++
- ASSERT_EQ(1, Foo()) << "blah blah" << foo;
-```
-
-we had to give up using `ASSERT*` and `FAIL*` (but not `EXPECT*` and
-`ADD_FAILURE*`) in constructors and destructors. The workaround is to move the
-content of your constructor/destructor to a private void member function, or
-switch to `EXPECT_*()` if that works. This
-[section](advanced.md#assertion-placement) in the user's guide explains it.
-
-## My SetUp() function is not called. Why?
-
-C++ is case-sensitive. Did you spell it as `Setup()`?
-
-Similarly, sometimes people spell `SetUpTestSuite()` as `SetupTestSuite()` and
-wonder why it's never called.
-
-## I have several test suites which share the same test fixture logic, do I have to define a new test fixture class for each of them? This seems pretty tedious.
-
-You don't have to. Instead of
-
-```c++
-class FooTest : public BaseTest {};
-
-TEST_F(FooTest, Abc) { ... }
-TEST_F(FooTest, Def) { ... }
-
-class BarTest : public BaseTest {};
-
-TEST_F(BarTest, Abc) { ... }
-TEST_F(BarTest, Def) { ... }
-```
-
-you can simply `typedef` the test fixtures:
-
-```c++
-typedef BaseTest FooTest;
-
-TEST_F(FooTest, Abc) { ... }
-TEST_F(FooTest, Def) { ... }
-
-typedef BaseTest BarTest;
-
-TEST_F(BarTest, Abc) { ... }
-TEST_F(BarTest, Def) { ... }
-```
-
-## GoogleTest output is buried in a whole bunch of LOG messages. What do I do?
-
-The GoogleTest output is meant to be a concise and human-friendly report. If
-your test generates textual output itself, it will mix with the GoogleTest
-output, making it hard to read. However, there is an easy solution to this
-problem.
-
-Since `LOG` messages go to stderr, we decided to let GoogleTest output go to
-stdout. This way, you can easily separate the two using redirection. For
-example:
-
-```shell
-$ ./my_test > gtest_output.txt
-```
-
-## Why should I prefer test fixtures over global variables?
-
-There are several good reasons:
-
-1. It's likely your test needs to change the states of its global variables.
- This makes it difficult to keep side effects from escaping one test and
- contaminating others, making debugging difficult. By using fixtures, each
- test has a fresh set of variables that's different (but with the same
- names). Thus, tests are kept independent of each other.
-2. Global variables pollute the global namespace.
-3. Test fixtures can be reused via subclassing, which cannot be done easily
- with global variables. This is useful if many test suites have something in
- common.
-
-## What can the statement argument in ASSERT_DEATH() be?
-
-`ASSERT_DEATH(statement, matcher)` (or any death assertion macro) can be used
-wherever *`statement`* is valid. So basically *`statement`* can be any C++
-statement that makes sense in the current context. In particular, it can
-reference global and/or local variables, and can be:
-
-* a simple function call (often the case),
-* a complex expression, or
-* a compound statement.
-
-Some examples are shown here:
-
-```c++
-// A death test can be a simple function call.
-TEST(MyDeathTest, FunctionCall) {
- ASSERT_DEATH(Xyz(5), "Xyz failed");
-}
-
-// Or a complex expression that references variables and functions.
-## GoogleTest prints the LOG messages in a death test's child process only when the test fails. How can I see the LOG messages when the death test succeeds?
-
-Printing the LOG messages generated by the statement inside `EXPECT_DEATH()`
-makes it harder to search for real problems in the parent's log. Therefore,
-GoogleTest only prints them when the death test has failed.
-
-If you really need to see such LOG messages, a workaround is to temporarily
-break the death test (e.g. by changing the regex pattern it is expected to
-match). Admittedly, this is a hack. We'll consider a more permanent solution
-after the fork-and-exec-style death tests are implemented.
-
-## The compiler complains about `no match for 'operator<<'` when I use an assertion. What gives?
-
-If you use a user-defined type `FooType` in an assertion, you must make sure
-there is an `std::ostream& operator<<(std::ostream&, const FooType&)` function
-defined such that we can print a value of `FooType`.
-
-In addition, if `FooType` is declared in a name space, the `<<` operator also
-needs to be defined in the *same* name space. See
-[Tip of the Week #49](http://abseil.io/tips/49) for details.
-
-## How do I suppress the memory leak messages on Windows?
-
-Since the statically initialized GoogleTest singleton requires allocations on
-the heap, the Visual C++ memory leak detector will report memory leaks at the
-end of the program run. The easiest way to avoid this is to use the
-`_CrtMemCheckpoint` and `_CrtMemDumpAllObjectsSince` calls to not report any
-statically initialized heap objects. See MSDN for more details and additional
-heap check/debug routines.
-
-## How can my code detect if it is running in a test?
-
-If you write code that sniffs whether it's running in a test and does different
-things accordingly, you are leaking test-only logic into production code and
-there is no easy way to ensure that the test-only code paths aren't run by
-mistake in production. Such cleverness also leads to
-[Heisenbugs](https://en.wikipedia.org/wiki/Heisenbug). Therefore we strongly
-advise against the practice, and GoogleTest doesn't provide a way to do it.
-
-In general, the recommended way to cause the code to behave differently under
-test is [Dependency Injection](http://en.wikipedia.org/wiki/Dependency_injection). You can inject
-different functionality from the test and from the production code. Since your
-production code doesn't link in the for-test logic at all (the
-[`testonly`](http://docs.bazel.build/versions/master/be/common-definitions.html#common.testonly) attribute for BUILD targets helps to ensure
-that), there is no danger in accidentally running it.
-
-However, if you *really*, *really*, *really* have no choice, and if you follow
-the rule of ending your test program names with `_test`, you can use the
-*horrible* hack of sniffing your executable name (`argv[0]` in `main()`) to know
-whether the code is under test.
-
-## How do I temporarily disable a test?
-
-If you have a broken test that you cannot fix right away, you can add the
-`DISABLED_` prefix to its name. This will exclude it from execution. This is
-better than commenting out the code or using `#if 0`, as disabled tests are
-still compiled (and thus won't rot).
-
-To include disabled tests in test execution, just invoke the test program with
-the `--gtest_also_run_disabled_tests` flag.
-
-## Is it OK if I have two separate `TEST(Foo, Bar)` test methods defined in different namespaces?
-
-Yes.
-
-The rule is **all test methods in the same test suite must use the same fixture
-class.** This means that the following is **allowed** because both tests use the
-same fixture class (`::testing::Test`).
-
-```c++
-namespace foo {
-TEST(CoolTest, DoSomething) {
- SUCCEED();
-}
-} // namespace foo
-
-namespace bar {
-TEST(CoolTest, DoSomething) {
- SUCCEED();
-}
-} // namespace bar
-```
-
-However, the following code is **not allowed** and will produce a runtime error
-from GoogleTest because the test methods are using different test fixture
-classes with the same test suite name.
-
-```c++
-namespace foo {
-class CoolTest : public ::testing::Test {}; // Fixture foo::CoolTest
-TEST_F(CoolTest, DoSomething) {
- SUCCEED();
-}
-} // namespace foo
-
-namespace bar {
-class CoolTest : public ::testing::Test {}; // Fixture: bar::CoolTest
-You cannot mock a variadic function (i.e. a function taking ellipsis (`...`)
-arguments) directly in gMock.
-
-The problem is that in general, there is *no way* for a mock object to know how
-many arguments are passed to the variadic method, and what the arguments' types
-are. Only the *author of the base class* knows the protocol, and we cannot look
-into his or her head.
-
-Therefore, to mock such a function, the *user* must teach the mock object how to
-figure out the number of arguments and their types. One way to do it is to
-provide overloaded versions of the function.
-
-Ellipsis arguments are inherited from C and not really a C++ feature. They are
-unsafe to use and don't work with arguments that have constructors or
-destructors. Therefore we recommend to avoid them in C++ as much as possible.
-
-### MSVC gives me warning C4301 or C4373 when I define a mock method with a const parameter. Why?
-
-If you compile this using Microsoft Visual C++ 2005 SP1:
-
-```cpp
-class Foo {
- ...
- virtual void Bar(const int i) = 0;
-};
-
-class MockFoo : public Foo {
- ...
- MOCK_METHOD(void, Bar, (const int i), (override));
-};
-```
-
-You may get the following warning:
-
-```shell
-warning C4301: 'MockFoo::Bar': overriding virtual function only differs from 'Foo::Bar' by const/volatile qualifier
-```
-
-This is a MSVC bug. The same code compiles fine with gcc, for example. If you
-use Visual C++ 2008 SP1, you would get the warning:
-
-```shell
-warning C4373: 'MockFoo::Bar': virtual function overrides 'Foo::Bar', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers
-```
-
-In C++, if you *declare* a function with a `const` parameter, the `const`
-modifier is ignored. Therefore, the `Foo` base class above is equivalent to:
-
-```cpp
-class Foo {
- ...
- virtual void Bar(int i) = 0; // int or const int? Makes no difference.
-};
-```
-
-In fact, you can *declare* `Bar()` with an `int` parameter, and define it with a
-`const int` parameter. The compiler will still match them up.
-
-Since making a parameter `const` is meaningless in the method declaration, we
-recommend to remove it in both `Foo` and `MockFoo`. That should workaround the
-VC bug.
-
-Note that we are talking about the *top-level* `const` modifier here. If the
-function parameter is passed by pointer or reference, declaring the pointee or
-referee as `const` is still meaningful. For example, the following two
-declarations are *not* equivalent:
-
-```cpp
-void Bar(int* p); // Neither p nor *p is const.
-void Bar(const int* p); // p is not const, but *p is.
-```
-
-### I can't figure out why gMock thinks my expectations are not satisfied. What should I do?
-
-You might want to run your test with `--gmock_verbose=info`. This flag lets
-gMock print a trace of every mock function call it receives. By studying the
-trace, you'll gain insights on why the expectations you set are not met.
-
-If you see the message "The mock function has no default action set, and its
-return type has no default value set.", then try
-[adding a default action](gmock_cheat_sheet.md#OnCall). Due to a known issue,
-unexpected calls on mocks without default actions don't print out a detailed
-comparison between the actual arguments and the expected arguments.
-
-### My program crashed and `ScopedMockLog` spit out tons of messages. Is it a gMock bug?
-
-gMock and `ScopedMockLog` are likely doing the right thing here.
-
-When a test crashes, the failure signal handler will try to log a lot of
-information (the stack trace, and the address map, for example). The messages
-are compounded if you have many threads with depth stacks. When `ScopedMockLog`
-intercepts these messages and finds that they don't match any expectations, it
-prints an error for each of them.
-
-You can learn to ignore the errors, or you can rewrite your expectations to make
-your test more robust, for example, by adding something like:
-### How can I assert that a function is NEVER called?
-
-```cpp
-using ::testing::_;
-...
- EXPECT_CALL(foo, Bar(_))
- .Times(0);
-```
-
-### I have a failed test where gMock tells me TWICE that a particular expectation is not satisfied. Isn't this redundant?
-
-When gMock detects a failure, it prints relevant information (the mock function
-arguments, the state of relevant expectations, and etc) to help the user debug.
-If another failure is detected, gMock will do the same, including printing the
-state of relevant expectations.
-
-Sometimes an expectation's state didn't change between two failures, and you'll
-see the same description of the state twice. They are however *not* redundant,
-as they refer to *different points in time*. The fact they are the same *is*
-interesting information.
-
-### I get a heapcheck failure when using a mock object, but using a real object is fine. What can be wrong?
-
-Does the class (hopefully a pure interface) you are mocking have a virtual
-destructor?
-
-Whenever you derive from a base class, make sure its destructor is virtual.
-Otherwise Bad Things will happen. Consider the following code:
-
-```cpp
-class Base {
- public:
- // Not virtual, but should be.
- ~Base() { ... }
- ...
-};
-
-class Derived : public Base {
- public:
- ...
- private:
- std::string value_;
-};
-
-...
- Base* p = new Derived;
- ...
- delete p; // Surprise! ~Base() will be called, but ~Derived() will not
- // - value_ is leaked.
-```
-
-By changing `~Base()` to virtual, `~Derived()` will be correctly called when
-`delete p` is executed, and the heap checker will be happy.
-
-### The "newer expectations override older ones" rule makes writing expectations awkward. Why does gMock do that?
-
-When people complain about this, often they are referring to code like:
-
-```cpp
-using ::testing::Return;
-...
- // foo.Bar() should be called twice, return 1 the first time, and return
- // 2 the second time. However, I have to write the expectations in the
- // reverse order. This sucks big time!!!
- EXPECT_CALL(foo, Bar())
- .WillOnce(Return(2))
- .RetiresOnSaturation();
- EXPECT_CALL(foo, Bar())
- .WillOnce(Return(1))
- .RetiresOnSaturation();
-```
-
-The problem, is that they didn't pick the **best** way to express the test's
-intent.
-
-By default, expectations don't have to be matched in *any* particular order. If
-you want them to match in a certain order, you need to be explicit. This is
-gMock's (and jMock's) fundamental philosophy: it's easy to accidentally
-over-specify your tests, and we want to make it harder to do so.
-
-There are two better ways to write the test spec. You could either put the
-expectations in sequence:
-
-```cpp
-using ::testing::Return;
-...
- // foo.Bar() should be called twice, return 1 the first time, and return
- // 2 the second time. Using a sequence, we can write the expectations
- // in their natural order.
- {
- InSequence s;
- EXPECT_CALL(foo, Bar())
- .WillOnce(Return(1))
- .RetiresOnSaturation();
- EXPECT_CALL(foo, Bar())
- .WillOnce(Return(2))
- .RetiresOnSaturation();
- }
-```
-
-or you can put the sequence of actions in the same expectation:
-
-```cpp
-using ::testing::Return;
-...
- // foo.Bar() should be called twice, return 1 the first time, and return
- // 2 the second time.
- EXPECT_CALL(foo, Bar())
- .WillOnce(Return(1))
- .WillOnce(Return(2))
- .RetiresOnSaturation();
-```
-
-Back to the original questions: why does gMock search the expectations (and
-`ON_CALL`s) from back to front? Because this allows a user to set up a mock's
-behavior for the common case early (e.g. in the mock's constructor or the test
-fixture's set-up phase) and customize it with more specific rules later. If
-gMock searches from front to back, this very useful pattern won't be possible.
-
-### gMock prints a warning when a function without EXPECT_CALL is called, even if I have set its behavior using ON_CALL. Would it be reasonable not to show the warning in this case?
-
-When choosing between being neat and being safe, we lean toward the latter. So
-the answer is that we think it's better to show the warning.
-
-Often people write `ON_CALL`s in the mock object's constructor or `SetUp()`, as
-the default behavior rarely changes from test to test. Then in the test body
-they set the expectations, which are often different for each test. Having an
-`ON_CALL` in the set-up part of a test doesn't mean that the calls are expected.
-If there's no `EXPECT_CALL` and the method is called, it's possibly an error. If
-we quietly let the call go through without notifying the user, bugs may creep in
-unnoticed.
-
-If, however, you are sure that the calls are OK, you can write
-
-```cpp
-using ::testing::_;
-...
- EXPECT_CALL(foo, Bar(_))
- .WillRepeatedly(...);
-```
-
-instead of
-
-```cpp
-using ::testing::_;
-...
- ON_CALL(foo, Bar(_))
- .WillByDefault(...);
-```
-
-This tells gMock that you do expect the calls and no warning should be printed.
-
-Also, you can control the verbosity by specifying `--gmock_verbose=error`. Other
-values are `info` and `warning`. If you find the output too noisy when
-debugging, just choose a less verbose level.
-
-### How can I delete the mock function's argument in an action?
-
-If your mock function takes a pointer argument and you want to delete that
-argument, you can use testing::DeleteArg<N>() to delete the N'th (zero-indexed)
-argument:
-
-```cpp
-using ::testing::_;
- ...
- MOCK_METHOD(void, Bar, (X* x, const Y& y));
- ...
- EXPECT_CALL(mock_foo_, Bar(_, _))
- .WillOnce(testing::DeleteArg<0>()));
-```
-
-### How can I perform an arbitrary action on a mock function's argument?
-
-If you find yourself needing to perform some action that's not supported by
-gMock directly, remember that you can define your own actions using
-[`MakeAction()`](#NewMonoActions) or
-[`MakePolymorphicAction()`](#NewPolyActions), or you can write a stub function
-and invoke it using [`Invoke()`](#FunctionsAsActions).
-
-```cpp
-using ::testing::_;
-using ::testing::Invoke;
- ...
- MOCK_METHOD(void, Bar, (X* p));
- ...
- EXPECT_CALL(mock_foo_, Bar(_))
- .WillOnce(Invoke(MyAction(...)));
-```
-
-### My code calls a static/global function. Can I mock it?
-
-You can, but you need to make some changes.
-
-In general, if you find yourself needing to mock a static function, it's a sign
-that your modules are too tightly coupled (and less flexible, less reusable,
-less testable, etc). You are probably better off defining a small interface and
-call the function through that interface, which then can be easily mocked. It's
-a bit of work initially, but usually pays for itself quickly.
-
-This Google Testing Blog
-[post](https://testing.googleblog.com/2008/06/defeat-static-cling.html) says it
-excellently. Check it out.
-
-### My mock object needs to do complex stuff. It's a lot of pain to specify the actions. gMock sucks!
-
-I know it's not a question, but you get an answer for free any way. :-)
-
-With gMock, you can create mocks in C++ easily. And people might be tempted to
-use them everywhere. Sometimes they work great, and sometimes you may find them,
-well, a pain to use. So, what's wrong in the latter case?
-
-When you write a test without using mocks, you exercise the code and assert that
-it returns the correct value or that the system is in an expected state. This is
-sometimes called "state-based testing".
-
-Mocks are great for what some call "interaction-based" testing: instead of
-checking the system state at the very end, mock objects verify that they are
-invoked the right way and report an error as soon as it arises, giving you a
-handle on the precise context in which the error was triggered. This is often
-more effective and economical to do than state-based testing.
-
-If you are doing state-based testing and using a test double just to simulate
-the real object, you are probably better off using a fake. Using a mock in this
-case causes pain, as it's not a strong point for mocks to perform complex
-actions. If you experience this and think that mocks suck, you are just not
-using the right tool for your problem. Or, you might be trying to solve the
-wrong problem. :-)
-
-### I got a warning "Uninteresting function call encountered - default action taken.." Should I panic?
-
-By all means, NO! It's just an FYI. :-)
-
-What it means is that you have a mock function, you haven't set any expectations
-on it (by gMock's rule this means that you are not interested in calls to this
-function and therefore it can be called any number of times), and it is called.
-That's OK - you didn't say it's not OK to call the function!
-
-What if you actually meant to disallow this function to be called, but forgot to
-write `EXPECT_CALL(foo, Bar()).Times(0)`? While one can argue that it's the
-user's fault, gMock tries to be nice and prints you a note.
-
-So, when you see the message and believe that there shouldn't be any
-uninteresting calls, you should investigate what's going on. To make your life
-easier, gMock dumps the stack trace when an uninteresting call is encountered.
-From that you can figure out which mock function it is, and how it is called.
-
-### I want to define a custom action. Should I use Invoke() or implement the ActionInterface interface?
-
-Either way is fine - you want to choose the one that's more convenient for your
-circumstance.
-
-Usually, if your action is for a particular function type, defining it using
-`Invoke()` should be easier; if your action can be used in functions of
-different types (e.g. if you are defining `Return(*value*)`),
-`MakePolymorphicAction()` is easiest. Sometimes you want precise control on what
-types of functions the action can be used in, and implementing `ActionInterface`
-is the way to go here. See the implementation of `Return()` in `gmock-actions.h`
-for an example.
-
-### I use SetArgPointee() in WillOnce(), but gcc complains about "conflicting return type specified". What does it mean?
-
-You got this error as gMock has no idea what value it should return when the
-mock method is called. `SetArgPointee()` says what the side effect is, but
-doesn't say what the return value should be. You need `DoAll()` to chain a
-`SetArgPointee()` with a `Return()` that provides a value appropriate to the API
-being mocked.
-
-See this [recipe](gmock_cook_book.md#mocking-side-effects) for more details and
-an example.
-
-### I have a huge mock class, and Microsoft Visual C++ runs out of memory when compiling it. What can I do?
-
-We've noticed that when the `/clr` compiler flag is used, Visual C++ uses 5~6
-times as much memory when compiling a mock class. We suggest to avoid `/clr`
-| `Return()` | Return from a `void` mock function. |
-| `Return(value)` | Return `value`. If the type of `value` is different to the mock function's return type, `value` is converted to the latter type <i>at the time the expectation is set</i>, not when the action is executed. |
-| `ReturnArg<N>()` | Return the `N`-th (0-based) argument. |
-| `ReturnNew<T>(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different object is created each time. |
-| `ReturnNull()` | Return a null pointer. |
-| `ReturnPointee(ptr)` | Return the value pointed to by `ptr`. |
-| `ReturnRef(variable)` | Return a reference to `variable`. |
-| `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. |
-| `ReturnRoundRobin({a1, ..., ak})` | Each call will return the next `ai` in the list, starting at the beginning when the end of the list is reached. |
-| `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. |
-
-## Using a Function, Functor, or Lambda as an Action
-
-In the following, by "callable" we mean a free function, `std::function`,
-| `f` | Invoke `f` with the arguments passed to the mock function, where `f` is a callable. |
-| `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. |
-| `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. |
-| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. |
-| `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. |
-| `InvokeArgument<N>(arg1, arg2, ..., argk)` | Invoke the mock function's `N`-th (0-based) argument, which must be a function or a functor, with the `k` arguments. |
-
-The return value of the invoked function is used as the return value of the
-action.
-
-When defining a callable to be used with `Invoke*()`, you can declare any unused
-| `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the result of `an` in each invocation. The first `n - 1` sub-actions must return void and will receive a readonly view of the arguments. |
-| `IgnoreResult(a)` | Perform action `a` and ignore its result. `a` must not return void. |
-| `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. |
-| `WithArgs<N1, N2, ..., Nk>(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. |
-| `WithoutArgs(a)` | Perform action `a` without any arguments. |
-| `IsFalse()` | `argument` evaluates to `false` in a Boolean context. |
-| `IsTrue()` | `argument` evaluates to `true` in a Boolean context. |
-| `IsNull()` | `argument` is a `NULL` pointer (raw or smart). |
-| `NotNull()` | `argument` is a non-null pointer (raw or smart). |
-| `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. (For testing whether an `optional<>` is set, check for equality with `nullopt`. You may need to use `Eq(nullopt)` if the inner type doesn't have `==`.)|
-| `VariantWith<T>(m)` | `argument` is `variant<>` that holds the alternative of type T with a value matching `m`. |
-| `Ref(variable)` | `argument` is a reference to `variable`. |
-| `TypedEq<type>(value)` | `argument` has type `type` and is equal to `value`. You may need to use this instead of `Eq(value)` when the mock function is overloaded. |
-
-Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or
-destructed later. If the compiler complains that `value` doesn't have a public
-copy constructor, try wrap it in `std::ref()`, e.g.
-`Eq(std::ref(non_copyable_value))`. If you do that, make sure
-`non_copyable_value` is not changed afterwards, or the meaning of your matcher
-will be changed.
-
-`IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types
-that can be explicitly converted to Boolean, but are not implicitly converted to
-Boolean. In other cases, you can use the basic
-[`EXPECT_TRUE` and `EXPECT_FALSE`](assertions.md#boolean) assertions.
-| `DoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as unequal. |
-| `FloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as unequal. |
-| `NanSensitiveDoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as equal. |
-| `NanSensitiveFloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as equal. |
-
-## String Matchers
-
-The `argument` can be either a C string or a C++ string object:
-| `ContainsRegex(string)` | `argument` matches the given regular expression. |
-| `EndsWith(suffix)` | `argument` ends with string `suffix`. |
-| `HasSubstr(string)` | `argument` contains `string` as a sub-string. |
-| `IsEmpty()` | `argument` is an empty string. |
-| `MatchesRegex(string)` | `argument` matches the given regular expression with the match starting at the first character and ending at the last character. |
-| `StartsWith(prefix)` | `argument` starts with string `prefix`. |
-| `StrCaseEq(string)` | `argument` is equal to `string`, ignoring case. |
-| `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring case. |
-| `StrEq(string)` | `argument` is equal to `string`. |
-| `StrNe(string)` | `argument` is not equal to `string`. |
-| `WhenBase64Unescaped(m)` | `argument` is a base-64 escaped string whose unescaped string matches `m`. |
-
-`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They
-use the regular expression syntax defined
-[here](../advanced.md#regular-expression-syntax). All of these matchers, except
-`ContainsRegex()` and `MatchesRegex()` work for wide strings as well.
-
-## Container Matchers
-
-Most STL-style containers support `==`, so you can use `Eq(expected_container)`
-or simply `expected_container` to match a container exactly. If you want to
-write the elements in-line, match them more flexibly, or get more informative
-| `BeginEndDistanceIs(m)` | `argument` is a container whose `begin()` and `end()` iterators are separated by a number of increments matching `m`. E.g. `BeginEndDistanceIs(2)` or `BeginEndDistanceIs(Lt(2))`. For containers that define a `size()` method, `SizeIs(m)` may be more efficient. |
-| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. |
-| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. |
-| `Contains(e).Times(n)` | `argument` contains elements that match `e`, which can be either a value or a matcher, and the number of matches is `n`, which can be either a value or a matcher. Unlike the plain `Contains` and `Each` this allows to check for arbitrary occurrences including testing for absence with `Contains(e).Times(0)`. |
-| `Each(e)` | `argument` is a container where *every* element matches `e`, which can be either a value or a matcher. |
-| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. |
-| `ElementsAreArray({e0, e1, ..., en})`, `ElementsAreArray(a_container)`, `ElementsAreArray(begin, end)`, `ElementsAreArray(array)`, or `ElementsAreArray(array, count)` | The same as `ElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
-| `IsEmpty()` | `argument` is an empty container (`container.empty()`). |
-| `IsSubsetOf({e0, e1, ..., en})`, `IsSubsetOf(a_container)`, `IsSubsetOf(begin, end)`, `IsSubsetOf(array)`, or `IsSubsetOf(array, count)` | `argument` matches `UnorderedElementsAre(x0, x1, ..., xk)` for some subset `{x0, x1, ..., xk}` of the expected matchers. |
-| `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. |
-| `Pointwise(m, container)`, `Pointwise(m, {e0, e1, ..., en})` | `argument` contains the same number of elements as in `container`, and for all i, (the i-th element in `argument`, the i-th element in `container`) match `m`, which is a matcher on 2-tuples. E.g. `Pointwise(Le(), upper_bounds)` verifies that each element in `argument` doesn't exceed the corresponding element in `upper_bounds`. See more detail below. |
-| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. |
-| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, and under *some* permutation of the elements, each element matches an `ei` (for a different `i`), which can be a value or a matcher. |
-| `UnorderedElementsAreArray({e0, e1, ..., en})`, `UnorderedElementsAreArray(a_container)`, `UnorderedElementsAreArray(begin, end)`, `UnorderedElementsAreArray(array)`, or `UnorderedElementsAreArray(array, count)` | The same as `UnorderedElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
-| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. |
-| `WhenSorted(m)` | When `argument` is sorted using the `<` operator, it matches container matcher `m`. E.g. `WhenSorted(ElementsAre(1, 2, 3))` verifies that `argument` contains elements 1, 2, and 3, ignoring order. |
-| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, except that the given comparator instead of `<` is used to sort `argument`. E.g. `WhenSortedBy(std::greater(), ElementsAre(3, 2, 1))`. |
-
-**Notes:**
-
-* These matchers can also match:
- 1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`),
- and
- 2. an array passed as a pointer and a count (e.g. in `Bar(const T* buffer,
- int len)` -- see [Multi-argument Matchers](#MultiArgMatchers)).
-* The array being matched may be multi-dimensional (i.e. its elements can be
- arrays).
-* `m` in `Pointwise(m, ...)` and `UnorderedPointwise(m, ...)` should be a
- matcher for `::std::tuple<T, U>` where `T` and `U` are the element type of
- the actual container and the expected container, respectively. For example,
- to compare two `Foo` containers where `Foo` doesn't support `operator==`,
-| `Field(&class::field, m)` | `argument.field` (or `argument->field` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. |
-| `Field(field_name, &class::field, m)` | The same as the two-parameter version, but provides a better error message. |
-| `Key(e)` | `argument.first` matches `e`, which can be either a value or a matcher. E.g. `Contains(Key(Le(5)))` can verify that a `map` contains a key `<= 5`. |
-| `Pair(m1, m2)` | `argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. |
-| `FieldsAre(m...)` | `argument` is a compatible object where each field matches piecewise with the matchers `m...`. A compatible object is any that supports the `std::tuple_size<Obj>`+`get<I>(obj)` protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates. |
-| `Property(&class::property, m)` | `argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. The method `property()` must take no argument and be declared as `const`. |
-| `Property(property_name, &class::property, m)` | The same as the two-parameter version, but provides a better error message.
-
-**Notes:**
-
-* You can use `FieldsAre()` to match any type that supports structured
- bindings, such as `std::tuple`, `std::pair`, `std::array`, and aggregate
-| `Address(m)` | the result of `std::addressof(argument)` matches `m`. |
-| `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. |
-| `Pointer(m)` | `argument` (either a smart pointer or a raw pointer) contains a pointer that matches `m`. `m` will match against the raw pointer regardless of the type of `argument`. |
-| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. |
-
-## Multi-argument Matchers {#MultiArgMatchers}
-
-Technically, all matchers match a *single* value. A "multi-argument" matcher is
-just one that matches a *tuple*. The following matchers can be used to match a
-tuple `(x, y)`:
-
-Matcher | Description
-:------ | :----------
-`Eq()` | `x == y`
-`Ge()` | `x >= y`
-`Gt()` | `x > y`
-`Le()` | `x <= y`
-`Lt()` | `x < y`
-`Ne()` | `x != y`
-
-You can use the following selectors to pick a subset of the arguments (or
-| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. |
-| `AllOfArray({m0, m1, ..., mn})`, `AllOfArray(a_container)`, `AllOfArray(begin, end)`, `AllOfArray(array)`, or `AllOfArray(array, count)` | The same as `AllOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
-| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. |
-| `AnyOfArray({m0, m1, ..., mn})`, `AnyOfArray(a_container)`, `AnyOfArray(begin, end)`, `AnyOfArray(array)`, or `AnyOfArray(array, count)` | The same as `AnyOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
-| `Not(m)` | `argument` doesn't match matcher `m`. |
-| `Conditional(cond, m1, m2)` | Matches matcher `m1` if `cond` evaluates to true, else matches `m2`.|
-| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. |
-| `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a matcher `IsDivisibleBy(n)` to match a number divisible by `n`. |
-| `MATCHER_P2(IsBetween, a, b, absl::StrCat(negation ? "isn't" : "is", " between ", PrintToString(a), " and ", PrintToString(b))) { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. |
-
-**Notes:**
-
-1. The `MATCHER*` macros cannot be used inside a function or class.
-2. The matcher body must be *purely functional* (i.e. it cannot have any side
- effect, and the result must not depend on anything other than the value
- being matched and the matcher parameters).
-3. You can use `PrintToString(x)` to convert a value `x` of any type to a
- string.
-4. You can use `ExplainMatchResult()` in a custom matcher to wrap another
-| `const` | Makes the mocked method a `const` method. Required if overriding a `const` method. |
-| `override` | Marks the method with `override`. Recommended if overriding a `virtual` method. |
-| `noexcept` | Marks the method with `noexcept`. Required if overriding a `noexcept` method. |
-| `Calltype(`*`calltype`*`)` | Sets the call type for the method, for example `Calltype(STDMETHODCALLTYPE)`. Useful on Windows. |
-| `ref(`*`qualifier`*`)` | Marks the method with the given reference qualifier, for example `ref(&)` or `ref(&&)`. Required if overriding a method that has a reference qualifier. |
-
-Note that commas in arguments prevent `MOCK_METHOD` from parsing the arguments
-correctly if they are not appropriately surrounded by parentheses. See the
-following example:
-
-```cpp
-class MyMock {
- public:
- // The following 2 lines will not compile due to commas in the arguments:
-| `ValuesIn(container)` or `ValuesIn(begin,end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)`. |
-| `Bool()` | Yields sequence `{false, true}`. |
-| `Combine(g1, g2, ..., gN)` | Yields as `std::tuple` *n*-tuples all combinations (Cartesian product) of the values generated by the given *n* generators `g1`, `g2`, ..., `gN`. |
-| `ConvertGenerator<T>(g)` | Yields values generated by generator `g`, `static_cast` to `T`. |
-The optional last argument *`name_generator`* is a function or functor that
-generates custom test name suffixes based on the test parameters. The function
-must accept an argument of type
-[`TestParamInfo<class ParamType>`](#TestParamInfo) and return a `std::string`.
-The test name suffix can only contain alphanumeric characters and underscores.
-GoogleTest provides [`PrintToStringParamName`](#PrintToStringParamName), or a
-Uninteresting mock function call - returning default value.
- Function call: Bar2(0, 1)
- Returns: false
-NOTE: You can safely ignore the above warning unless this call should not happen. Do not suppress it by blindly adding an EXPECT_CALL() if you don't mean to enforce the call. See https://github.com/google/googletest/blob/main/docs/gmock_cook_book.md#knowing-when-to-expect for details.
-[ OK ] GMockOutputTest.UninterestingCall
-[ RUN ] GMockOutputTest.UninterestingCallToVoidFunction
-
-GMOCK WARNING:
-Uninteresting mock function call - returning directly.
- Function call: Bar3(0, 1)
-NOTE: You can safely ignore the above warning unless this call should not happen. Do not suppress it by blindly adding an EXPECT_CALL() if you don't mean to enforce the call. See https://github.com/google/googletest/blob/main/docs/gmock_cook_book.md#knowing-when-to-expect for details.
-[ OK ] GMockOutputTest.UninterestingCallToVoidFunction
-[ RUN ] GMockOutputTest.RetiredExpectation
-unknown file: Failure
-
-Unexpected mock function call - returning default value.
- Function call: Bar2(1, 1)
- Returns: false
-Google Mock tried the following 2 expectations, but none matched:
-[ RUN ] GMockOutputTest.UninterestingCallWithDefaultAction
-
-GMOCK WARNING:
-Uninteresting mock function call - taking default action specified at:
-FILE:#:
- Function call: Bar2(2, 2)
- Returns: true
-NOTE: You can safely ignore the above warning unless this call should not happen. Do not suppress it by blindly adding an EXPECT_CALL() if you don't mean to enforce the call. See https://github.com/google/googletest/blob/main/docs/gmock_cook_book.md#knowing-when-to-expect for details.
-
-GMOCK WARNING:
-Uninteresting mock function call - taking default action specified at:
-FILE:#:
- Function call: Bar2(1, 1)
- Returns: false
-NOTE: You can safely ignore the above warning unless this call should not happen. Do not suppress it by blindly adding an EXPECT_CALL() if you don't mean to enforce the call. See https://github.com/google/googletest/blob/main/docs/gmock_cook_book.md#knowing-when-to-expect for details.
-[ OK ] GMockOutputTest.UninterestingCallWithDefaultAction
-[ RUN ] GMockOutputTest.ExplicitActionsRunOutWithDefaultAction
-
-GMOCK WARNING:
-FILE:#: Too few actions specified in EXPECT_CALL(foo_, Bar2(_, _))...
-Expected to be called twice, but has only 1 WillOnce().
-GMOCK WARNING:
-FILE:#: Actions ran out in EXPECT_CALL(foo_, Bar2(_, _))...
-Called 2 times, but only 1 WillOnce() is specified - taking default action specified at:
-FILE:#:
-Stack trace:
-[ OK ] GMockOutputTest.ExplicitActionsRunOutWithDefaultAction
-[ RUN ] GMockOutputTest.CatchesLeakedMocks
-[ OK ] GMockOutputTest.CatchesLeakedMocks
-[ RUN ] GMockOutputTest.PrintsMatcher
-FILE:#: Failure
-Value of: (std::pair<int, bool>(42, true))
-Expected: is pair (first: is >= 48, second: true)
- Actual: (42, true) (of type std::pair<int, bool>)
-FILE:#: ERROR: this mock object should be deleted but never is. Its address is @0x#.
-FILE:#: ERROR: this mock object should be deleted but never is. Its address is @0x#.
-FILE:#: ERROR: this mock object should be deleted but never is. Its address is @0x#.
-ERROR: 3 leaked mock objects found at program exit. Expectations on a mock object are verified when the object is destructed. Leaking a mock means that its expectations aren't verified, which is usually a test bug. If you really intend to leak a mock, you can suppress this error using testing::Mock::AllowLeak(mock_object), or you may use a fake or stub instead of a mock.