Revise documentation to include AbslStringify
PiperOrigin-RevId: 518039451 Change-Id: Ife548d0f83266746ce1981bea31e70e6b43027c9
This commit is contained in:
parent
471087fbfc
commit
3288c4deae
197
docs/advanced.md
197
docs/advanced.md
@ -1,9 +1,9 @@
|
|||||||
# Advanced googletest Topics
|
# Advanced GoogleTest Topics
|
||||||
|
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
Now that you have read the [googletest Primer](primer.md) and learned how to
|
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
|
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
|
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
|
messages, propagate fatal failures, reuse and speed up your test fixtures, and
|
||||||
use various flags with your tests.
|
use various flags with your tests.
|
||||||
@ -25,7 +25,7 @@ Reference.
|
|||||||
|
|
||||||
### Predicate Assertions for Better Error Messages
|
### 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
|
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
|
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
|
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
|
is awkward especially when the expression has side-effects or is expensive to
|
||||||
evaluate.
|
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
|
#### Using an Existing Boolean Function
|
||||||
|
|
||||||
@ -304,9 +304,9 @@ TEST_F(SkipFixture, SkipsOneTest) {
|
|||||||
|
|
||||||
As with assertion macros, you can stream a custom message into `GTEST_SKIP()`.
|
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.
|
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
|
This printer knows how to print built-in C++ types, native arrays, STL
|
||||||
@ -315,73 +315,96 @@ 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
|
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
|
to do a better job at printing your particular type than to dump the bytes. To
|
||||||
do that, define `<<` for your type:
|
do that, define an `AbslStringify()` overload as a `friend` function template
|
||||||
|
for your type:
|
||||||
```c++
|
|
||||||
#include <ostream>
|
|
||||||
|
|
||||||
|
```cpp
|
||||||
namespace foo {
|
namespace foo {
|
||||||
|
|
||||||
class Bar { // We want googletest to be able to print instances of this.
|
class Point { // We want GoogleTest to be able to print instances of this.
|
||||||
...
|
...
|
||||||
// Create a free inline friend function.
|
// Provide a friend overload.
|
||||||
friend std::ostream& operator<<(std::ostream& os, const Bar& bar) {
|
template <typename Sink>
|
||||||
return os << bar.DebugString(); // whatever needed to print bar to os
|
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
|
// 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
|
// AbslStringify overload is defined in the SAME namespace that defines Point.
|
||||||
// rules rely on that.
|
// C++'s look-up rules rely on that.
|
||||||
std::ostream& operator<<(std::ostream& os, const Bar& bar) {
|
enum class EnumWithStringify { kMany = 0, kChoices = 1 };
|
||||||
return os << bar.DebugString(); // whatever needed to print bar to os
|
|
||||||
|
template <typename Sink>
|
||||||
|
void AbslStringify(Sink& sink, EnumWithStringify e) {
|
||||||
|
absl::Format(&sink, "%s", e == EnumWithStringify::kMany ? "Many" : "Choices");
|
||||||
}
|
}
|
||||||
|
|
||||||
} // namespace foo
|
} // namespace foo
|
||||||
```
|
```
|
||||||
|
|
||||||
Sometimes, this might not be an option: your team may consider it bad style to
|
{: .callout .note}
|
||||||
have a `<<` operator for `Bar`, or `Bar` may already have a `<<` operator that
|
Note: `AbslStringify()` utilizes a generic "sink" buffer to construct its
|
||||||
doesn't do what you want (and you cannot change it). If so, you can instead
|
string. For more information about supported operations on `AbslStringify()`'s
|
||||||
define a `PrintTo()` function like this:
|
sink, see go/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++
|
```c++
|
||||||
#include <ostream>
|
#include <ostream>
|
||||||
|
|
||||||
namespace foo {
|
namespace foo {
|
||||||
|
|
||||||
class Bar {
|
class Point {
|
||||||
...
|
...
|
||||||
friend void PrintTo(const Bar& bar, std::ostream* os) {
|
friend void PrintTo(const Point& point, std::ostream* os) {
|
||||||
*os << bar.DebugString(); // whatever needed to print bar to 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()
|
// 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
|
// is defined in the SAME namespace that defines Point. C++'s look-up rules
|
||||||
// on that.
|
// rely on that.
|
||||||
void PrintTo(const Bar& bar, std::ostream* os) {
|
void PrintTo(const Point& point, std::ostream* os) {
|
||||||
*os << bar.DebugString(); // whatever needed to print bar to os
|
*os << "(" << point.x << "," << point.y << ")";
|
||||||
}
|
}
|
||||||
|
|
||||||
} // namespace foo
|
} // namespace foo
|
||||||
```
|
```
|
||||||
|
|
||||||
If you have defined both `<<` and `PrintTo()`, the latter will be used when
|
If you have defined both `AbslStringify()` and `PrintTo()`, the latter will be
|
||||||
googletest is concerned. This allows you to customize how the value appears in
|
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 its
|
GoogleTest's output without affecting code that relies on the behavior of
|
||||||
`<<` operator.
|
`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`:
|
call `::testing::PrintToString(x)`, which returns an `std::string`:
|
||||||
|
|
||||||
```c++
|
```c++
|
||||||
vector<pair<Bar, int> > bar_ints = GetBarIntVector();
|
vector<pair<Point, int> > point_ints = GetPointIntVector();
|
||||||
|
|
||||||
EXPECT_TRUE(IsCorrectBarIntVector(bar_ints))
|
EXPECT_TRUE(IsCorrectPointIntVector(point_ints))
|
||||||
<< "bar_ints = " << testing::PrintToString(bar_ints);
|
<< "point_ints = " << testing::PrintToString(point_ints);
|
||||||
```
|
```
|
||||||
|
|
||||||
|
For more details regarding `AbslStringify()` and its integration with other
|
||||||
|
libraries, see go/abslstringify.
|
||||||
|
|
||||||
## Death Tests
|
## Death Tests
|
||||||
|
|
||||||
In many applications, there are assertions that can cause application failure if
|
In many applications, there are assertions that can cause application failure if
|
||||||
@ -451,7 +474,7 @@ Note that a death test only cares about three things:
|
|||||||
3. does the stderr output match `matcher`?
|
3. does the stderr output match `matcher`?
|
||||||
|
|
||||||
In particular, if `statement` generates an `ASSERT_*` or `EXPECT_*` failure, it
|
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.
|
the process.
|
||||||
|
|
||||||
### Death Test Naming
|
### Death Test Naming
|
||||||
@ -482,14 +505,14 @@ TEST_F(FooDeathTest, DoesThat) {
|
|||||||
|
|
||||||
### Regular Expression Syntax
|
### Regular Expression Syntax
|
||||||
|
|
||||||
When built with Bazel and using Abseil, googletest uses the
|
When built with Bazel and using Abseil, GoogleTest uses the
|
||||||
[RE2](https://github.com/google/re2/wiki/Syntax) syntax. Otherwise, for POSIX
|
[RE2](https://github.com/google/re2/wiki/Syntax) syntax. Otherwise, for POSIX
|
||||||
systems (Linux, Cygwin, Mac), googletest uses the
|
systems (Linux, Cygwin, Mac), GoogleTest uses the
|
||||||
[POSIX extended regular expression](http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html#tag_09_04)
|
[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
|
syntax. To learn about POSIX syntax, you may want to read this
|
||||||
[Wikipedia entry](http://en.wikipedia.org/wiki/Regular_expression#POSIX_extended).
|
[Wikipedia entry](http://en.wikipedia.org/wiki/Regular_expression#POSIX_extended).
|
||||||
|
|
||||||
On Windows, googletest uses its own simple regular expression implementation. It
|
On Windows, GoogleTest uses its own simple regular expression implementation. It
|
||||||
lacks many features. For example, we don't support union (`"x|y"`), grouping
|
lacks many features. For example, we don't support union (`"x|y"`), grouping
|
||||||
(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among
|
(`"(xy)"`), brackets (`"[xy]"`), and repetition count (`"x{5,7}"`), among
|
||||||
others. Below is what we do support (`A` denotes a literal character, period
|
others. Below is what we do support (`A` denotes a literal character, period
|
||||||
@ -519,7 +542,7 @@ Expression | Meaning
|
|||||||
`$` | matches the end 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`
|
`xy` | matches `x` followed by `y`
|
||||||
|
|
||||||
To help you determine which capability is available on your system, googletest
|
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:
|
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
|
`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
|
tests to work in all cases, you can either `#if` on these macros or use the more
|
||||||
@ -539,7 +562,7 @@ arrange that kind of environment. For example, statically-initialized modules
|
|||||||
may start threads before main is ever reached. Once threads have been created,
|
may start threads before main is ever reached. Once threads have been created,
|
||||||
it may be difficult or impossible to clean them up.
|
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
|
1. A warning is emitted if multiple threads are running when a death test is
|
||||||
encountered.
|
encountered.
|
||||||
@ -592,7 +615,7 @@ TEST(MyDeathTest, TestTwo) {
|
|||||||
|
|
||||||
The `statement` argument of `ASSERT_EXIT()` can be any valid C++ statement. If
|
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
|
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
|
may return from the current function (e.g. `ASSERT_TRUE()`), so be sure to avoid
|
||||||
them in `statement`.
|
them in `statement`.
|
||||||
|
|
||||||
@ -726,7 +749,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
|
either exceptions, the `(ASSERT|EXPECT)_NO_FATAL_FAILURE` assertions or the
|
||||||
`HasFatalFailure()` function. They are described in the following two
|
`HasFatalFailure()` function. They are described in the following two
|
||||||
subsections.
|
subsections.
|
||||||
@ -760,7 +783,7 @@ in it, the test will continue after the subroutine returns. This may not be what
|
|||||||
you want.
|
you want.
|
||||||
|
|
||||||
Often people want fatal failures to propagate like exceptions. For that
|
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
|
Fatal assertion | Nonfatal assertion | Verifies
|
||||||
------------------------------------- | ------------------------------------- | --------
|
------------------------------------- | ------------------------------------- | --------
|
||||||
@ -852,7 +875,7 @@ will output XML like this:
|
|||||||
> needs to be prefixed with `::testing::Test::` if used outside of the
|
> needs to be prefixed with `::testing::Test::` if used outside of the
|
||||||
> `TEST` body and the test fixture class.
|
> `TEST` body and the test fixture class.
|
||||||
> * *`key`* must be a valid XML attribute name, and cannot conflict with the
|
> * *`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`).
|
> `type_param`, and `value_param`).
|
||||||
> * Calling `RecordProperty()` outside of the lifespan of a test is allowed.
|
> * 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
|
> If it's called outside of a test but between a test suite's
|
||||||
@ -863,13 +886,13 @@ will output XML like this:
|
|||||||
|
|
||||||
## Sharing Resources Between Tests in the Same Test Suite
|
## 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
|
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
|
that are expensive to set up, making the one-copy-per-test model prohibitively
|
||||||
expensive.
|
expensive.
|
||||||
|
|
||||||
If the tests don't change the resource, there's no harm in their sharing a
|
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:
|
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
|
1. In your test fixture class (say `FooTest` ), declare as `static` some member
|
||||||
@ -881,7 +904,7 @@ also supports per-test-suite set-up/tear-down. To use it:
|
|||||||
`u`!) to set up the shared resources and a `static void TearDownTestSuite()`
|
`u`!) to set up the shared resources and a `static void TearDownTestSuite()`
|
||||||
function to tear them down.
|
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
|
*first test* in the `FooTest` test suite (i.e. before creating the first
|
||||||
`FooTest` object), and calls `TearDownTestSuite()` after running the *last test*
|
`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
|
in it (i.e. after deleting the last `FooTest` object). In between, the tests can
|
||||||
@ -974,7 +997,7 @@ 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:
|
calling the `::testing::AddGlobalTestEnvironment()` function:
|
||||||
|
|
||||||
```c++
|
```c++
|
||||||
@ -991,7 +1014,7 @@ 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
|
will be called in the order they are registered, and their `TearDown()` will be
|
||||||
called in the reverse order.
|
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.
|
Therefore **do not delete them** by yourself.
|
||||||
|
|
||||||
You should call `AddGlobalTestEnvironment()` before `RUN_ALL_TESTS()` is called,
|
You should call `AddGlobalTestEnvironment()` before `RUN_ALL_TESTS()` is called,
|
||||||
@ -1501,12 +1524,12 @@ To test them, we use the following special techniques:
|
|||||||
|
|
||||||
## "Catching" Failures
|
## "Catching" Failures
|
||||||
|
|
||||||
If you are building a testing utility on top of googletest, you'll want to test
|
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.
|
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.
|
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
|
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?
|
we test that a piece of code generates an expected failure?
|
||||||
|
|
||||||
`"gtest/gtest-spi.h"` contains some constructs to do this.
|
`"gtest/gtest-spi.h"` contains some constructs to do this.
|
||||||
@ -1649,9 +1672,9 @@ particular, you cannot find the test suite name in `SetUpTestSuite()`,
|
|||||||
`TearDownTestSuite()` (where you know the test suite name implicitly), or
|
`TearDownTestSuite()` (where you know the test suite name implicitly), or
|
||||||
functions called from them.
|
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
|
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
|
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
|
method, among others. You may use this API to augment or replace the standard
|
||||||
@ -1712,7 +1735,7 @@ Here's an example:
|
|||||||
### Using Event Listeners
|
### Using Event Listeners
|
||||||
|
|
||||||
To use the event listener you have defined, add an instance of it to the
|
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"
|
[`TestEventListeners`](reference/testing.md#TestEventListeners) - note the "s"
|
||||||
at the end of the name) in your `main()` function, before calling
|
at the end of the name) in your `main()` function, before calling
|
||||||
`RUN_ALL_TESTS()`:
|
`RUN_ALL_TESTS()`:
|
||||||
@ -1723,7 +1746,7 @@ int main(int argc, char** argv) {
|
|||||||
// Gets hold of the event listener list.
|
// Gets hold of the event listener list.
|
||||||
testing::TestEventListeners& listeners =
|
testing::TestEventListeners& listeners =
|
||||||
testing::UnitTest::GetInstance()->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);
|
listeners.Append(new MinimalistPrinter);
|
||||||
return RUN_ALL_TESTS();
|
return RUN_ALL_TESTS();
|
||||||
}
|
}
|
||||||
@ -1775,7 +1798,7 @@ See [sample10_unittest.cc] for an example of a failure-raising listener.
|
|||||||
|
|
||||||
## Running Test Programs: Advanced Options
|
## 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
|
directly and affect their behavior via the following environment variables
|
||||||
and/or command line flags. For the flags to work, your programs must call
|
and/or command line flags. For the flags to work, your programs must call
|
||||||
`::testing::InitGoogleTest()` before calling `RUN_ALL_TESTS()`.
|
`::testing::InitGoogleTest()` before calling `RUN_ALL_TESTS()`.
|
||||||
@ -1808,10 +1831,10 @@ corresponding environment variable for this flag.
|
|||||||
|
|
||||||
#### Running a Subset of the Tests
|
#### 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
|
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
|
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.
|
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
|
The format of a filter is a '`:`'-separated list of wildcard patterns (called
|
||||||
@ -1842,7 +1865,7 @@ For example:
|
|||||||
|
|
||||||
#### Stop test execution upon first failure
|
#### 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
|
cases (e.g. iterative test development & execution) it may be desirable stop
|
||||||
test execution upon first failure (trading improved latency for completeness).
|
test execution upon first failure (trading improved latency for completeness).
|
||||||
If `GTEST_FAIL_FAST` environment variable or `--gtest_fail_fast` flag is set,
|
If `GTEST_FAIL_FAST` environment variable or `--gtest_fail_fast` flag is set,
|
||||||
@ -1859,7 +1882,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
|
to the front of the name of each test, or alternatively add it to the front of
|
||||||
the test suite name.
|
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:
|
will still be compiled:
|
||||||
|
|
||||||
```c++
|
```c++
|
||||||
@ -1874,7 +1897,7 @@ TEST_F(DISABLED_BarTest, DoesXyz) { ... }
|
|||||||
|
|
||||||
{: .callout .note}
|
{: .callout .note}
|
||||||
NOTE: This feature should only be used for temporary pain-relief. You still have
|
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.
|
a banner warning you if a test program contains any disabled tests.
|
||||||
|
|
||||||
{: .callout .tip}
|
{: .callout .tip}
|
||||||
@ -1932,16 +1955,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.
|
environment variable to `1`) to run the tests in a program in a random order.
|
||||||
This helps to reveal bad dependencies between tests.
|
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
|
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
|
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`
|
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
|
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
|
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.
|
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.
|
random seed and re-shuffle the tests in each iteration.
|
||||||
|
|
||||||
### Distributing Test Functions to Multiple Machines
|
### Distributing Test Functions to Multiple Machines
|
||||||
@ -2000,7 +2023,7 @@ shards, but here's one possible scenario:
|
|||||||
|
|
||||||
#### Colored Terminal Output
|
#### 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:
|
important information:
|
||||||
|
|
||||||
<pre>...
|
<pre>...
|
||||||
@ -2025,25 +2048,25 @@ important information:
|
|||||||
|
|
||||||
You can set the `GTEST_COLOR` environment variable or the `--gtest_color`
|
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,
|
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
|
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`.
|
platforms) the `TERM` environment variable is set to `xterm` or `xterm-color`.
|
||||||
|
|
||||||
#### Suppressing test passes
|
#### 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
|
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`.
|
`--gtest_brief=1`, or set the GTEST_BRIEF environment variable to `1`.
|
||||||
|
|
||||||
#### Suppressing the Elapsed Time
|
#### 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
|
that, run the test program with the `--gtest_print_time=0` command line flag, or
|
||||||
set the GTEST_PRINT_TIME environment variable to `0`.
|
set the GTEST_PRINT_TIME environment variable to `0`.
|
||||||
|
|
||||||
#### Suppressing UTF-8 Text Output
|
#### 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
|
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
|
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
|
text because, for example, you don't have an UTF-8 compatible output medium, run
|
||||||
@ -2052,7 +2075,7 @@ environment variable to `0`.
|
|||||||
|
|
||||||
#### Generating an XML Report
|
#### 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
|
textual output. The report contains the duration of each test, and thus can help
|
||||||
you identify slow tests.
|
you identify slow tests.
|
||||||
|
|
||||||
@ -2063,15 +2086,15 @@ in which case the output can be found in the `test_detail.xml` file in the
|
|||||||
current directory.
|
current directory.
|
||||||
|
|
||||||
If you specify a directory (for example, `"xml:output/directory/"` on Linux or
|
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
|
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
|
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.
|
`foo_test_1.xml`) to avoid overwriting it.
|
||||||
|
|
||||||
The report is based on the `junitreport` Ant task. Since that format was
|
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
|
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
|
```xml
|
||||||
<testsuites name="AllTests" ...>
|
<testsuites name="AllTests" ...>
|
||||||
@ -2086,8 +2109,8 @@ apply to googletest tests, as shown here:
|
|||||||
```
|
```
|
||||||
|
|
||||||
* The root `<testsuites>` element corresponds to the entire test program.
|
* The root `<testsuites>` element corresponds to the entire test program.
|
||||||
* `<testsuite>` elements correspond to googletest test suites.
|
* `<testsuite>` elements correspond to GoogleTest test suites.
|
||||||
* `<testcase>` elements correspond to googletest test functions.
|
* `<testcase>` elements correspond to GoogleTest test functions.
|
||||||
|
|
||||||
For instance, the following program
|
For instance, the following program
|
||||||
|
|
||||||
@ -2120,7 +2143,7 @@ could generate this report:
|
|||||||
Things to note:
|
Things to note:
|
||||||
|
|
||||||
* The `tests` attribute of a `<testsuites>` or `<testsuite>` element tells how
|
* 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.
|
`failures` attribute tells how many of them failed.
|
||||||
|
|
||||||
* The `time` attribute expresses the duration of the test, test suite, or
|
* The `time` attribute expresses the duration of the test, test suite, or
|
||||||
@ -2132,12 +2155,12 @@ Things to note:
|
|||||||
* The `file` and `line` attributes record the source file location, where the
|
* The `file` and `line` attributes record the source file location, where the
|
||||||
test was defined.
|
test was defined.
|
||||||
|
|
||||||
* Each `<failure>` element corresponds to a single failed googletest
|
* Each `<failure>` element corresponds to a single failed GoogleTest
|
||||||
assertion.
|
assertion.
|
||||||
|
|
||||||
#### Generating a JSON Report
|
#### 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
|
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
|
`--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
|
create the file at the given location. You can also just use the string
|
||||||
@ -2362,7 +2385,7 @@ variable has been set.
|
|||||||
|
|
||||||
When running test programs under a debugger, it's very convenient if the
|
When running test programs under a debugger, it's very convenient if the
|
||||||
debugger can catch an assertion failure and automatically drop into interactive
|
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
|
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`
|
other than `0`. Alternatively, you can use the `--gtest_break_on_failure`
|
||||||
@ -2370,9 +2393,9 @@ command line flag.
|
|||||||
|
|
||||||
#### Disabling Catching Test-Thrown Exceptions
|
#### 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
|
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
|
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
|
uncaught exception will cause a pop-up window, so catching the exceptions allows
|
||||||
you to run the tests automatically.
|
you to run the tests automatically.
|
||||||
@ -2410,4 +2433,4 @@ void __tsan_on_report() {
|
|||||||
```
|
```
|
||||||
|
|
||||||
After compiling your project with one of the sanitizers enabled, if a particular
|
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.
|
||||||
|
Loading…
Reference in New Issue
Block a user