ryan/libdpf
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update googletest to 1.18.0 and SIMDe to 0.8.2.

Browse source 
Googletest 1.18 asks for CMake 3.13 or newer, so configuring the tests no longer warns that CMake compatibility below 3.10 is deprecated.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Ryan Henry 2026-09-24 14:30:19 -06:00
parent e4e666f459
commit 3f10e05176
912 changed files with 224964 additions and 11502 deletions
Download patch file Download diff file Expand all files Collapse all files

14
test/googletest/docs/_layouts/default.html
View file

@ -7,15 +7,15 @@
{% seo %}
<link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-9PTP6FW1M5"></script>
<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-197576187-1', { 'storage': 'none' });
ga('set', 'referrer', document.referrer.split('?')[0]);
ga('set', 'location', window.location.href.split('?')[0]);
ga('set', 'anonymizeIp', true);
ga('send', 'pageview');
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-9PTP6FW1M5');
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>
</head>
<body>
<div class="sidebar">

395
test/googletest/docs/advanced.md
View file

@ -1,9 +1,9 @@
# Advanced googletest Topics
# Advanced GoogleTest Topics
## Introduction
Now that you have read the [googletest Primer](primer.md) and learned how to
write tests using googletest, it's time to learn some new tricks. This document
Now that you have read the [GoogleTest Primer](primer.md) and learned how to
write tests using GoogleTest, it's time to learn some new tricks. This document
will show you more assertions as well as how to construct complex failure
messages, propagate fatal failures, reuse and speed up your test fixtures, and
use various flags with your tests.
@ -25,7 +25,7 @@ Reference.
### Predicate Assertions for Better Error Messages
Even though googletest has a rich set of assertions, they can never be complete,
Even though GoogleTest has a rich set of assertions, they can never be complete,
as it's impossible (nor a good idea) to anticipate all scenarios a user might
run into. Therefore, sometimes a user has to use `EXPECT_TRUE()` to check a
complex expression, for lack of a better macro. This has the problem of not
@ -35,7 +35,7 @@ failure message by themselves, streaming it into `EXPECT_TRUE()`. However, this
is awkward especially when the expression has side-effects or is expensive to
evaluate.
googletest gives you three different options to solve this problem:
GoogleTest gives you three different options to solve this problem:
#### Using an Existing Boolean Function
@ -286,7 +286,7 @@ For example:
```c++
TEST(SkipTest, DoesSkip) {
GTEST_SKIP() << "Skipping single test";
EXPECT_EQ(0, 1); // Won't fail; it won't be executed
FAIL(); // Won't fail; it won't be executed
}
class SkipFixture : public ::testing::Test {
@ -298,15 +298,15 @@ class SkipFixture : public ::testing::Test {
// Tests for SkipFixture won't be executed.
TEST_F(SkipFixture, SkipsOneTest) {
EXPECT_EQ(5, 7); // Won't fail
FAIL(); // Won't fail; it won't be executed
}
```
As with assertion macros, you can stream a custom message into `GTEST_SKIP()`.
## Teaching googletest How to Print Your Values
## Teaching GoogleTest How to Print Your Values
When a test assertion such as `EXPECT_EQ` fails, googletest prints the argument
When a test assertion such as `EXPECT_EQ` fails, GoogleTest prints the argument
values to help you debug. It does this using a user-extensible value printer.
This printer knows how to print built-in C++ types, native arrays, STL
@ -315,73 +315,143 @@ prints the raw bytes in the value and hopes that you the user can figure it out.
As mentioned earlier, the printer is *extensible*. That means you can teach it
to do a better job at printing your particular type than to dump the bytes. To
do that, define `<<` for your type:
```c++
#include <ostream>
do that, define an `AbslStringify()` overload as a `friend` function template
for your type:
```cpp
namespace foo {
class Bar { // We want googletest to be able to print instances of this.
...
// Create a free inline friend function.
friend std::ostream& operator<<(std::ostream& os, const Bar& bar) {
return os << bar.DebugString(); // whatever needed to print bar to os
class Point { // We want GoogleTest to be able to print instances of this.
...
// Provide a friend overload.
template <typename Sink>
friend void AbslStringify(Sink& sink, const Point& point) {
absl::Format(&sink, "(%d, %d)", point.x, point.y);
}
int x;
int y;
};
// If you can't declare the function in the class it's important that the
// << operator is defined in the SAME namespace that defines Bar. C++'s look-up
// rules rely on that.
std::ostream& operator<<(std::ostream& os, const Bar& bar) {
return os << bar.DebugString(); // whatever needed to print bar to os
// AbslStringify overload is defined in the SAME namespace that defines Point.
// C++'s look-up rules rely on that.
enum class EnumWithStringify { kMany = 0, kChoices = 1 };
template <typename Sink>
void AbslStringify(Sink& sink, EnumWithStringify e) {
absl::Format(&sink, "%s", e == EnumWithStringify::kMany ? "Many" : "Choices");
}
} // namespace foo
```
Sometimes, this might not be an option: your team may consider it bad style to
have a `<<` operator for `Bar`, or `Bar` may already have a `<<` operator that
doesn't do what you want (and you cannot change it). If so, you can instead
define a `PrintTo()` function like this:
{: .callout .note}
Note: `AbslStringify()` utilizes a generic "sink" buffer to construct its
string. For more information about supported operations on `AbslStringify()`'s
sink, see
[the `AbslStringify()` documentation](https://abseil.io/docs/cpp/guides/abslstringify).
`AbslStringify()` can also use `absl::StrFormat`'s catch-all `%v` type specifier
within its own format strings to perform type deduction. `Point` above could be
formatted as `"(%v, %v)"` for example, and deduce the `int` values as `%d`.
Sometimes, `AbslStringify()` might not be an option: your team may wish to print
types with extra debugging information for testing purposes only. If so, you can
instead define a `PrintTo()` function like this:
```c++
#include <ostream>
namespace foo {
class Bar {
class Point {
...
friend void PrintTo(const Bar& bar, std::ostream* os) {
*os << bar.DebugString(); // whatever needed to print bar to os
friend void PrintTo(const Point& point, std::ostream* os) {
*os << "(" << point.x << "," << point.y << ")";
}
int x;
int y;
};
// If you can't declare the function in the class it's important that PrintTo()
// is defined in the SAME namespace that defines Bar. C++'s look-up rules rely
// on that.
void PrintTo(const Bar& bar, std::ostream* os) {
*os << bar.DebugString(); // whatever needed to print bar to os
// is defined in the SAME namespace that defines Point. C++'s look-up rules
// rely on that.
void PrintTo(const Point& point, std::ostream* os) {
*os << "(" << point.x << "," << point.y << ")";
}
} // namespace foo
```
If you have defined both `<<` and `PrintTo()`, the latter will be used when
googletest is concerned. This allows you to customize how the value appears in
googletest's output without affecting code that relies on the behavior of its
`<<` operator.
If you have defined both `AbslStringify()` and `PrintTo()`, the latter will be
used by GoogleTest. This allows you to customize how the value appears in
GoogleTest's output without affecting code that relies on the behavior of
`AbslStringify()`.
If you want to print a value `x` using googletest's value printer yourself, just
If you have an existing `<<` operator and would like to define an
`AbslStringify()`, the latter will be used for GoogleTest printing.
If you want to print a value `x` using GoogleTest's value printer yourself, just
call `::testing::PrintToString(x)`, which returns an `std::string`:
```c++
vector<pair<Bar, int> > bar_ints = GetBarIntVector();
vector<pair<Point, int> > point_ints = GetPointIntVector();
EXPECT_TRUE(IsCorrectBarIntVector(bar_ints))
<< "bar_ints = " << testing::PrintToString(bar_ints);
EXPECT_TRUE(IsCorrectPointIntVector(point_ints))
<< "point_ints = " << testing::PrintToString(point_ints);
```
For more details regarding `AbslStringify()` and its integration with other
libraries, see
[the documentation](https://abseil.io/docs/cpp/guides/abslstringify).
## Regular Expression Syntax
When built with Bazel and using Abseil, GoogleTest uses the
[RE2](https://github.com/google/re2/wiki/Syntax) syntax. Otherwise, for POSIX
systems (Linux, Cygwin, Mac), GoogleTest uses the
[POSIX extended regular expression](https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04)
syntax. To learn about POSIX syntax, you may want to read this
[Wikipedia entry](https://en.wikipedia.org/wiki/Regular_expression#POSIX_extended).
On Windows, GoogleTest uses its own simple regular expression implementation. It
lacks many features. For example, we don't support union (`"x|y"`), grouping
(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among
others. Below is what we do support (`A` denotes a literal character, period
(`.`), or a single `\\ ` escape sequence; `x` and `y` denote regular
expressions.):
Expression | Meaning
---------- | --------------------------------------------------------------
`c` | matches any literal character `c`
`\\d` | matches any decimal digit
`\\D` | matches any character that's not a decimal digit
`\\f` | matches `\f`
`\\n` | matches `\n`
`\\r` | matches `\r`
`\\s` | matches any ASCII whitespace, including `\n`
`\\S` | matches any character that's not a whitespace
`\\t` | matches `\t`
`\\v` | matches `\v`
`\\w` | matches any letter, `_`, or decimal digit
`\\W` | matches any character that `\\w` doesn't match
`\\c` | matches any literal character `c`, which must be a punctuation
`.` | matches any single character except `\n`
`A?` | matches 0 or 1 occurrences of `A`
`A*` | matches 0 or many occurrences of `A`
`A+` | matches 1 or many occurrences of `A`
`^` | matches the beginning of a string (not that of each line)
`$` | matches the end of a string (not that of each line)
`xy` | matches `x` followed by `y`
To help you determine which capability is available on your system, GoogleTest
defines macros to govern which regular expression it is using. The macros are:
`GTEST_USES_SIMPLE_RE=1` or `GTEST_USES_POSIX_RE=1`. If you want your death
tests to work in all cases, you can either `#if` on these macros or use the more
limited syntax only.
## Death Tests
In many applications, there are assertions that can cause application failure if
@ -393,7 +463,7 @@ corruption, security holes, or worse. Hence it is vitally important to test that
such assertion statements work as expected.
Since these precondition checks cause the processes to die, we call such tests
_death tests_. More generally, any test that checks that a program terminates
*death tests*. More generally, any test that checks that a program terminates
(except by throwing an exception) in an expected fashion is also a death test.
Note that if a piece of code throws an exception, we don't consider it "death"
@ -439,6 +509,12 @@ verifies that:
exit with exit code 0, and
* calling `KillProcess()` kills the process with signal `SIGKILL`.
{: .callout .warning}
Warning: If your death test contains mocks and is expecting a specific exit
code, then you must allow the mock objects to be leaked via `Mock::AllowLeak`.
This is because the mock leak detector will exit with its own error code if it
detects a leak.
The test function body may contain other assertions and statements as well, if
necessary.
@ -451,7 +527,7 @@ Note that a death test only cares about three things:
3. does the stderr output match `matcher`?
In particular, if `statement` generates an `ASSERT_*` or `EXPECT_*` failure, it
will **not** cause the death test to fail, as googletest assertions don't abort
will **not** cause the death test to fail, as GoogleTest assertions don't abort
the process.
### Death Test Naming
@ -480,51 +556,6 @@ TEST_F(FooDeathTest, DoesThat) {
}
```
### Regular Expression Syntax
When built with Bazel and using Abseil, googletest uses the
[RE2](https://github.com/google/re2/wiki/Syntax) syntax. Otherwise, for POSIX
systems (Linux, Cygwin, Mac), googletest uses the
[POSIX extended regular expression](http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04)
syntax. To learn about POSIX syntax, you may want to read this
[Wikipedia entry](http://en.wikipedia.org/wiki/Regular_expression#POSIX_extended).
On Windows, googletest uses its own simple regular expression implementation. It
lacks many features. For example, we don't support union (`"x|y"`), grouping
(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among
others. Below is what we do support (`A` denotes a literal character, period
(`.`), or a single `\\ ` escape sequence; `x` and `y` denote regular
expressions.):
Expression | Meaning
---------- | --------------------------------------------------------------
`c` | matches any literal character `c`
`\\d` | matches any decimal digit
`\\D` | matches any character that's not a decimal digit
`\\f` | matches `\f`
`\\n` | matches `\n`
`\\r` | matches `\r`
`\\s` | matches any ASCII whitespace, including `\n`
`\\S` | matches any character that's not a whitespace
`\\t` | matches `\t`
`\\v` | matches `\v`
`\\w` | matches any letter, `_`, or decimal digit
`\\W` | matches any character that `\\w` doesn't match
`\\c` | matches any literal character `c`, which must be a punctuation
`.` | matches any single character except `\n`
`A?` | matches 0 or 1 occurrences of `A`
`A*` | matches 0 or many occurrences of `A`
`A+` | matches 1 or many occurrences of `A`
`^` | matches the beginning of a string (not that of each line)
`$` | matches the end of a string (not that of each line)
`xy` | matches `x` followed by `y`
To help you determine which capability is available on your system, googletest
defines macros to govern which regular expression it is using. The macros are:
`GTEST_USES_SIMPLE_RE=1` or `GTEST_USES_POSIX_RE=1`. If you want your death
tests to work in all cases, you can either `#if` on these macros or use the more
limited syntax only.
### How It Works
See [Death Assertions](reference/assertions.md#death) in the Assertions
@ -539,7 +570,7 @@ arrange that kind of environment. For example, statically-initialized modules
may start threads before main is ever reached. Once threads have been created,
it may be difficult or impossible to clean them up.
googletest has three features intended to raise awareness of threading issues.
GoogleTest has three features intended to raise awareness of threading issues.
1. A warning is emitted if multiple threads are running when a death test is
encountered.
@ -592,7 +623,7 @@ TEST(MyDeathTest, TestTwo) {
The `statement` argument of `ASSERT_EXIT()` can be any valid C++ statement. If
it leaves the current function via a `return` statement or by throwing an
exception, the death test is considered to have failed. Some googletest macros
exception, the death test is considered to have failed. Some GoogleTest macros
may return from the current function (e.g. `ASSERT_TRUE()`), so be sure to avoid
them in `statement`.
@ -704,7 +735,7 @@ Some tips on using `SCOPED_TRACE`:
### Propagating Fatal Failures
A common pitfall when using `ASSERT_*` and `FAIL*` is not understanding that
when they fail they only abort the _current function_, not the entire test. For
when they fail they only abort the *current function*, not the entire test. For
example, the following test will segfault:
```c++
@ -726,7 +757,7 @@ TEST(FooTest, Bar) {
}
```
To alleviate this, googletest provides three different solutions. You could use
To alleviate this, GoogleTest provides three different solutions. You could use
either exceptions, the `(ASSERT|EXPECT)_NO_FATAL_FAILURE` assertions or the
`HasFatalFailure()` function. They are described in the following two
subsections.
@ -760,7 +791,7 @@ in it, the test will continue after the subroutine returns. This may not be what
you want.
Often people want fatal failures to propagate like exceptions. For that
googletest offers the following macros:
GoogleTest offers the following macros:
Fatal assertion | Nonfatal assertion | Verifies
------------------------------------- | ------------------------------------- | --------
@ -852,7 +883,7 @@ will output XML like this:
> needs to be prefixed with `::testing::Test::` if used outside of the
> `TEST` body and the test fixture class.
> * *`key`* must be a valid XML attribute name, and cannot conflict with the
> ones already used by googletest (`name`, `status`, `time`, `classname`,
> ones already used by GoogleTest (`name`, `status`, `time`, `classname`,
> `type_param`, and `value_param`).
> * Calling `RecordProperty()` outside of the lifespan of a test is allowed.
> If it's called outside of a test but between a test suite's
@ -863,25 +894,25 @@ will output XML like this:
## Sharing Resources Between Tests in the Same Test Suite
googletest creates a new test fixture object for each test in order to make
GoogleTest creates a new test fixture object for each test in order to make
tests independent and easier to debug. However, sometimes tests use resources
that are expensive to set up, making the one-copy-per-test model prohibitively
expensive.
If the tests don't change the resource, there's no harm in their sharing a
single resource copy. So, in addition to per-test set-up/tear-down, googletest
single resource copy. So, in addition to per-test set-up/tear-down, GoogleTest
also supports per-test-suite set-up/tear-down. To use it:
1. In your test fixture class (say `FooTest` ), declare as `static` some member
variables to hold the shared resources.
2. Outside your test fixture class (typically just below it), define those
member variables, optionally giving them initial values.
3. In the same test fixture class, define a `static void SetUpTestSuite()`
function (remember not to spell it as **`SetupTestSuite`** with a small
`u`!) to set up the shared resources and a `static void TearDownTestSuite()`
function to tear them down.
3. In the same test fixture class, define a public member function `static void
SetUpTestSuite()` (remember not to spell it as **`SetupTestSuite`** with a
small `u`!) to set up the shared resources and a `static void
TearDownTestSuite()` function to tear them down.
That's it! googletest automatically calls `SetUpTestSuite()` before running the
That's it! GoogleTest automatically calls `SetUpTestSuite()` before running the
*first test* in the `FooTest` test suite (i.e. before creating the first
`FooTest` object), and calls `TearDownTestSuite()` after running the *last test*
in it (i.e. after deleting the last `FooTest` object). In between, the tests can
@ -974,24 +1005,34 @@ class Environment : public ::testing::Environment {
};
```
Then, you register an instance of your environment class with googletest by
Then, you register an instance of your environment class with GoogleTest by
calling the `::testing::AddGlobalTestEnvironment()` function:
```c++
Environment* AddGlobalTestEnvironment(Environment* env);
```
Now, when `RUN_ALL_TESTS()` is called, it first calls the `SetUp()` method of
each environment object, then runs the tests if none of the environments
reported fatal failures and `GTEST_SKIP()` was not called. `RUN_ALL_TESTS()`
always calls `TearDown()` with each environment object, regardless of whether or
not the tests were run.
Now, when `RUN_ALL_TESTS()` is invoked, it first calls the `SetUp()` method. The
tests are then executed, provided that none of the environments have reported
fatal failures and `GTEST_SKIP()` has not been invoked. Finally, `TearDown()` is
called.
Note that `SetUp()` and `TearDown()` are only invoked if there is at least one
test to be performed. Importantly, `TearDown()` is executed even if the test is
not run due to a fatal failure or `GTEST_SKIP()`.
Calling `SetUp()` and `TearDown()` for each iteration depends on the flag
`gtest_recreate_environments_when_repeating`. `SetUp()` and `TearDown()` are
called for each environment object when the object is recreated for each
iteration. However, if test environments are not recreated for each iteration,
`SetUp()` is called only on the first iteration, and `TearDown()` is called only
on the last iteration.
It's OK to register multiple environment objects. In this suite, their `SetUp()`
will be called in the order they are registered, and their `TearDown()` will be
called in the reverse order.
Note that googletest takes ownership of the registered environment objects.
Note that GoogleTest takes ownership of the registered environment objects.
Therefore **do not delete them** by yourself.
You should call `AddGlobalTestEnvironment()` before `RUN_ALL_TESTS()` is called,
@ -1043,7 +1084,7 @@ they must be declared **public** rather than **protected** in order to use
```c++
class FooTest :
public testing::TestWithParam<const char*> {
public testing::TestWithParam<absl::string_view> {
// You can implement all the usual fixture class members here.
// To access the test parameter, call GetParam() from class
// TestWithParam<T>.
@ -1054,7 +1095,7 @@ class BaseTest : public testing::Test {
...
};
class BarTest : public BaseTest,
public testing::WithParamInterface<const char*> {
public testing::WithParamInterface<absl::string_view> {
...
};
```
@ -1125,8 +1166,8 @@ with parameter values `"cat"` and `"dog"` using the
[`ValuesIn`](reference/testing.md#param-generators) parameter generator:
```c++
const char* pets[] = {"cat", "dog"};
INSTANTIATE_TEST_SUITE_P(Pets, FooTest, testing::ValuesIn(pets));
constexpr absl::string_view kPets[] = {"cat", "dog"};
INSTANTIATE_TEST_SUITE_P(Pets, FooTest, testing::ValuesIn(kPets));
```
The tests from the instantiation above will have these names:
@ -1409,17 +1450,19 @@ are two cases to consider:
To test them, we use the following special techniques:
* Both static functions and definitions/declarations in an unnamed namespace
are only visible within the same translation unit. To test them, you can
`#include` the entire `.cc` file being tested in your `*_test.cc` file.
(#including `.cc` files is not a good way to reuse code - you should not do
this in production code!)
are only visible within the same translation unit. To test them, move the
private code into the `foo::internal` namespace, where `foo` is the
namespace your project normally uses, and put the private declarations in a
`*-internal.h` file. Your production `.cc` files and your tests are allowed
to include this internal header, but your clients are not. This way, you can
fully test your internal implementation without leaking it to your clients.
However, a better approach is to move the private code into the
`foo::internal` namespace, where `foo` is the namespace your project
normally uses, and put the private declarations in a `*-internal.h` file.
Your production `.cc` files and your tests are allowed to include this
internal header, but your clients are not. This way, you can fully test your
internal implementation without leaking it to your clients.
{: .callout .note}
NOTE: It is also technically *possible* to `#include` the entire `.cc` file
being tested in your `*_test.cc` file to test static functions and
definitions/declarations in an unnamed namespace. However, this technique is
**not recommended** by this documentation and it is only presented here for the
sake of completeness.
* Private class members are only accessible from within the class or by
friends. To access a class' private members, you can declare your test
@ -1432,10 +1475,7 @@ To test them, we use the following special techniques:
Another way to test private members is to refactor them into an
implementation class, which is then declared in a `*-internal.h` file. Your
clients aren't allowed to include this header but your tests can. Such is
called the
[Pimpl](https://www.gamedev.net/articles/programming/general-and-gameplay-programming/the-c-pimpl-r1794/)
(Private Implementation) idiom.
clients aren't allowed to include this header but your tests can.
Or, you can declare an individual test as a friend of your class by adding
this line in the class body:
@ -1501,12 +1541,12 @@ To test them, we use the following special techniques:
## "Catching" Failures
If you are building a testing utility on top of googletest, you'll want to test
your utility. What framework would you use to test it? googletest, of course.
If you are building a testing utility on top of GoogleTest, you'll want to test
your utility. What framework would you use to test it? GoogleTest, of course.
The challenge is to verify that your testing utility reports failures correctly.
In frameworks that report a failure by throwing an exception, you could catch
the exception and assert on it. But googletest doesn't use exceptions, so how do
the exception and assert on it. But GoogleTest doesn't use exceptions, so how do
we test that a piece of code generates an expected failure?
`"gtest/gtest-spi.h"` contains some constructs to do this.
@ -1649,9 +1689,9 @@ particular, you cannot find the test suite name in `SetUpTestSuite()`,
`TearDownTestSuite()` (where you know the test suite name implicitly), or
functions called from them.
## Extending googletest by Handling Test Events
## Extending GoogleTest by Handling Test Events
googletest provides an **event listener API** to let you receive notifications
GoogleTest provides an **event listener API** to let you receive notifications
about the progress of a test program and test failures. The events you can
listen to include the start and end of the test program, a test suite, or a test
method, among others. You may use this API to augment or replace the standard
@ -1712,7 +1752,7 @@ Here's an example:
### Using Event Listeners
To use the event listener you have defined, add an instance of it to the
googletest event listener list (represented by class
GoogleTest event listener list (represented by class
[`TestEventListeners`](reference/testing.md#TestEventListeners) - note the "s"
at the end of the name) in your `main()` function, before calling
`RUN_ALL_TESTS()`:
@ -1723,7 +1763,7 @@ int main(int argc, char** argv) {
// Gets hold of the event listener list.
testing::TestEventListeners& listeners =
testing::UnitTest::GetInstance()->listeners();
// Adds a listener to the end. googletest takes the ownership.
// Adds a listener to the end. GoogleTest takes the ownership.
listeners.Append(new MinimalistPrinter);
return RUN_ALL_TESTS();
}
@ -1775,13 +1815,13 @@ See [sample10_unittest.cc] for an example of a failure-raising listener.
## Running Test Programs: Advanced Options
googletest test programs are ordinary executables. Once built, you can run them
GoogleTest test programs are ordinary executables. Once built, you can run them
directly and affect their behavior via the following environment variables
and/or command line flags. For the flags to work, your programs must call
`::testing::InitGoogleTest()` before calling `RUN_ALL_TESTS()`.
To see a list of supported flags and their usage, please run your test program
with the `--help` flag. You can also use `-h`, `-?`, or `/?` for short.
with the `--help` flag.
If an option is specified both by an environment variable and by a flag, the
latter takes precedence.
@ -1808,10 +1848,10 @@ corresponding environment variable for this flag.
#### Running a Subset of the Tests
By default, a googletest program runs all tests the user has defined. Sometimes,
By default, a GoogleTest program runs all tests the user has defined. Sometimes,
you want to run only a subset of the tests (e.g. for debugging or quickly
verifying a change). If you set the `GTEST_FILTER` environment variable or the
`--gtest_filter` flag to a filter string, googletest will only run the tests
`--gtest_filter` flag to a filter string, GoogleTest will only run the tests
whose full names (in the form of `TestSuiteName.TestName`) match the filter.
The format of a filter is a '`:`'-separated list of wildcard patterns (called
@ -1842,7 +1882,7 @@ For example:
#### Stop test execution upon first failure
By default, a googletest program runs all tests the user has defined. In some
By default, a GoogleTest program runs all tests the user has defined. In some
cases (e.g. iterative test development & execution) it may be desirable stop
test execution upon first failure (trading improved latency for completeness).
If `GTEST_FAIL_FAST` environment variable or `--gtest_fail_fast` flag is set,
@ -1859,7 +1899,7 @@ If you need to disable all tests in a test suite, you can either add `DISABLED_`
to the front of the name of each test, or alternatively add it to the front of
the test suite name.
For example, the following tests won't be run by googletest, even though they
For example, the following tests won't be run by GoogleTest, even though they
will still be compiled:
```c++
@ -1874,7 +1914,7 @@ TEST_F(DISABLED_BarTest, DoesXyz) { ... }
{: .callout .note}
NOTE: This feature should only be used for temporary pain-relief. You still have
to fix the disabled tests at a later date. As a reminder, googletest will print
to fix the disabled tests at a later date. As a reminder, GoogleTest will print
a banner warning you if a test program contains any disabled tests.
{: .callout .tip}
@ -1890,6 +1930,35 @@ the `--gtest_also_run_disabled_tests` flag or set the
You can combine this with the `--gtest_filter` flag to further select which
disabled tests to run.
### Enforcing Having At Least One Test Case
A not uncommon programmer mistake is to write a test program that has no test
case linked in. This can happen, for example, when you put test case definitions
in a library and the library is not marked as "always link".
To catch such mistakes, run the test program with the
`--gtest_fail_if_no_test_linked` flag or set the `GTEST_FAIL_IF_NO_TEST_LINKED`
environment variable to a value other than `0`. Now the program will fail if no
test case is linked in.
Note that *any* test case linked in makes the program valid for the purpose of
this check. In particular, even a disabled test case suffices.
### Enforcing Running At Least One Test Case
In addition to enforcing that tests are defined in the binary with
`--gtest_fail_if_no_test_linked`, it is also possible to enforce that a test
case was actually executed to ensure that resources are not consumed by tests
that do nothing.
To catch such optimization opportunities, run the test program with the
`--gtest_fail_if_no_test_selected` flag or set the
`GTEST_FAIL_IF_NO_TEST_SELECTED` environment variable to a value other than `0`.
A test is considered selected if it begins to run, even if it is later skipped
via `GTEST_SKIP`. Thus, `DISABLED` tests do not count as selected and neither do
tests that are not matched by `--gtest_filter`.
### Repeating the Tests
Once in a while you'll run into a test whose result is hit-or-miss. Perhaps it
@ -1932,16 +2001,16 @@ You can specify the `--gtest_shuffle` flag (or set the `GTEST_SHUFFLE`
environment variable to `1`) to run the tests in a program in a random order.
This helps to reveal bad dependencies between tests.
By default, googletest uses a random seed calculated from the current time.
By default, GoogleTest uses a random seed calculated from the current time.
Therefore you'll get a different order every time. The console output includes
the random seed value, such that you can reproduce an order-related test failure
later. To specify the random seed explicitly, use the `--gtest_random_seed=SEED`
flag (or set the `GTEST_RANDOM_SEED` environment variable), where `SEED` is an
integer in the range [0, 99999]. The seed value 0 is special: it tells
googletest to do the default behavior of calculating the seed from the current
GoogleTest to do the default behavior of calculating the seed from the current
time.
If you combine this with `--gtest_repeat=N`, googletest will pick a different
If you combine this with `--gtest_repeat=N`, GoogleTest will pick a different
random seed and re-shuffle the tests in each iteration.
### Distributing Test Functions to Multiple Machines
@ -2000,7 +2069,7 @@ shards, but here's one possible scenario:
#### Colored Terminal Output
googletest can use colors in its terminal output to make it easier to spot the
GoogleTest can use colors in its terminal output to make it easier to spot the
important information:
<pre>...
@ -2025,25 +2094,25 @@ important information:
You can set the `GTEST_COLOR` environment variable or the `--gtest_color`
command line flag to `yes`, `no`, or `auto` (the default) to enable colors,
disable colors, or let googletest decide. When the value is `auto`, googletest
disable colors, or let GoogleTest decide. When the value is `auto`, GoogleTest
will use colors if and only if the output goes to a terminal and (on non-Windows
platforms) the `TERM` environment variable is set to `xterm` or `xterm-color`.
#### Suppressing test passes
By default, googletest prints 1 line of output for each test, indicating if it
By default, GoogleTest prints 1 line of output for each test, indicating if it
passed or failed. To show only test failures, run the test program with
`--gtest_brief=1`, or set the GTEST_BRIEF environment variable to `1`.
#### Suppressing the Elapsed Time
By default, googletest prints the time it takes to run each test. To disable
By default, GoogleTest prints the time it takes to run each test. To disable
that, run the test program with the `--gtest_print_time=0` command line flag, or
set the GTEST_PRINT_TIME environment variable to `0`.
#### Suppressing UTF-8 Text Output
In case of assertion failures, googletest prints expected and actual values of
In case of assertion failures, GoogleTest prints expected and actual values of
type `string` both as hex-encoded strings as well as in readable UTF-8 text if
they contain valid non-ASCII UTF-8 characters. If you want to suppress the UTF-8
text because, for example, you don't have an UTF-8 compatible output medium, run
@ -2052,7 +2121,7 @@ environment variable to `0`.
#### Generating an XML Report
googletest can emit a detailed XML report to a file in addition to its normal
GoogleTest can emit a detailed XML report to a file in addition to its normal
textual output. The report contains the duration of each test, and thus can help
you identify slow tests.
@ -2063,15 +2132,15 @@ in which case the output can be found in the `test_detail.xml` file in the
current directory.
If you specify a directory (for example, `"xml:output/directory/"` on Linux or
`"xml:output\directory\"` on Windows), googletest will create the XML file in
`"xml:output\directory\"` on Windows), GoogleTest will create the XML file in
that directory, named after the test executable (e.g. `foo_test.xml` for test
program `foo_test` or `foo_test.exe`). If the file already exists (perhaps left
over from a previous run), googletest will pick a different name (e.g.
over from a previous run), GoogleTest will pick a different name (e.g.
`foo_test_1.xml`) to avoid overwriting it.
The report is based on the `junitreport` Ant task. Since that format was
originally intended for Java, a little interpretation is required to make it
apply to googletest tests, as shown here:
apply to GoogleTest tests, as shown here:
```xml
<testsuites name="AllTests" ...>
@ -2086,8 +2155,8 @@ apply to googletest tests, as shown here:
```
* The root `<testsuites>` element corresponds to the entire test program.
* `<testsuite>` elements correspond to googletest test suites.
* `<testcase>` elements correspond to googletest test functions.
* `<testsuite>` elements correspond to GoogleTest test suites.
* `<testcase>` elements correspond to GoogleTest test functions.
For instance, the following program
@ -2120,7 +2189,7 @@ could generate this report:
Things to note:
* The `tests` attribute of a `<testsuites>` or `<testsuite>` element tells how
many test functions the googletest program or test suite contains, while the
many test functions the GoogleTest program or test suite contains, while the
`failures` attribute tells how many of them failed.
* The `time` attribute expresses the duration of the test, test suite, or
@ -2132,12 +2201,12 @@ Things to note:
* The `file` and `line` attributes record the source file location, where the
test was defined.
* Each `<failure>` element corresponds to a single failed googletest
* Each `<failure>` element corresponds to a single failed GoogleTest
assertion.
#### Generating a JSON Report
googletest can also emit a JSON report as an alternative format to XML. To
GoogleTest can also emit a JSON report as an alternative format to XML. To
generate the JSON report, set the `GTEST_OUTPUT` environment variable or the
`--gtest_output` flag to the string `"json:path_to_output_file"`, which will
create the file at the given location. You can also just use the string
@ -2148,7 +2217,7 @@ The report format conforms to the following JSON Schema:
```json
{
"$schema": "http://json-schema.org/schema#",
"$schema": "https://json-schema.org/schema#",
"type": "object",
"definitions": {
"TestCase": {
@ -2349,7 +2418,7 @@ IMPORTANT: The exact format of the JSON document is subject to change.
#### Detecting Test Premature Exit
Google Test implements the _premature-exit-file_ protocol for test runners to
Google Test implements the *premature-exit-file* protocol for test runners to
catch any kind of unexpected exits of test programs. Upon start, Google Test
creates the file which will be automatically deleted after all work has been
finished. Then, the test runner can check if this file exists. In case the file
@ -2362,7 +2431,7 @@ variable has been set.
When running test programs under a debugger, it's very convenient if the
debugger can catch an assertion failure and automatically drop into interactive
mode. googletest's *break-on-failure* mode supports this behavior.
mode. GoogleTest's *break-on-failure* mode supports this behavior.
To enable it, set the `GTEST_BREAK_ON_FAILURE` environment variable to a value
other than `0`. Alternatively, you can use the `--gtest_break_on_failure`
@ -2370,9 +2439,9 @@ command line flag.
#### Disabling Catching Test-Thrown Exceptions
googletest can be used either with or without exceptions enabled. If a test
GoogleTest can be used either with or without exceptions enabled. If a test
throws a C++ exception or (on Windows) a structured exception (SEH), by default
googletest catches it, reports it as a test failure, and continues with the next
GoogleTest catches it, reports it as a test failure, and continues with the next
test method. This maximizes the coverage of a test run. Also, on Windows an
uncaught exception will cause a pop-up window, so catching the exceptions allows
you to run the tests automatically.
@ -2410,4 +2479,4 @@ void __tsan_on_report() {
```
After compiling your project with one of the sanitizers enabled, if a particular
test triggers a sanitizer error, googletest will report that it failed.
test triggers a sanitizer error, GoogleTest will report that it failed.

70
test/googletest/docs/faq.md
View file

@ -3,7 +3,7 @@
## Why should test suite names and test names not contain underscore?
{: .callout .note}
Note: GoogleTest reserves underscore (`_`) for special purpose keywords, such as
Note: GoogleTest reserves underscore (`_`) for special-purpose keywords, such as
[the `DISABLED_` prefix](advanced.md#temporarily-disabling-tests), in addition
to the following rationale.
@ -33,9 +33,9 @@ contains `_`?
`TestSuiteName_Bar__Test`, which is invalid.
So clearly `TestSuiteName` and `TestName` cannot start or end with `_`
(Actually, `TestSuiteName` can start with `_` -- as long as the `_` isn't
followed by an upper-case letter. But that's getting complicated. So for
simplicity we just say that it cannot start with `_`.).
(Actually, `TestSuiteName` can start with `_`—as long as the `_` isn't followed
by an upper-case letter. But that's getting complicated. So for simplicity we
just say that it cannot start with `_`.).
It may seem fine for `TestSuiteName` and `TestName` to contain `_` in the
middle. However, consider this:
@ -128,30 +128,9 @@ 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
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
@ -192,16 +171,16 @@ class Foo {
};
```
You also need to define it *outside* of the class body in `foo.cc`:
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. :-)
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
@ -311,7 +290,7 @@ 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()`.
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
@ -352,7 +331,7 @@ You may still want to use `SetUp()/TearDown()` in the following cases:
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?
## 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.
@ -410,7 +389,7 @@ 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.
## 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
@ -532,20 +511,7 @@ However, there are cases where you have to define your own:
list of the constructor. (Early versions of `gcc` doesn't force you to
initialize the const member. It's a bug that has been fixed in `gcc 4`.)
## Why does ASSERT_DEATH complain about previous threads that were already joined?
With the Linux pthread library, there is no turning back once you cross the line
from a single thread to multiple threads. The first time you create a thread, a
manager thread is created in addition, so you get 3, not 2, threads. Later when
the thread you create joins the main thread, the thread count decrements by 1,
but the manager thread will never be killed, so you still have 2 threads, which
means you cannot safely run a death test.
The new NPTL thread library doesn't suffer from this problem, as it doesn't
create a manager thread. However, if you don't control which machine your test
runs on, you shouldn't depend on this.
## Why does GoogleTest require the entire test suite, instead of individual tests, to be named *DeathTest when it uses ASSERT_DEATH?
## Why does GoogleTest require the entire test suite, instead of individual tests, to be named `*DeathTest` when it uses `ASSERT_DEATH`?
GoogleTest does not interleave tests from different test suites. That is, it
runs all tests in one test suite first, and then runs all tests in the next test
@ -570,7 +536,7 @@ interleave tests from different test suites, we need to run all tests in the
`FooTest` case before running any test in the `BarTest` case. This contradicts
with the requirement to run `BarTest.DefDeathTest` before `FooTest.Uvw`.
## But I don't like calling my entire test suite \*DeathTest when it contains both death tests and non-death tests. What do I do?
## But I don't like calling my entire test suite `*DeathTest` when it contains both death tests and non-death tests. What do I do?
You don't have to, but if you like, you may split up the test suite into
`FooTest` and `FooDeathTest`, where the names make it clear that they are
@ -607,7 +573,7 @@ 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.
[Tip of the Week #49](https://abseil.io/tips/49) for details.
## How do I suppress the memory leak messages on Windows?
@ -628,10 +594,10 @@ mistake in production. Such cleverness also leads to
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
test is [Dependency Injection](https://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
[`testonly`](https://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
@ -654,7 +620,7 @@ the `--gtest_also_run_disabled_tests` flag.
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
class**. This means that the following is **allowed** because both tests use the
same fixture class (`::testing::Test`).
```c++

6
test/googletest/docs/gmock_cheat_sheet.md
View file

@ -20,7 +20,7 @@ class Foo {
(note that `~Foo()` **must** be virtual) we can define its mock as
```cpp
#include "gmock/gmock.h"
#include <gmock/gmock.h>
class MockFoo : public Foo {
public:
@ -130,7 +130,7 @@ TEST(BarTest, DoesThis) {
## Setting Default Actions {#OnCall}
gMock has a **built-in default action** for any function that returns `void`,
`bool`, a numeric value, or a pointer. In C++11, it will additionally returns
`bool`, a numeric value, or a pointer. In C++11, it additionally returns
the default-constructed value, if one exists for the given type.
To customize the default action for functions with return type `T`, use
@ -153,7 +153,7 @@ To customize the default action for functions with return type `T`, use
EXPECT_NE(buzz1, buzz2);
// Resets the default action for return type std::unique_ptr<Buzz>,
// to avoid interfere with other tests.
// to avoid interfering with other tests.
DefaultValue<std::unique_ptr<Buzz>>::Clear();
```

240
test/googletest/docs/gmock_cook_book.md
View file

@ -177,7 +177,7 @@ class StackInterface {
template <typename Elem>
class MockStack : public StackInterface<Elem> {
...
MOCK_METHOD(int, GetSize, (), (override));
MOCK_METHOD(int, GetSize, (), (const, override));
MOCK_METHOD(void, Push, (const Elem& x), (override));
};
```
@ -697,9 +697,9 @@ TEST(AbcTest, Xyz) {
EXPECT_CALL(foo, DoThat(_, _));
int n = 0;
EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked.
EXPECT_EQ(foo.DoThis(5), '+'); // FakeFoo::DoThis() is invoked.
foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked.
EXPECT_EQ(2, n);
EXPECT_EQ(n, 2);
}
```
@ -900,15 +900,16 @@ using ::testing::Not;
Matchers are function objects, and parametrized matchers can be composed just
like any other function. However because their types can be long and rarely
provide meaningful information, it can be easier to express them with C++14
generic lambdas to avoid specifying types. For example,
provide meaningful information, it can be easier to express them with template
parameters and `auto`. For example,
```cpp
using ::testing::Contains;
using ::testing::Property;
inline constexpr auto HasFoo = [](const auto& f) {
return Property("foo", &MyClass::foo, Contains(f));
template <typename SubMatcher>
inline constexpr auto HasFoo(const SubMatcher& sub_matcher) {
return Property("foo", &MyClass::foo, Contains(sub_matcher));
};
...
EXPECT_THAT(x, HasFoo("blah"));
@ -936,8 +937,8 @@ casts a matcher `m` to type `Matcher<T>`. To ensure safety, gMock checks that
floating-point numbers), the conversion from `T` to `U` is not lossy (in
other words, any value representable by `T` can also be represented by `U`);
and
3. When `U` is a reference, `T` must also be a reference (as the underlying
matcher may be interested in the address of the `U` value).
3. When `U` is a non-const reference, `T` must also be a reference (as the
underlying matcher may be interested in the address of the `U` value).
The code won't compile if any of these conditions isn't met.
@ -1129,11 +1130,11 @@ using STL's `<functional>` header is just painful). For example, here's a
predicate that's satisfied by any number that is >= 0, <= 100, and != 50:
```cpp
using testing::AllOf;
using testing::Ge;
using testing::Le;
using testing::Matches;
using testing::Ne;
using ::testing::AllOf;
using ::testing::Ge;
using ::testing::Le;
using ::testing::Matches;
using ::testing::Ne;
...
Matches(AllOf(Ge(0), Le(100), Ne(50)))
```
@ -1861,7 +1862,7 @@ error. So, what shall you do?
Though you may be tempted, DO NOT use `std::ref()`:
```cpp
using testing::Return;
using ::testing::Return;
class MockFoo : public Foo {
public:
@ -1873,7 +1874,7 @@ class MockFoo : public Foo {
EXPECT_CALL(foo, GetValue())
.WillRepeatedly(Return(std::ref(x))); // Wrong!
x = 42;
EXPECT_EQ(42, foo.GetValue());
EXPECT_EQ(foo.GetValue(), 42);
```
Unfortunately, it doesn't work here. The above code will fail with error:
@ -1895,14 +1896,14 @@ the expectation is set, and `Return(std::ref(x))` will always return 0.
returns the value pointed to by `pointer` at the time the action is *executed*:
```cpp
using testing::ReturnPointee;
using ::testing::ReturnPointee;
...
int x = 0;
MockFoo foo;
EXPECT_CALL(foo, GetValue())
.WillRepeatedly(ReturnPointee(&x)); // Note the & here.
x = 42;
EXPECT_EQ(42, foo.GetValue()); // This will succeed now.
EXPECT_EQ(foo.GetValue(), 42); // This will succeed now.
```
### Combining Actions
@ -1927,6 +1928,12 @@ class MockFoo : public Foo {
action_n));
```
The return value of the last action **must** match the return type of the mocked
method. In the example above, `action_n` could be `Return(true)`, or a lambda
that returns a `bool`, but not `SaveArg`, which returns `void`. Otherwise the
signature of `DoAll` would not match the signature expected by `WillOnce`, which
is the signature of the mocked method, and it wouldn't compile.
### Verifying Complex Arguments {#SaveArgVerify}
If you want to verify that a method is called with a particular argument but the
@ -2264,7 +2271,7 @@ TEST_F(FooTest, Test) {
EXPECT_CALL(foo, DoThis(2))
.WillOnce(Invoke(NewPermanentCallback(SignOfSum, 5)));
EXPECT_EQ('+', foo.DoThis(2)); // Invokes SignOfSum(5, 2).
EXPECT_EQ(foo.DoThis(2), '+'); // Invokes SignOfSum(5, 2).
}
```
@ -2640,8 +2647,8 @@ action will exhibit different behaviors. Example:
.WillRepeatedly(IncrementCounter(0));
foo.DoThis(); // Returns 1.
foo.DoThis(); // Returns 2.
foo.DoThat(); // Returns 1 - Blah() uses a different
// counter than Bar()'s.
foo.DoThat(); // Returns 1 - DoThat() uses a different
// counter than DoThis()'s.
```
versus
@ -2771,36 +2778,33 @@ returns a null `unique_ptr`, that’s what you’ll get if you don’t specify a
action:
```cpp
using ::testing::IsNull;
...
// Use the default action.
EXPECT_CALL(mock_buzzer_, MakeBuzz("hello"));
// Triggers the previous EXPECT_CALL.
EXPECT_EQ(nullptr, mock_buzzer_.MakeBuzz("hello"));
EXPECT_THAT(mock_buzzer_.MakeBuzz("hello"), IsNull());
```
If you are not happy with the default action, you can tweak it as usual; see
[Setting Default Actions](#OnCall).
If you just need to return a pre-defined move-only value, you can use the
`Return(ByMove(...))` action:
If you just need to return a move-only value, you can use it in combination with
`WillOnce`. For example:
```cpp
// When this fires, the unique_ptr<> specified by ByMove(...) will
// be returned.
EXPECT_CALL(mock_buzzer_, MakeBuzz("world"))
.WillOnce(Return(ByMove(std::make_unique<Buzz>(AccessLevel::kInternal))));
EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("world"));
EXPECT_CALL(mock_buzzer_, MakeBuzz("hello"))
.WillOnce(Return(std::make_unique<Buzz>(AccessLevel::kInternal)));
EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("hello"));
```
Note that `ByMove()` is essential here - if you drop it, the code won’t compile.
Quiz time! What do you think will happen if a `Return(ByMove(...))` action is
performed more than once (e.g. you write `...
.WillRepeatedly(Return(ByMove(...)));`)? Come think of it, after the first time
the action runs, the source value will be consumed (since it’s a move-only
value), so the next time around, there’s no value to move from -- you’ll get a
run-time error that `Return(ByMove(...))` can only be run once.
Quiz time! What do you think will happen if a `Return` action is performed more
than once (e.g. you write `... .WillRepeatedly(Return(std::move(...)));`)? Come
think of it, after the first time the action runs, the source value will be
consumed (since it’s a move-only value), so the next time around, there’s no
value to move from -- you’ll get a run-time error that `Return(std::move(...))`
can only be run once.
If you need your mock method to do more than just moving a pre-defined value,
remember that you can always use a lambda or a callable object, which can do
@ -2817,7 +2821,7 @@ pretty much anything you want:
```
Every time this `EXPECT_CALL` fires, a new `unique_ptr<Buzz>` will be created
and returned. You cannot do this with `Return(ByMove(...))`.
and returned. You cannot do this with `Return(std::make_unique<...>(...))`.
That covers returning move-only values; but how do we work with methods
accepting move-only arguments? The answer is that they work normally, although
@ -3197,11 +3201,11 @@ You can unlock this power by running your test with the `--gmock_verbose=info`
flag. For example, given the test program:
```cpp
#include "gmock/gmock.h"
#include <gmock/gmock.h>
using testing::_;
using testing::HasSubstr;
using testing::Return;
using ::testing::_;
using ::testing::HasSubstr;
using ::testing::Return;
class MockFoo {
public:
@ -3309,7 +3313,7 @@ For convenience, we allow the description string to be empty (`""`), in which
case gMock will use the sequence of words in the matcher name as the
description.
For example:
#### Basic Example
```cpp
MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; }
@ -3347,6 +3351,8 @@ If the above assertions fail, they will print something like:
where the descriptions `"is divisible by 7"` and `"not (is divisible by 7)"` are
automatically calculated from the matcher name `IsDivisibleBy7`.
#### Adding Custom Failure Messages
As you may have noticed, the auto-generated descriptions (especially those for
the negation) may not be so great. You can always override them with a `string`
expression of your own:
@ -3380,21 +3386,84 @@ With this definition, the above assertion will give a better message:
Actual: 27 (the remainder is 6)
```
#### `MatchAndExplain`
You should let `MatchAndExplain()` print *any additional information* that can
help a user understand the match result. Note that it should explain why the
match succeeds in case of a success (unless it's obvious) - this is useful when
the matcher is used inside `Not()`. There is no need to print the argument value
itself, as gMock already prints it for you.
{: .callout .note}
NOTE: The type of the value being matched (`arg_type`) is determined by the
context in which you use the matcher and is supplied to you by the compiler, so
you don't need to worry about declaring it (nor can you). This allows the
matcher to be polymorphic. For example, `IsDivisibleBy7()` can be used to match
any type where the value of `(arg % 7) == 0` can be implicitly converted to a
`bool`. In the `Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an
`int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will
be `unsigned long`; and so on.
#### Argument Types
The type of the value being matched (`arg_type`) is determined by the context in
which you use the matcher and is supplied to you by the compiler, so you don't
need to worry about declaring it (nor can you). This allows the matcher to be
polymorphic. For example, `IsDivisibleBy7()` can be used to match any type where
the value of `(arg % 7) == 0` can be implicitly converted to a `bool`. In the
`Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an `int`,
`arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will be
`unsigned long`; and so on.
#### Anti-pattern: Using EXPECT_ Statements in Matchers
Using `EXPECT_...` statements inside custom matcher definitions is an
**anti-pattern** and should be avoided.
While it might appear to write matchers more concisely and generate informative
messages, this pattern has critical issues:
1. **Negation Breakage (`Not`):** If wrapped in `Not(IsDivisibleBy7())`,
evaluating it still triggers the internal `EXPECT_EQ`, registering a test
failure on the runner even when the overall assertion is expected to
succeed.
2. **Composition / Container Breakage (`AnyOf`, `AllOf`, `Contains`):** When
composed or used inside container matchers, elements that are expected
mismatches will trigger the internal `EXPECT_` and register spurious
failures.
3. **ASSERT_* compilation errors:** `ASSERT_*` macros use `return;` to abort
from a void function. Since matchers return `bool`, using `ASSERT_` inside
them triggers a compilation error.
4. **Purity Violations:** Matchers must be functionally pure (side-effect
free), whereas registering global failures is a major side effect.
5. **Line Number Confusion:** Failure reports point to the matcher's definition
line rather than the calling `EXPECT_THAT`
line.
##### The Anti-Pattern
```cpp
// Anti-pattern: Do not do this!
MATCHER(IsDivisibleBy7, "") {
const auto remainder = arg % 7;
EXPECT_EQ(remainder, 0); // Spurious failures if negated/composed!
return true;
}
```
##### The Correct Solution
To write concise matchers that delegate to other matchers and safely propagate
the mismatch explanation, use **`::testing::ExplainMatchResult`** instead,
passing it the sub-matcher, the value to check, and the `result_listener`:
```cpp
MATCHER(IsDivisibleBy7, "") {
const auto remainder = arg % 7;
return ::testing::ExplainMatchResult(::testing::Eq(0), remainder,
result_listener);
}
```
If you write a test that includes the line:
```cpp
EXPECT_THAT(28, Not(IsDivisibleBy7()));
```
it will correctly report the mismatch, properly point to the `EXPECT_THAT` line
number, and support negation (`Not`) and composition (`AllOf`, `AnyOf`, etc.)
without registering spurious failures.
### Writing New Parameterized Matchers Quickly
@ -3533,12 +3602,17 @@ general leads to better compiler error messages that pay off in the long run.
They also allow overloading matchers based on parameter types (as opposed to
just based on the number of parameters).
### Writing New Monomorphic Matchers
### Writing New Monomorphic Matchers {#MonomorphicMatchers}
A matcher of argument type `T` implements the matcher interface for `T` and does
two things: it tests whether a value of type `T` matches the matcher, and can
describe what kind of values it matches. The latter ability is used for
generating readable error messages when expectations are violated.
A matcher of type `testing::Matcher<T>` implements the matcher interface for `T`
and does two things: it tests whether a value of type `T` matches the matcher,
and can describe what kind of values it matches. The latter ability is used for
generating readable error messages when expectations are violated. Some matchers
can even explain why it matches or doesn't match a certain value, which can be
helpful when the reason isn't obvious.
Because a matcher of type `testing::Matcher<T>` for a particular type `T` can
only be used to match a value of type `T`, we call it "monomorphic."
A matcher of `T` must declare a typedef like:
@ -3553,7 +3627,7 @@ and supports the following operations:
bool matched = matcher.MatchAndExplain(value, maybe_os);
// where `value` is of type `T` and
// `maybe_os` is of type `std::ostream*`, where it can be null if the caller
// is not interested in there textual explanation.
// is not interested in the textual explanation.
matcher.DescribeTo(os);
matcher.DescribeNegationTo(os);
@ -3628,10 +3702,18 @@ Expected: is divisible by 7
Tip: for convenience, `MatchAndExplain()` can take a `MatchResultListener*`
instead of `std::ostream*`.
### Writing New Polymorphic Matchers
### Writing New Polymorphic Matchers {#PolymorphicMatchers}
Expanding what we learned above to *polymorphic* matchers is now just as simple
as adding templates in the right place.
Unlike a monomorphic matcher, which can only be used to match a value of a
particular type, a *polymorphic* matcher is one that can be used to match values
of multiple types. For example, `Eq(5)` is a polymorphic matcher as it can be
used to match an `int`, a `double`, a `float`, and so on. You should think of a
polymorphic matcher as a *matcher factory* as opposed to a
`testing::Matcher<SomeType>` - itself is not an actual matcher, but can be
implicitly converted to a `testing::Matcher<SomeType>` depending on the context.
Expanding what we learned above to polymorphic matchers is now as simple as
adding templates in the right place.
```cpp
@ -3757,6 +3839,26 @@ virtual.
Like in a monomorphic matcher, you may explain the match result by streaming
additional information to the `listener` argument in `MatchAndExplain()`.
### Implementing Composite Matchers {#CompositeMatchers}
Sometimes we want to define a matcher that takes other matchers as parameters.
For example, `DistanceFrom(target, m)` is a polymorphic matcher that takes a
matcher `m` as a parameter. It tests that the distance from `target` to the
value being matched satisfies sub-matcher `m`.
If you are implementing such a composite matcher, you'll need to generate the
description of the matcher based on the description(s) of its sub-matcher(s).
You can see the implementation of `DistanceFrom()` in
`googlemock/include/gmock/gmock-matchers.h` for an example. In particular, pay
attention to `DistanceFromMatcherImpl`. Notice that it stores the sub-matcher as
a `const Matcher<const Distance&> distance_matcher_` instead of a polymorphic
matcher - this allows it to call `distance_matcher_.DescribeTo(os)` to describe
the sub-matcher. If the sub-matcher is stored as a polymorphic matcher instead,
it would not be possible to get its description as in general polymorphic
matchers don't know how to describe themselves - they are matcher factories
instead of actual matchers; only after being converted to `Matcher<SomeType>`
can they be described.
### Writing New Cardinalities
A cardinality is used in `Times()` to tell gMock how many times you expect a
@ -3822,15 +3924,15 @@ If the built-in actions don't work for you, you can easily define your own one.
All you need is a call operator with a signature compatible with the mocked
function. So you can use a lambda:
```
```cpp
MockFunction<int(int)> mock;
EXPECT_CALL(mock, Call).WillOnce([](const int input) { return input * 7; });
EXPECT_EQ(14, mock.AsStdFunction()(2));
EXPECT_EQ(mock.AsStdFunction()(2), 14);
```
Or a struct with a call operator (even a templated one):
```
```cpp
struct MultiplyBy {
template <typename T>
T operator()(T arg) { return arg * multiplier; }
@ -3845,16 +3947,16 @@ struct MultiplyBy {
It's also fine for the callable to take no arguments, ignoring the arguments
supplied to the mock function:
```
```cpp
MockFunction<int(int)> mock;
EXPECT_CALL(mock, Call).WillOnce([] { return 17; });
EXPECT_EQ(17, mock.AsStdFunction()(0));
EXPECT_EQ(mock.AsStdFunction()(0), 17);
```
When used with `WillOnce`, the callable can assume it will be called at most
once and is allowed to be a move-only type:
```
```cpp
// An action that contains move-only types and has an &&-qualified operator,
// demanding in the type system that it be called at most once. This can be
// used with WillOnce, but the compiler will reject it if handed to
@ -4298,7 +4400,7 @@ particular type than to dump the bytes.
### Mock std::function {#MockFunction}
`std::function` is a general function type introduced in C++11. It is a
preferred way of passing callbacks to new interfaces. Functions are copiable,
preferred way of passing callbacks to new interfaces. Functions are copyable,
and are not usually passed around by pointer, which makes them tricky to mock.
But fear not - `MockFunction` can help you with that.

12
test/googletest/docs/gmock_for_dummies.md
View file

@ -90,14 +90,14 @@ gMock is bundled with googletest.
## A Case for Mock Turtles
Let's look at an example. Suppose you are developing a graphics program that
relies on a [LOGO](http://en.wikipedia.org/wiki/Logo_programming_language)-like
relies on a [LOGO](https://en.wikipedia.org/wiki/Logo_programming_language)-like
API for drawing. How would you test that it does the right thing? Well, you can
run it and compare the screen with a golden screen snapshot, but let's admit it:
tests like this are expensive to run and fragile (What if you just upgraded to a
shiny new graphics card that has better anti-aliasing? Suddenly you have to
update all your golden images.). It would be too painful if all your tests are
like this. Fortunately, you learned about
[Dependency Injection](http://en.wikipedia.org/wiki/Dependency_injection) and know the right thing
[Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) and know the right thing
to do: instead of having your application talk to the system API directly, wrap
the API in an interface (say, `Turtle`) and code to that interface:
@ -164,7 +164,7 @@ follow:
After the process, you should have something like:
```cpp
#include "gmock/gmock.h" // Brings in gMock.
#include <gmock/gmock.h> // Brings in gMock.
class MockTurtle : public Turtle {
public:
@ -224,8 +224,8 @@ Here's an example:
```cpp
#include "path/to/mock-turtle.h"
#include "gmock/gmock.h"
#include "gtest/gtest.h"
#include <gmock/gmock.h>
#include <gtest/gtest.h>
using ::testing::AtLeast; // #1
@ -261,6 +261,8 @@ happen. Therefore it's a good idea to turn on the heap checker in your tests
when you allocate mocks on the heap. You get that automatically if you use the
`gtest_main` library already.
###### Expectation Ordering
**Important note:** gMock requires expectations to be set **before** the mock
functions are called, otherwise the behavior is **undefined**. Do not alternate
between calls to `EXPECT_CALL()` and calls to the mock functions, and do not set

14
test/googletest/docs/pkgconfig.md
View file

@ -19,19 +19,15 @@ examples here we assume you want to compile the sample
Using `pkg-config` in CMake is fairly easy:
```cmake
cmake_minimum_required(VERSION 3.0)
cmake_policy(SET CMP0048 NEW)
project(my_gtest_pkgconfig VERSION 0.0.1 LANGUAGES CXX)
find_package(PkgConfig)
pkg_search_module(GTEST REQUIRED gtest_main)
add_executable(testapp samples/sample3_unittest.cc)
target_link_libraries(testapp ${GTEST_LDFLAGS})
target_compile_options(testapp PUBLIC ${GTEST_CFLAGS})
add_executable(testapp)
target_sources(testapp PRIVATE samples/sample3_unittest.cc)
target_link_libraries(testapp PRIVATE ${GTEST_LDFLAGS})
target_compile_options(testapp PRIVATE ${GTEST_CFLAGS})
include(CTest)
enable_testing()
add_test(first_and_only_test testapp)
```

39
test/googletest/docs/platforms.md
View file

@ -1,35 +1,8 @@
# Supported Platforms
GoogleTest requires a codebase and compiler compliant with the C++11 standard or
newer.
The GoogleTest code is officially supported on the following platforms.
Operating systems or tools not listed below are community-supported. For
community-supported platforms, patches that do not complicate the code may be
considered.
If you notice any problems on your platform, please file an issue on the
[GoogleTest GitHub Issue Tracker](https://github.com/google/googletest/issues).
Pull requests containing fixes are welcome!
### Operating systems
* Linux
* macOS
* Windows
### Compilers
* gcc 5.0+
* clang 5.0+
* MSVC 2015+
**macOS users:** Xcode 9.3+ provides clang 5.0+.
### Build systems
* [Bazel](https://bazel.build/)
* [CMake](https://cmake.org/)
Bazel is the build system used by the team internally and in tests. CMake is
supported on a best-effort basis and by the community.
GoogleTest follows Google's
[Foundational C++ Support Policy](https://opensource.google/documentation/policies/cplusplus-support).
See
[this table](https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md)
for a list of currently supported versions compilers, platforms, and build
tools.

131
test/googletest/docs/primer.md
View file

@ -1,84 +1,84 @@
# Googletest Primer
# GoogleTest Primer
## Introduction: Why googletest?
## Introduction: Why GoogleTest?
*googletest* helps you write better C++ tests.
*GoogleTest* helps you write better C++ tests.
googletest is a testing framework developed by the Testing Technology team with
GoogleTest is a testing framework developed by the Testing Technology team with
Google's specific requirements and constraints in mind. Whether you work on
Linux, Windows, or a Mac, if you write C++ code, googletest can help you. And it
Linux, Windows, or a Mac, if you write C++ code, GoogleTest can help you. And it
supports *any* kind of tests, not just unit tests.
So what makes a good test, and how does googletest fit in? We believe:
So what makes a good test, and how does GoogleTest fit in? We believe:
1. Tests should be *independent* and *repeatable*. It's a pain to debug a test
that succeeds or fails as a result of other tests. googletest isolates the
that succeeds or fails as a result of other tests. GoogleTest isolates the
tests by running each of them on a different object. When a test fails,
googletest allows you to run it in isolation for quick debugging.
GoogleTest allows you to run it in isolation for quick debugging.
2. Tests should be well *organized* and reflect the structure of the tested
code. googletest groups related tests into test suites that can share data
code. GoogleTest groups related tests into test suites that can share data
and subroutines. This common pattern is easy to recognize and makes tests
easy to maintain. Such consistency is especially helpful when people switch
projects and start to work on a new code base.
3. Tests should be *portable* and *reusable*. Google has a lot of code that is
platform-neutral; its tests should also be platform-neutral. googletest
platform-neutral; its tests should also be platform-neutral. GoogleTest
works on different OSes, with different compilers, with or without
exceptions, so googletest tests can work with a variety of configurations.
exceptions, so GoogleTest tests can work with a variety of configurations.
4. When tests fail, they should provide as much *information* about the problem
as possible. googletest doesn't stop at the first test failure. Instead, it
as possible. GoogleTest doesn't stop at the first test failure. Instead, it
only stops the current test and continues with the next. You can also set up
tests that report non-fatal failures after which the current test continues.
Thus, you can detect and fix multiple bugs in a single run-edit-compile
cycle.
5. The testing framework should liberate test writers from housekeeping chores
and let them focus on the test *content*. googletest automatically keeps
and let them focus on the test *content*. GoogleTest automatically keeps
track of all tests defined, and doesn't require the user to enumerate them
in order to run them.
6. Tests should be *fast*. With googletest, you can reuse shared resources
6. Tests should be *fast*. With GoogleTest, you can reuse shared resources
across tests and pay for the set-up/tear-down only once, without making
tests depend on each other.
Since googletest is based on the popular xUnit architecture, you'll feel right
Since GoogleTest is based on the popular xUnit architecture, you'll feel right
at home if you've used JUnit or PyUnit before. If not, it will take you about 10
minutes to learn the basics and get started. So let's go!
## Beware of the nomenclature
## Beware of the Nomenclature
{: .callout .note}
_Note:_ There might be some confusion arising from different definitions of the
terms _Test_, _Test Case_ and _Test Suite_, so beware of misunderstanding these.
*Note:* There might be some confusion arising from different definitions of the
terms *Test*, *Test Case* and *Test Suite*, so beware of misunderstanding these.
Historically, googletest started to use the term _Test Case_ for grouping
Historically, GoogleTest started to use the term *Test Case* for grouping
related tests, whereas current publications, including International Software
Testing Qualifications Board ([ISTQB](http://www.istqb.org/)) materials and
Testing Qualifications Board ([ISTQB](https://www.istqb.org/)) materials and
various textbooks on software quality, use the term
_[Test Suite][istqb test suite]_ for this.
*[Test Suite][istqb test suite]* for this.
The related term _Test_, as it is used in googletest, corresponds to the term
_[Test Case][istqb test case]_ of ISTQB and others.
The related term *Test*, as it is used in GoogleTest, corresponds to the term
*[Test Case][istqb test case]* of ISTQB and others.
The term _Test_ is commonly of broad enough sense, including ISTQB's definition
of _Test Case_, so it's not much of a problem here. But the term _Test Case_ as
The term *Test* is commonly of broad enough sense, including ISTQB's definition
of *Test Case*, so it's not much of a problem here. But the term *Test Case* as
was used in Google Test is of contradictory sense and thus confusing.
googletest recently started replacing the term _Test Case_ with _Test Suite_.
GoogleTest recently started replacing the term *Test Case* with *Test Suite*.
The preferred API is *TestSuite*. The older TestCase API is being slowly
deprecated and refactored away.
So please be aware of the different definitions of the terms:
Meaning | googletest Term | [ISTQB](http://www.istqb.org/) Term
Meaning | GoogleTest Term | [ISTQB](https://www.istqb.org/) Term
:----------------------------------------------------------------------------------- | :---------------------- | :----------------------------------
Exercise a particular program path with specific input values and verify the results | [TEST()](#simple-tests) | [Test Case][istqb test case]
[istqb test case]: http://glossary.istqb.org/en/search/test%20case
[istqb test suite]: http://glossary.istqb.org/en/search/test%20suite
[istqb test case]: https://glossary.istqb.org/en_US/term/test-case
[istqb test suite]: https://glossary.istqb.org/en_US/term/test-suite
## Basic Concepts
When using googletest, you start by writing *assertions*, which are statements
When using GoogleTest, you start by writing *assertions*, which are statements
that check whether a condition is true. An assertion's result can be *success*,
*nonfatal failure*, or *fatal failure*. If a fatal failure occurs, it aborts the
current function; otherwise the program continues normally.
@ -98,11 +98,11 @@ assertion level and building up to tests and test suites.
## Assertions
googletest assertions are macros that resemble function calls. You test a class
GoogleTest assertions are macros that resemble function calls. You test a class
or function by making assertions about its behavior. When an assertion fails,
googletest prints the assertion's source file and line number location, along
GoogleTest prints the assertion's source file and line number location, along
with a failure message. You may also supply a custom failure message which will
be appended to googletest's message.
be appended to GoogleTest's message.
The assertions come in pairs that test the same thing but have different effects
on the current function. `ASSERT_*` versions generate fatal failures when they
@ -149,7 +149,7 @@ To create a test:
1. Use the `TEST()` macro to define and name a test function. These are
ordinary C++ functions that don't return a value.
2. In this function, along with any valid C++ statements you want to include,
use the various googletest assertions to check values.
use the various GoogleTest assertions to check values.
3. The test's result is determined by the assertions; if any assertion in the
test fails (either fatally or non-fatally), or if the test crashes, the
entire test fails. Otherwise, it succeeds.
@ -190,7 +190,7 @@ TEST(FactorialTest, HandlesPositiveInput) {
}
```
googletest groups the test results by test suites, so logically related tests
GoogleTest groups the test results by test suites, so logically related tests
should be in the same test suite; in other words, the first argument to their
`TEST()` should be the same. In the above example, we have two tests,
`HandlesZeroInput` and `HandlesPositiveInput`, that belong to the same test
@ -210,7 +210,7 @@ objects for several different tests.
To create a fixture:
1. Derive a class from `::testing::Test` . Start its body with `protected:`, as
1. Derive a class from `testing::Test` . Start its body with `protected:`, as
we'll want to access fixture members from sub-classes.
2. Inside the class, declare any objects you plan to use.
3. If necessary, write a default constructor or `SetUp()` function to prepare
@ -227,14 +227,14 @@ When using a fixture, use `TEST_F()` instead of `TEST()` as it allows you to
access objects and subroutines in the test fixture:
```c++
TEST_F(TestFixtureName, TestName) {
TEST_F(TestFixtureClassName, TestName) {
... test body ...
}
```
Like `TEST()`, the first argument is the test suite name, but for `TEST_F()`
this must be the name of the test fixture class. You've probably guessed: `_F`
is for fixture.
Unlike `TEST()`, in `TEST_F()` the first argument must be the name of the test
fixture class. (`_F` stands for "Fixture"). No test suite name is specified for
this macro.
Unfortunately, the C++ macro system does not allow us to create a single macro
that can handle both types of tests. Using the wrong macro causes a compiler
@ -244,12 +244,12 @@ Also, you must first define a test fixture class before using it in a
`TEST_F()`, or you'll get the compiler error "`virtual outside class
declaration`".
For each test defined with `TEST_F()`, googletest will create a *fresh* test
For each test defined with `TEST_F()`, GoogleTest will create a *fresh* test
fixture at runtime, immediately initialize it via `SetUp()`, run the test, clean
up by calling `TearDown()`, and then delete the test fixture. Note that
different tests in the same test suite have different test fixture objects, and
googletest always deletes a test fixture before it creates the next one.
googletest does **not** reuse the same test fixture for multiple tests. Any
GoogleTest always deletes a test fixture before it creates the next one.
GoogleTest does **not** reuse the same test fixture for multiple tests. Any
changes one test makes to the fixture do not affect other tests.
As an example, let's write tests for a FIFO queue class named `Queue`, which has
@ -271,16 +271,16 @@ First, define a fixture class. By convention, you should give it the name
`FooTest` where `Foo` is the class being tested.
```c++
class QueueTest : public ::testing::Test {
class QueueTest : public testing::Test {
protected:
void SetUp() override {
QueueTest() {
// q0_ remains empty
q1_.Enqueue(1);
q2_.Enqueue(2);
q2_.Enqueue(3);
}
// void TearDown() override {}
// ~QueueTest() override = default;
Queue<int> q0_;
Queue<int> q1_;
@ -288,8 +288,9 @@ class QueueTest : public ::testing::Test {
};
```
In this case, `TearDown()` is not needed since we don't have to clean up after
each test, other than what's already done by the destructor.
In this case, we don't need to define a destructor or a `TearDown()` method,
because the implicit destructor generated by the compiler will perform all of
the necessary cleanup.
Now we'll write tests using `TEST_F()` and this fixture.
@ -325,19 +326,17 @@ would lead to a segfault when `n` is `NULL`.
When these tests run, the following happens:
1. googletest constructs a `QueueTest` object (let's call it `t1`).
2. `t1.SetUp()` initializes `t1`.
3. The first test (`IsEmptyInitially`) runs on `t1`.
4. `t1.TearDown()` cleans up after the test finishes.
5. `t1` is destructed.
6. The above steps are repeated on another `QueueTest` object, this time
1. GoogleTest constructs a `QueueTest` object (let's call it `t1`).
2. The first test (`IsEmptyInitially`) runs on `t1`.
3. `t1` is destructed.
4. The above steps are repeated on another `QueueTest` object, this time
running the `DequeueWorks` test.
**Availability**: Linux, Windows, Mac.
## Invoking the Tests
`TEST()` and `TEST_F()` implicitly register their tests with googletest. So,
`TEST()` and `TEST_F()` implicitly register their tests with GoogleTest. So,
unlike with many other C++ testing frameworks, you don't have to re-list all
your defined tests in order to run them.
@ -348,7 +347,7 @@ test suites, or even different source files.
When invoked, the `RUN_ALL_TESTS()` macro:
* Saves the state of all googletest flags.
* Saves the state of all GoogleTest flags.
* Creates a test fixture object for the first test.
@ -360,7 +359,7 @@ When invoked, the `RUN_ALL_TESTS()` macro:
* Deletes the fixture.
* Restores the state of all googletest flags.
* Restores the state of all GoogleTest flags.
* Repeats the above steps for the next test, until all tests have run.
@ -374,14 +373,14 @@ If a fatal failure happens the subsequent steps will be skipped.
> return the value of `RUN_ALL_TESTS()`.
>
> Also, you should call `RUN_ALL_TESTS()` only **once**. Calling it more than
> once conflicts with some advanced googletest features (e.g., thread-safe
> once conflicts with some advanced GoogleTest features (e.g., thread-safe
> [death tests](advanced.md#death-tests)) and thus is not supported.
**Availability**: Linux, Windows, Mac.
## Writing the main() Function
Most users should _not_ need to write their own `main` function and instead link
Most users should *not* need to write their own `main` function and instead link
with `gtest_main` (as opposed to with `gtest`), which defines a suitable entry
point. See the end of this section for details. The remainder of this section
should only apply when you need to do something custom before the tests run that
@ -395,14 +394,14 @@ You can start from this boilerplate:
```c++
#include "this/package/foo.h"
#include "gtest/gtest.h"
#include <gtest/gtest.h>
namespace my {
namespace project {
namespace {
// The fixture for testing class Foo.
class FooTest : public ::testing::Test {
class FooTest : public testing::Test {
protected:
// You can remove any or all of the following functions if their bodies would
// be empty.
@ -450,14 +449,14 @@ TEST_F(FooTest, DoesXyz) {
} // namespace my
int main(int argc, char **argv) {
::testing::InitGoogleTest(&argc, argv);
testing::InitGoogleTest(&argc, argv);
return RUN_ALL_TESTS();
}
```
The `::testing::InitGoogleTest()` function parses the command line for
googletest flags, and removes all recognized flags. This allows the user to
control a test program's behavior via various flags, which we'll cover in the
The `testing::InitGoogleTest()` function parses the command line for GoogleTest
flags, and removes all recognized flags. This allows the user to control a test
program's behavior via various flags, which we'll cover in the
[AdvancedGuide](advanced.md). You **must** call this function before calling
`RUN_ALL_TESTS()`, or the flags won't be properly initialized.
@ -476,7 +475,7 @@ NOTE: `ParseGUnitFlags()` is deprecated in favor of `InitGoogleTest()`.
* Google Test is designed to be thread-safe. The implementation is thread-safe
on systems where the `pthreads` library is available. It is currently
_unsafe_ to use Google Test assertions from two threads concurrently on
*unsafe* to use Google Test assertions from two threads concurrently on
other systems (e.g. Windows). In most tests this is not an issue as usually
the assertions are done in the main thread. If you want to help, you can
volunteer to implement the necessary synchronization primitives in

62
test/googletest/docs/quickstart-bazel.md
View file

@ -9,9 +9,9 @@ we recommend this tutorial as a starting point.
To complete this tutorial, you'll need:
* A compatible operating system (e.g. Linux, macOS, Windows).
* A compatible C++ compiler that supports at least C++14.
* [Bazel](https://bazel.build/), the preferred build system used by the
GoogleTest team.
* A compatible C++ compiler that supports at least C++17.
* [Bazel](https://bazel.build/) 7.0 or higher, the preferred build system used
by the GoogleTest team.
See [Supported Platforms](platforms.md) for more information about platforms
compatible with GoogleTest.
@ -28,7 +28,7 @@ A
[Bazel workspace](https://docs.bazel.build/versions/main/build-ref.html#workspace)
is a directory on your filesystem that you use to manage source files for the
software you want to build. Each workspace directory has a text file named
`WORKSPACE` which may be empty, or may contain references to external
`MODULE.bazel` which may be empty, or may contain references to external
dependencies required to build the outputs.
First, create a directory for your workspace:
@ -37,30 +37,20 @@ First, create a directory for your workspace:
$ mkdir my_workspace && cd my_workspace
```
Next, you’ll create the `WORKSPACE` file to specify dependencies. A common and
recommended way to depend on GoogleTest is to use a
[Bazel external dependency](https://docs.bazel.build/versions/main/external.html)
via the
[`http_archive` rule](https://docs.bazel.build/versions/main/repo/http.html#http_archive).
To do this, in the root directory of your workspace (`my_workspace/`), create a
file named `WORKSPACE` with the following contents:
Next, you’ll create the `MODULE.bazel` file to specify dependencies. As of Bazel
7.0, the recommended way to consume GoogleTest is through the
[Bazel Central Registry](https://registry.bazel.build/modules/googletest). To do
this, create a `MODULE.bazel` file in the root directory of your Bazel workspace
with the following content:
```
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
# MODULE.bazel
http_archive(
name = "com_google_googletest",
urls = ["https://github.com/google/googletest/archive/5ab508a01f9eb089207ee87fd547d290da39d015.zip"],
strip_prefix = "googletest-5ab508a01f9eb089207ee87fd547d290da39d015",
)
# Choose the most recent version available at
# https://registry.bazel.build/modules/googletest
bazel_dep(name = "googletest", version = "1.18.0")
```
The above configuration declares a dependency on GoogleTest which is downloaded
as a ZIP archive from GitHub. In the above example,
`5ab508a01f9eb089207ee87fd547d290da39d015` is the Git commit hash of the
GoogleTest version to use; we recommend updating the hash often to point to the
latest version. Use a recent hash on the `main` branch.
Now you're ready to build C++ code that uses GoogleTest.
## Create and run a binary
@ -92,23 +82,33 @@ following contents:
```
cc_test(
name = "hello_test",
size = "small",
srcs = ["hello_test.cc"],
deps = ["@com_google_googletest//:gtest_main"],
name = "hello_test",
size = "small",
srcs = ["hello_test.cc"],
deps = [
"@googletest//:gtest",
"@googletest//:gtest_main",
],
)
```
This `cc_test` rule declares the C++ test binary you want to build, and links to
GoogleTest (`//:gtest_main`) using the prefix you specified in the `WORKSPACE`
file (`@com_google_googletest`). For more information about Bazel `BUILD` files,
see the
the GoogleTest library (`@googletest//:gtest"`) and the GoogleTest `main()`
function (`@googletest//:gtest_main`). For more information about Bazel `BUILD`
files, see the
[Bazel C++ Tutorial](https://docs.bazel.build/versions/main/tutorial/cpp.html).
{: .callout .note}
NOTE: In the example below, we assume Clang or GCC and set `--cxxopt=-std=c++17`
to ensure that GoogleTest is compiled as C++17 instead of the compiler's default
setting. For MSVC, the equivalent would be `--cxxopt=/std:c++17`. See
[Supported Platforms](platforms.md) for more details on supported language
versions.
Now you can build and run your test:
<pre>
<strong>my_workspace$ bazel test --test_output=all //:hello_test</strong>
<strong>$ bazel test --cxxopt=-std=c++17 --test_output=all //:hello_test</strong>
INFO: Analyzed target //:hello_test (26 packages loaded, 362 targets configured).
INFO: Found 1 test target...
INFO: From Testing //:hello_test:

7
test/googletest/docs/quickstart-cmake.md
View file

@ -10,7 +10,7 @@ this tutorial as a starting point. If your project uses Bazel, see the
To complete this tutorial, you'll need:
* A compatible operating system (e.g. Linux, macOS, Windows).
* A compatible C++ compiler that supports at least C++14.
* A compatible C++ compiler that supports at least C++17.
* [CMake](https://cmake.org/) and a compatible build tool for building the
project.
* Compatible build tools include
@ -52,8 +52,9 @@ To do this, in your project directory (`my_project`), create a file named
cmake_minimum_required(VERSION 3.14)
project(my_project)
# GoogleTest requires at least C++14
set(CMAKE_CXX_STANDARD 14)
# GoogleTest requires at least C++17
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
include(FetchContent)
FetchContent_Declare(

7
test/googletest/docs/reference/actions.md
View file

@ -24,7 +24,8 @@ provided by GoogleTest. All actions are defined in the `::testing` namespace.
| :--------------------------------- | :-------------------------------------- |
| `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`. |
| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer` by copy-assignment. |
| `SaveArgByMove<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer` by move-assignment. |
| `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. |
@ -47,8 +48,8 @@ functor, or lambda.
| `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.
The return value of the invoked function (except `InvokeArgument`) is used as
the return value of the action.
When defining a callable to be used with `Invoke*()`, you can declare any unused
parameters as `Unused`:

17
test/googletest/docs/reference/assertions.md
View file

@ -1,7 +1,7 @@
# Assertions Reference
This page lists the assertion macros provided by GoogleTest for verifying code
behavior. To use them, include the header `gtest/gtest.h`.
behavior. To use them, add `#include <gtest/gtest.h>`.
The majority of the macros listed below come as a pair with an `EXPECT_` variant
and an `ASSERT_` variant. Upon failure, `EXPECT_` macros generate nonfatal
@ -88,7 +88,7 @@ For example, the following code verifies that the string `value1` starts with
10:
```cpp
#include "gmock/gmock.h"
#include <gmock/gmock.h>
using ::testing::AllOf;
using ::testing::Gt;
@ -276,7 +276,8 @@ Units in the Last Place (ULPs). To learn more about ULPs, see the article
`ASSERT_FLOAT_EQ(`*`val1`*`,`*`val2`*`)`
Verifies that the two `float` values *`val1`* and *`val2`* are approximately
equal, to within 4 ULPs from each other.
equal, to within 4 ULPs from each other. Infinity and the largest finite float
value are considered to be one ULP apart.
### EXPECT_DOUBLE_EQ {#EXPECT_DOUBLE_EQ}
@ -284,7 +285,8 @@ equal, to within 4 ULPs from each other.
`ASSERT_DOUBLE_EQ(`*`val1`*`,`*`val2`*`)`
Verifies that the two `double` values *`val1`* and *`val2`* are approximately
equal, to within 4 ULPs from each other.
equal, to within 4 ULPs from each other. Infinity and the largest finite double
value are considered to be one ULP apart.
### EXPECT_NEAR {#EXPECT_NEAR}
@ -294,6 +296,11 @@ equal, to within 4 ULPs from each other.
Verifies that the difference between *`val1`* and *`val2`* does not exceed the
absolute error bound *`abs_error`*.
If *`val`* and *`val2`* are both infinity of the same sign, the difference is
considered to be 0. Otherwise, if either value is infinity, the difference is
considered to be infinity. All non-NaN values (including infinity) are
considered to not exceed an *`abs_error`* of infinity.
## Exception Assertions {#exceptions}
The following assertions verify that a piece of code throws, or does not throw,
@ -515,7 +522,7 @@ Verifies that *`expression`* is a success `HRESULT`.
### EXPECT_HRESULT_FAILED {#EXPECT_HRESULT_FAILED}
`EXPECT_HRESULT_FAILED(`*`expression`*`)` \
`EXPECT_HRESULT_FAILED(`*`expression`*`)`
`ASSERT_HRESULT_FAILED(`*`expression`*`)`
Verifies that *`expression`* is a failure `HRESULT`.

58
test/googletest/docs/reference/matchers.md
View file

@ -1,5 +1,7 @@
# Matchers Reference
<!-- disableFinding(LINK_RELATIVE_G3DOC) -->
A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
`EXPECT_CALL()`, or use it to validate a value directly using two macros:
@ -42,11 +44,14 @@ Matcher | Description
| `Lt(value)` | `argument < value` |
| `Ne(value)` | `argument != value` |
| `IsFalse()` | `argument` evaluates to `false` in a Boolean context. |
| `DistanceFrom(target, m)` | The distance between `argument` and `target` (computed by `abs(argument - target)`) matches `m`. |
| `DistanceFrom(target, get_distance, m)` | The distance between `argument` and `target` (computed by `get_distance(argument, target)`) matches `m`. |
| `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 `==`.)|
| `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. (For testing whether an `optional<>` is unset, 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`. |
| `AnyWith<T>(m)` | `argument` is `any<>` that holds a value 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. |
@ -109,6 +114,33 @@ 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.
## Exception Matchers
| Matcher | Description |
| :---------------------------------------- | :------------------------------- |
| `Throws<E>()` | The `argument` is a callable object that, when called, throws an exception of the expected type `E`. |
| `Throws<E>(m)` | The `argument` is a callable object that, when called, throws an exception of type `E` that satisfies the matcher `m`. |
| `ThrowsMessage<E>(m)` | The `argument` is a callable object that, when called, throws an exception of type `E` with a message that satisfies the matcher `m`. |
Examples:
```cpp
auto argument = [] { throw std::runtime_error("error msg"); };
// Checks if the lambda throws a `std::runtime_error`.
EXPECT_THAT(argument, Throws<std::runtime_error>());
// Checks if the lambda throws a `std::runtime_error` with a specific message
// that matches "error msg".
EXPECT_THAT(argument,
Throws<std::runtime_error>(Property(&std::runtime_error::what,
Eq("error msg"))));
// Checks if the lambda throws a `std::runtime_error` with a message that
// contains "msg".
EXPECT_THAT(argument, ThrowsMessage<std::runtime_error>(HasSubstr("msg")));
```
## Container Matchers
Most STL-style containers support `==`, so you can use `Eq(expected_container)`
@ -171,6 +203,11 @@ messages, you can use:
| `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.
{: .callout .warning}
Warning: Don't use `Property()` against member functions that you do not own,
because taking addresses of functions is fragile and generally not part of the
contract of the function.
**Notes:**
* You can use `FieldsAre()` to match any type that supports structured
@ -189,10 +226,6 @@ messages, you can use:
EXPECT_THAT(s, FieldsAre(42, "aloha"));
```
* Don't use `Property()` against member functions that you do not own, because
taking addresses of functions is fragile and generally not part of the
contract of the function.
## Matching the Result of a Function, Functor, or Callback
| Matcher | Description |
@ -223,6 +256,14 @@ Matcher | Description
`Le()` | `x <= y`
`Lt()` | `x < y`
`Ne()` | `x != y`
`FloatEq()` | `x` approximately equals `y`
`DoubleEq()` | `x` approximately equals `y`
`NanSensitiveFloatEq()` | Same as `FloatEq()`, but treats two NaNs as equal
`NanSensitiveDoubleEq()` | Same as `DoubleEq()`, but treats two NaNs as equal
`FloatNear(max_abs_error)` | `x` is within `max_abs_error` of `y`
`DoubleNear(max_abs_error)` | `x` is within `max_abs_error` of `y`
`NanSensitiveFloatNear(max_abs_error)` | Same as `FloatNear(max_abs_error)`, but treats two NaNs as near
`NanSensitiveDoubleNear(max_abs_error)` | Same as `DoubleNear(max_abs_error)`, but treats two NaNs as near
You can use the following selectors to pick a subset of the arguments (or
reorder them) to participate in the matching:
@ -266,6 +307,13 @@ which must be a permanent callback.
## Defining Matchers
{: .callout .note}
Note: full details about defining new matchers are in the
[cookbook](../gmock_cook_book.md#NewMatchers). In particular, if `MATCHER`
macros are not sufficient, you can directly implement
[monomorphic](../gmock_cook_book.md#MonomorphicMatchers) or
[polymorphic](../gmock_cook_book.md#PolymorphicMatchers) matchers.
| Macro | Description |
| :----------------------------------- | :------------------------------------ |
| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. |

3
test/googletest/docs/reference/mocking.md
View file

@ -1,8 +1,7 @@
# Mocking Reference
This page lists the facilities provided by GoogleTest for creating and working
with mock objects. To use them, include the header
`gmock/gmock.h`.
with mock objects. To use them, add `#include <gmock/gmock.h>`.
## Macros {#macros}

199
test/googletest/docs/reference/testing.md
View file

@ -3,7 +3,7 @@
<!--* toc_depth: 3 *-->
This page lists the facilities provided by GoogleTest for writing test programs.
To use them, include the header `gtest/gtest.h`.
To use them, add `#include <gtest/gtest.h>`.
## Macros
@ -94,7 +94,8 @@ Instantiates the value-parameterized test suite *`TestSuiteName`* (defined with
The argument *`InstantiationName`* is a unique name for the instantiation of the
test suite, to distinguish between multiple instantiations. In test output, the
instantiation name is added as a prefix to the test suite name
*`TestSuiteName`*.
*`TestSuiteName`*. If *`InstantiationName`* is empty
(`INSTANTIATE_TEST_SUITE_P(, ...)`), no prefix is added.
The argument *`param_generator`* is one of the following GoogleTest-provided
functions that generate the test parameters, all defined in the `::testing`
@ -109,7 +110,8 @@ namespace:
| `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`. |
| `ConvertGenerator<T>(g)` or `ConvertGenerator(g, func)` | Yields values generated by generator `g`, `static_cast` from `T`. (Note: `T` might not be what you expect. See [*Using ConvertGenerator*](#using-convertgenerator) below.) The second overload uses `func` to perform the conversion. |
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
@ -121,8 +123,8 @@ custom function can be used for more control:
```cpp
INSTANTIATE_TEST_SUITE_P(
MyInstantiation, MyTestSuite,
::testing::Values(...),
[](const ::testing::TestParamInfo<MyTestSuite::ParamType>& info) {
testing::Values(...),
[](const testing::TestParamInfo<MyTestSuite::ParamType>& info) {
// Can use info.param here to generate the test suffix
std::string name = ...
return name;
@ -135,9 +137,107 @@ For more information, see
See also
[`GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST`](#GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST).
###### Using `ConvertGenerator`
The functions listed in the table above appear to return generators that create
values of the desired types, but this is not generally the case. Rather, they
typically return factory objects that convert to the the desired generators.
This affords some flexibility in allowing you to specify values of types that
are different from, yet implicitly convertible to, the actual parameter type
required by your fixture class.
For example, you can do the following with a fixture that requires an `int`
parameter:
```cpp
INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
testing::Values(1, 1.2)); // Yes, Values() supports heterogeneous argument types.
```
It might seem obvious that `1.2` &mdash; a `double` &mdash; will be converted to
an `int` but in actuality it requires some template gymnastics involving the
indirection described in the previous paragraph.
What if your parameter type is not implicitly convertible from the generated
type but is *explicitly* convertible? There will be no automatic conversion, but
you can force it by applying `ConvertGenerator<T>`. The compiler can
automatically deduce the target type (your fixture's parameter type), but
because of the aforementioned indirection it cannot decide what the generated
type should be. You need to tell it, by providing the type `T` explicitly. Thus
`T` should not be your fixture's parameter type, but rather an intermediate type
that is supported by the factory object, and which can be `static_cast` to the
fixture's parameter type:
```cpp
// The fixture's parameter type.
class MyParam {
public:
// Explicit converting ctor.
explicit MyParam(const std::tuple<int, bool>& t);
...
};
INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
ConvertGenerator<std::tuple<int, bool>>(Combine(Values(0.1, 1.2), Bool())));
```
In this example `Combine` supports the generation of `std::tuple<int, bool>>`
objects (even though the provided values for the first tuple element are
`double`s) and those `tuple`s get converted into `MyParam` objects by virtue of
the call to `ConvertGenerator`.
For parameter types that are not convertible from the generated types you can
provide a callable that does the conversion. The callable accepts an object of
the generated type and returns an object of the fixture's parameter type. The
generated type can often be deduced by the compiler from the callable's call
signature so you do not usually need specify it explicitly (but see a caveat
below).
```cpp
// The fixture's parameter type.
class MyParam {
public:
MyParam(int, bool);
...
};
INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
ConvertGenerator(Combine(Values(1, 1.2), Bool()),
[](const std::tuple<int, bool>& t){
const auto [i, b] = t;
return MyParam(i, b);
}));
```
The callable may be anything that can be used to initialize a `std::function`
with the appropriate call signature. Note the callable's return object gets
`static_cast` to the fixture's parameter type, so it does not have to be of that
exact type, only convertible to it.
**Caveat:** Consider the following example.
```cpp
INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
ConvertGenerator(Values(std::string("s")), [](std::string_view s) { ... }));
```
The `string` argument gets copied into the factory object returned by `Values`.
Then, because the generated type deduced from the lambda is `string_view`, the
factory object spawns a generator that holds a `string_view` referencing that
`string`. Unfortunately, by the time this generator gets invoked, the factory
object is gone and the `string_view` is dangling.
To overcome this problem you can specify the generated type explicitly:
`ConvertGenerator<std::string>(Values(std::string("s")), [](std::string_view s)
{ ... })`. Alternatively, you can change the lambda's signature to take a
`std::string` or a `const std::string&` (the latter will not leave you with a
dangling reference because the type deduction strips off the reference and the
`const`).
### TYPED_TEST_SUITE {#TYPED_TEST_SUITE}
`TYPED_TEST_SUITE(`*`TestFixtureName`*`,`*`Types`*`)`
`TYPED_TEST_SUITE(`*`TestFixtureName`*`,`*`Types`*`,`*`NameGenerator`*`)`
Defines a typed test suite based on the test fixture *`TestFixtureName`*. The
test suite name is *`TestFixtureName`*.
@ -147,7 +247,7 @@ type, for example:
```cpp
template <typename T>
class MyFixture : public ::testing::Test {
class MyFixture : public testing::Test {
public:
...
using List = std::list<T>;
@ -167,6 +267,22 @@ TYPED_TEST_SUITE(MyFixture, MyTypes);
The type alias (`using` or `typedef`) is necessary for the `TYPED_TEST_SUITE`
macro to parse correctly.
The optional third argument *`NameGenerator`* allows specifying a class that
exposes a templated static function `GetName(int)`. For example:
```cpp
class NameGenerator {
public:
template <typename T>
static std::string GetName(int) {
if constexpr (std::is_same_v<T, char>) return "char";
if constexpr (std::is_same_v<T, int>) return "int";
if constexpr (std::is_same_v<T, unsigned int>) return "unsignedInt";
}
};
TYPED_TEST_SUITE(MyFixture, MyTypes, NameGenerator);
```
See also [`TYPED_TEST`](#TYPED_TEST) and
[Typed Tests](../advanced.md#typed-tests) for more information.
@ -276,7 +392,8 @@ must be registered with
The argument *`InstantiationName`* is a unique name for the instantiation of the
test suite, to distinguish between multiple instantiations. In test output, the
instantiation name is added as a prefix to the test suite name
*`TestSuiteName`*.
*`TestSuiteName`*. If *`InstantiationName`* is empty
(`INSTANTIATE_TYPED_TEST_SUITE_P(, ...)`), no prefix is added.
The argument *`Types`* is a [`Types`](#Types) object representing the list of
types to run the tests on, for example:
@ -323,7 +440,7 @@ Then the test code should look like:
```cpp
namespace my_namespace {
class MyClassTest : public ::testing::Test {
class MyClassTest : public testing::Test {
...
};
@ -386,7 +503,7 @@ GoogleTest defines the following classes and types to help with writing tests.
### AssertionResult {#AssertionResult}
`::testing::AssertionResult`
`testing::AssertionResult`
A class for indicating whether an assertion was successful.
@ -400,14 +517,14 @@ To create an instance of this class, use one of the factory functions
### AssertionException {#AssertionException}
`::testing::AssertionException`
`testing::AssertionException`
Exception which can be thrown from
[`TestEventListener::OnTestPartResult`](#TestEventListener::OnTestPartResult).
### EmptyTestEventListener {#EmptyTestEventListener}
`::testing::EmptyTestEventListener`
`testing::EmptyTestEventListener`
Provides an empty implementation of all methods in the
[`TestEventListener`](#TestEventListener) interface, such that a subclass only
@ -415,7 +532,7 @@ needs to override the methods it cares about.
### Environment {#Environment}
`::testing::Environment`
`testing::Environment`
Represents a global test environment. See
[Global Set-Up and Tear-Down](../advanced.md#global-set-up-and-tear-down).
@ -436,7 +553,7 @@ Override this to define how to tear down the environment.
### ScopedTrace {#ScopedTrace}
`::testing::ScopedTrace`
`testing::ScopedTrace`
An instance of this class causes a trace to be included in every test failure
message generated by code in the scope of the lifetime of the `ScopedTrace`
@ -452,7 +569,7 @@ ScopedTrace(const char* file, int line, const T& message)
Example usage:
```cpp
::testing::ScopedTrace trace("file.cc", 123, "message");
testing::ScopedTrace trace("file.cc", 123, "message");
```
The resulting trace includes the given source file path and line number, and the
@ -463,7 +580,7 @@ See also [`SCOPED_TRACE`](#SCOPED_TRACE).
### Test {#Test}
`::testing::Test`
`testing::Test`
The abstract class that all tests inherit from. `Test` is not copyable.
@ -551,7 +668,7 @@ after running each individual test.
### TestWithParam {#TestWithParam}
`::testing::TestWithParam<T>`
`testing::TestWithParam<T>`
A convenience class which inherits from both [`Test`](#Test) and
[`WithParamInterface<T>`](#WithParamInterface).
@ -671,7 +788,7 @@ during execution of `SetUpTestSuite` and `TearDownTestSuite`.
### TestInfo {#TestInfo}
`::testing::TestInfo`
`testing::TestInfo`
Stores information about a test.
@ -750,7 +867,7 @@ Returns the result of the test. See [`TestResult`](#TestResult).
### TestParamInfo {#TestParamInfo}
`::testing::TestParamInfo<T>`
`testing::TestParamInfo<T>`
Describes a parameter to a value-parameterized test. The type `T` is the type of
the parameter.
@ -760,7 +877,7 @@ and its integer index respectively.
### UnitTest {#UnitTest}
`::testing::UnitTest`
`testing::UnitTest`
This class contains information about the test program.
@ -928,7 +1045,7 @@ GoogleTest. See [`TestEventListeners`](#TestEventListeners).
### TestEventListener {#TestEventListener}
`::testing::TestEventListener`
`testing::TestEventListener`
The interface for tracing execution of tests. The methods below are listed in
the order the corresponding events are fired.
@ -1026,7 +1143,7 @@ Fired after all test activities have ended.
### TestEventListeners {#TestEventListeners}
`::testing::TestEventListeners`
`testing::TestEventListeners`
Lets users add listeners to track events in GoogleTest.
@ -1071,7 +1188,7 @@ the caller and makes this function return `NULL` the next time.
### TestPartResult {#TestPartResult}
`::testing::TestPartResult`
`testing::TestPartResult`
A copyable object representing the result of a test part (i.e. an assertion or
an explicit `FAIL()`, `ADD_FAILURE()`, or `SUCCESS()`).
@ -1153,7 +1270,7 @@ Returns true if and only if the test part failed.
### TestProperty {#TestProperty}
`::testing::TestProperty`
`testing::TestProperty`
A copyable object representing a user-specified test property which can be
output as a key/value string pair.
@ -1180,7 +1297,7 @@ Sets a new value, overriding the previous one.
### TestResult {#TestResult}
`::testing::TestResult`
`testing::TestResult`
Contains information about the result of a single test.
@ -1261,20 +1378,20 @@ range, aborts the program.
### TimeInMillis {#TimeInMillis}
`::testing::TimeInMillis`
`testing::TimeInMillis`
An integer type representing time in milliseconds.
### Types {#Types}
`::testing::Types<T...>`
`testing::Types<T...>`
Represents a list of types for use in typed tests and type-parameterized tests.
The template argument `T...` can be any number of types, for example:
```
::testing::Types<char, int, unsigned int>
testing::Types<char, int, unsigned int>
```
See [Typed Tests](../advanced.md#typed-tests) and
@ -1283,7 +1400,7 @@ information.
### WithParamInterface {#WithParamInterface}
`::testing::WithParamInterface<T>`
`testing::WithParamInterface<T>`
The pure interface class that all value-parameterized tests inherit from.
@ -1309,14 +1426,16 @@ tests.
### InitGoogleTest {#InitGoogleTest}
`void ::testing::InitGoogleTest(int* argc, char** argv)` \
`void ::testing::InitGoogleTest(int* argc, wchar_t** argv)` \
`void ::testing::InitGoogleTest()`
`void testing::InitGoogleTest(int* argc, char** argv)` \
`void testing::InitGoogleTest(int* argc, wchar_t** argv)` \
`void testing::InitGoogleTest()`
Initializes GoogleTest. This must be called before calling
[`RUN_ALL_TESTS()`](#RUN_ALL_TESTS). In particular, it parses the command line
for the flags that GoogleTest recognizes. Whenever a GoogleTest flag is seen, it
is removed from `argv`, and `*argc` is decremented.
is removed from `argv`, and `*argc` is decremented. Keep in mind that `argv`
must terminate with a `NULL` pointer (i.e. `argv[argc]` is `NULL`), which is
already the case with the default `argv` passed to `main`.
No value is returned. Instead, the GoogleTest flag variables are updated.
@ -1328,7 +1447,7 @@ platforms where there is no `argc`/`argv`.
### AddGlobalTestEnvironment {#AddGlobalTestEnvironment}
`Environment* ::testing::AddGlobalTestEnvironment(Environment* env)`
`Environment* testing::AddGlobalTestEnvironment(Environment* env)`
Adds a test environment to the test program. Must be called before
[`RUN_ALL_TESTS()`](#RUN_ALL_TESTS) is called. See
@ -1341,7 +1460,7 @@ See also [`Environment`](#Environment).
```cpp
template <typename Factory>
TestInfo* ::testing::RegisterTest(const char* test_suite_name, const char* test_name,
TestInfo* testing::RegisterTest(const char* test_suite_name, const char* test_name,
const char* type_param, const char* value_param,
const char* file, int line, Factory factory)
```
@ -1380,27 +1499,27 @@ an all-caps name.
### AssertionSuccess {#AssertionSuccess}
`AssertionResult ::testing::AssertionSuccess()`
`AssertionResult testing::AssertionSuccess()`
Creates a successful assertion result. See
[`AssertionResult`](#AssertionResult).
### AssertionFailure {#AssertionFailure}
`AssertionResult ::testing::AssertionFailure()`
`AssertionResult testing::AssertionFailure()`
Creates a failed assertion result. Use the `<<` operator to store a failure
message:
```cpp
::testing::AssertionFailure() << "My failure message";
testing::AssertionFailure() << "My failure message";
```
See [`AssertionResult`](#AssertionResult).
### StaticAssertTypeEq {#StaticAssertTypeEq}
`::testing::StaticAssertTypeEq<T1, T2>()`
`testing::StaticAssertTypeEq<T1, T2>()`
Compile-time assertion for type equality. Compiles if and only if `T1` and `T2`
are the same type. The value it returns is irrelevant.
@ -1409,7 +1528,7 @@ See [Type Assertions](../advanced.md#type-assertions) for more information.
### PrintToString {#PrintToString}
`std::string ::testing::PrintToString(x)`
`std::string testing::PrintToString(x)`
Prints any value `x` using GoogleTest's value printer.
@ -1419,7 +1538,7 @@ for more information.
### PrintToStringParamName {#PrintToStringParamName}
`std::string ::testing::PrintToStringParamName(TestParamInfo<T>& info)`
`std::string testing::PrintToStringParamName(TestParamInfo<T>& info)`
A built-in parameterized test name generator which returns the result of
[`PrintToString`](#PrintToString) called on `info.param`. Does not work when the