mirror of
https://github.com/jbeder/yaml-cpp.git
synced 2025-09-09 12:41:17 +00:00
Update googletest to 1.13
Fix issue with CMake 4.0
This commit is contained in:
Christoph Grüninger
committed by
Jesse Beder
Jesse Beder
parent
c9371de783
commit
2f86d13775
115
test/googletest-1.13.0/docs/reference/actions.md
Normal file
115
test/googletest-1.13.0/docs/reference/actions.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Actions Reference
|
||||
|
||||
[**Actions**](../gmock_for_dummies.md#actions-what-should-it-do) specify what a
|
||||
mock function should do when invoked. This page lists the built-in actions
|
||||
provided by GoogleTest. All actions are defined in the `::testing` namespace.
|
||||
|
||||
## Returning a Value
|
||||
|
||||
| Action | Description |
|
||||
| :-------------------------------- | :-------------------------------------------- |
|
||||
| `Return()` | Return from a `void` mock function. |
|
||||
| `Return(value)` | Return `value`. If the type of `value` is different to the mock function's return type, `value` is converted to the latter type <i>at the time the expectation is set</i>, not when the action is executed. |
|
||||
| `ReturnArg<N>()` | Return the `N`-th (0-based) argument. |
|
||||
| `ReturnNew<T>(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different object is created each time. |
|
||||
| `ReturnNull()` | Return a null pointer. |
|
||||
| `ReturnPointee(ptr)` | Return the value pointed to by `ptr`. |
|
||||
| `ReturnRef(variable)` | Return a reference to `variable`. |
|
||||
| `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. |
|
||||
| `ReturnRoundRobin({a1, ..., ak})` | Each call will return the next `ai` in the list, starting at the beginning when the end of the list is reached. |
|
||||
|
||||
## Side Effects
|
||||
|
||||
| Action | Description |
|
||||
| :--------------------------------- | :-------------------------------------- |
|
||||
| `Assign(&variable, value)` | Assign `value` to variable. |
|
||||
| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. |
|
||||
| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. |
|
||||
| `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. |
|
||||
| `SetArgReferee<N>(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. |
|
||||
| `SetArgPointee<N>(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. |
|
||||
| `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0. |
|
||||
| `SetArrayArgument<N>(first, last)` | Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range. |
|
||||
| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. |
|
||||
| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. |
|
||||
|
||||
## Using a Function, Functor, or Lambda as an Action
|
||||
|
||||
In the following, by "callable" we mean a free function, `std::function`,
|
||||
functor, or lambda.
|
||||
|
||||
| Action | Description |
|
||||
| :---------------------------------- | :------------------------------------- |
|
||||
| `f` | Invoke `f` with the arguments passed to the mock function, where `f` is a callable. |
|
||||
| `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. |
|
||||
| `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. |
|
||||
| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. |
|
||||
| `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. |
|
||||
| `InvokeArgument<N>(arg1, arg2, ..., argk)` | Invoke the mock function's `N`-th (0-based) argument, which must be a function or a functor, with the `k` arguments. |
|
||||
|
||||
The return value of the invoked function is used as the return value of the
|
||||
action.
|
||||
|
||||
When defining a callable to be used with `Invoke*()`, you can declare any unused
|
||||
parameters as `Unused`:
|
||||
|
||||
```cpp
|
||||
using ::testing::Invoke;
|
||||
double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); }
|
||||
...
|
||||
EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance));
|
||||
```
|
||||
|
||||
`Invoke(callback)` and `InvokeWithoutArgs(callback)` take ownership of
|
||||
`callback`, which must be permanent. The type of `callback` must be a base
|
||||
callback type instead of a derived one, e.g.
|
||||
|
||||
```cpp
|
||||
BlockingClosure* done = new BlockingClosure;
|
||||
... Invoke(done) ...; // This won't compile!
|
||||
|
||||
Closure* done2 = new BlockingClosure;
|
||||
... Invoke(done2) ...; // This works.
|
||||
```
|
||||
|
||||
In `InvokeArgument<N>(...)`, if an argument needs to be passed by reference,
|
||||
wrap it inside `std::ref()`. For example,
|
||||
|
||||
```cpp
|
||||
using ::testing::InvokeArgument;
|
||||
...
|
||||
InvokeArgument<2>(5, string("Hi"), std::ref(foo))
|
||||
```
|
||||
|
||||
calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by
|
||||
value, and `foo` by reference.
|
||||
|
||||
## Default Action
|
||||
|
||||
| Action | Description |
|
||||
| :------------ | :----------------------------------------------------- |
|
||||
| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). |
|
||||
|
||||
{: .callout .note}
|
||||
**Note:** due to technical reasons, `DoDefault()` cannot be used inside a
|
||||
composite action - trying to do so will result in a run-time error.
|
||||
|
||||
## Composite Actions
|
||||
|
||||
| Action | Description |
|
||||
| :----------------------------- | :------------------------------------------ |
|
||||
| `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the result of `an` in each invocation. The first `n - 1` sub-actions must return void and will receive a readonly view of the arguments. |
|
||||
| `IgnoreResult(a)` | Perform action `a` and ignore its result. `a` must not return void. |
|
||||
| `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. |
|
||||
| `WithArgs<N1, N2, ..., Nk>(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. |
|
||||
| `WithoutArgs(a)` | Perform action `a` without any arguments. |
|
||||
|
||||
## Defining Actions
|
||||
|
||||
| Macro | Description |
|
||||
| :--------------------------------- | :-------------------------------------- |
|
||||
| `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. |
|
||||
| `ACTION_P(Plus, n) { return arg0 + n; }` | Defines an action `Plus(n)` to return the sum of the mock function's argument #0 and `n`. |
|
||||
| `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. |
|
||||
|
||||
The `ACTION*` macros cannot be used inside a function or class.
|
||||
633
test/googletest-1.13.0/docs/reference/assertions.md
Normal file
633
test/googletest-1.13.0/docs/reference/assertions.md
Normal 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");
|
||||
```
|
||||
290
test/googletest-1.13.0/docs/reference/matchers.md
Normal file
290
test/googletest-1.13.0/docs/reference/matchers.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# Matchers Reference
|
||||
|
||||
A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
|
||||
`EXPECT_CALL()`, or use it to validate a value directly using two macros:
|
||||
|
||||
| Macro | Description |
|
||||
| :----------------------------------- | :------------------------------------ |
|
||||
| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. |
|
||||
| `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. |
|
||||
|
||||
{: .callout .warning}
|
||||
**WARNING:** Equality matching via `EXPECT_THAT(actual_value, expected_value)`
|
||||
is supported, however note that implicit conversions can cause surprising
|
||||
results. For example, `EXPECT_THAT(some_bool, "some string")` will compile and
|
||||
may pass unintentionally.
|
||||
|
||||
**BEST PRACTICE:** Prefer to make the comparison explicit via
|
||||
`EXPECT_THAT(actual_value, Eq(expected_value))` or `EXPECT_EQ(actual_value,
|
||||
expected_value)`.
|
||||
|
||||
Built-in matchers (where `argument` is the function argument, e.g.
|
||||
`actual_value` in the example above, or when used in the context of
|
||||
`EXPECT_CALL(mock_object, method(matchers))`, the arguments of `method`) are
|
||||
divided into several categories. All matchers are defined in the `::testing`
|
||||
namespace unless otherwise noted.
|
||||
|
||||
## Wildcard
|
||||
|
||||
Matcher | Description
|
||||
:-------------------------- | :-----------------------------------------------
|
||||
`_` | `argument` can be any value of the correct type.
|
||||
`A<type>()` or `An<type>()` | `argument` can be any value of type `type`.
|
||||
|
||||
## Generic Comparison
|
||||
|
||||
| Matcher | Description |
|
||||
| :--------------------- | :-------------------------------------------------- |
|
||||
| `Eq(value)` or `value` | `argument == value` |
|
||||
| `Ge(value)` | `argument >= value` |
|
||||
| `Gt(value)` | `argument > value` |
|
||||
| `Le(value)` | `argument <= value` |
|
||||
| `Lt(value)` | `argument < value` |
|
||||
| `Ne(value)` | `argument != value` |
|
||||
| `IsFalse()` | `argument` evaluates to `false` in a Boolean context. |
|
||||
| `IsTrue()` | `argument` evaluates to `true` in a Boolean context. |
|
||||
| `IsNull()` | `argument` is a `NULL` pointer (raw or smart). |
|
||||
| `NotNull()` | `argument` is a non-null pointer (raw or smart). |
|
||||
| `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. (For testing whether an `optional<>` is set, check for equality with `nullopt`. You may need to use `Eq(nullopt)` if the inner type doesn't have `==`.)|
|
||||
| `VariantWith<T>(m)` | `argument` is `variant<>` that holds the alternative of type T with a value matching `m`. |
|
||||
| `Ref(variable)` | `argument` is a reference to `variable`. |
|
||||
| `TypedEq<type>(value)` | `argument` has type `type` and is equal to `value`. You may need to use this instead of `Eq(value)` when the mock function is overloaded. |
|
||||
|
||||
Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or
|
||||
destructed later. If the compiler complains that `value` doesn't have a public
|
||||
copy constructor, try wrap it in `std::ref()`, e.g.
|
||||
`Eq(std::ref(non_copyable_value))`. If you do that, make sure
|
||||
`non_copyable_value` is not changed afterwards, or the meaning of your matcher
|
||||
will be changed.
|
||||
|
||||
`IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types
|
||||
that can be explicitly converted to Boolean, but are not implicitly converted to
|
||||
Boolean. In other cases, you can use the basic
|
||||
[`EXPECT_TRUE` and `EXPECT_FALSE`](assertions.md#boolean) assertions.
|
||||
|
||||
## Floating-Point Matchers {#FpMatchers}
|
||||
|
||||
| Matcher | Description |
|
||||
| :------------------------------- | :--------------------------------- |
|
||||
| `DoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. |
|
||||
| `FloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. |
|
||||
| `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. |
|
||||
| `NanSensitiveFloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. |
|
||||
| `IsNan()` | `argument` is any floating-point type with a NaN value. |
|
||||
|
||||
The above matchers use ULP-based comparison (the same as used in googletest).
|
||||
They automatically pick a reasonable error bound based on the absolute value of
|
||||
the expected value. `DoubleEq()` and `FloatEq()` conform to the IEEE standard,
|
||||
which requires comparing two NaNs for equality to return false. The
|
||||
`NanSensitive*` version instead treats two NaNs as equal, which is often what a
|
||||
user wants.
|
||||
|
||||
| Matcher | Description |
|
||||
| :------------------------------------------------ | :----------------------- |
|
||||
| `DoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as unequal. |
|
||||
| `FloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as unequal. |
|
||||
| `NanSensitiveDoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as equal. |
|
||||
| `NanSensitiveFloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as equal. |
|
||||
|
||||
## String Matchers
|
||||
|
||||
The `argument` can be either a C string or a C++ string object:
|
||||
|
||||
| Matcher | Description |
|
||||
| :---------------------- | :------------------------------------------------- |
|
||||
| `ContainsRegex(string)` | `argument` matches the given regular expression. |
|
||||
| `EndsWith(suffix)` | `argument` ends with string `suffix`. |
|
||||
| `HasSubstr(string)` | `argument` contains `string` as a sub-string. |
|
||||
| `IsEmpty()` | `argument` is an empty string. |
|
||||
| `MatchesRegex(string)` | `argument` matches the given regular expression with the match starting at the first character and ending at the last character. |
|
||||
| `StartsWith(prefix)` | `argument` starts with string `prefix`. |
|
||||
| `StrCaseEq(string)` | `argument` is equal to `string`, ignoring case. |
|
||||
| `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring case. |
|
||||
| `StrEq(string)` | `argument` is equal to `string`. |
|
||||
| `StrNe(string)` | `argument` is not equal to `string`. |
|
||||
| `WhenBase64Unescaped(m)` | `argument` is a base-64 escaped string whose unescaped string matches `m`. |
|
||||
|
||||
`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They
|
||||
use the regular expression syntax defined
|
||||
[here](../advanced.md#regular-expression-syntax). All of these matchers, except
|
||||
`ContainsRegex()` and `MatchesRegex()` work for wide strings as well.
|
||||
|
||||
## Container Matchers
|
||||
|
||||
Most STL-style containers support `==`, so you can use `Eq(expected_container)`
|
||||
or simply `expected_container` to match a container exactly. If you want to
|
||||
write the elements in-line, match them more flexibly, or get more informative
|
||||
messages, you can use:
|
||||
|
||||
| Matcher | Description |
|
||||
| :---------------------------------------- | :------------------------------- |
|
||||
| `BeginEndDistanceIs(m)` | `argument` is a container whose `begin()` and `end()` iterators are separated by a number of increments matching `m`. E.g. `BeginEndDistanceIs(2)` or `BeginEndDistanceIs(Lt(2))`. For containers that define a `size()` method, `SizeIs(m)` may be more efficient. |
|
||||
| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. |
|
||||
| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. |
|
||||
| `Contains(e).Times(n)` | `argument` contains elements that match `e`, which can be either a value or a matcher, and the number of matches is `n`, which can be either a value or a matcher. Unlike the plain `Contains` and `Each` this allows to check for arbitrary occurrences including testing for absence with `Contains(e).Times(0)`. |
|
||||
| `Each(e)` | `argument` is a container where *every* element matches `e`, which can be either a value or a matcher. |
|
||||
| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. |
|
||||
| `ElementsAreArray({e0, e1, ..., en})`, `ElementsAreArray(a_container)`, `ElementsAreArray(begin, end)`, `ElementsAreArray(array)`, or `ElementsAreArray(array, count)` | The same as `ElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
|
||||
| `IsEmpty()` | `argument` is an empty container (`container.empty()`). |
|
||||
| `IsSubsetOf({e0, e1, ..., en})`, `IsSubsetOf(a_container)`, `IsSubsetOf(begin, end)`, `IsSubsetOf(array)`, or `IsSubsetOf(array, count)` | `argument` matches `UnorderedElementsAre(x0, x1, ..., xk)` for some subset `{x0, x1, ..., xk}` of the expected matchers. |
|
||||
| `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. |
|
||||
| `Pointwise(m, container)`, `Pointwise(m, {e0, e1, ..., en})` | `argument` contains the same number of elements as in `container`, and for all i, (the i-th element in `argument`, the i-th element in `container`) match `m`, which is a matcher on 2-tuples. E.g. `Pointwise(Le(), upper_bounds)` verifies that each element in `argument` doesn't exceed the corresponding element in `upper_bounds`. See more detail below. |
|
||||
| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. |
|
||||
| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, and under *some* permutation of the elements, each element matches an `ei` (for a different `i`), which can be a value or a matcher. |
|
||||
| `UnorderedElementsAreArray({e0, e1, ..., en})`, `UnorderedElementsAreArray(a_container)`, `UnorderedElementsAreArray(begin, end)`, `UnorderedElementsAreArray(array)`, or `UnorderedElementsAreArray(array, count)` | The same as `UnorderedElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
|
||||
| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. |
|
||||
| `WhenSorted(m)` | When `argument` is sorted using the `<` operator, it matches container matcher `m`. E.g. `WhenSorted(ElementsAre(1, 2, 3))` verifies that `argument` contains elements 1, 2, and 3, ignoring order. |
|
||||
| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, except that the given comparator instead of `<` is used to sort `argument`. E.g. `WhenSortedBy(std::greater(), ElementsAre(3, 2, 1))`. |
|
||||
|
||||
**Notes:**
|
||||
|
||||
* These matchers can also match:
|
||||
1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`),
|
||||
and
|
||||
2. an array passed as a pointer and a count (e.g. in `Bar(const T* buffer,
|
||||
int len)` -- see [Multi-argument Matchers](#MultiArgMatchers)).
|
||||
* The array being matched may be multi-dimensional (i.e. its elements can be
|
||||
arrays).
|
||||
* `m` in `Pointwise(m, ...)` and `UnorderedPointwise(m, ...)` should be a
|
||||
matcher for `::std::tuple<T, U>` where `T` and `U` are the element type of
|
||||
the actual container and the expected container, respectively. For example,
|
||||
to compare two `Foo` containers where `Foo` doesn't support `operator==`,
|
||||
one might write:
|
||||
|
||||
```cpp
|
||||
MATCHER(FooEq, "") {
|
||||
return std::get<0>(arg).Equals(std::get<1>(arg));
|
||||
}
|
||||
...
|
||||
EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos));
|
||||
```
|
||||
|
||||
## Member Matchers
|
||||
|
||||
| Matcher | Description |
|
||||
| :------------------------------ | :----------------------------------------- |
|
||||
| `Field(&class::field, m)` | `argument.field` (or `argument->field` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. |
|
||||
| `Field(field_name, &class::field, m)` | The same as the two-parameter version, but provides a better error message. |
|
||||
| `Key(e)` | `argument.first` matches `e`, which can be either a value or a matcher. E.g. `Contains(Key(Le(5)))` can verify that a `map` contains a key `<= 5`. |
|
||||
| `Pair(m1, m2)` | `argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. |
|
||||
| `FieldsAre(m...)` | `argument` is a compatible object where each field matches piecewise with the matchers `m...`. A compatible object is any that supports the `std::tuple_size<Obj>`+`get<I>(obj)` protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates. |
|
||||
| `Property(&class::property, m)` | `argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. The method `property()` must take no argument and be declared as `const`. |
|
||||
| `Property(property_name, &class::property, m)` | The same as the two-parameter version, but provides a better error message.
|
||||
|
||||
**Notes:**
|
||||
|
||||
* You can use `FieldsAre()` to match any type that supports structured
|
||||
bindings, such as `std::tuple`, `std::pair`, `std::array`, and aggregate
|
||||
types. For example:
|
||||
|
||||
```cpp
|
||||
std::tuple<int, std::string> my_tuple{7, "hello world"};
|
||||
EXPECT_THAT(my_tuple, FieldsAre(Ge(0), HasSubstr("hello")));
|
||||
|
||||
struct MyStruct {
|
||||
int value = 42;
|
||||
std::string greeting = "aloha";
|
||||
};
|
||||
MyStruct s;
|
||||
EXPECT_THAT(s, FieldsAre(42, "aloha"));
|
||||
```
|
||||
|
||||
* Don't use `Property()` against member functions that you do not own, because
|
||||
taking addresses of functions is fragile and generally not part of the
|
||||
contract of the function.
|
||||
|
||||
## Matching the Result of a Function, Functor, or Callback
|
||||
|
||||
| Matcher | Description |
|
||||
| :--------------- | :------------------------------------------------ |
|
||||
| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. |
|
||||
| `ResultOf(result_description, f, m)` | The same as the two-parameter version, but provides a better error message.
|
||||
|
||||
## Pointer Matchers
|
||||
|
||||
| Matcher | Description |
|
||||
| :------------------------ | :---------------------------------------------- |
|
||||
| `Address(m)` | the result of `std::addressof(argument)` matches `m`. |
|
||||
| `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. |
|
||||
| `Pointer(m)` | `argument` (either a smart pointer or a raw pointer) contains a pointer that matches `m`. `m` will match against the raw pointer regardless of the type of `argument`. |
|
||||
| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. |
|
||||
|
||||
## Multi-argument Matchers {#MultiArgMatchers}
|
||||
|
||||
Technically, all matchers match a *single* value. A "multi-argument" matcher is
|
||||
just one that matches a *tuple*. The following matchers can be used to match a
|
||||
tuple `(x, y)`:
|
||||
|
||||
Matcher | Description
|
||||
:------ | :----------
|
||||
`Eq()` | `x == y`
|
||||
`Ge()` | `x >= y`
|
||||
`Gt()` | `x > y`
|
||||
`Le()` | `x <= y`
|
||||
`Lt()` | `x < y`
|
||||
`Ne()` | `x != y`
|
||||
|
||||
You can use the following selectors to pick a subset of the arguments (or
|
||||
reorder them) to participate in the matching:
|
||||
|
||||
| Matcher | Description |
|
||||
| :------------------------- | :---------------------------------------------- |
|
||||
| `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`. |
|
||||
| `Args<N1, N2, ..., Nk>(m)` | The tuple of the `k` selected (using 0-based indices) arguments matches `m`, e.g. `Args<1, 2>(Eq())`. |
|
||||
|
||||
## Composite Matchers
|
||||
|
||||
You can make a matcher from one or more other matchers:
|
||||
|
||||
| Matcher | Description |
|
||||
| :------------------------------- | :-------------------------------------- |
|
||||
| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. |
|
||||
| `AllOfArray({m0, m1, ..., mn})`, `AllOfArray(a_container)`, `AllOfArray(begin, end)`, `AllOfArray(array)`, or `AllOfArray(array, count)` | The same as `AllOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
|
||||
| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. |
|
||||
| `AnyOfArray({m0, m1, ..., mn})`, `AnyOfArray(a_container)`, `AnyOfArray(begin, end)`, `AnyOfArray(array)`, or `AnyOfArray(array, count)` | The same as `AnyOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
|
||||
| `Not(m)` | `argument` doesn't match matcher `m`. |
|
||||
| `Conditional(cond, m1, m2)` | Matches matcher `m1` if `cond` evaluates to true, else matches `m2`.|
|
||||
|
||||
## Adapters for Matchers
|
||||
|
||||
| Matcher | Description |
|
||||
| :---------------------- | :------------------------------------ |
|
||||
| `MatcherCast<T>(m)` | casts matcher `m` to type `Matcher<T>`. |
|
||||
| `SafeMatcherCast<T>(m)` | [safely casts](../gmock_cook_book.md#SafeMatcherCast) matcher `m` to type `Matcher<T>`. |
|
||||
| `Truly(predicate)` | `predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor. |
|
||||
|
||||
`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`,
|
||||
which must be a permanent callback.
|
||||
|
||||
## Using Matchers as Predicates {#MatchersAsPredicatesCheat}
|
||||
|
||||
| Matcher | Description |
|
||||
| :---------------------------- | :------------------------------------------ |
|
||||
| `Matches(m)(value)` | evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor. |
|
||||
| `ExplainMatchResult(m, value, result_listener)` | evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. |
|
||||
| `Value(value, m)` | evaluates to `true` if `value` matches `m`. |
|
||||
|
||||
## Defining Matchers
|
||||
|
||||
| Macro | Description |
|
||||
| :----------------------------------- | :------------------------------------ |
|
||||
| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. |
|
||||
| `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a matcher `IsDivisibleBy(n)` to match a number divisible by `n`. |
|
||||
| `MATCHER_P2(IsBetween, a, b, absl::StrCat(negation ? "isn't" : "is", " between ", PrintToString(a), " and ", PrintToString(b))) { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. |
|
||||
|
||||
**Notes:**
|
||||
|
||||
1. The `MATCHER*` macros cannot be used inside a function or class.
|
||||
2. The matcher body must be *purely functional* (i.e. it cannot have any side
|
||||
effect, and the result must not depend on anything other than the value
|
||||
being matched and the matcher parameters).
|
||||
3. You can use `PrintToString(x)` to convert a value `x` of any type to a
|
||||
string.
|
||||
4. You can use `ExplainMatchResult()` in a custom matcher to wrap another
|
||||
matcher, for example:
|
||||
|
||||
```cpp
|
||||
MATCHER_P(NestedPropertyMatches, matcher, "") {
|
||||
return ExplainMatchResult(matcher, arg.nested().property(), result_listener);
|
||||
}
|
||||
```
|
||||
589
test/googletest-1.13.0/docs/reference/mocking.md
Normal file
589
test/googletest-1.13.0/docs/reference/mocking.md
Normal file
@@ -0,0 +1,589 @@
|
||||
# Mocking Reference
|
||||
|
||||
This page lists the facilities provided by GoogleTest for creating and working
|
||||
with mock objects. To use them, include the header
|
||||
`gmock/gmock.h`.
|
||||
|
||||
## Macros {#macros}
|
||||
|
||||
GoogleTest defines the following macros for working with mocks.
|
||||
|
||||
### MOCK_METHOD {#MOCK_METHOD}
|
||||
|
||||
`MOCK_METHOD(`*`return_type`*`,`*`method_name`*`, (`*`args...`*`));` \
|
||||
`MOCK_METHOD(`*`return_type`*`,`*`method_name`*`, (`*`args...`*`),
|
||||
(`*`specs...`*`));`
|
||||
|
||||
Defines a mock method *`method_name`* with arguments `(`*`args...`*`)` and
|
||||
return type *`return_type`* within a mock class.
|
||||
|
||||
The parameters of `MOCK_METHOD` mirror the method declaration. The optional
|
||||
fourth parameter *`specs...`* is a comma-separated list of qualifiers. The
|
||||
following qualifiers are accepted:
|
||||
|
||||
| Qualifier | Meaning |
|
||||
| -------------------------- | -------------------------------------------- |
|
||||
| `const` | Makes the mocked method a `const` method. Required if overriding a `const` method. |
|
||||
| `override` | Marks the method with `override`. Recommended if overriding a `virtual` method. |
|
||||
| `noexcept` | Marks the method with `noexcept`. Required if overriding a `noexcept` method. |
|
||||
| `Calltype(`*`calltype`*`)` | Sets the call type for the method, for example `Calltype(STDMETHODCALLTYPE)`. Useful on Windows. |
|
||||
| `ref(`*`qualifier`*`)` | Marks the method with the given reference qualifier, for example `ref(&)` or `ref(&&)`. Required if overriding a method that has a reference qualifier. |
|
||||
|
||||
Note that commas in arguments prevent `MOCK_METHOD` from parsing the arguments
|
||||
correctly if they are not appropriately surrounded by parentheses. See the
|
||||
following example:
|
||||
|
||||
```cpp
|
||||
class MyMock {
|
||||
public:
|
||||
// The following 2 lines will not compile due to commas in the arguments:
|
||||
MOCK_METHOD(std::pair<bool, int>, GetPair, ()); // Error!
|
||||
MOCK_METHOD(bool, CheckMap, (std::map<int, double>, bool)); // Error!
|
||||
|
||||
// One solution - wrap arguments that contain commas in parentheses:
|
||||
MOCK_METHOD((std::pair<bool, int>), GetPair, ());
|
||||
MOCK_METHOD(bool, CheckMap, ((std::map<int, double>), bool));
|
||||
|
||||
// Another solution - use type aliases:
|
||||
using BoolAndInt = std::pair<bool, int>;
|
||||
MOCK_METHOD(BoolAndInt, GetPair, ());
|
||||
using MapIntDouble = std::map<int, double>;
|
||||
MOCK_METHOD(bool, CheckMap, (MapIntDouble, bool));
|
||||
};
|
||||
```
|
||||
|
||||
`MOCK_METHOD` must be used in the `public:` section of a mock class definition,
|
||||
regardless of whether the method being mocked is `public`, `protected`, or
|
||||
`private` in the base class.
|
||||
|
||||
### EXPECT_CALL {#EXPECT_CALL}
|
||||
|
||||
`EXPECT_CALL(`*`mock_object`*`,`*`method_name`*`(`*`matchers...`*`))`
|
||||
|
||||
Creates an [expectation](../gmock_for_dummies.md#setting-expectations) that the
|
||||
method *`method_name`* of the object *`mock_object`* is called with arguments
|
||||
that match the given matchers *`matchers...`*. `EXPECT_CALL` must precede any
|
||||
code that exercises the mock object.
|
||||
|
||||
The parameter *`matchers...`* is a comma-separated list of
|
||||
[matchers](../gmock_for_dummies.md#matchers-what-arguments-do-we-expect) that
|
||||
correspond to each argument of the method *`method_name`*. The expectation will
|
||||
apply only to calls of *`method_name`* whose arguments match all of the
|
||||
matchers. If `(`*`matchers...`*`)` is omitted, the expectation behaves as if
|
||||
each argument's matcher were a [wildcard matcher (`_`)](matchers.md#wildcard).
|
||||
See the [Matchers Reference](matchers.md) for a list of all built-in matchers.
|
||||
|
||||
The following chainable clauses can be used to modify the expectation, and they
|
||||
must be used in the following order:
|
||||
|
||||
```cpp
|
||||
EXPECT_CALL(mock_object, method_name(matchers...))
|
||||
.With(multi_argument_matcher) // Can be used at most once
|
||||
.Times(cardinality) // Can be used at most once
|
||||
.InSequence(sequences...) // Can be used any number of times
|
||||
.After(expectations...) // Can be used any number of times
|
||||
.WillOnce(action) // Can be used any number of times
|
||||
.WillRepeatedly(action) // Can be used at most once
|
||||
.RetiresOnSaturation(); // Can be used at most once
|
||||
```
|
||||
|
||||
See details for each modifier clause below.
|
||||
|
||||
#### With {#EXPECT_CALL.With}
|
||||
|
||||
`.With(`*`multi_argument_matcher`*`)`
|
||||
|
||||
Restricts the expectation to apply only to mock function calls whose arguments
|
||||
as a whole match the multi-argument matcher *`multi_argument_matcher`*.
|
||||
|
||||
GoogleTest passes all of the arguments as one tuple into the matcher. The
|
||||
parameter *`multi_argument_matcher`* must thus be a matcher of type
|
||||
`Matcher<std::tuple<A1, ..., An>>`, where `A1, ..., An` are the types of the
|
||||
function arguments.
|
||||
|
||||
For example, the following code sets the expectation that
|
||||
`my_mock.SetPosition()` is called with any two arguments, the first argument
|
||||
being less than the second:
|
||||
|
||||
```cpp
|
||||
using ::testing::_;
|
||||
using ::testing::Lt;
|
||||
...
|
||||
EXPECT_CALL(my_mock, SetPosition(_, _))
|
||||
.With(Lt());
|
||||
```
|
||||
|
||||
GoogleTest provides some built-in matchers for 2-tuples, including the `Lt()`
|
||||
matcher above. See [Multi-argument Matchers](matchers.md#MultiArgMatchers).
|
||||
|
||||
The `With` clause can be used at most once on an expectation and must be the
|
||||
first clause.
|
||||
|
||||
#### Times {#EXPECT_CALL.Times}
|
||||
|
||||
`.Times(`*`cardinality`*`)`
|
||||
|
||||
Specifies how many times the mock function call is expected.
|
||||
|
||||
The parameter *`cardinality`* represents the number of expected calls and can be
|
||||
one of the following, all defined in the `::testing` namespace:
|
||||
|
||||
| Cardinality | Meaning |
|
||||
| ------------------- | --------------------------------------------------- |
|
||||
| `AnyNumber()` | The function can be called any number of times. |
|
||||
| `AtLeast(n)` | The function call is expected at least *n* times. |
|
||||
| `AtMost(n)` | The function call is expected at most *n* times. |
|
||||
| `Between(m, n)` | The function call is expected between *m* and *n* times, inclusive. |
|
||||
| `Exactly(n)` or `n` | The function call is expected exactly *n* times. If *n* is 0, the call should never happen. |
|
||||
|
||||
If the `Times` clause is omitted, GoogleTest infers the cardinality as follows:
|
||||
|
||||
* If neither [`WillOnce`](#EXPECT_CALL.WillOnce) nor
|
||||
[`WillRepeatedly`](#EXPECT_CALL.WillRepeatedly) are specified, the inferred
|
||||
cardinality is `Times(1)`.
|
||||
* If there are *n* `WillOnce` clauses and no `WillRepeatedly` clause, where
|
||||
*n* >= 1, the inferred cardinality is `Times(n)`.
|
||||
* If there are *n* `WillOnce` clauses and one `WillRepeatedly` clause, where
|
||||
*n* >= 0, the inferred cardinality is `Times(AtLeast(n))`.
|
||||
|
||||
The `Times` clause can be used at most once on an expectation.
|
||||
|
||||
#### InSequence {#EXPECT_CALL.InSequence}
|
||||
|
||||
`.InSequence(`*`sequences...`*`)`
|
||||
|
||||
Specifies that the mock function call is expected in a certain sequence.
|
||||
|
||||
The parameter *`sequences...`* is any number of [`Sequence`](#Sequence) objects.
|
||||
Expected calls assigned to the same sequence are expected to occur in the order
|
||||
the expectations are declared.
|
||||
|
||||
For example, the following code sets the expectation that the `Reset()` method
|
||||
of `my_mock` is called before both `GetSize()` and `Describe()`, and `GetSize()`
|
||||
and `Describe()` can occur in any order relative to each other:
|
||||
|
||||
```cpp
|
||||
using ::testing::Sequence;
|
||||
Sequence s1, s2;
|
||||
...
|
||||
EXPECT_CALL(my_mock, Reset())
|
||||
.InSequence(s1, s2);
|
||||
EXPECT_CALL(my_mock, GetSize())
|
||||
.InSequence(s1);
|
||||
EXPECT_CALL(my_mock, Describe())
|
||||
.InSequence(s2);
|
||||
```
|
||||
|
||||
The `InSequence` clause can be used any number of times on an expectation.
|
||||
|
||||
See also the [`InSequence` class](#InSequence).
|
||||
|
||||
#### After {#EXPECT_CALL.After}
|
||||
|
||||
`.After(`*`expectations...`*`)`
|
||||
|
||||
Specifies that the mock function call is expected to occur after one or more
|
||||
other calls.
|
||||
|
||||
The parameter *`expectations...`* can be up to five
|
||||
[`Expectation`](#Expectation) or [`ExpectationSet`](#ExpectationSet) objects.
|
||||
The mock function call is expected to occur after all of the given expectations.
|
||||
|
||||
For example, the following code sets the expectation that the `Describe()`
|
||||
method of `my_mock` is called only after both `InitX()` and `InitY()` have been
|
||||
called.
|
||||
|
||||
```cpp
|
||||
using ::testing::Expectation;
|
||||
...
|
||||
Expectation init_x = EXPECT_CALL(my_mock, InitX());
|
||||
Expectation init_y = EXPECT_CALL(my_mock, InitY());
|
||||
EXPECT_CALL(my_mock, Describe())
|
||||
.After(init_x, init_y);
|
||||
```
|
||||
|
||||
The `ExpectationSet` object is helpful when the number of prerequisites for an
|
||||
expectation is large or variable, for example:
|
||||
|
||||
```cpp
|
||||
using ::testing::ExpectationSet;
|
||||
...
|
||||
ExpectationSet all_inits;
|
||||
// Collect all expectations of InitElement() calls
|
||||
for (int i = 0; i < element_count; i++) {
|
||||
all_inits += EXPECT_CALL(my_mock, InitElement(i));
|
||||
}
|
||||
EXPECT_CALL(my_mock, Describe())
|
||||
.After(all_inits); // Expect Describe() call after all InitElement() calls
|
||||
```
|
||||
|
||||
The `After` clause can be used any number of times on an expectation.
|
||||
|
||||
#### WillOnce {#EXPECT_CALL.WillOnce}
|
||||
|
||||
`.WillOnce(`*`action`*`)`
|
||||
|
||||
Specifies the mock function's actual behavior when invoked, for a single
|
||||
matching function call.
|
||||
|
||||
The parameter *`action`* represents the
|
||||
[action](../gmock_for_dummies.md#actions-what-should-it-do) that the function
|
||||
call will perform. See the [Actions Reference](actions.md) for a list of
|
||||
built-in actions.
|
||||
|
||||
The use of `WillOnce` implicitly sets a cardinality on the expectation when
|
||||
`Times` is not specified. See [`Times`](#EXPECT_CALL.Times).
|
||||
|
||||
Each matching function call will perform the next action in the order declared.
|
||||
For example, the following code specifies that `my_mock.GetNumber()` is expected
|
||||
to be called exactly 3 times and will return `1`, `2`, and `3` respectively on
|
||||
the first, second, and third calls:
|
||||
|
||||
```cpp
|
||||
using ::testing::Return;
|
||||
...
|
||||
EXPECT_CALL(my_mock, GetNumber())
|
||||
.WillOnce(Return(1))
|
||||
.WillOnce(Return(2))
|
||||
.WillOnce(Return(3));
|
||||
```
|
||||
|
||||
The `WillOnce` clause can be used any number of times on an expectation. Unlike
|
||||
`WillRepeatedly`, the action fed to each `WillOnce` call will be called at most
|
||||
once, so may be a move-only type and/or have an `&&`-qualified call operator.
|
||||
|
||||
#### WillRepeatedly {#EXPECT_CALL.WillRepeatedly}
|
||||
|
||||
`.WillRepeatedly(`*`action`*`)`
|
||||
|
||||
Specifies the mock function's actual behavior when invoked, for all subsequent
|
||||
matching function calls. Takes effect after the actions specified in the
|
||||
[`WillOnce`](#EXPECT_CALL.WillOnce) clauses, if any, have been performed.
|
||||
|
||||
The parameter *`action`* represents the
|
||||
[action](../gmock_for_dummies.md#actions-what-should-it-do) that the function
|
||||
call will perform. See the [Actions Reference](actions.md) for a list of
|
||||
built-in actions.
|
||||
|
||||
The use of `WillRepeatedly` implicitly sets a cardinality on the expectation
|
||||
when `Times` is not specified. See [`Times`](#EXPECT_CALL.Times).
|
||||
|
||||
If any `WillOnce` clauses have been specified, matching function calls will
|
||||
perform those actions before the action specified by `WillRepeatedly`. See the
|
||||
following example:
|
||||
|
||||
```cpp
|
||||
using ::testing::Return;
|
||||
...
|
||||
EXPECT_CALL(my_mock, GetName())
|
||||
.WillRepeatedly(Return("John Doe")); // Return "John Doe" on all calls
|
||||
|
||||
EXPECT_CALL(my_mock, GetNumber())
|
||||
.WillOnce(Return(42)) // Return 42 on the first call
|
||||
.WillRepeatedly(Return(7)); // Return 7 on all subsequent calls
|
||||
```
|
||||
|
||||
The `WillRepeatedly` clause can be used at most once on an expectation.
|
||||
|
||||
#### RetiresOnSaturation {#EXPECT_CALL.RetiresOnSaturation}
|
||||
|
||||
`.RetiresOnSaturation()`
|
||||
|
||||
Indicates that the expectation will no longer be active after the expected
|
||||
number of matching function calls has been reached.
|
||||
|
||||
The `RetiresOnSaturation` clause is only meaningful for expectations with an
|
||||
upper-bounded cardinality. The expectation will *retire* (no longer match any
|
||||
function calls) after it has been *saturated* (the upper bound has been
|
||||
reached). See the following example:
|
||||
|
||||
```cpp
|
||||
using ::testing::_;
|
||||
using ::testing::AnyNumber;
|
||||
...
|
||||
EXPECT_CALL(my_mock, SetNumber(_)) // Expectation 1
|
||||
.Times(AnyNumber());
|
||||
EXPECT_CALL(my_mock, SetNumber(7)) // Expectation 2
|
||||
.Times(2)
|
||||
.RetiresOnSaturation();
|
||||
```
|
||||
|
||||
In the above example, the first two calls to `my_mock.SetNumber(7)` match
|
||||
expectation 2, which then becomes inactive and no longer matches any calls. A
|
||||
third call to `my_mock.SetNumber(7)` would then match expectation 1. Without
|
||||
`RetiresOnSaturation()` on expectation 2, a third call to `my_mock.SetNumber(7)`
|
||||
would match expectation 2 again, producing a failure since the limit of 2 calls
|
||||
was exceeded.
|
||||
|
||||
The `RetiresOnSaturation` clause can be used at most once on an expectation and
|
||||
must be the last clause.
|
||||
|
||||
### ON_CALL {#ON_CALL}
|
||||
|
||||
`ON_CALL(`*`mock_object`*`,`*`method_name`*`(`*`matchers...`*`))`
|
||||
|
||||
Defines what happens when the method *`method_name`* of the object
|
||||
*`mock_object`* is called with arguments that match the given matchers
|
||||
*`matchers...`*. Requires a modifier clause to specify the method's behavior.
|
||||
*Does not* set any expectations that the method will be called.
|
||||
|
||||
The parameter *`matchers...`* is a comma-separated list of
|
||||
[matchers](../gmock_for_dummies.md#matchers-what-arguments-do-we-expect) that
|
||||
correspond to each argument of the method *`method_name`*. The `ON_CALL`
|
||||
specification will apply only to calls of *`method_name`* whose arguments match
|
||||
all of the matchers. If `(`*`matchers...`*`)` is omitted, the behavior is as if
|
||||
each argument's matcher were a [wildcard matcher (`_`)](matchers.md#wildcard).
|
||||
See the [Matchers Reference](matchers.md) for a list of all built-in matchers.
|
||||
|
||||
The following chainable clauses can be used to set the method's behavior, and
|
||||
they must be used in the following order:
|
||||
|
||||
```cpp
|
||||
ON_CALL(mock_object, method_name(matchers...))
|
||||
.With(multi_argument_matcher) // Can be used at most once
|
||||
.WillByDefault(action); // Required
|
||||
```
|
||||
|
||||
See details for each modifier clause below.
|
||||
|
||||
#### With {#ON_CALL.With}
|
||||
|
||||
`.With(`*`multi_argument_matcher`*`)`
|
||||
|
||||
Restricts the specification to only mock function calls whose arguments as a
|
||||
whole match the multi-argument matcher *`multi_argument_matcher`*.
|
||||
|
||||
GoogleTest passes all of the arguments as one tuple into the matcher. The
|
||||
parameter *`multi_argument_matcher`* must thus be a matcher of type
|
||||
`Matcher<std::tuple<A1, ..., An>>`, where `A1, ..., An` are the types of the
|
||||
function arguments.
|
||||
|
||||
For example, the following code sets the default behavior when
|
||||
`my_mock.SetPosition()` is called with any two arguments, the first argument
|
||||
being less than the second:
|
||||
|
||||
```cpp
|
||||
using ::testing::_;
|
||||
using ::testing::Lt;
|
||||
using ::testing::Return;
|
||||
...
|
||||
ON_CALL(my_mock, SetPosition(_, _))
|
||||
.With(Lt())
|
||||
.WillByDefault(Return(true));
|
||||
```
|
||||
|
||||
GoogleTest provides some built-in matchers for 2-tuples, including the `Lt()`
|
||||
matcher above. See [Multi-argument Matchers](matchers.md#MultiArgMatchers).
|
||||
|
||||
The `With` clause can be used at most once with each `ON_CALL` statement.
|
||||
|
||||
#### WillByDefault {#ON_CALL.WillByDefault}
|
||||
|
||||
`.WillByDefault(`*`action`*`)`
|
||||
|
||||
Specifies the default behavior of a matching mock function call.
|
||||
|
||||
The parameter *`action`* represents the
|
||||
[action](../gmock_for_dummies.md#actions-what-should-it-do) that the function
|
||||
call will perform. See the [Actions Reference](actions.md) for a list of
|
||||
built-in actions.
|
||||
|
||||
For example, the following code specifies that by default, a call to
|
||||
`my_mock.Greet()` will return `"hello"`:
|
||||
|
||||
```cpp
|
||||
using ::testing::Return;
|
||||
...
|
||||
ON_CALL(my_mock, Greet())
|
||||
.WillByDefault(Return("hello"));
|
||||
```
|
||||
|
||||
The action specified by `WillByDefault` is superseded by the actions specified
|
||||
on a matching `EXPECT_CALL` statement, if any. See the
|
||||
[`WillOnce`](#EXPECT_CALL.WillOnce) and
|
||||
[`WillRepeatedly`](#EXPECT_CALL.WillRepeatedly) clauses of `EXPECT_CALL`.
|
||||
|
||||
The `WillByDefault` clause must be used exactly once with each `ON_CALL`
|
||||
statement.
|
||||
|
||||
## Classes {#classes}
|
||||
|
||||
GoogleTest defines the following classes for working with mocks.
|
||||
|
||||
### DefaultValue {#DefaultValue}
|
||||
|
||||
`::testing::DefaultValue<T>`
|
||||
|
||||
Allows a user to specify the default value for a type `T` that is both copyable
|
||||
and publicly destructible (i.e. anything that can be used as a function return
|
||||
type). For mock functions with a return type of `T`, this default value is
|
||||
returned from function calls that do not specify an action.
|
||||
|
||||
Provides the static methods `Set()`, `SetFactory()`, and `Clear()` to manage the
|
||||
default value:
|
||||
|
||||
```cpp
|
||||
// Sets the default value to be returned. T must be copy constructible.
|
||||
DefaultValue<T>::Set(value);
|
||||
|
||||
// Sets a factory. Will be invoked on demand. T must be move constructible.
|
||||
T MakeT();
|
||||
DefaultValue<T>::SetFactory(&MakeT);
|
||||
|
||||
// Unsets the default value.
|
||||
DefaultValue<T>::Clear();
|
||||
```
|
||||
|
||||
### NiceMock {#NiceMock}
|
||||
|
||||
`::testing::NiceMock<T>`
|
||||
|
||||
Represents a mock object that suppresses warnings on
|
||||
[uninteresting calls](../gmock_cook_book.md#uninteresting-vs-unexpected). The
|
||||
template parameter `T` is any mock class, except for another `NiceMock`,
|
||||
`NaggyMock`, or `StrictMock`.
|
||||
|
||||
Usage of `NiceMock<T>` is analogous to usage of `T`. `NiceMock<T>` is a subclass
|
||||
of `T`, so it can be used wherever an object of type `T` is accepted. In
|
||||
addition, `NiceMock<T>` can be constructed with any arguments that a constructor
|
||||
of `T` accepts.
|
||||
|
||||
For example, the following code suppresses warnings on the mock `my_mock` of
|
||||
type `MockClass` if a method other than `DoSomething()` is called:
|
||||
|
||||
```cpp
|
||||
using ::testing::NiceMock;
|
||||
...
|
||||
NiceMock<MockClass> my_mock("some", "args");
|
||||
EXPECT_CALL(my_mock, DoSomething());
|
||||
... code that uses my_mock ...
|
||||
```
|
||||
|
||||
`NiceMock<T>` only works for mock methods defined using the `MOCK_METHOD` macro
|
||||
directly in the definition of class `T`. If a mock method is defined in a base
|
||||
class of `T`, a warning might still be generated.
|
||||
|
||||
`NiceMock<T>` might not work correctly if the destructor of `T` is not virtual.
|
||||
|
||||
### NaggyMock {#NaggyMock}
|
||||
|
||||
`::testing::NaggyMock<T>`
|
||||
|
||||
Represents a mock object that generates warnings on
|
||||
[uninteresting calls](../gmock_cook_book.md#uninteresting-vs-unexpected). The
|
||||
template parameter `T` is any mock class, except for another `NiceMock`,
|
||||
`NaggyMock`, or `StrictMock`.
|
||||
|
||||
Usage of `NaggyMock<T>` is analogous to usage of `T`. `NaggyMock<T>` is a
|
||||
subclass of `T`, so it can be used wherever an object of type `T` is accepted.
|
||||
In addition, `NaggyMock<T>` can be constructed with any arguments that a
|
||||
constructor of `T` accepts.
|
||||
|
||||
For example, the following code generates warnings on the mock `my_mock` of type
|
||||
`MockClass` if a method other than `DoSomething()` is called:
|
||||
|
||||
```cpp
|
||||
using ::testing::NaggyMock;
|
||||
...
|
||||
NaggyMock<MockClass> my_mock("some", "args");
|
||||
EXPECT_CALL(my_mock, DoSomething());
|
||||
... code that uses my_mock ...
|
||||
```
|
||||
|
||||
Mock objects of type `T` by default behave the same way as `NaggyMock<T>`.
|
||||
|
||||
### StrictMock {#StrictMock}
|
||||
|
||||
`::testing::StrictMock<T>`
|
||||
|
||||
Represents a mock object that generates test failures on
|
||||
[uninteresting calls](../gmock_cook_book.md#uninteresting-vs-unexpected). The
|
||||
template parameter `T` is any mock class, except for another `NiceMock`,
|
||||
`NaggyMock`, or `StrictMock`.
|
||||
|
||||
Usage of `StrictMock<T>` is analogous to usage of `T`. `StrictMock<T>` is a
|
||||
subclass of `T`, so it can be used wherever an object of type `T` is accepted.
|
||||
In addition, `StrictMock<T>` can be constructed with any arguments that a
|
||||
constructor of `T` accepts.
|
||||
|
||||
For example, the following code generates a test failure on the mock `my_mock`
|
||||
of type `MockClass` if a method other than `DoSomething()` is called:
|
||||
|
||||
```cpp
|
||||
using ::testing::StrictMock;
|
||||
...
|
||||
StrictMock<MockClass> my_mock("some", "args");
|
||||
EXPECT_CALL(my_mock, DoSomething());
|
||||
... code that uses my_mock ...
|
||||
```
|
||||
|
||||
`StrictMock<T>` only works for mock methods defined using the `MOCK_METHOD`
|
||||
macro directly in the definition of class `T`. If a mock method is defined in a
|
||||
base class of `T`, a failure might not be generated.
|
||||
|
||||
`StrictMock<T>` might not work correctly if the destructor of `T` is not
|
||||
virtual.
|
||||
|
||||
### Sequence {#Sequence}
|
||||
|
||||
`::testing::Sequence`
|
||||
|
||||
Represents a chronological sequence of expectations. See the
|
||||
[`InSequence`](#EXPECT_CALL.InSequence) clause of `EXPECT_CALL` for usage.
|
||||
|
||||
### InSequence {#InSequence}
|
||||
|
||||
`::testing::InSequence`
|
||||
|
||||
An object of this type causes all expectations encountered in its scope to be
|
||||
put in an anonymous sequence.
|
||||
|
||||
This allows more convenient expression of multiple expectations in a single
|
||||
sequence:
|
||||
|
||||
```cpp
|
||||
using ::testing::InSequence;
|
||||
{
|
||||
InSequence seq;
|
||||
|
||||
// The following are expected to occur in the order declared.
|
||||
EXPECT_CALL(...);
|
||||
EXPECT_CALL(...);
|
||||
...
|
||||
EXPECT_CALL(...);
|
||||
}
|
||||
```
|
||||
|
||||
The name of the `InSequence` object does not matter.
|
||||
|
||||
### Expectation {#Expectation}
|
||||
|
||||
`::testing::Expectation`
|
||||
|
||||
Represents a mock function call expectation as created by
|
||||
[`EXPECT_CALL`](#EXPECT_CALL):
|
||||
|
||||
```cpp
|
||||
using ::testing::Expectation;
|
||||
Expectation my_expectation = EXPECT_CALL(...);
|
||||
```
|
||||
|
||||
Useful for specifying sequences of expectations; see the
|
||||
[`After`](#EXPECT_CALL.After) clause of `EXPECT_CALL`.
|
||||
|
||||
### ExpectationSet {#ExpectationSet}
|
||||
|
||||
`::testing::ExpectationSet`
|
||||
|
||||
Represents a set of mock function call expectations.
|
||||
|
||||
Use the `+=` operator to add [`Expectation`](#Expectation) objects to the set:
|
||||
|
||||
```cpp
|
||||
using ::testing::ExpectationSet;
|
||||
ExpectationSet my_expectations;
|
||||
my_expectations += EXPECT_CALL(...);
|
||||
```
|
||||
|
||||
Useful for specifying sequences of expectations; see the
|
||||
[`After`](#EXPECT_CALL.After) clause of `EXPECT_CALL`.
|
||||
1431
test/googletest-1.13.0/docs/reference/testing.md
Normal file
1431
test/googletest-1.13.0/docs/reference/testing.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user