xref: /aosp_15_r20/external/googletest/docs/reference/assertions.md (revision 481dde660366d6f317d242b6974ef1b20adb843c)
1*481dde66SAndroid Build Coastguard Worker# Assertions Reference
2*481dde66SAndroid Build Coastguard Worker
3*481dde66SAndroid Build Coastguard WorkerThis page lists the assertion macros provided by GoogleTest for verifying code
4*481dde66SAndroid Build Coastguard Workerbehavior. To use them, add `#include <gtest/gtest.h>`.
5*481dde66SAndroid Build Coastguard Worker
6*481dde66SAndroid Build Coastguard WorkerThe majority of the macros listed below come as a pair with an `EXPECT_` variant
7*481dde66SAndroid Build Coastguard Workerand an `ASSERT_` variant. Upon failure, `EXPECT_` macros generate nonfatal
8*481dde66SAndroid Build Coastguard Workerfailures and allow the current function to continue running, while `ASSERT_`
9*481dde66SAndroid Build Coastguard Workermacros generate fatal failures and abort the current function.
10*481dde66SAndroid Build Coastguard Worker
11*481dde66SAndroid Build Coastguard WorkerAll assertion macros support streaming a custom failure message into them with
12*481dde66SAndroid Build Coastguard Workerthe `<<` operator, for example:
13*481dde66SAndroid Build Coastguard Worker
14*481dde66SAndroid Build Coastguard Worker```cpp
15*481dde66SAndroid Build Coastguard WorkerEXPECT_TRUE(my_condition) << "My condition is not true";
16*481dde66SAndroid Build Coastguard Worker```
17*481dde66SAndroid Build Coastguard Worker
18*481dde66SAndroid Build Coastguard WorkerAnything that can be streamed to an `ostream` can be streamed to an assertion
19*481dde66SAndroid Build Coastguard Workermacro—in particular, C strings and string objects. If a wide string (`wchar_t*`,
20*481dde66SAndroid Build Coastguard Worker`TCHAR*` in `UNICODE` mode on Windows, or `std::wstring`) is streamed to an
21*481dde66SAndroid Build Coastguard Workerassertion, it will be translated to UTF-8 when printed.
22*481dde66SAndroid Build Coastguard Worker
23*481dde66SAndroid Build Coastguard Worker## Explicit Success and Failure {#success-failure}
24*481dde66SAndroid Build Coastguard Worker
25*481dde66SAndroid Build Coastguard WorkerThe assertions in this section generate a success or failure directly instead of
26*481dde66SAndroid Build Coastguard Workertesting a value or expression. These are useful when control flow, rather than a
27*481dde66SAndroid Build Coastguard WorkerBoolean expression, determines the test's success or failure, as shown by the
28*481dde66SAndroid Build Coastguard Workerfollowing example:
29*481dde66SAndroid Build Coastguard Worker
30*481dde66SAndroid Build Coastguard Worker```c++
31*481dde66SAndroid Build Coastguard Workerswitch(expression) {
32*481dde66SAndroid Build Coastguard Worker  case 1:
33*481dde66SAndroid Build Coastguard Worker    ... some checks ...
34*481dde66SAndroid Build Coastguard Worker  case 2:
35*481dde66SAndroid Build Coastguard Worker    ... some other checks ...
36*481dde66SAndroid Build Coastguard Worker  default:
37*481dde66SAndroid Build Coastguard Worker    FAIL() << "We shouldn't get here.";
38*481dde66SAndroid Build Coastguard Worker}
39*481dde66SAndroid Build Coastguard Worker```
40*481dde66SAndroid Build Coastguard Worker
41*481dde66SAndroid Build Coastguard Worker### SUCCEED {#SUCCEED}
42*481dde66SAndroid Build Coastguard Worker
43*481dde66SAndroid Build Coastguard Worker`SUCCEED()`
44*481dde66SAndroid Build Coastguard Worker
45*481dde66SAndroid Build Coastguard WorkerGenerates a success. This *does not* make the overall test succeed. A test is
46*481dde66SAndroid Build Coastguard Workerconsidered successful only if none of its assertions fail during its execution.
47*481dde66SAndroid Build Coastguard Worker
48*481dde66SAndroid Build Coastguard WorkerThe `SUCCEED` assertion is purely documentary and currently doesn't generate any
49*481dde66SAndroid Build Coastguard Workeruser-visible output. However, we may add `SUCCEED` messages to GoogleTest output
50*481dde66SAndroid Build Coastguard Workerin the future.
51*481dde66SAndroid Build Coastguard Worker
52*481dde66SAndroid Build Coastguard Worker### FAIL {#FAIL}
53*481dde66SAndroid Build Coastguard Worker
54*481dde66SAndroid Build Coastguard Worker`FAIL()`
55*481dde66SAndroid Build Coastguard Worker
56*481dde66SAndroid Build Coastguard WorkerGenerates a fatal failure, which returns from the current function.
57*481dde66SAndroid Build Coastguard Worker
58*481dde66SAndroid Build Coastguard WorkerCan only be used in functions that return `void`. See
59*481dde66SAndroid Build Coastguard Worker[Assertion Placement](../advanced.md#assertion-placement) for more information.
60*481dde66SAndroid Build Coastguard Worker
61*481dde66SAndroid Build Coastguard Worker### ADD_FAILURE {#ADD_FAILURE}
62*481dde66SAndroid Build Coastguard Worker
63*481dde66SAndroid Build Coastguard Worker`ADD_FAILURE()`
64*481dde66SAndroid Build Coastguard Worker
65*481dde66SAndroid Build Coastguard WorkerGenerates a nonfatal failure, which allows the current function to continue
66*481dde66SAndroid Build Coastguard Workerrunning.
67*481dde66SAndroid Build Coastguard Worker
68*481dde66SAndroid Build Coastguard Worker### ADD_FAILURE_AT {#ADD_FAILURE_AT}
69*481dde66SAndroid Build Coastguard Worker
70*481dde66SAndroid Build Coastguard Worker`ADD_FAILURE_AT(`*`file_path`*`,`*`line_number`*`)`
71*481dde66SAndroid Build Coastguard Worker
72*481dde66SAndroid Build Coastguard WorkerGenerates a nonfatal failure at the file and line number specified.
73*481dde66SAndroid Build Coastguard Worker
74*481dde66SAndroid Build Coastguard Worker## Generalized Assertion {#generalized}
75*481dde66SAndroid Build Coastguard Worker
76*481dde66SAndroid Build Coastguard WorkerThe following assertion allows [matchers](matchers.md) to be used to verify
77*481dde66SAndroid Build Coastguard Workervalues.
78*481dde66SAndroid Build Coastguard Worker
79*481dde66SAndroid Build Coastguard Worker### EXPECT_THAT {#EXPECT_THAT}
80*481dde66SAndroid Build Coastguard Worker
81*481dde66SAndroid Build Coastguard Worker`EXPECT_THAT(`*`value`*`,`*`matcher`*`)` \
82*481dde66SAndroid Build Coastguard Worker`ASSERT_THAT(`*`value`*`,`*`matcher`*`)`
83*481dde66SAndroid Build Coastguard Worker
84*481dde66SAndroid Build Coastguard WorkerVerifies that *`value`* matches the [matcher](matchers.md) *`matcher`*.
85*481dde66SAndroid Build Coastguard Worker
86*481dde66SAndroid Build Coastguard WorkerFor example, the following code verifies that the string `value1` starts with
87*481dde66SAndroid Build Coastguard Worker`"Hello"`, `value2` matches a regular expression, and `value3` is between 5 and
88*481dde66SAndroid Build Coastguard Worker10:
89*481dde66SAndroid Build Coastguard Worker
90*481dde66SAndroid Build Coastguard Worker```cpp
91*481dde66SAndroid Build Coastguard Worker#include <gmock/gmock.h>
92*481dde66SAndroid Build Coastguard Worker
93*481dde66SAndroid Build Coastguard Workerusing ::testing::AllOf;
94*481dde66SAndroid Build Coastguard Workerusing ::testing::Gt;
95*481dde66SAndroid Build Coastguard Workerusing ::testing::Lt;
96*481dde66SAndroid Build Coastguard Workerusing ::testing::MatchesRegex;
97*481dde66SAndroid Build Coastguard Workerusing ::testing::StartsWith;
98*481dde66SAndroid Build Coastguard Worker
99*481dde66SAndroid Build Coastguard Worker...
100*481dde66SAndroid Build Coastguard WorkerEXPECT_THAT(value1, StartsWith("Hello"));
101*481dde66SAndroid Build Coastguard WorkerEXPECT_THAT(value2, MatchesRegex("Line \\d+"));
102*481dde66SAndroid Build Coastguard WorkerASSERT_THAT(value3, AllOf(Gt(5), Lt(10)));
103*481dde66SAndroid Build Coastguard Worker```
104*481dde66SAndroid Build Coastguard Worker
105*481dde66SAndroid Build Coastguard WorkerMatchers enable assertions of this form to read like English and generate
106*481dde66SAndroid Build Coastguard Workerinformative failure messages. For example, if the above assertion on `value1`
107*481dde66SAndroid Build Coastguard Workerfails, the resulting message will be similar to the following:
108*481dde66SAndroid Build Coastguard Worker
109*481dde66SAndroid Build Coastguard Worker```
110*481dde66SAndroid Build Coastguard WorkerValue of: value1
111*481dde66SAndroid Build Coastguard Worker  Actual: "Hi, world!"
112*481dde66SAndroid Build Coastguard WorkerExpected: starts with "Hello"
113*481dde66SAndroid Build Coastguard Worker```
114*481dde66SAndroid Build Coastguard Worker
115*481dde66SAndroid Build Coastguard WorkerGoogleTest provides a built-in library of matchers—see the
116*481dde66SAndroid Build Coastguard Worker[Matchers Reference](matchers.md). It is also possible to write your own
117*481dde66SAndroid Build Coastguard Workermatchers—see [Writing New Matchers Quickly](../gmock_cook_book.md#NewMatchers).
118*481dde66SAndroid Build Coastguard WorkerThe use of matchers makes `EXPECT_THAT` a powerful, extensible assertion.
119*481dde66SAndroid Build Coastguard Worker
120*481dde66SAndroid Build Coastguard Worker*The idea for this assertion was borrowed from Joe Walnes' Hamcrest project,
121*481dde66SAndroid Build Coastguard Workerwhich adds `assertThat()` to JUnit.*
122*481dde66SAndroid Build Coastguard Worker
123*481dde66SAndroid Build Coastguard Worker## Boolean Conditions {#boolean}
124*481dde66SAndroid Build Coastguard Worker
125*481dde66SAndroid Build Coastguard WorkerThe following assertions test Boolean conditions.
126*481dde66SAndroid Build Coastguard Worker
127*481dde66SAndroid Build Coastguard Worker### EXPECT_TRUE {#EXPECT_TRUE}
128*481dde66SAndroid Build Coastguard Worker
129*481dde66SAndroid Build Coastguard Worker`EXPECT_TRUE(`*`condition`*`)` \
130*481dde66SAndroid Build Coastguard Worker`ASSERT_TRUE(`*`condition`*`)`
131*481dde66SAndroid Build Coastguard Worker
132*481dde66SAndroid Build Coastguard WorkerVerifies that *`condition`* is true.
133*481dde66SAndroid Build Coastguard Worker
134*481dde66SAndroid Build Coastguard Worker### EXPECT_FALSE {#EXPECT_FALSE}
135*481dde66SAndroid Build Coastguard Worker
136*481dde66SAndroid Build Coastguard Worker`EXPECT_FALSE(`*`condition`*`)` \
137*481dde66SAndroid Build Coastguard Worker`ASSERT_FALSE(`*`condition`*`)`
138*481dde66SAndroid Build Coastguard Worker
139*481dde66SAndroid Build Coastguard WorkerVerifies that *`condition`* is false.
140*481dde66SAndroid Build Coastguard Worker
141*481dde66SAndroid Build Coastguard Worker## Binary Comparison {#binary-comparison}
142*481dde66SAndroid Build Coastguard Worker
143*481dde66SAndroid Build Coastguard WorkerThe following assertions compare two values. The value arguments must be
144*481dde66SAndroid Build Coastguard Workercomparable by the assertion's comparison operator, otherwise a compiler error
145*481dde66SAndroid Build Coastguard Workerwill result.
146*481dde66SAndroid Build Coastguard Worker
147*481dde66SAndroid Build Coastguard WorkerIf an argument supports the `<<` operator, it will be called to print the
148*481dde66SAndroid Build Coastguard Workerargument when the assertion fails. Otherwise, GoogleTest will attempt to print
149*481dde66SAndroid Build Coastguard Workerthem in the best way it can—see
150*481dde66SAndroid Build Coastguard Worker[Teaching GoogleTest How to Print Your Values](../advanced.md#teaching-googletest-how-to-print-your-values).
151*481dde66SAndroid Build Coastguard Worker
152*481dde66SAndroid Build Coastguard WorkerArguments are always evaluated exactly once, so it's OK for the arguments to
153*481dde66SAndroid Build Coastguard Workerhave side effects. However, the argument evaluation order is undefined and
154*481dde66SAndroid Build Coastguard Workerprograms should not depend on any particular argument evaluation order.
155*481dde66SAndroid Build Coastguard Worker
156*481dde66SAndroid Build Coastguard WorkerThese assertions work with both narrow and wide string objects (`string` and
157*481dde66SAndroid Build Coastguard Worker`wstring`).
158*481dde66SAndroid Build Coastguard Worker
159*481dde66SAndroid Build Coastguard WorkerSee also the [Floating-Point Comparison](#floating-point) assertions to compare
160*481dde66SAndroid Build Coastguard Workerfloating-point numbers and avoid problems caused by rounding.
161*481dde66SAndroid Build Coastguard Worker
162*481dde66SAndroid Build Coastguard Worker### EXPECT_EQ {#EXPECT_EQ}
163*481dde66SAndroid Build Coastguard Worker
164*481dde66SAndroid Build Coastguard Worker`EXPECT_EQ(`*`val1`*`,`*`val2`*`)` \
165*481dde66SAndroid Build Coastguard Worker`ASSERT_EQ(`*`val1`*`,`*`val2`*`)`
166*481dde66SAndroid Build Coastguard Worker
167*481dde66SAndroid Build Coastguard WorkerVerifies that *`val1`*`==`*`val2`*.
168*481dde66SAndroid Build Coastguard Worker
169*481dde66SAndroid Build Coastguard WorkerDoes pointer equality on pointers. If used on two C strings, it tests if they
170*481dde66SAndroid Build Coastguard Workerare in the same memory location, not if they have the same value. Use
171*481dde66SAndroid Build Coastguard Worker[`EXPECT_STREQ`](#EXPECT_STREQ) to compare C strings (e.g. `const char*`) by
172*481dde66SAndroid Build Coastguard Workervalue.
173*481dde66SAndroid Build Coastguard Worker
174*481dde66SAndroid Build Coastguard WorkerWhen comparing a pointer to `NULL`, use `EXPECT_EQ(`*`ptr`*`, nullptr)` instead
175*481dde66SAndroid Build Coastguard Workerof `EXPECT_EQ(`*`ptr`*`, NULL)`.
176*481dde66SAndroid Build Coastguard Worker
177*481dde66SAndroid Build Coastguard Worker### EXPECT_NE {#EXPECT_NE}
178*481dde66SAndroid Build Coastguard Worker
179*481dde66SAndroid Build Coastguard Worker`EXPECT_NE(`*`val1`*`,`*`val2`*`)` \
180*481dde66SAndroid Build Coastguard Worker`ASSERT_NE(`*`val1`*`,`*`val2`*`)`
181*481dde66SAndroid Build Coastguard Worker
182*481dde66SAndroid Build Coastguard WorkerVerifies that *`val1`*`!=`*`val2`*.
183*481dde66SAndroid Build Coastguard Worker
184*481dde66SAndroid Build Coastguard WorkerDoes pointer equality on pointers. If used on two C strings, it tests if they
185*481dde66SAndroid Build Coastguard Workerare in different memory locations, not if they have different values. Use
186*481dde66SAndroid Build Coastguard Worker[`EXPECT_STRNE`](#EXPECT_STRNE) to compare C strings (e.g. `const char*`) by
187*481dde66SAndroid Build Coastguard Workervalue.
188*481dde66SAndroid Build Coastguard Worker
189*481dde66SAndroid Build Coastguard WorkerWhen comparing a pointer to `NULL`, use `EXPECT_NE(`*`ptr`*`, nullptr)` instead
190*481dde66SAndroid Build Coastguard Workerof `EXPECT_NE(`*`ptr`*`, NULL)`.
191*481dde66SAndroid Build Coastguard Worker
192*481dde66SAndroid Build Coastguard Worker### EXPECT_LT {#EXPECT_LT}
193*481dde66SAndroid Build Coastguard Worker
194*481dde66SAndroid Build Coastguard Worker`EXPECT_LT(`*`val1`*`,`*`val2`*`)` \
195*481dde66SAndroid Build Coastguard Worker`ASSERT_LT(`*`val1`*`,`*`val2`*`)`
196*481dde66SAndroid Build Coastguard Worker
197*481dde66SAndroid Build Coastguard WorkerVerifies that *`val1`*`<`*`val2`*.
198*481dde66SAndroid Build Coastguard Worker
199*481dde66SAndroid Build Coastguard Worker### EXPECT_LE {#EXPECT_LE}
200*481dde66SAndroid Build Coastguard Worker
201*481dde66SAndroid Build Coastguard Worker`EXPECT_LE(`*`val1`*`,`*`val2`*`)` \
202*481dde66SAndroid Build Coastguard Worker`ASSERT_LE(`*`val1`*`,`*`val2`*`)`
203*481dde66SAndroid Build Coastguard Worker
204*481dde66SAndroid Build Coastguard WorkerVerifies that *`val1`*`<=`*`val2`*.
205*481dde66SAndroid Build Coastguard Worker
206*481dde66SAndroid Build Coastguard Worker### EXPECT_GT {#EXPECT_GT}
207*481dde66SAndroid Build Coastguard Worker
208*481dde66SAndroid Build Coastguard Worker`EXPECT_GT(`*`val1`*`,`*`val2`*`)` \
209*481dde66SAndroid Build Coastguard Worker`ASSERT_GT(`*`val1`*`,`*`val2`*`)`
210*481dde66SAndroid Build Coastguard Worker
211*481dde66SAndroid Build Coastguard WorkerVerifies that *`val1`*`>`*`val2`*.
212*481dde66SAndroid Build Coastguard Worker
213*481dde66SAndroid Build Coastguard Worker### EXPECT_GE {#EXPECT_GE}
214*481dde66SAndroid Build Coastguard Worker
215*481dde66SAndroid Build Coastguard Worker`EXPECT_GE(`*`val1`*`,`*`val2`*`)` \
216*481dde66SAndroid Build Coastguard Worker`ASSERT_GE(`*`val1`*`,`*`val2`*`)`
217*481dde66SAndroid Build Coastguard Worker
218*481dde66SAndroid Build Coastguard WorkerVerifies that *`val1`*`>=`*`val2`*.
219*481dde66SAndroid Build Coastguard Worker
220*481dde66SAndroid Build Coastguard Worker## String Comparison {#c-strings}
221*481dde66SAndroid Build Coastguard Worker
222*481dde66SAndroid Build Coastguard WorkerThe following assertions compare two **C strings**. To compare two `string`
223*481dde66SAndroid Build Coastguard Workerobjects, use [`EXPECT_EQ`](#EXPECT_EQ) or [`EXPECT_NE`](#EXPECT_NE) instead.
224*481dde66SAndroid Build Coastguard Worker
225*481dde66SAndroid Build Coastguard WorkerThese assertions also accept wide C strings (`wchar_t*`). If a comparison of two
226*481dde66SAndroid Build Coastguard Workerwide strings fails, their values will be printed as UTF-8 narrow strings.
227*481dde66SAndroid Build Coastguard Worker
228*481dde66SAndroid Build Coastguard WorkerTo compare a C string with `NULL`, use `EXPECT_EQ(`*`c_string`*`, nullptr)` or
229*481dde66SAndroid Build Coastguard Worker`EXPECT_NE(`*`c_string`*`, nullptr)`.
230*481dde66SAndroid Build Coastguard Worker
231*481dde66SAndroid Build Coastguard Worker### EXPECT_STREQ {#EXPECT_STREQ}
232*481dde66SAndroid Build Coastguard Worker
233*481dde66SAndroid Build Coastguard Worker`EXPECT_STREQ(`*`str1`*`,`*`str2`*`)` \
234*481dde66SAndroid Build Coastguard Worker`ASSERT_STREQ(`*`str1`*`,`*`str2`*`)`
235*481dde66SAndroid Build Coastguard Worker
236*481dde66SAndroid Build Coastguard WorkerVerifies that the two C strings *`str1`* and *`str2`* have the same contents.
237*481dde66SAndroid Build Coastguard Worker
238*481dde66SAndroid Build Coastguard Worker### EXPECT_STRNE {#EXPECT_STRNE}
239*481dde66SAndroid Build Coastguard Worker
240*481dde66SAndroid Build Coastguard Worker`EXPECT_STRNE(`*`str1`*`,`*`str2`*`)` \
241*481dde66SAndroid Build Coastguard Worker`ASSERT_STRNE(`*`str1`*`,`*`str2`*`)`
242*481dde66SAndroid Build Coastguard Worker
243*481dde66SAndroid Build Coastguard WorkerVerifies that the two C strings *`str1`* and *`str2`* have different contents.
244*481dde66SAndroid Build Coastguard Worker
245*481dde66SAndroid Build Coastguard Worker### EXPECT_STRCASEEQ {#EXPECT_STRCASEEQ}
246*481dde66SAndroid Build Coastguard Worker
247*481dde66SAndroid Build Coastguard Worker`EXPECT_STRCASEEQ(`*`str1`*`,`*`str2`*`)` \
248*481dde66SAndroid Build Coastguard Worker`ASSERT_STRCASEEQ(`*`str1`*`,`*`str2`*`)`
249*481dde66SAndroid Build Coastguard Worker
250*481dde66SAndroid Build Coastguard WorkerVerifies that the two C strings *`str1`* and *`str2`* have the same contents,
251*481dde66SAndroid Build Coastguard Workerignoring case.
252*481dde66SAndroid Build Coastguard Worker
253*481dde66SAndroid Build Coastguard Worker### EXPECT_STRCASENE {#EXPECT_STRCASENE}
254*481dde66SAndroid Build Coastguard Worker
255*481dde66SAndroid Build Coastguard Worker`EXPECT_STRCASENE(`*`str1`*`,`*`str2`*`)` \
256*481dde66SAndroid Build Coastguard Worker`ASSERT_STRCASENE(`*`str1`*`,`*`str2`*`)`
257*481dde66SAndroid Build Coastguard Worker
258*481dde66SAndroid Build Coastguard WorkerVerifies that the two C strings *`str1`* and *`str2`* have different contents,
259*481dde66SAndroid Build Coastguard Workerignoring case.
260*481dde66SAndroid Build Coastguard Worker
261*481dde66SAndroid Build Coastguard Worker## Floating-Point Comparison {#floating-point}
262*481dde66SAndroid Build Coastguard Worker
263*481dde66SAndroid Build Coastguard WorkerThe following assertions compare two floating-point values.
264*481dde66SAndroid Build Coastguard Worker
265*481dde66SAndroid Build Coastguard WorkerDue to rounding errors, it is very unlikely that two floating-point values will
266*481dde66SAndroid Build Coastguard Workermatch exactly, so `EXPECT_EQ` is not suitable. In general, for floating-point
267*481dde66SAndroid Build Coastguard Workercomparison to make sense, the user needs to carefully choose the error bound.
268*481dde66SAndroid Build Coastguard Worker
269*481dde66SAndroid Build Coastguard WorkerGoogleTest also provides assertions that use a default error bound based on
270*481dde66SAndroid Build Coastguard WorkerUnits in the Last Place (ULPs). To learn more about ULPs, see the article
271*481dde66SAndroid Build Coastguard Worker[Comparing Floating Point Numbers](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/).
272*481dde66SAndroid Build Coastguard Worker
273*481dde66SAndroid Build Coastguard Worker### EXPECT_FLOAT_EQ {#EXPECT_FLOAT_EQ}
274*481dde66SAndroid Build Coastguard Worker
275*481dde66SAndroid Build Coastguard Worker`EXPECT_FLOAT_EQ(`*`val1`*`,`*`val2`*`)` \
276*481dde66SAndroid Build Coastguard Worker`ASSERT_FLOAT_EQ(`*`val1`*`,`*`val2`*`)`
277*481dde66SAndroid Build Coastguard Worker
278*481dde66SAndroid Build Coastguard WorkerVerifies that the two `float` values *`val1`* and *`val2`* are approximately
279*481dde66SAndroid Build Coastguard Workerequal, to within 4 ULPs from each other.
280*481dde66SAndroid Build Coastguard Worker
281*481dde66SAndroid Build Coastguard Worker### EXPECT_DOUBLE_EQ {#EXPECT_DOUBLE_EQ}
282*481dde66SAndroid Build Coastguard Worker
283*481dde66SAndroid Build Coastguard Worker`EXPECT_DOUBLE_EQ(`*`val1`*`,`*`val2`*`)` \
284*481dde66SAndroid Build Coastguard Worker`ASSERT_DOUBLE_EQ(`*`val1`*`,`*`val2`*`)`
285*481dde66SAndroid Build Coastguard Worker
286*481dde66SAndroid Build Coastguard WorkerVerifies that the two `double` values *`val1`* and *`val2`* are approximately
287*481dde66SAndroid Build Coastguard Workerequal, to within 4 ULPs from each other.
288*481dde66SAndroid Build Coastguard Worker
289*481dde66SAndroid Build Coastguard Worker### EXPECT_NEAR {#EXPECT_NEAR}
290*481dde66SAndroid Build Coastguard Worker
291*481dde66SAndroid Build Coastguard Worker`EXPECT_NEAR(`*`val1`*`,`*`val2`*`,`*`abs_error`*`)` \
292*481dde66SAndroid Build Coastguard Worker`ASSERT_NEAR(`*`val1`*`,`*`val2`*`,`*`abs_error`*`)`
293*481dde66SAndroid Build Coastguard Worker
294*481dde66SAndroid Build Coastguard WorkerVerifies that the difference between *`val1`* and *`val2`* does not exceed the
295*481dde66SAndroid Build Coastguard Workerabsolute error bound *`abs_error`*.
296*481dde66SAndroid Build Coastguard Worker
297*481dde66SAndroid Build Coastguard Worker## Exception Assertions {#exceptions}
298*481dde66SAndroid Build Coastguard Worker
299*481dde66SAndroid Build Coastguard WorkerThe following assertions verify that a piece of code throws, or does not throw,
300*481dde66SAndroid Build Coastguard Workeran exception. Usage requires exceptions to be enabled in the build environment.
301*481dde66SAndroid Build Coastguard Worker
302*481dde66SAndroid Build Coastguard WorkerNote that the piece of code under test can be a compound statement, for example:
303*481dde66SAndroid Build Coastguard Worker
304*481dde66SAndroid Build Coastguard Worker```cpp
305*481dde66SAndroid Build Coastguard WorkerEXPECT_NO_THROW({
306*481dde66SAndroid Build Coastguard Worker  int n = 5;
307*481dde66SAndroid Build Coastguard Worker  DoSomething(&n);
308*481dde66SAndroid Build Coastguard Worker});
309*481dde66SAndroid Build Coastguard Worker```
310*481dde66SAndroid Build Coastguard Worker
311*481dde66SAndroid Build Coastguard Worker### EXPECT_THROW {#EXPECT_THROW}
312*481dde66SAndroid Build Coastguard Worker
313*481dde66SAndroid Build Coastguard Worker`EXPECT_THROW(`*`statement`*`,`*`exception_type`*`)` \
314*481dde66SAndroid Build Coastguard Worker`ASSERT_THROW(`*`statement`*`,`*`exception_type`*`)`
315*481dde66SAndroid Build Coastguard Worker
316*481dde66SAndroid Build Coastguard WorkerVerifies that *`statement`* throws an exception of type *`exception_type`*.
317*481dde66SAndroid Build Coastguard Worker
318*481dde66SAndroid Build Coastguard Worker### EXPECT_ANY_THROW {#EXPECT_ANY_THROW}
319*481dde66SAndroid Build Coastguard Worker
320*481dde66SAndroid Build Coastguard Worker`EXPECT_ANY_THROW(`*`statement`*`)` \
321*481dde66SAndroid Build Coastguard Worker`ASSERT_ANY_THROW(`*`statement`*`)`
322*481dde66SAndroid Build Coastguard Worker
323*481dde66SAndroid Build Coastguard WorkerVerifies that *`statement`* throws an exception of any type.
324*481dde66SAndroid Build Coastguard Worker
325*481dde66SAndroid Build Coastguard Worker### EXPECT_NO_THROW {#EXPECT_NO_THROW}
326*481dde66SAndroid Build Coastguard Worker
327*481dde66SAndroid Build Coastguard Worker`EXPECT_NO_THROW(`*`statement`*`)` \
328*481dde66SAndroid Build Coastguard Worker`ASSERT_NO_THROW(`*`statement`*`)`
329*481dde66SAndroid Build Coastguard Worker
330*481dde66SAndroid Build Coastguard WorkerVerifies that *`statement`* does not throw any exception.
331*481dde66SAndroid Build Coastguard Worker
332*481dde66SAndroid Build Coastguard Worker## Predicate Assertions {#predicates}
333*481dde66SAndroid Build Coastguard Worker
334*481dde66SAndroid Build Coastguard WorkerThe following assertions enable more complex predicates to be verified while
335*481dde66SAndroid Build Coastguard Workerprinting a more clear failure message than if `EXPECT_TRUE` were used alone.
336*481dde66SAndroid Build Coastguard Worker
337*481dde66SAndroid Build Coastguard Worker### EXPECT_PRED* {#EXPECT_PRED}
338*481dde66SAndroid Build Coastguard Worker
339*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED1(`*`pred`*`,`*`val1`*`)` \
340*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED2(`*`pred`*`,`*`val1`*`,`*`val2`*`)` \
341*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED3(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \
342*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED4(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)` \
343*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED5(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)`
344*481dde66SAndroid Build Coastguard Worker
345*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED1(`*`pred`*`,`*`val1`*`)` \
346*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED2(`*`pred`*`,`*`val1`*`,`*`val2`*`)` \
347*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED3(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \
348*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED4(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)` \
349*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED5(`*`pred`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)`
350*481dde66SAndroid Build Coastguard Worker
351*481dde66SAndroid Build Coastguard WorkerVerifies that the predicate *`pred`* returns `true` when passed the given values
352*481dde66SAndroid Build Coastguard Workeras arguments.
353*481dde66SAndroid Build Coastguard Worker
354*481dde66SAndroid Build Coastguard WorkerThe parameter *`pred`* is a function or functor that accepts as many arguments
355*481dde66SAndroid Build Coastguard Workeras the corresponding macro accepts values. If *`pred`* returns `true` for the
356*481dde66SAndroid Build Coastguard Workergiven arguments, the assertion succeeds, otherwise the assertion fails.
357*481dde66SAndroid Build Coastguard Worker
358*481dde66SAndroid Build Coastguard WorkerWhen the assertion fails, it prints the value of each argument. Arguments are
359*481dde66SAndroid Build Coastguard Workeralways evaluated exactly once.
360*481dde66SAndroid Build Coastguard Worker
361*481dde66SAndroid Build Coastguard WorkerAs an example, see the following code:
362*481dde66SAndroid Build Coastguard Worker
363*481dde66SAndroid Build Coastguard Worker```cpp
364*481dde66SAndroid Build Coastguard Worker// Returns true if m and n have no common divisors except 1.
365*481dde66SAndroid Build Coastguard Workerbool MutuallyPrime(int m, int n) { ... }
366*481dde66SAndroid Build Coastguard Worker...
367*481dde66SAndroid Build Coastguard Workerconst int a = 3;
368*481dde66SAndroid Build Coastguard Workerconst int b = 4;
369*481dde66SAndroid Build Coastguard Workerconst int c = 10;
370*481dde66SAndroid Build Coastguard Worker...
371*481dde66SAndroid Build Coastguard WorkerEXPECT_PRED2(MutuallyPrime, a, b);  // Succeeds
372*481dde66SAndroid Build Coastguard WorkerEXPECT_PRED2(MutuallyPrime, b, c);  // Fails
373*481dde66SAndroid Build Coastguard Worker```
374*481dde66SAndroid Build Coastguard Worker
375*481dde66SAndroid Build Coastguard WorkerIn the above example, the first assertion succeeds, and the second fails with
376*481dde66SAndroid Build Coastguard Workerthe following message:
377*481dde66SAndroid Build Coastguard Worker
378*481dde66SAndroid Build Coastguard Worker```
379*481dde66SAndroid Build Coastguard WorkerMutuallyPrime(b, c) is false, where
380*481dde66SAndroid Build Coastguard Workerb is 4
381*481dde66SAndroid Build Coastguard Workerc is 10
382*481dde66SAndroid Build Coastguard Worker```
383*481dde66SAndroid Build Coastguard Worker
384*481dde66SAndroid Build Coastguard WorkerNote that if the given predicate is an overloaded function or a function
385*481dde66SAndroid Build Coastguard Workertemplate, the assertion macro might not be able to determine which version to
386*481dde66SAndroid Build Coastguard Workeruse, and it might be necessary to explicitly specify the type of the function.
387*481dde66SAndroid Build Coastguard WorkerFor example, for a Boolean function `IsPositive()` overloaded to take either a
388*481dde66SAndroid Build Coastguard Workersingle `int` or `double` argument, it would be necessary to write one of the
389*481dde66SAndroid Build Coastguard Workerfollowing:
390*481dde66SAndroid Build Coastguard Worker
391*481dde66SAndroid Build Coastguard Worker```cpp
392*481dde66SAndroid Build Coastguard WorkerEXPECT_PRED1(static_cast<bool (*)(int)>(IsPositive), 5);
393*481dde66SAndroid Build Coastguard WorkerEXPECT_PRED1(static_cast<bool (*)(double)>(IsPositive), 3.14);
394*481dde66SAndroid Build Coastguard Worker```
395*481dde66SAndroid Build Coastguard Worker
396*481dde66SAndroid Build Coastguard WorkerWriting simply `EXPECT_PRED1(IsPositive, 5);` would result in a compiler error.
397*481dde66SAndroid Build Coastguard WorkerSimilarly, to use a template function, specify the template arguments:
398*481dde66SAndroid Build Coastguard Worker
399*481dde66SAndroid Build Coastguard Worker```cpp
400*481dde66SAndroid Build Coastguard Workertemplate <typename T>
401*481dde66SAndroid Build Coastguard Workerbool IsNegative(T x) {
402*481dde66SAndroid Build Coastguard Worker  return x < 0;
403*481dde66SAndroid Build Coastguard Worker}
404*481dde66SAndroid Build Coastguard Worker...
405*481dde66SAndroid Build Coastguard WorkerEXPECT_PRED1(IsNegative<int>, -5);  // Must specify type for IsNegative
406*481dde66SAndroid Build Coastguard Worker```
407*481dde66SAndroid Build Coastguard Worker
408*481dde66SAndroid Build Coastguard WorkerIf a template has multiple parameters, wrap the predicate in parentheses so the
409*481dde66SAndroid Build Coastguard Workermacro arguments are parsed correctly:
410*481dde66SAndroid Build Coastguard Worker
411*481dde66SAndroid Build Coastguard Worker```cpp
412*481dde66SAndroid Build Coastguard WorkerASSERT_PRED2((MyPredicate<int, int>), 5, 0);
413*481dde66SAndroid Build Coastguard Worker```
414*481dde66SAndroid Build Coastguard Worker
415*481dde66SAndroid Build Coastguard Worker### EXPECT_PRED_FORMAT* {#EXPECT_PRED_FORMAT}
416*481dde66SAndroid Build Coastguard Worker
417*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED_FORMAT1(`*`pred_formatter`*`,`*`val1`*`)` \
418*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED_FORMAT2(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`)` \
419*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED_FORMAT3(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \
420*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED_FORMAT4(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)`
421*481dde66SAndroid Build Coastguard Worker\
422*481dde66SAndroid Build Coastguard Worker`EXPECT_PRED_FORMAT5(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)`
423*481dde66SAndroid Build Coastguard Worker
424*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED_FORMAT1(`*`pred_formatter`*`,`*`val1`*`)` \
425*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED_FORMAT2(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`)` \
426*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED_FORMAT3(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`)` \
427*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED_FORMAT4(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`)`
428*481dde66SAndroid Build Coastguard Worker\
429*481dde66SAndroid Build Coastguard Worker`ASSERT_PRED_FORMAT5(`*`pred_formatter`*`,`*`val1`*`,`*`val2`*`,`*`val3`*`,`*`val4`*`,`*`val5`*`)`
430*481dde66SAndroid Build Coastguard Worker
431*481dde66SAndroid Build Coastguard WorkerVerifies that the predicate *`pred_formatter`* succeeds when passed the given
432*481dde66SAndroid Build Coastguard Workervalues as arguments.
433*481dde66SAndroid Build Coastguard Worker
434*481dde66SAndroid Build Coastguard WorkerThe parameter *`pred_formatter`* is a *predicate-formatter*, which is a function
435*481dde66SAndroid Build Coastguard Workeror functor with the signature:
436*481dde66SAndroid Build Coastguard Worker
437*481dde66SAndroid Build Coastguard Worker```cpp
438*481dde66SAndroid Build Coastguard Workertesting::AssertionResult PredicateFormatter(const char* expr1,
439*481dde66SAndroid Build Coastguard Worker                                            const char* expr2,
440*481dde66SAndroid Build Coastguard Worker                                            ...
441*481dde66SAndroid Build Coastguard Worker                                            const char* exprn,
442*481dde66SAndroid Build Coastguard Worker                                            T1 val1,
443*481dde66SAndroid Build Coastguard Worker                                            T2 val2,
444*481dde66SAndroid Build Coastguard Worker                                            ...
445*481dde66SAndroid Build Coastguard Worker                                            Tn valn);
446*481dde66SAndroid Build Coastguard Worker```
447*481dde66SAndroid Build Coastguard Worker
448*481dde66SAndroid Build Coastguard Workerwhere *`val1`*, *`val2`*, ..., *`valn`* are the values of the predicate
449*481dde66SAndroid Build Coastguard Workerarguments, and *`expr1`*, *`expr2`*, ..., *`exprn`* are the corresponding
450*481dde66SAndroid Build Coastguard Workerexpressions as they appear in the source code. The types `T1`, `T2`, ..., `Tn`
451*481dde66SAndroid Build Coastguard Workercan be either value types or reference types; if an argument has type `T`, it
452*481dde66SAndroid Build Coastguard Workercan be declared as either `T` or `const T&`, whichever is appropriate. For more
453*481dde66SAndroid Build Coastguard Workerabout the return type `testing::AssertionResult`, see
454*481dde66SAndroid Build Coastguard Worker[Using a Function That Returns an AssertionResult](../advanced.md#using-a-function-that-returns-an-assertionresult).
455*481dde66SAndroid Build Coastguard Worker
456*481dde66SAndroid Build Coastguard WorkerAs an example, see the following code:
457*481dde66SAndroid Build Coastguard Worker
458*481dde66SAndroid Build Coastguard Worker```cpp
459*481dde66SAndroid Build Coastguard Worker// Returns the smallest prime common divisor of m and n,
460*481dde66SAndroid Build Coastguard Worker// or 1 when m and n are mutually prime.
461*481dde66SAndroid Build Coastguard Workerint SmallestPrimeCommonDivisor(int m, int n) { ... }
462*481dde66SAndroid Build Coastguard Worker
463*481dde66SAndroid Build Coastguard Worker// Returns true if m and n have no common divisors except 1.
464*481dde66SAndroid Build Coastguard Workerbool MutuallyPrime(int m, int n) { ... }
465*481dde66SAndroid Build Coastguard Worker
466*481dde66SAndroid Build Coastguard Worker// A predicate-formatter for asserting that two integers are mutually prime.
467*481dde66SAndroid Build Coastguard Workertesting::AssertionResult AssertMutuallyPrime(const char* m_expr,
468*481dde66SAndroid Build Coastguard Worker                                             const char* n_expr,
469*481dde66SAndroid Build Coastguard Worker                                             int m,
470*481dde66SAndroid Build Coastguard Worker                                             int n) {
471*481dde66SAndroid Build Coastguard Worker  if (MutuallyPrime(m, n)) return testing::AssertionSuccess();
472*481dde66SAndroid Build Coastguard Worker
473*481dde66SAndroid Build Coastguard Worker  return testing::AssertionFailure() << m_expr << " and " << n_expr
474*481dde66SAndroid Build Coastguard Worker      << " (" << m << " and " << n << ") are not mutually prime, "
475*481dde66SAndroid Build Coastguard Worker      << "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n);
476*481dde66SAndroid Build Coastguard Worker}
477*481dde66SAndroid Build Coastguard Worker
478*481dde66SAndroid Build Coastguard Worker...
479*481dde66SAndroid Build Coastguard Workerconst int a = 3;
480*481dde66SAndroid Build Coastguard Workerconst int b = 4;
481*481dde66SAndroid Build Coastguard Workerconst int c = 10;
482*481dde66SAndroid Build Coastguard Worker...
483*481dde66SAndroid Build Coastguard WorkerEXPECT_PRED_FORMAT2(AssertMutuallyPrime, a, b);  // Succeeds
484*481dde66SAndroid Build Coastguard WorkerEXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c);  // Fails
485*481dde66SAndroid Build Coastguard Worker```
486*481dde66SAndroid Build Coastguard Worker
487*481dde66SAndroid Build Coastguard WorkerIn the above example, the final assertion fails and the predicate-formatter
488*481dde66SAndroid Build Coastguard Workerproduces the following failure message:
489*481dde66SAndroid Build Coastguard Worker
490*481dde66SAndroid Build Coastguard Worker```
491*481dde66SAndroid Build Coastguard Workerb and c (4 and 10) are not mutually prime, as they have a common divisor 2
492*481dde66SAndroid Build Coastguard Worker```
493*481dde66SAndroid Build Coastguard Worker
494*481dde66SAndroid Build Coastguard Worker## Windows HRESULT Assertions {#HRESULT}
495*481dde66SAndroid Build Coastguard Worker
496*481dde66SAndroid Build Coastguard WorkerThe following assertions test for `HRESULT` success or failure. For example:
497*481dde66SAndroid Build Coastguard Worker
498*481dde66SAndroid Build Coastguard Worker```cpp
499*481dde66SAndroid Build Coastguard WorkerCComPtr<IShellDispatch2> shell;
500*481dde66SAndroid Build Coastguard WorkerASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application"));
501*481dde66SAndroid Build Coastguard WorkerCComVariant empty;
502*481dde66SAndroid Build Coastguard WorkerASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty));
503*481dde66SAndroid Build Coastguard Worker```
504*481dde66SAndroid Build Coastguard Worker
505*481dde66SAndroid Build Coastguard WorkerThe generated output contains the human-readable error message associated with
506*481dde66SAndroid Build Coastguard Workerthe returned `HRESULT` code.
507*481dde66SAndroid Build Coastguard Worker
508*481dde66SAndroid Build Coastguard Worker### EXPECT_HRESULT_SUCCEEDED {#EXPECT_HRESULT_SUCCEEDED}
509*481dde66SAndroid Build Coastguard Worker
510*481dde66SAndroid Build Coastguard Worker`EXPECT_HRESULT_SUCCEEDED(`*`expression`*`)` \
511*481dde66SAndroid Build Coastguard Worker`ASSERT_HRESULT_SUCCEEDED(`*`expression`*`)`
512*481dde66SAndroid Build Coastguard Worker
513*481dde66SAndroid Build Coastguard WorkerVerifies that *`expression`* is a success `HRESULT`.
514*481dde66SAndroid Build Coastguard Worker
515*481dde66SAndroid Build Coastguard Worker### EXPECT_HRESULT_FAILED {#EXPECT_HRESULT_FAILED}
516*481dde66SAndroid Build Coastguard Worker
517*481dde66SAndroid Build Coastguard Worker`EXPECT_HRESULT_FAILED(`*`expression`*`)` \
518*481dde66SAndroid Build Coastguard Worker`ASSERT_HRESULT_FAILED(`*`expression`*`)`
519*481dde66SAndroid Build Coastguard Worker
520*481dde66SAndroid Build Coastguard WorkerVerifies that *`expression`* is a failure `HRESULT`.
521*481dde66SAndroid Build Coastguard Worker
522*481dde66SAndroid Build Coastguard Worker## Death Assertions {#death}
523*481dde66SAndroid Build Coastguard Worker
524*481dde66SAndroid Build Coastguard WorkerThe following assertions verify that a piece of code causes the process to
525*481dde66SAndroid Build Coastguard Workerterminate. For context, see [Death Tests](../advanced.md#death-tests).
526*481dde66SAndroid Build Coastguard Worker
527*481dde66SAndroid Build Coastguard WorkerThese assertions spawn a new process and execute the code under test in that
528*481dde66SAndroid Build Coastguard Workerprocess. How that happens depends on the platform and the variable
529*481dde66SAndroid Build Coastguard Worker`::testing::GTEST_FLAG(death_test_style)`, which is initialized from the
530*481dde66SAndroid Build Coastguard Workercommand-line flag `--gtest_death_test_style`.
531*481dde66SAndroid Build Coastguard Worker
532*481dde66SAndroid Build Coastguard Worker*   On POSIX systems, `fork()` (or `clone()` on Linux) is used to spawn the
533*481dde66SAndroid Build Coastguard Worker    child, after which:
534*481dde66SAndroid Build Coastguard Worker    *   If the variable's value is `"fast"`, the death test statement is
535*481dde66SAndroid Build Coastguard Worker        immediately executed.
536*481dde66SAndroid Build Coastguard Worker    *   If the variable's value is `"threadsafe"`, the child process re-executes
537*481dde66SAndroid Build Coastguard Worker        the unit test binary just as it was originally invoked, but with some
538*481dde66SAndroid Build Coastguard Worker        extra flags to cause just the single death test under consideration to
539*481dde66SAndroid Build Coastguard Worker        be run.
540*481dde66SAndroid Build Coastguard Worker*   On Windows, the child is spawned using the `CreateProcess()` API, and
541*481dde66SAndroid Build Coastguard Worker    re-executes the binary to cause just the single death test under
542*481dde66SAndroid Build Coastguard Worker    consideration to be run - much like the `"threadsafe"` mode on POSIX.
543*481dde66SAndroid Build Coastguard Worker
544*481dde66SAndroid Build Coastguard WorkerOther values for the variable are illegal and will cause the death test to fail.
545*481dde66SAndroid Build Coastguard WorkerCurrently, the flag's default value is
546*481dde66SAndroid Build Coastguard Worker**`"fast"`**.
547*481dde66SAndroid Build Coastguard Worker
548*481dde66SAndroid Build Coastguard WorkerIf the death test statement runs to completion without dying, the child process
549*481dde66SAndroid Build Coastguard Workerwill nonetheless terminate, and the assertion fails.
550*481dde66SAndroid Build Coastguard Worker
551*481dde66SAndroid Build Coastguard WorkerNote that the piece of code under test can be a compound statement, for example:
552*481dde66SAndroid Build Coastguard Worker
553*481dde66SAndroid Build Coastguard Worker```cpp
554*481dde66SAndroid Build Coastguard WorkerEXPECT_DEATH({
555*481dde66SAndroid Build Coastguard Worker  int n = 5;
556*481dde66SAndroid Build Coastguard Worker  DoSomething(&n);
557*481dde66SAndroid Build Coastguard Worker}, "Error on line .* of DoSomething()");
558*481dde66SAndroid Build Coastguard Worker```
559*481dde66SAndroid Build Coastguard Worker
560*481dde66SAndroid Build Coastguard Worker### EXPECT_DEATH {#EXPECT_DEATH}
561*481dde66SAndroid Build Coastguard Worker
562*481dde66SAndroid Build Coastguard Worker`EXPECT_DEATH(`*`statement`*`,`*`matcher`*`)` \
563*481dde66SAndroid Build Coastguard Worker`ASSERT_DEATH(`*`statement`*`,`*`matcher`*`)`
564*481dde66SAndroid Build Coastguard Worker
565*481dde66SAndroid Build Coastguard WorkerVerifies that *`statement`* causes the process to terminate with a nonzero exit
566*481dde66SAndroid Build Coastguard Workerstatus and produces `stderr` output that matches *`matcher`*.
567*481dde66SAndroid Build Coastguard Worker
568*481dde66SAndroid Build Coastguard WorkerThe parameter *`matcher`* is either a [matcher](matchers.md) for a `const
569*481dde66SAndroid Build Coastguard Workerstd::string&`, or a regular expression (see
570*481dde66SAndroid Build Coastguard Worker[Regular Expression Syntax](../advanced.md#regular-expression-syntax))—a bare
571*481dde66SAndroid Build Coastguard Workerstring *`s`* (with no matcher) is treated as
572*481dde66SAndroid Build Coastguard Worker[`ContainsRegex(s)`](matchers.md#string-matchers), **not**
573*481dde66SAndroid Build Coastguard Worker[`Eq(s)`](matchers.md#generic-comparison).
574*481dde66SAndroid Build Coastguard Worker
575*481dde66SAndroid Build Coastguard WorkerFor example, the following code verifies that calling `DoSomething(42)` causes
576*481dde66SAndroid Build Coastguard Workerthe process to die with an error message that contains the text `My error`:
577*481dde66SAndroid Build Coastguard Worker
578*481dde66SAndroid Build Coastguard Worker```cpp
579*481dde66SAndroid Build Coastguard WorkerEXPECT_DEATH(DoSomething(42), "My error");
580*481dde66SAndroid Build Coastguard Worker```
581*481dde66SAndroid Build Coastguard Worker
582*481dde66SAndroid Build Coastguard Worker### EXPECT_DEATH_IF_SUPPORTED {#EXPECT_DEATH_IF_SUPPORTED}
583*481dde66SAndroid Build Coastguard Worker
584*481dde66SAndroid Build Coastguard Worker`EXPECT_DEATH_IF_SUPPORTED(`*`statement`*`,`*`matcher`*`)` \
585*481dde66SAndroid Build Coastguard Worker`ASSERT_DEATH_IF_SUPPORTED(`*`statement`*`,`*`matcher`*`)`
586*481dde66SAndroid Build Coastguard Worker
587*481dde66SAndroid Build Coastguard WorkerIf death tests are supported, behaves the same as
588*481dde66SAndroid Build Coastguard Worker[`EXPECT_DEATH`](#EXPECT_DEATH). Otherwise, verifies nothing.
589*481dde66SAndroid Build Coastguard Worker
590*481dde66SAndroid Build Coastguard Worker### EXPECT_DEBUG_DEATH {#EXPECT_DEBUG_DEATH}
591*481dde66SAndroid Build Coastguard Worker
592*481dde66SAndroid Build Coastguard Worker`EXPECT_DEBUG_DEATH(`*`statement`*`,`*`matcher`*`)` \
593*481dde66SAndroid Build Coastguard Worker`ASSERT_DEBUG_DEATH(`*`statement`*`,`*`matcher`*`)`
594*481dde66SAndroid Build Coastguard Worker
595*481dde66SAndroid Build Coastguard WorkerIn debug mode, behaves the same as [`EXPECT_DEATH`](#EXPECT_DEATH). When not in
596*481dde66SAndroid Build Coastguard Workerdebug mode (i.e. `NDEBUG` is defined), just executes *`statement`*.
597*481dde66SAndroid Build Coastguard Worker
598*481dde66SAndroid Build Coastguard Worker### EXPECT_EXIT {#EXPECT_EXIT}
599*481dde66SAndroid Build Coastguard Worker
600*481dde66SAndroid Build Coastguard Worker`EXPECT_EXIT(`*`statement`*`,`*`predicate`*`,`*`matcher`*`)` \
601*481dde66SAndroid Build Coastguard Worker`ASSERT_EXIT(`*`statement`*`,`*`predicate`*`,`*`matcher`*`)`
602*481dde66SAndroid Build Coastguard Worker
603*481dde66SAndroid Build Coastguard WorkerVerifies that *`statement`* causes the process to terminate with an exit status
604*481dde66SAndroid Build Coastguard Workerthat satisfies *`predicate`*, and produces `stderr` output that matches
605*481dde66SAndroid Build Coastguard Worker*`matcher`*.
606*481dde66SAndroid Build Coastguard Worker
607*481dde66SAndroid Build Coastguard WorkerThe parameter *`predicate`* is a function or functor that accepts an `int` exit
608*481dde66SAndroid Build Coastguard Workerstatus and returns a `bool`. GoogleTest provides two predicates to handle common
609*481dde66SAndroid Build Coastguard Workercases:
610*481dde66SAndroid Build Coastguard Worker
611*481dde66SAndroid Build Coastguard Worker```cpp
612*481dde66SAndroid Build Coastguard Worker// Returns true if the program exited normally with the given exit status code.
613*481dde66SAndroid Build Coastguard Worker::testing::ExitedWithCode(exit_code);
614*481dde66SAndroid Build Coastguard Worker
615*481dde66SAndroid Build Coastguard Worker// Returns true if the program was killed by the given signal.
616*481dde66SAndroid Build Coastguard Worker// Not available on Windows.
617*481dde66SAndroid Build Coastguard Worker::testing::KilledBySignal(signal_number);
618*481dde66SAndroid Build Coastguard Worker```
619*481dde66SAndroid Build Coastguard Worker
620*481dde66SAndroid Build Coastguard WorkerThe parameter *`matcher`* is either a [matcher](matchers.md) for a `const
621*481dde66SAndroid Build Coastguard Workerstd::string&`, or a regular expression (see
622*481dde66SAndroid Build Coastguard Worker[Regular Expression Syntax](../advanced.md#regular-expression-syntax))—a bare
623*481dde66SAndroid Build Coastguard Workerstring *`s`* (with no matcher) is treated as
624*481dde66SAndroid Build Coastguard Worker[`ContainsRegex(s)`](matchers.md#string-matchers), **not**
625*481dde66SAndroid Build Coastguard Worker[`Eq(s)`](matchers.md#generic-comparison).
626*481dde66SAndroid Build Coastguard Worker
627*481dde66SAndroid Build Coastguard WorkerFor example, the following code verifies that calling `NormalExit()` causes the
628*481dde66SAndroid Build Coastguard Workerprocess to print a message containing the text `Success` to `stderr` and exit
629*481dde66SAndroid Build Coastguard Workerwith exit status code 0:
630*481dde66SAndroid Build Coastguard Worker
631*481dde66SAndroid Build Coastguard Worker```cpp
632*481dde66SAndroid Build Coastguard WorkerEXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success");
633*481dde66SAndroid Build Coastguard Worker```
634