Revise documentation to include AbslStringify
PiperOrigin-RevId: 518039451 Change-Id: Ife548d0f83266746ce1981bea31e70e6b43027c9
This commit is contained in:
Phoebe Liang
Copybara-Service
parent
471087fbfc
commit
3288c4deae
199
docs/advanced.md
199
docs/advanced.md
@ -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
|
||||
|
||||
@ -304,9 +304,9 @@ TEST_F(SkipFixture, SkipsOneTest) {
|
||||
|
||||
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,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
|
||||
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 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++
|
||||
#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 go/abslstringify.
|
||||
|
||||
## Death Tests
|
||||
|
||||
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`?
|
||||
|
||||
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
|
||||
@ -482,14 +505,14 @@ TEST_F(FooDeathTest, DoesThat) {
|
||||
|
||||
### 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
|
||||
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)
|
||||
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
|
||||
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
|
||||
@ -519,7 +542,7 @@ Expression | Meaning
|
||||
`$` | 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
|
||||
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
|
||||
@ -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,
|
||||
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 +615,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`.
|
||||
|
||||
@ -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
|
||||
`HasFatalFailure()` function. They are described in the following two
|
||||
subsections.
|
||||
@ -760,7 +783,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 +875,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,13 +886,13 @@ 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
|
||||
@ -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()`
|
||||
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,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:
|
||||
|
||||
```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
|
||||
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,
|
||||
@ -1501,12 +1524,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 +1672,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 +1735,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 +1746,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,7 +1798,7 @@ 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()`.
|
||||
@ -1808,10 +1831,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 +1865,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 +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
|
||||
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 +1897,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}
|
||||
@ -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.
|
||||
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 +2023,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 +2048,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 +2075,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 +2086,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 +2109,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 +2143,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 +2155,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
|
||||
@ -2362,7 +2385,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 +2393,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 +2433,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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user