gitMirror/googletest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Googletest export

Browse Source 
Create Assertions Reference

PiperOrigin-RevId: 375824718
This commit is contained in:
Abseil Team 2021-05-25 19:49:11 -04:00 committed by Andy Soffer
parent 8ceecc27c7
commit d5d6ff940b
7 changed files with 704 additions and 581 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/_data/navigation.yml
View File

@ -21,6 +21,8 @@ nav:
url: "/gmock_cheat_sheet.html" url: "/gmock_cheat_sheet.html"
- section: "References" - section: "References"
items: items:
- title: "Assertions"
url: "/reference/assertions.html"
- title: "Matchers" - title: "Matchers"
url: "/reference/matchers.html" url: "/reference/matchers.html"
- title: "Actions" - title: "Actions"

413
docs/advanced.md
View File

@ -15,71 +15,13 @@ assertions.
### Explicit Success and Failure ### Explicit Success and Failure
These three assertions do not actually test a value or expression. Instead, they See [Explicit Success and Failure](reference/assertions.md#success-failure) in
generate a success or failure directly. Like the macros that actually perform a the Assertions Reference.
test, you may stream a custom failure message into them.
```c++
SUCCEED();
```
Generates a success. This does **NOT** make the overall test succeed. A test is
considered successful only if none of its assertions fail during its execution.
{: .callout .note}
NOTE: `SUCCEED()` is purely documentary and currently doesn't generate any
user-visible output. However, we may add `SUCCEED()` messages to googletest's
output in the future.
```c++
FAIL();
ADD_FAILURE();
ADD_FAILURE_AT("file_path", line_number);
```
`FAIL()` generates a fatal failure, while `ADD_FAILURE()` and `ADD_FAILURE_AT()`
generate a nonfatal failure. These are useful when control flow, rather than a
Boolean expression, determines the test's success or failure. For example, you
might want to write something like:
```c++
switch(expression) {
case 1:
... some checks ...
case 2:
... some other checks ...
default:
FAIL() << "We shouldn't get here.";
}
```
{: .callout .note}
NOTE: you can only use `FAIL()` in functions that return `void`. See the
[Assertion Placement section](#assertion-placement) for more information.
### Exception Assertions ### Exception Assertions
These are for verifying that a piece of code throws (or does not throw) an See [Exception Assertions](reference/assertions.md#exceptions) in the Assertions
exception of the given type: Reference.
Fatal assertion | Nonfatal assertion | Verifies
------------------------------------------ | ------------------------------------------ | --------
`ASSERT_THROW(statement, exception_type);` | `EXPECT_THROW(statement, exception_type);` | `statement` throws an exception of the given type
`ASSERT_ANY_THROW(statement);` | `EXPECT_ANY_THROW(statement);` | `statement` throws an exception of any type
`ASSERT_NO_THROW(statement);` | `EXPECT_NO_THROW(statement);` | `statement` doesn't throw any exception
Examples:
```c++
ASSERT_THROW(Foo(5), bar_exception);
EXPECT_NO_THROW({
int n = 5;
Bar(&n);
});
```
**Availability**: requires exceptions to be enabled in the build environment
### Predicate Assertions for Better Error Messages ### Predicate Assertions for Better Error Messages
@ -99,59 +41,9 @@ googletest gives you three different options to solve this problem:
If you already have a function or functor that returns `bool` (or a type that If you already have a function or functor that returns `bool` (or a type that
can be implicitly converted to `bool`), you can use it in a *predicate can be implicitly converted to `bool`), you can use it in a *predicate
assertion* to get the function arguments printed for free: assertion* to get the function arguments printed for free. See
[`EXPECT_PRED*`](reference/assertions.md#EXPECT_PRED) in the Assertions
Reference for details.
| Fatal assertion | Nonfatal assertion | Verifies |
| --------------------------------- | --------------------------------- | --------------------------- |
| `ASSERT_PRED1(pred1, val1)` | `EXPECT_PRED1(pred1, val1)` | `pred1(val1)` is true |
| `ASSERT_PRED2(pred2, val1, val2)` | `EXPECT_PRED2(pred2, val1, val2)` | `pred2(val1, val2)` is true |
| `...` | `...` | `...` |
In the above, `predn` is an `n`-ary predicate function or functor, where `val1`,
`val2`, ..., and `valn` are its arguments. The assertion succeeds if the
predicate returns `true` when applied to the given arguments, and fails
otherwise. When the assertion fails, it prints the value of each argument. In
either case, the arguments are evaluated exactly once.
Here's an example. Given
```c++
// Returns true if m and n have no common divisors except 1.
bool MutuallyPrime(int m, int n) { ... }
const int a = 3;
const int b = 4;
const int c = 10;
```
the assertion
```c++
EXPECT_PRED2(MutuallyPrime, a, b);
```
will succeed, while the assertion
```c++
EXPECT_PRED2(MutuallyPrime, b, c);
```
will fail with the message
```none
MutuallyPrime(b, c) is false, where
b is 4
c is 10
```
{: .callout .note}
> NOTE:
>
> 1. If you see a compiler error "no matching function to call" when using
> `ASSERT_PRED*` or `EXPECT_PRED*`, please see
> [this](faq.md#the-compiler-complains-no-matching-function-to-call-when-i-use-assert_pred-how-do-i-fix-it)
> for how to resolve it.
#### Using a Function That Returns an AssertionResult #### Using a Function That Returns an AssertionResult
@ -242,157 +134,40 @@ Then the statement `EXPECT_FALSE(IsEven(Fib(6)))` will print
#### Using a Predicate-Formatter #### Using a Predicate-Formatter
If you find the default message generated by `(ASSERT|EXPECT)_PRED*` and If you find the default message generated by
`(ASSERT|EXPECT)_(TRUE|FALSE)` unsatisfactory, or some arguments to your [`EXPECT_PRED*`](reference/assertions.md#EXPECT_PRED) and
predicate do not support streaming to `ostream`, you can instead use the [`EXPECT_TRUE`](reference/assertions.md#EXPECT_TRUE) unsatisfactory, or some
following *predicate-formatter assertions* to *fully* customize how the message arguments to your predicate do not support streaming to `ostream`, you can
is formatted: instead use *predicate-formatter assertions* to *fully* customize how the
message is formatted. See
Fatal assertion | Nonfatal assertion | Verifies [`EXPECT_PRED_FORMAT*`](reference/assertions.md#EXPECT_PRED_FORMAT) in the
------------------------------------------------ | ------------------------------------------------ | -------- Assertions Reference for details.
`ASSERT_PRED_FORMAT1(pred_format1, val1);` | `EXPECT_PRED_FORMAT1(pred_format1, val1);` | `pred_format1(val1)` is successful
`ASSERT_PRED_FORMAT2(pred_format2, val1, val2);` | `EXPECT_PRED_FORMAT2(pred_format2, val1, val2);` | `pred_format2(val1, val2)` is successful
`...` | `...` | ...
The difference between this and the previous group of macros is that instead of
a predicate, `(ASSERT|EXPECT)_PRED_FORMAT*` take a *predicate-formatter*
(`pred_formatn`), which is a function or functor with the signature:
```c++
testing::AssertionResult PredicateFormattern(const char* expr1,
const char* expr2,
...
const char* exprn,
T1 val1,
T2 val2,
...
Tn valn);
```
where `val1`, `val2`, ..., and `valn` are the values of the predicate arguments,
and `expr1`, `expr2`, ..., and `exprn` are the corresponding expressions as they
appear in the source code. The types `T1`, `T2`, ..., and `Tn` can be either
value types or reference types. For example, if an argument has type `Foo`, you
can declare it as either `Foo` or `const Foo&`, whichever is appropriate.
As an example, let's improve the failure message in `MutuallyPrime()`, which was
used with `EXPECT_PRED2()`:
```c++
// Returns the smallest prime common divisor of m and n,
// or 1 when m and n are mutually prime.
int SmallestPrimeCommonDivisor(int m, int n) { ... }
// A predicate-formatter for asserting that two integers are mutually prime.
testing::AssertionResult AssertMutuallyPrime(const char* m_expr,
const char* n_expr,
int m,
int n) {
if (MutuallyPrime(m, n)) return testing::AssertionSuccess();
return testing::AssertionFailure() << m_expr << " and " << n_expr
<< " (" << m << " and " << n << ") are not mutually prime, "
<< "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n);
}
```
With this predicate-formatter, we can use
```c++
EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c);
```
to generate the message
```none
b and c (4 and 10) are not mutually prime, as they have a common divisor 2.
```
As you may have realized, many of the built-in assertions we introduced earlier
are special cases of `(EXPECT|ASSERT)_PRED_FORMAT*`. In fact, most of them are
indeed defined using `(EXPECT|ASSERT)_PRED_FORMAT*`.
### Floating-Point Comparison ### Floating-Point Comparison
Comparing floating-point numbers is tricky. Due to round-off errors, it is very See [Floating-Point Comparison](reference/assertions.md#floating-point) in the
unlikely that two floating-points will match exactly. Therefore, `ASSERT_EQ` 's Assertions Reference.
naive comparison usually doesn't work. And since floating-points can have a wide
value range, no single fixed error bound works. It's better to compare by a
fixed relative error bound, except for values close to 0 due to the loss of
precision there.
In general, for floating-point comparison to make sense, the user needs to
carefully choose the error bound. If they don't want or care to, comparing in
terms of Units in the Last Place (ULPs) is a good default, and googletest
provides assertions to do this. Full details about ULPs are quite long; if you
want to learn more, see
[here](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/).
#### Floating-Point Macros
| Fatal assertion | Nonfatal assertion | Verifies |
| ------------------------------- | ------------------------------- | ---------------------------------------- |
| `ASSERT_FLOAT_EQ(val1, val2);` | `EXPECT_FLOAT_EQ(val1, val2);` | the two `float` values are almost equal |
| `ASSERT_DOUBLE_EQ(val1, val2);` | `EXPECT_DOUBLE_EQ(val1, val2);` | the two `double` values are almost equal |
By "almost equal" we mean the values are within 4 ULP's from each other.
The following assertions allow you to choose the acceptable error bound:
| Fatal assertion | Nonfatal assertion | Verifies |
| ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- |
| `ASSERT_NEAR(val1, val2, abs_error);` | `EXPECT_NEAR(val1, val2, abs_error);` | the difference between `val1` and `val2` doesn't exceed the given absolute error |
#### Floating-Point Predicate-Format Functions #### Floating-Point Predicate-Format Functions
Some floating-point operations are useful, but not that often used. In order to Some floating-point operations are useful, but not that often used. In order to
avoid an explosion of new macros, we provide them as predicate-format functions avoid an explosion of new macros, we provide them as predicate-format functions
that can be used in predicate assertion macros (e.g. `EXPECT_PRED_FORMAT2`, that can be used in the predicate assertion macro
etc). [`EXPECT_PRED_FORMAT2`](reference/assertions.md#EXPECT_PRED_FORMAT), for
example:
```c++ ```c++
EXPECT_PRED_FORMAT2(testing::FloatLE, val1, val2); EXPECT_PRED_FORMAT2(testing::FloatLE, val1, val2);
EXPECT_PRED_FORMAT2(testing::DoubleLE, val1, val2); EXPECT_PRED_FORMAT2(testing::DoubleLE, val1, val2);
``` ```
Verifies that `val1` is less than, or almost equal to, `val2`. You can replace The above code verifies that `val1` is less than, or approximately equal to,
`EXPECT_PRED_FORMAT2` in the above table with `ASSERT_PRED_FORMAT2`. `val2`.
### Asserting Using gMock Matchers ### Asserting Using gMock Matchers
gMock comes with a library of *matchers* for validating arguments passed to mock See [`EXPECT_THAT`](reference/assertions.md#EXPECT_THAT) in the Assertions
objects. A gMock matcher is basically a predicate that knows how to describe Reference.
itself. It can be used in these assertion macros:
| Fatal assertion | Nonfatal assertion | Verifies |
| ------------------------------ | ------------------------------ | --------------------- |
| `ASSERT_THAT(value, matcher);` | `EXPECT_THAT(value, matcher);` | value matches matcher |
For example, `StartsWith(prefix)` is a matcher that matches a string starting
with `prefix`, and you can write:
```c++
using ::testing::StartsWith;
...
// Verifies that Foo() returns a string starting with "Hello".
EXPECT_THAT(Foo(), StartsWith("Hello"));
```
See
[Using Matchers in googletest Assertions](gmock_cook_book.md#using-matchers-in-googletest-assertions)
in the gMock Cookbook for more details. For a list of built-in matchers, see the
[Matchers Reference](reference/matchers.md). You can also write your own
matchers—see [Writing New Matchers Quickly](gmock_cook_book.md#NewMatchers).
gMock is bundled with googletest, so you don't need to add any build dependency
in order to take advantage of this. Just include `"gmock/gmock.h"`
and you're ready to go.
### More String Assertions ### More String Assertions
@ -400,8 +175,9 @@ and you're ready to go.
you haven't.) you haven't.)
You can use the gMock [string matchers](reference/matchers.md#string-matchers) You can use the gMock [string matchers](reference/matchers.md#string-matchers)
with `EXPECT_THAT()` or `ASSERT_THAT()` to do more string comparison tricks with [`EXPECT_THAT`](reference/assertions.md#EXPECT_THAT) to do more string
(sub-string, prefix, suffix, regular expression, and etc). For example, comparison tricks (sub-string, prefix, suffix, regular expression, and etc). For
example,
```c++ ```c++
using ::testing::HasSubstr; using ::testing::HasSubstr;
@ -413,24 +189,8 @@ using ::testing::MatchesRegex;
### Windows HRESULT assertions ### Windows HRESULT assertions
These assertions test for `HRESULT` success or failure. See [Windows HRESULT Assertions](reference/assertions.md#HRESULT) in the
Assertions Reference.
Fatal assertion | Nonfatal assertion | Verifies
-------------------------------------- | -------------------------------------- | --------
`ASSERT_HRESULT_SUCCEEDED(expression)` | `EXPECT_HRESULT_SUCCEEDED(expression)` | `expression` is a success `HRESULT`
`ASSERT_HRESULT_FAILED(expression)` | `EXPECT_HRESULT_FAILED(expression)` | `expression` is a failure `HRESULT`
The generated output contains the human-readable error message associated with
the `HRESULT` code returned by `expression`.
You might use them like this:
```c++
CComPtr<IShellDispatch2> shell;
ASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application"));
CComVariant empty;
ASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty));
```
### Type Assertions ### Type Assertions
@ -644,71 +404,12 @@ If you want to test `EXPECT_*()/ASSERT_*()` failures in your test code, see
### How to Write a Death Test ### How to Write a Death Test
googletest has the following macros to support death tests: GoogleTest provides assertion macros to support death tests. See
[Death Assertions](reference/assertions.md#death) in the Assertions Reference
for details.
Fatal assertion | Nonfatal assertion | Verifies To write a death test, simply use one of the macros inside your test function.
------------------------------------------------ | ------------------------------------------------ | -------- For example,
`ASSERT_DEATH(statement, matcher);` | `EXPECT_DEATH(statement, matcher);` | `statement` crashes with the given error
`ASSERT_DEATH_IF_SUPPORTED(statement, matcher);` | `EXPECT_DEATH_IF_SUPPORTED(statement, matcher);` | if death tests are supported, verifies that `statement` crashes with the given error; otherwise verifies nothing
`ASSERT_DEBUG_DEATH(statement, matcher);` | `EXPECT_DEBUG_DEATH(statement, matcher);` | `statement` crashes with the given error **in debug mode**. When not in debug (i.e. `NDEBUG` is defined), this just executes `statement`
`ASSERT_EXIT(statement, predicate, matcher);` | `EXPECT_EXIT(statement, predicate, matcher);` | `statement` exits with the given error, and its exit code matches `predicate`
where `statement` is a statement that is expected to cause the process to die,
`predicate` is a function or function object that evaluates an integer exit
status, and `matcher` is either a gMock matcher matching a `const std::string&`
or a (Perl) regular expression - either of which is matched against the stderr
output of `statement`. For legacy reasons, a bare string (i.e. with no matcher)
is interpreted as `ContainsRegex(str)`, **not** `Eq(str)`. Note that `statement`
can be *any valid statement* (including *compound statement*) and doesn't have
to be an expression.
As usual, the `ASSERT` variants abort the current test function, while the
`EXPECT` variants do not.
{: .callout .note}
> NOTE: We use the word "crash" here to mean that the process terminates with a
> *non-zero* exit status code. There are two possibilities: either the process
> has called `exit()` or `_exit()` with a non-zero value, or it may be killed by
> a signal.
>
> This means that if *`statement`* terminates the process with a 0 exit code, it
> is *not* considered a crash by `EXPECT_DEATH`. Use `EXPECT_EXIT` instead if
> this is the case, or if you want to restrict the exit code more precisely.
A predicate here must accept an `int` and return a `bool`. The death test
succeeds only if the predicate returns `true`. googletest defines a few
predicates that handle the most common cases:
```c++
::testing::ExitedWithCode(exit_code)
```
This expression is `true` if the program exited normally with the given exit
code.
```c++
testing::KilledBySignal(signal_number) // Not available on Windows.
```
This expression is `true` if the program was killed by the given signal.
The `*_DEATH` macros are convenient wrappers for `*_EXIT` that use a predicate
that verifies the process' exit code is non-zero.
Note that a death test only cares about three things:
1. does `statement` abort or exit the process?
2. (in the case of `ASSERT_EXIT` and `EXPECT_EXIT`) does the exit status
satisfy `predicate`? Or (in the case of `ASSERT_DEATH` and `EXPECT_DEATH`)
is the exit status non-zero? And
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
the process.
To write a death test, simply use one of the above macros inside your test
function. For example,
```c++ ```c++
TEST(MyDeathTest, Foo) { TEST(MyDeathTest, Foo) {
@ -723,8 +424,8 @@ TEST(MyDeathTest, NormalExit) {
EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success"); EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success");
} }
TEST(MyDeathTest, KillMyself) { TEST(MyDeathTest, KillProcess) {
EXPECT_EXIT(KillMyself(), testing::KilledBySignal(SIGKILL), EXPECT_EXIT(KillProcess(), testing::KilledBySignal(SIGKILL),
"Sending myself unblockable signal"); "Sending myself unblockable signal");
} }
``` ```
@ -734,11 +435,23 @@ verifies that:
* calling `Foo(5)` causes the process to die with the given error message, * calling `Foo(5)` causes the process to die with the given error message,
* calling `NormalExit()` causes the process to print `"Success"` to stderr and * calling `NormalExit()` causes the process to print `"Success"` to stderr and
exit with exit code 0, and exit with exit code 0, and
* calling `KillMyself()` kills the process with signal `SIGKILL`. * calling `KillProcess()` kills the process with signal `SIGKILL`.
The test function body may contain other assertions and statements as well, if The test function body may contain other assertions and statements as well, if
necessary. necessary.
Note that a death test only cares about three things:
1. does `statement` abort or exit the process?
2. (in the case of `ASSERT_EXIT` and `EXPECT_EXIT`) does the exit status
satisfy `predicate`? Or (in the case of `ASSERT_DEATH` and `EXPECT_DEATH`)
is the exit status non-zero? And
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
the process.
### Death Test Naming ### Death Test Naming
{: .callout .important} {: .callout .important}
@ -810,32 +523,8 @@ limited syntax only.
### How It Works ### How It Works
Under the hood, `ASSERT_EXIT()` spawns a new process and executes the death test See [Death Assertions](reference/assertions.md#death) in the Assertions
statement in that process. The details of how precisely that happens depend on Reference.
the platform and the variable `::testing::GTEST_FLAG(death_test_style)` (which is
initialized from the command-line flag `--gtest_death_test_style`).
* On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the
child, after which:
* If the variable's value is `"fast"`, the death test statement is
immediately executed.
* If the variable's value is `"threadsafe"`, the child process re-executes
the unit test binary just as it was originally invoked, but with some
extra flags to cause just the single death test under consideration to
be run.
* On Windows, the child is spawned using the `CreateProcess()` API, and
re-executes the binary to cause just the single death test under
consideration to be run - much like the `threadsafe` mode on POSIX.
Other values for the variable are illegal and will cause the death test to fail.
Currently, the flag's default value is
**`"fast"`**.
1. the child's exit status satisfies the predicate, and
2. the child's stderr matches the regular expression.
If the death test statement runs to completion without dying, the child process
will nonetheless terminate, and the assertion fails.
### Death Tests And Threads ### Death Tests And Threads

73
docs/faq.md
View File

@ -279,8 +279,9 @@ disabled by our build system. Please see more details
## My death test hangs (or seg-faults). How do I fix it? ## My death test hangs (or seg-faults). How do I fix it?
In googletest, death tests are run in a child process and the way they work is In googletest, death tests are run in a child process and the way they work is
delicate. To write death tests you really need to understand how they work. delicate. To write death tests you really need to understand how they work—see
Please make sure you have read [this](advanced.md#how-it-works). the details at [Death Assertions](reference/assertions.md#death) in the
Assertions Reference.
In particular, death tests don't like having multiple threads in the parent In particular, death tests don't like having multiple threads in the parent
process. So the first thing you can try is to eliminate creating threads outside process. So the first thing you can try is to eliminate creating threads outside
@ -353,72 +354,8 @@ You may still want to use `SetUp()/TearDown()` in the following cases:
## 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?
If the predicate function you use in `ASSERT_PRED*` or `EXPECT_PRED*` is See details for [`EXPECT_PRED*`](reference/assertions.md#EXPECT_PRED) in the
overloaded or a template, the compiler will have trouble figuring out which Assertions Reference.
overloaded version it should use. `ASSERT_PRED_FORMAT*` and
`EXPECT_PRED_FORMAT*` don't have this problem.
If you see this error, you might want to switch to
`(ASSERT|EXPECT)_PRED_FORMAT*`, which will also give you a better failure
message. If, however, that is not an option, you can resolve the problem by
explicitly telling the compiler which version to pick.
For example, suppose you have
```c++
bool IsPositive(int n) {
return n > 0;
}
bool IsPositive(double x) {
return x > 0;
}
```
you will get a compiler error if you write
```c++
EXPECT_PRED1(IsPositive, 5);
```
However, this will work:
```c++
EXPECT_PRED1(static_cast<bool (*)(int)>(IsPositive), 5);
```
(The stuff inside the angled brackets for the `static_cast` operator is the type
of the function pointer for the `int`-version of `IsPositive()`.)
As another example, when you have a template function
```c++
template <typename T>
bool IsNegative(T x) {
return x < 0;
}
```
you can use it in a predicate assertion like this:
```c++
ASSERT_PRED1(IsNegative<int>, -5);
```
Things are more interesting if your template has more than one parameter. The
following won't compile:
```c++
ASSERT_PRED2(GreaterThan<int, int>, 5, 0);
```
as the C++ pre-processor thinks you are giving `ASSERT_PRED2` 4 arguments, which
is one more than expected. The workaround is to wrap the predicate function in
parentheses:
```c++
ASSERT_PRED2((GreaterThan<int, int>), 5, 0);
```
## My compiler complains about "ignoring return value" when I call RUN_ALL_TESTS(). Why? ## My compiler complains about "ignoring return value" when I call RUN_ALL_TESTS(). Why?

47
docs/gmock_cook_book.md
View File

@ -1137,51 +1137,8 @@ Matches(AllOf(Ge(0), Le(100), Ne(50)))
### Using Matchers in googletest Assertions ### Using Matchers in googletest Assertions
Since matchers are basically predicates that also know how to describe See [`EXPECT_THAT`](reference/assertions.md#EXPECT_THAT) in the Assertions
themselves, there is a way to take advantage of them in googletest assertions. Reference.
It's called `ASSERT_THAT` and `EXPECT_THAT`:
```cpp
ASSERT_THAT(value, matcher); // Asserts that value matches matcher.
EXPECT_THAT(value, matcher); // The non-fatal version.
```
For example, in a googletest test you can write:
```cpp
#include "gmock/gmock.h"
using ::testing::AllOf;
using ::testing::Ge;
using ::testing::Le;
using ::testing::MatchesRegex;
using ::testing::StartsWith;
...
EXPECT_THAT(Foo(), StartsWith("Hello"));
EXPECT_THAT(Bar(), MatchesRegex("Line \\d+"));
ASSERT_THAT(Baz(), AllOf(Ge(5), Le(10)));
```
which (as you can probably guess) executes `Foo()`, `Bar()`, and `Baz()`, and
verifies that:
* `Foo()` returns a string that starts with `"Hello"`.
* `Bar()` returns a string that matches regular expression `"Line \\d+"`.
* `Baz()` returns a number in the range [5, 10].
The nice thing about these macros is that *they read like English*. They
generate informative messages too. For example, if the first `EXPECT_THAT()`
above fails, the message will be something like:
```cpp
Value of: Foo()
Actual: "Hi, world!"
Expected: starts with "Hello"
```
**Credit:** The idea of `(ASSERT|EXPECT)_THAT` was borrowed from Joe Walnes'
Hamcrest project, which adds `assertThat()` to JUnit.
### Using Predicates as Matchers ### Using Predicates as Matchers

115
docs/primer.md
View File

@ -118,7 +118,10 @@ Depending on the nature of the leak, it may or may not be worth fixing - so keep
this in mind if you get a heap checker error in addition to assertion errors. this in mind if you get a heap checker error in addition to assertion errors.
To provide a custom failure message, simply stream it into the macro using the To provide a custom failure message, simply stream it into the macro using the
`<<` operator or a sequence of such operators. An example: `<<` operator or a sequence of such operators. See the following example, using
the
[`ASSERT_EQ` and `EXPECT_EQ`](reference/assertions.md?cl=374325853#EXPECT_EQ)
macros to verify value equality:
```c++ ```c++
ASSERT_EQ(x.size(), y.size()) << "Vectors x and y are of unequal length"; ASSERT_EQ(x.size(), y.size()) << "Vectors x and y are of unequal length";
@ -133,110 +136,12 @@ macro--in particular, C strings and `string` objects. If a wide string
(`wchar_t*`, `TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is (`wchar_t*`, `TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is
streamed to an assertion, it will be translated to UTF-8 when printed. streamed to an assertion, it will be translated to UTF-8 when printed.
### Basic Assertions GoogleTest provides a collection of assertions for verifying the behavior of
your code in various ways. You can check Boolean conditions, compare values
These assertions do basic true/false condition testing. based on relational operators, verify string values, floating-point values, and
much more. There are even assertions that enable you to verify more complex
Fatal assertion | Nonfatal assertion | Verifies states by providing custom predicates. For the complete list of assertions
-------------------------- | -------------------------- | -------------------- provided by GoogleTest, see the [Assertions Reference](reference/assertions.md).
`ASSERT_TRUE(condition);` | `EXPECT_TRUE(condition);` | `condition` is true
`ASSERT_FALSE(condition);` | `EXPECT_FALSE(condition);` | `condition` is false
Remember, when they fail, `ASSERT_*` yields a fatal failure and returns from the
current function, while `EXPECT_*` yields a nonfatal failure, allowing the
function to continue running. In either case, an assertion failure means its
containing test fails.
**Availability**: Linux, Windows, Mac.
### Binary Comparison
This section describes assertions that compare two values.
Fatal assertion | Nonfatal assertion | Verifies
------------------------ | ------------------------ | --------------
`ASSERT_EQ(val1, val2);` | `EXPECT_EQ(val1, val2);` | `val1 == val2`
`ASSERT_NE(val1, val2);` | `EXPECT_NE(val1, val2);` | `val1 != val2`
`ASSERT_LT(val1, val2);` | `EXPECT_LT(val1, val2);` | `val1 < val2`
`ASSERT_LE(val1, val2);` | `EXPECT_LE(val1, val2);` | `val1 <= val2`
`ASSERT_GT(val1, val2);` | `EXPECT_GT(val1, val2);` | `val1 > val2`
`ASSERT_GE(val1, val2);` | `EXPECT_GE(val1, val2);` | `val1 >= val2`
Value arguments must be comparable by the assertion's comparison operator or
you'll get a compiler error. We used to require the arguments to support the
`<<` operator for streaming to an `ostream`, but this is no longer necessary. If
`<<` is supported, it will be called to print the arguments when the assertion
fails; otherwise googletest will attempt to print them in the best way it can.
For more details and how to customize the printing of the arguments, see the
[documentation](./advanced.md#teaching-googletest-how-to-print-your-values).
These assertions can work with a user-defined type, but only if you define the
corresponding comparison operator (e.g., `==` or `<`). Since this is discouraged
by the Google
[C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Operator_Overloading),
you may need to use `ASSERT_TRUE()` or `EXPECT_TRUE()` to assert the equality of
two objects of a user-defined type.
However, when possible, `ASSERT_EQ(actual, expected)` is preferred to
`ASSERT_TRUE(actual == expected)`, since it tells you `actual` and `expected`'s
values on failure.
Arguments are always evaluated exactly once. Therefore, it's OK for the
arguments to have side effects. However, as with any ordinary C/C++ function,
the arguments' evaluation order is undefined (i.e., the compiler is free to
choose any order), and your code should not depend on any particular argument
evaluation order.
`ASSERT_EQ()` does pointer equality on pointers. If used on two C strings, it
tests if they are in the same memory location, not if they have the same value.
Therefore, if you want to compare C strings (e.g. `const char*`) by value, use
`ASSERT_STREQ()`, which will be described later on. In particular, to assert
that a C string is `NULL`, use `ASSERT_STREQ(c_string, NULL)`. Consider using
`ASSERT_EQ(c_string, nullptr)` if c++11 is supported. To compare two `string`
objects, you should use `ASSERT_EQ`.
When doing pointer comparisons use `*_EQ(ptr, nullptr)` and `*_NE(ptr, nullptr)`
instead of `*_EQ(ptr, NULL)` and `*_NE(ptr, NULL)`. This is because `nullptr` is
typed, while `NULL` is not. See the [FAQ](faq.md) for more details.
If you're working with floating point numbers, you may want to use the floating
point variations of some of these macros in order to avoid problems caused by
rounding. See [Advanced googletest Topics](advanced.md) for details.
Macros in this section work with both narrow and wide string objects (`string`
and `wstring`).
**Availability**: Linux, Windows, Mac.
**Historical note**: Before February 2016 `*_EQ` had a convention of calling it
as `ASSERT_EQ(expected, actual)`, so lots of existing code uses this order. Now
`*_EQ` treats both parameters in the same way.
### String Comparison
The assertions in this group compare two **C strings**. If you want to compare
two `string` objects, use `EXPECT_EQ`, `EXPECT_NE`, and etc instead.
| Fatal assertion | Nonfatal assertion | Verifies |
| -------------------------- | ------------------------------ | -------------------------------------------------------- |
| `ASSERT_STREQ(str1,str2);` | `EXPECT_STREQ(str1,str2);` | the two C strings have the same content |
| `ASSERT_STRNE(str1,str2);` | `EXPECT_STRNE(str1,str2);` | the two C strings have different contents |
| `ASSERT_STRCASEEQ(str1,str2);` | `EXPECT_STRCASEEQ(str1,str2);` | the two C strings have the same content, ignoring case |
| `ASSERT_STRCASENE(str1,str2);` | `EXPECT_STRCASENE(str1,str2);` | the two C strings have different contents, ignoring case |
Note that "CASE" in an assertion name means that case is ignored. A `NULL`
pointer and an empty string are considered *different*.
`*STREQ*` and `*STRNE*` also accept wide C strings (`wchar_t*`). If a comparison
of two wide strings fails, their values will be printed as UTF-8 narrow strings.
**Availability**: Linux, Windows, Mac.
**See also**: For more string comparison tricks (substring, prefix, suffix, and
regular expression matching, for example), see [this](advanced.md) in the
Advanced googletest Guide.
## Simple Tests ## Simple Tests

633
docs/reference/assertions.md Normal file
View File

@ -0,0 +1,633 @@
# Assertions Reference
This page lists the assertion macros provided by GoogleTest for verifying code
behavior. To use them, include the header `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
failures and allow the current function to continue running, while `ASSERT_`
macros generate fatal failures and abort the current function.
All assertion macros support streaming a custom failure message into them with
the `<<` operator, for example:
```cpp
EXPECT_TRUE(my_condition) << "My condition is not true";
```
Anything that can be streamed to an `ostream` can be streamed to an assertion
macro—in particular, C strings and string objects. If a wide string (`wchar_t*`,
`TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is streamed to an
assertion, it will be translated to UTF-8 when printed.
## Explicit Success and Failure {#success-failure}
The assertions in this section generate a success or failure directly instead of
testing a value or expression. These are useful when control flow, rather than a
Boolean expression, determines the test's success or failure, as shown by the
following example:
```c++
switch(expression) {
case 1:
... some checks ...
case 2:
... some other checks ...
default:
FAIL() << "We shouldn't get here.";
}
```
### SUCCEED {#SUCCEED}
`SUCCEED()`
Generates a success. This *does not* make the overall test succeed. A test is
considered successful only if none of its assertions fail during its execution.
The `SUCCEED` assertion is purely documentary and currently doesn't generate any
user-visible output. However, we may add `SUCCEED` messages to GoogleTest output
in the future.
### FAIL {#FAIL}
`FAIL()`
Generates a fatal failure, which returns from the current function.
Can only be used in functions that return `void`. See
[Assertion Placement](../advanced.md#assertion-placement) for more information.
### ADD_FAILURE {#ADD_FAILURE}
`ADD_FAILURE()`
Generates a nonfatal failure, which allows the current function to continue
running.
### ADD_FAILURE_AT {#ADD_FAILURE_AT}
`ADD_FAILURE_AT(`*`file_path`*`,`*`line_number`*`)`
Generates a nonfatal failure at the file and line number specified.
## Generalized Assertion {#generalized}
The following assertion allows [matchers](matchers.md) to be used to verify
values.
### EXPECT_THAT {#EXPECT_THAT}
`EXPECT_THAT(`*`value`*`,`*`matcher`*`)` \
`ASSERT_THAT(`*`value`*`,`*`matcher`*`)`
Verifies that *`value`* matches the [matcher](matchers.md) *`matcher`*.
For example, the following code verifies that the string `value1` starts with
`"Hello"`, `value2` matches a regular expression, and `value3` is between 5 and
10:
```cpp
#include "gmock/gmock.h"
using ::testing::AllOf;
using ::testing::Gt;
using ::testing::Lt;
using ::testing::MatchesRegex;
using ::testing::StartsWith;
...
EXPECT_THAT(value1, StartsWith("Hello"));
EXPECT_THAT(value2, MatchesRegex("Line \\d+"));
ASSERT_THAT(value3, AllOf(Gt(5), Lt(10)));
```
Matchers enable assertions of this form to read like English and generate
informative failure messages. For example, if the above assertion on `value1`
fails, the resulting message will be similar to the following:
```
Value of: value1
Actual: "Hi, world!"
Expected: starts with "Hello"
```
GoogleTest provides a built-in library of matchers—see the
[Matchers Reference](matchers.md). It is also possible to write your own
matchers—see [Writing New Matchers Quickly](../gmock_cook_book.md#NewMatchers).
The use of matchers makes `EXPECT_THAT` a powerful, extensible assertion.
*The idea for this assertion was borrowed from Joe Walnes' Hamcrest project,
which adds `assertThat()` to JUnit.*
## Boolean Conditions {#boolean}
The following assertions test Boolean conditions.
### EXPECT_TRUE {#EXPECT_TRUE}
`EXPECT_TRUE(`*`condition`*`)` \
`ASSERT_TRUE(`*`condition`*`)`
Verifies that *`condition`* is true.
### EXPECT_FALSE {#EXPECT_FALSE}
`EXPECT_FALSE(`*`condition`*`)` \
`ASSERT_FALSE(`*`condition`*`)`
Verifies that *`condition`* is false.
## Binary Comparison {#binary-comparison}
The following assertions compare two values. The value arguments must be
comparable by the assertion's comparison operator, otherwise a compiler error
will result.
If an argument supports the `<<` operator, it will be called to print the
argument when the assertion fails. Otherwise, GoogleTest will attempt to print
them in the best way it can—see
[Teaching GoogleTest How to Print Your Values](../advanced.md#teaching-googletest-how-to-print-your-values).
Arguments are always evaluated exactly once, so it's OK for the arguments to
have side effects. However, the argument evaluation order is undefined and
programs should not depend on any particular argument evaluation order.
These assertions work with both narrow and wide string objects (`string` and
`wstring`).
See also the [Floating-Point Comparison](#floating-point) assertions to compare
floating-point numbers and avoid problems caused by rounding.
### EXPECT_EQ {#EXPECT_EQ}
`EXPECT_EQ(`*`val1`*`,`*`val2`*`)` \
`ASSERT_EQ(`*`val1`*`,`*`val2`*`)`
Verifies that *`val1`*`==`*`val2`*.
Does pointer equality on pointers. If used on two C strings, it tests if they
are in the same memory location, not if they have the same value. Use
[`EXPECT_STREQ`](#EXPECT_STREQ) to compare C strings (e.g. `const char*`) by
value.
When comparing a pointer to `NULL`, use `EXPECT_EQ(`*`ptr`*`, nullptr)` instead
of `EXPECT_EQ(`*`ptr`*`, NULL)`.
### EXPECT_NE {#EXPECT_NE}
`EXPECT_NE(`*`val1`*`,`*`val2`*`)` \
`ASSERT_NE(`*`val1`*`,`*`val2`*`)`
Verifies that *`val1`*`!=`*`val2`*.
Does pointer equality on pointers. If used on two C strings, it tests if they
are in different memory locations, not if they have different values. Use
[`EXPECT_STRNE`](#EXPECT_STRNE) to compare C strings (e.g. `const char*`) by
value.
When comparing a pointer to `NULL`, use `EXPECT_NE(`*`ptr`*`, nullptr)` instead
of `EXPECT_NE(`*`ptr`*`, NULL)`.
### EXPECT_LT {#EXPECT_LT}
`EXPECT_LT(`*`val1`*`,`*`val2`*`)` \
`ASSERT_LT(`*`val1`*`,`*`val2`*`)`
Verifies that *`val1`*`<`*`val2`*.
### EXPECT_LE {#EXPECT_LE}
`EXPECT_LE(`*`val1`*`,`*`val2`*`)` \
`ASSERT_LE(`*`val1`*`,`*`val2`*`)`
Verifies that *`val1`*`<=`*`val2`*.
### EXPECT_GT {#EXPECT_GT}
`EXPECT_GT(`*`val1`*`,`*`val2`*`)` \
`ASSERT_GT(`*`val1`*`,`*`val2`*`)`
Verifies that *`val1`*`>`*`val2`*.
### EXPECT_GE {#EXPECT_GE}
`EXPECT_GE(`*`val1`*`,`*`val2`*`)` \
`ASSERT_GE(`*`val1`*`,`*`val2`*`)`
Verifies that *`val1`*`>=`*`val2`*.
## String Comparison {#c-strings}
The following assertions compare two **C strings**. To compare two `string`
objects, use [`EXPECT_EQ`](#EXPECT_EQ) or [`EXPECT_NE`](#EXPECT_NE) instead.
These assertions also accept wide C strings (`wchar_t*`). If a comparison of two
wide strings fails, their values will be printed as UTF-8 narrow strings.
To compare a C string with `NULL`, use `EXPECT_EQ(`*`c_string`*`, nullptr)` or
`EXPECT_NE(`*`c_string`*`, nullptr)`.
### EXPECT_STREQ {#EXPECT_STREQ}
`EXPECT_STREQ(`*`str1`*`,`*`str2`*`)` \
`ASSERT_STREQ(`*`str1`*`,`*`str2`*`)`
Verifies that the two C strings *`str1`* and *`str2`* have the same contents.
### EXPECT_STRNE {#EXPECT_STRNE}
`EXPECT_STRNE(`*`str1`*`,`*`str2`*`)` \
`ASSERT_STRNE(`*`str1`*`,`*`str2`*`)`
Verifies that the two C strings *`str1`* and *`str2`* have different contents.
### EXPECT_STRCASEEQ {#EXPECT_STRCASEEQ}
`EXPECT_STRCASEEQ(`*`str1`*`,`*`str2`*`)` \
`ASSERT_STRCASEEQ(`*`str1`*`,`*`str2`*`)`
Verifies that the two C strings *`str1`* and *`str2`* have the same contents,
ignoring case.
### EXPECT_STRCASENE {#EXPECT_STRCASENE}
`EXPECT_STRCASENE(`*`str1`*`,`*`str2`*`)` \
`ASSERT_STRCASENE(`*`str1`*`,`*`str2`*`)`
Verifies that the two C strings *`str1`* and *`str2`* have different contents,
ignoring case.
## Floating-Point Comparison {#floating-point}
The following assertions compare two floating-point values.
Due to rounding errors, it is very unlikely that two floating-point values will
match exactly, so `EXPECT_EQ` is not suitable. In general, for floating-point
comparison to make sense, the user needs to carefully choose the error bound.
GoogleTest also provides assertions that use a default error bound based on
Units in the Last Place (ULPs). To learn more about ULPs, see the article
[Comparing Floating Point Numbers](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/).
### EXPECT_FLOAT_EQ {#EXPECT_FLOAT_EQ}
`EXPECT_FLOAT_EQ(`*`val1`*`,`*`val2`*`)` \
`ASSERT_FLOAT_EQ(`*`val1`*`,`*`val2`*`)`
Verifies that the two `float` values *`val1`* and *`val2`* are approximately
equal, to within 4 ULPs from each other.
### EXPECT_DOUBLE_EQ {#EXPECT_DOUBLE_EQ}
`EXPECT_DOUBLE_EQ(`*`val1`*`,`*`val2`*`)` \
`ASSERT_DOUBLE_EQ(`*`val1`*`,`*`val2`*`)`
Verifies that the two `double` values *`val1`* and *`val2`* are approximately
equal, to within 4 ULPs from each other.
### EXPECT_NEAR {#EXPECT_NEAR}
`EXPECT_NEAR(`*`val1`*`,`*`val2`*`,`*`abs_error`*`)` \
`ASSERT_NEAR(`*`val1`*`,`*`val2`*`,`*`abs_error`*`)`
Verifies that the difference between *`val1`* and *`val2`* does not exceed the
absolute error bound *`abs_error`*.
## Exception Assertions {#exceptions}
The following assertions verify that a piece of code throws, or does not throw,
an exception. Usage requires exceptions to be enabled in the build environment.
Note that the piece of code under test can be a compound statement, for example:
```cpp
EXPECT_NO_THROW({
int n = 5;
DoSomething(&n);
});
```
### EXPECT_THROW {#EXPECT_THROW}
`EXPECT_THROW(`*`statement`*`,`*`exception_type`*`)` \
`ASSERT_THROW(`*`statement`*`,`*`exception_type`*`)`
Verifies that *`statement`* throws an exception of type *`exception_type`*.
### EXPECT_ANY_THROW {#EXPECT_ANY_THROW}
`EXPECT_ANY_THROW(`*`statement`*`)` \
`ASSERT_ANY_THROW(`*`statement`*`)`
Verifies that *`statement`* throws an exception of any type.
### EXPECT_NO_THROW {#EXPECT_NO_THROW}
`EXPECT_NO_THROW(`*`statement`*`)` \
`ASSERT_NO_THROW(`*`statement`*`)`
Verifies that *`statement`* does not throw any exception.
## Predicate Assertions {#predicates}
The following assertions enable more complex predicates to be verified while
printing a more clear failure message than if `EXPECT_TRUE` were used alone.
### EXPECT_PRED* {#EXPECT_PRED}
`EXPECT_PRED1(`*`pred`*`,`*`val1`*`)` \
`EXPECT_PRED2(`*`pred`*`,`*`val1`*`,`*`val2`*`)` \
`EXPECT_PRED3(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \
`EXPECT_PRED4(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)` \
`EXPECT_PRED5(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)`
`ASSERT_PRED1(`*`pred`*`,`*`val1`*`)` \
`ASSERT_PRED2(`*`pred`*`,`*`val1`*`,`*`val2`*`)` \
`ASSERT_PRED3(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \
`ASSERT_PRED4(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)` \
`ASSERT_PRED5(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)`
Verifies that the predicate *`pred`* returns `true` when passed the given values
as arguments.
The parameter *`pred`* is a function or functor that accepts as many arguments
as the corresponding macro accepts values. If *`pred`* returns `true` for the
given arguments, the assertion succeeds, otherwise the assertion fails.
When the assertion fails, it prints the value of each argument. Arguments are
always evaluated exactly once.
As an example, see the following code:
```cpp
// Returns true if m and n have no common divisors except 1.
bool MutuallyPrime(int m, int n) { ... }
...
const int a = 3;
const int b = 4;
const int c = 10;
...
EXPECT_PRED2(MutuallyPrime, a, b); // Succeeds
EXPECT_PRED2(MutuallyPrime, b, c); // Fails
```
In the above example, the first assertion succeeds, and the second fails with
the following message:
```
MutuallyPrime(b, c) is false, where
b is 4
c is 10
```
Note that if the given predicate is an overloaded function or a function
template, the assertion macro might not be able to determine which version to
use, and it might be necessary to explicitly specify the type of the function.
For example, for a Boolean function `IsPositive()` overloaded to take either a
single `int` or `double` argument, it would be necessary to write one of the
following:
```cpp
EXPECT_PRED1(static_cast<bool (*)(int)>(IsPositive), 5);
EXPECT_PRED1(static_cast<bool (*)(double)>(IsPositive), 3.14);
```
Writing simply `EXPECT_PRED1(IsPositive, 5);` would result in a compiler error.
Similarly, to use a template function, specify the template arguments:
```cpp
template <typename T>
bool IsNegative(T x) {
return x < 0;
}
...
EXPECT_PRED1(IsNegative<int>, -5); // Must specify type for IsNegative
```
If a template has multiple parameters, wrap the predicate in parentheses so the
macro arguments are parsed correctly:
```cpp
ASSERT_PRED2((MyPredicate<int, int>), 5, 0);
```
### EXPECT_PRED_FORMAT* {#EXPECT_PRED_FORMAT}
`EXPECT_PRED_FORMAT1(`*`pred_formatter`*`,`*`val1`*`)` \
`EXPECT_PRED_FORMAT2(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`)` \
`EXPECT_PRED_FORMAT3(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \
`EXPECT_PRED_FORMAT4(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)`
\
`EXPECT_PRED_FORMAT5(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)`
`ASSERT_PRED_FORMAT1(`*`pred_formatter`*`,`*`val1`*`)` \
`ASSERT_PRED_FORMAT2(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`)` \
`ASSERT_PRED_FORMAT3(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \
`ASSERT_PRED_FORMAT4(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)`
\
`ASSERT_PRED_FORMAT5(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)`
Verifies that the predicate *`pred_formatter`* succeeds when passed the given
values as arguments.
The parameter *`pred_formatter`* is a *predicate-formatter*, which is a function
or functor with the signature:
```cpp
testing::AssertionResult PredicateFormatter(const char* expr1,
const char* expr2,
...
const char* exprn,
T1 val1,
T2 val2,
...
Tn valn);
```
where *`val1`*, *`val2`*, ..., *`valn`* are the values of the predicate
arguments, and *`expr1`*, *`expr2`*, ..., *`exprn`* are the corresponding
expressions as they appear in the source code. The types `T1`, `T2`, ..., `Tn`
can be either value types or reference types; if an argument has type `T`, it
can be declared as either `T` or `const T&`, whichever is appropriate. For more
about the return type `testing::AssertionResult`, see
[Using a Function That Returns an AssertionResult](../advanced.md#using-a-function-that-returns-an-assertionresult).
As an example, see the following code:
```cpp
// Returns the smallest prime common divisor of m and n,
// or 1 when m and n are mutually prime.
int SmallestPrimeCommonDivisor(int m, int n) { ... }
// Returns true if m and n have no common divisors except 1.
bool MutuallyPrime(int m, int n) { ... }
// A predicate-formatter for asserting that two integers are mutually prime.
testing::AssertionResult AssertMutuallyPrime(const char* m_expr,
const char* n_expr,
int m,
int n) {
if (MutuallyPrime(m, n)) return testing::AssertionSuccess();
return testing::AssertionFailure() << m_expr << " and " << n_expr
<< " (" << m << " and " << n << ") are not mutually prime, "
<< "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n);
}
...
const int a = 3;
const int b = 4;
const int c = 10;
...
EXPECT_PRED_FORMAT2(AssertMutuallyPrime, a, b); // Succeeds
EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c); // Fails
```
In the above example, the final assertion fails and the predicate-formatter
produces the following failure message:
```
b and c (4 and 10) are not mutually prime, as they have a common divisor 2
```
## Windows HRESULT Assertions {#HRESULT}
The following assertions test for `HRESULT` success or failure. For example:
```cpp
CComPtr<IShellDispatch2> shell;
ASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application"));
CComVariant empty;
ASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty));
```
The generated output contains the human-readable error message associated with
the returned `HRESULT` code.
### EXPECT_HRESULT_SUCCEEDED {#EXPECT_HRESULT_SUCCEEDED}
`EXPECT_HRESULT_SUCCEEDED(`*`expression`*`)` \
`ASSERT_HRESULT_SUCCEEDED(`*`expression`*`)`
Verifies that *`expression`* is a success `HRESULT`.
### EXPECT_HRESULT_FAILED {#EXPECT_HRESULT_FAILED}
`EXPECT_HRESULT_FAILED(`*`expression`*`)` \
`EXPECT_HRESULT_FAILED(`*`expression`*`)`
Verifies that *`expression`* is a failure `HRESULT`.
## Death Assertions {#death}
The following assertions verify that a piece of code causes the process to
terminate. For context, see [Death Tests](../advanced.md#death-tests).
These assertions spawn a new process and execute the code under test in that
process. How that happens depends on the platform and the variable
`::testing::GTEST_FLAG(death_test_style)`, which is initialized from the
command-line flag `--gtest_death_test_style`.
* On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the
child, after which:
* If the variable's value is `"fast"`, the death test statement is
immediately executed.
* If the variable's value is `"threadsafe"`, the child process re-executes
the unit test binary just as it was originally invoked, but with some
extra flags to cause just the single death test under consideration to
be run.
* On Windows, the child is spawned using the `CreateProcess()` API, and
re-executes the binary to cause just the single death test under
consideration to be run - much like the `"threadsafe"` mode on POSIX.
Other values for the variable are illegal and will cause the death test to fail.
Currently, the flag's default value is
**`"fast"`**.
If the death test statement runs to completion without dying, the child process
will nonetheless terminate, and the assertion fails.
Note that the piece of code under test can be a compound statement, for example:
```cpp
EXPECT_DEATH({
int n = 5;
DoSomething(&n);
}, "Error on line .* of DoSomething()");
```
### EXPECT_DEATH {#EXPECT_DEATH}
`EXPECT_DEATH(`*`statement`*`,`*`matcher`*`)` \
`ASSERT_DEATH(`*`statement`*`,`*`matcher`*`)`
Verifies that *`statement`* causes the process to terminate with a nonzero exit
status and produces `stderr` output that matches *`matcher`*.
The parameter *`matcher`* is either a [matcher](matchers.md) for a `const
std::string&`, or a regular expression (see
[Regular Expression Syntax](../advanced.md#regular-expression-syntax))—a bare
string *`s`* (with no matcher) is treated as
[`ContainsRegex(s)`](matchers.md#string-matchers), **not**
[`Eq(s)`](matchers.md#generic-comparison).
For example, the following code verifies that calling `DoSomething(42)` causes
the process to die with an error message that contains the text `My error`:
```cpp
EXPECT_DEATH(DoSomething(42), "My error");
```
### EXPECT_DEATH_IF_SUPPORTED {#EXPECT_DEATH_IF_SUPPORTED}
`EXPECT_DEATH_IF_SUPPORTED(`*`statement`*`,`*`matcher`*`)` \
`ASSERT_DEATH_IF_SUPPORTED(`*`statement`*`,`*`matcher`*`)`
If death tests are supported, behaves the same as
[`EXPECT_DEATH`](#EXPECT_DEATH). Otherwise, verifies nothing.
### EXPECT_DEBUG_DEATH {#EXPECT_DEBUG_DEATH}
`EXPECT_DEBUG_DEATH(`*`statement`*`,`*`matcher`*`)` \
`ASSERT_DEBUG_DEATH(`*`statement`*`,`*`matcher`*`)`
In debug mode, behaves the same as [`EXPECT_DEATH`](#EXPECT_DEATH). When not in
debug mode (i.e. `NDEBUG` is defined), just executes *`statement`*.
### EXPECT_EXIT {#EXPECT_EXIT}
`EXPECT_EXIT(`*`statement`*`,`*`predicate`*`,`*`matcher`*`)` \
`ASSERT_EXIT(`*`statement`*`,`*`predicate`*`,`*`matcher`*`)`
Verifies that *`statement`* causes the process to terminate with an exit status
that satisfies *`predicate`*, and produces `stderr` output that matches
*`matcher`*.
The parameter *`predicate`* is a function or functor that accepts an `int` exit
status and returns a `bool`. GoogleTest provides two predicates to handle common
cases:
```cpp
// Returns true if the program exited normally with the given exit status code.
::testing::ExitedWithCode(exit_code);
// Returns true if the program was killed by the given signal.
// Not available on Windows.
::testing::KilledBySignal(signal_number);
```
The parameter *`matcher`* is either a [matcher](matchers.md) for a `const
std::string&`, or a regular expression (see
[Regular Expression Syntax](../advanced.md#regular-expression-syntax))—a bare
string *`s`* (with no matcher) is treated as
[`ContainsRegex(s)`](matchers.md#string-matchers), **not**
[`Eq(s)`](matchers.md#generic-comparison).
For example, the following code verifies that calling `NormalExit()` causes the
process to print a message containing the text `Success` to `stderr` and exit
with exit status code 0:
```cpp
EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success");
```

2
docs/reference/matchers.md
View File

@ -56,7 +56,7 @@ will be changed.
`IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types `IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types
that can be explicitly converted to Boolean, but are not implicitly converted to that can be explicitly converted to Boolean, but are not implicitly converted to
Boolean. In other cases, you can use the basic Boolean. In other cases, you can use the basic
[`EXPECT_TRUE` and `EXPECT_FALSE`](../primer.md#basic-assertions) assertions. [`EXPECT_TRUE` and `EXPECT_FALSE`](assertions.md#boolean) assertions.
## Floating-Point Matchers {#FpMatchers} ## Floating-Point Matchers {#FpMatchers}