]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // Copyright 2005, Google Inc. |
2 | // All rights reserved. | |
3 | // | |
4 | // Redistribution and use in source and binary forms, with or without | |
5 | // modification, are permitted provided that the following conditions are | |
6 | // met: | |
7 | // | |
8 | // * Redistributions of source code must retain the above copyright | |
9 | // notice, this list of conditions and the following disclaimer. | |
10 | // * Redistributions in binary form must reproduce the above | |
11 | // copyright notice, this list of conditions and the following disclaimer | |
12 | // in the documentation and/or other materials provided with the | |
13 | // distribution. | |
14 | // * Neither the name of Google Inc. nor the names of its | |
15 | // contributors may be used to endorse or promote products derived from | |
16 | // this software without specific prior written permission. | |
17 | // | |
18 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
19 | // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
20 | // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
21 | // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
22 | // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
23 | // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
24 | // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
25 | // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
26 | // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
27 | // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
28 | // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
9f95a23c | 29 | |
7c673cae | 30 | // |
9f95a23c | 31 | // The Google C++ Testing and Mocking Framework (Google Test) |
7c673cae FG |
32 | // |
33 | // This header file defines the public API for death tests. It is | |
34 | // #included by gtest.h so a user doesn't need to include this | |
35 | // directly. | |
9f95a23c | 36 | // GOOGLETEST_CM0001 DO NOT DELETE |
7c673cae FG |
37 | |
38 | #ifndef GTEST_INCLUDE_GTEST_GTEST_DEATH_TEST_H_ | |
39 | #define GTEST_INCLUDE_GTEST_GTEST_DEATH_TEST_H_ | |
40 | ||
41 | #include "gtest/internal/gtest-death-test-internal.h" | |
42 | ||
43 | namespace testing { | |
44 | ||
45 | // This flag controls the style of death tests. Valid values are "threadsafe", | |
46 | // meaning that the death test child process will re-execute the test binary | |
47 | // from the start, running only a single death test, or "fast", | |
48 | // meaning that the child process will execute the test logic immediately | |
49 | // after forking. | |
50 | GTEST_DECLARE_string_(death_test_style); | |
51 | ||
52 | #if GTEST_HAS_DEATH_TEST | |
53 | ||
54 | namespace internal { | |
55 | ||
56 | // Returns a Boolean value indicating whether the caller is currently | |
57 | // executing in the context of the death test child process. Tools such as | |
58 | // Valgrind heap checkers may need this to modify their behavior in death | |
59 | // tests. IMPORTANT: This is an internal utility. Using it may break the | |
60 | // implementation of death tests. User code MUST NOT use it. | |
61 | GTEST_API_ bool InDeathTestChild(); | |
62 | ||
63 | } // namespace internal | |
64 | ||
65 | // The following macros are useful for writing death tests. | |
66 | ||
67 | // Here's what happens when an ASSERT_DEATH* or EXPECT_DEATH* is | |
68 | // executed: | |
69 | // | |
70 | // 1. It generates a warning if there is more than one active | |
71 | // thread. This is because it's safe to fork() or clone() only | |
72 | // when there is a single thread. | |
73 | // | |
74 | // 2. The parent process clone()s a sub-process and runs the death | |
75 | // test in it; the sub-process exits with code 0 at the end of the | |
76 | // death test, if it hasn't exited already. | |
77 | // | |
78 | // 3. The parent process waits for the sub-process to terminate. | |
79 | // | |
80 | // 4. The parent process checks the exit code and error message of | |
81 | // the sub-process. | |
82 | // | |
83 | // Examples: | |
84 | // | |
85 | // ASSERT_DEATH(server.SendMessage(56, "Hello"), "Invalid port number"); | |
86 | // for (int i = 0; i < 5; i++) { | |
87 | // EXPECT_DEATH(server.ProcessRequest(i), | |
88 | // "Invalid request .* in ProcessRequest()") | |
89 | // << "Failed to die on request " << i; | |
90 | // } | |
91 | // | |
92 | // ASSERT_EXIT(server.ExitNow(), ::testing::ExitedWithCode(0), "Exiting"); | |
93 | // | |
94 | // bool KilledBySIGHUP(int exit_code) { | |
95 | // return WIFSIGNALED(exit_code) && WTERMSIG(exit_code) == SIGHUP; | |
96 | // } | |
97 | // | |
98 | // ASSERT_EXIT(client.HangUpServer(), KilledBySIGHUP, "Hanging up!"); | |
99 | // | |
100 | // On the regular expressions used in death tests: | |
101 | // | |
9f95a23c | 102 | // GOOGLETEST_CM0005 DO NOT DELETE |
7c673cae FG |
103 | // On POSIX-compliant systems (*nix), we use the <regex.h> library, |
104 | // which uses the POSIX extended regex syntax. | |
105 | // | |
9f95a23c | 106 | // On other platforms (e.g. Windows or Mac), we only support a simple regex |
7c673cae FG |
107 | // syntax implemented as part of Google Test. This limited |
108 | // implementation should be enough most of the time when writing | |
109 | // death tests; though it lacks many features you can find in PCRE | |
110 | // or POSIX extended regex syntax. For example, we don't support | |
111 | // union ("x|y"), grouping ("(xy)"), brackets ("[xy]"), and | |
112 | // repetition count ("x{5,7}"), among others. | |
113 | // | |
114 | // Below is the syntax that we do support. We chose it to be a | |
115 | // subset of both PCRE and POSIX extended regex, so it's easy to | |
116 | // learn wherever you come from. In the following: 'A' denotes a | |
117 | // literal character, period (.), or a single \\ escape sequence; | |
118 | // 'x' and 'y' denote regular expressions; 'm' and 'n' are for | |
119 | // natural numbers. | |
120 | // | |
121 | // c matches any literal character c | |
122 | // \\d matches any decimal digit | |
123 | // \\D matches any character that's not a decimal digit | |
124 | // \\f matches \f | |
125 | // \\n matches \n | |
126 | // \\r matches \r | |
127 | // \\s matches any ASCII whitespace, including \n | |
128 | // \\S matches any character that's not a whitespace | |
129 | // \\t matches \t | |
130 | // \\v matches \v | |
131 | // \\w matches any letter, _, or decimal digit | |
132 | // \\W matches any character that \\w doesn't match | |
133 | // \\c matches any literal character c, which must be a punctuation | |
134 | // . matches any single character except \n | |
135 | // A? matches 0 or 1 occurrences of A | |
136 | // A* matches 0 or many occurrences of A | |
137 | // A+ matches 1 or many occurrences of A | |
138 | // ^ matches the beginning of a string (not that of each line) | |
139 | // $ matches the end of a string (not that of each line) | |
140 | // xy matches x followed by y | |
141 | // | |
142 | // If you accidentally use PCRE or POSIX extended regex features | |
143 | // not implemented by us, you will get a run-time failure. In that | |
144 | // case, please try to rewrite your regular expression within the | |
145 | // above syntax. | |
146 | // | |
147 | // This implementation is *not* meant to be as highly tuned or robust | |
148 | // as a compiled regex library, but should perform well enough for a | |
149 | // death test, which already incurs significant overhead by launching | |
150 | // a child process. | |
151 | // | |
152 | // Known caveats: | |
153 | // | |
154 | // A "threadsafe" style death test obtains the path to the test | |
155 | // program from argv[0] and re-executes it in the sub-process. For | |
156 | // simplicity, the current implementation doesn't search the PATH | |
157 | // when launching the sub-process. This means that the user must | |
158 | // invoke the test program via a path that contains at least one | |
159 | // path separator (e.g. path/to/foo_test and | |
160 | // /absolute/path/to/bar_test are fine, but foo_test is not). This | |
161 | // is rarely a problem as people usually don't put the test binary | |
162 | // directory in PATH. | |
163 | // | |
7c673cae FG |
164 | |
165 | // Asserts that a given statement causes the program to exit, with an | |
166 | // integer exit status that satisfies predicate, and emitting error output | |
167 | // that matches regex. | |
168 | # define ASSERT_EXIT(statement, predicate, regex) \ | |
169 | GTEST_DEATH_TEST_(statement, predicate, regex, GTEST_FATAL_FAILURE_) | |
170 | ||
171 | // Like ASSERT_EXIT, but continues on to successive tests in the | |
9f95a23c | 172 | // test suite, if any: |
7c673cae FG |
173 | # define EXPECT_EXIT(statement, predicate, regex) \ |
174 | GTEST_DEATH_TEST_(statement, predicate, regex, GTEST_NONFATAL_FAILURE_) | |
175 | ||
176 | // Asserts that a given statement causes the program to exit, either by | |
177 | // explicitly exiting with a nonzero exit code or being killed by a | |
178 | // signal, and emitting error output that matches regex. | |
179 | # define ASSERT_DEATH(statement, regex) \ | |
180 | ASSERT_EXIT(statement, ::testing::internal::ExitedUnsuccessfully, regex) | |
181 | ||
182 | // Like ASSERT_DEATH, but continues on to successive tests in the | |
9f95a23c | 183 | // test suite, if any: |
7c673cae FG |
184 | # define EXPECT_DEATH(statement, regex) \ |
185 | EXPECT_EXIT(statement, ::testing::internal::ExitedUnsuccessfully, regex) | |
186 | ||
187 | // Two predicate classes that can be used in {ASSERT,EXPECT}_EXIT*: | |
188 | ||
189 | // Tests that an exit code describes a normal exit with a given exit code. | |
190 | class GTEST_API_ ExitedWithCode { | |
191 | public: | |
192 | explicit ExitedWithCode(int exit_code); | |
193 | bool operator()(int exit_status) const; | |
194 | private: | |
195 | // No implementation - assignment is unsupported. | |
196 | void operator=(const ExitedWithCode& other); | |
197 | ||
198 | const int exit_code_; | |
199 | }; | |
200 | ||
9f95a23c | 201 | # if !GTEST_OS_WINDOWS && !GTEST_OS_FUCHSIA |
7c673cae FG |
202 | // Tests that an exit code describes an exit due to termination by a |
203 | // given signal. | |
9f95a23c | 204 | // GOOGLETEST_CM0006 DO NOT DELETE |
7c673cae FG |
205 | class GTEST_API_ KilledBySignal { |
206 | public: | |
207 | explicit KilledBySignal(int signum); | |
208 | bool operator()(int exit_status) const; | |
209 | private: | |
210 | const int signum_; | |
211 | }; | |
212 | # endif // !GTEST_OS_WINDOWS | |
213 | ||
214 | // EXPECT_DEBUG_DEATH asserts that the given statements die in debug mode. | |
215 | // The death testing framework causes this to have interesting semantics, | |
216 | // since the sideeffects of the call are only visible in opt mode, and not | |
217 | // in debug mode. | |
218 | // | |
219 | // In practice, this can be used to test functions that utilize the | |
220 | // LOG(DFATAL) macro using the following style: | |
221 | // | |
222 | // int DieInDebugOr12(int* sideeffect) { | |
223 | // if (sideeffect) { | |
224 | // *sideeffect = 12; | |
225 | // } | |
226 | // LOG(DFATAL) << "death"; | |
227 | // return 12; | |
228 | // } | |
229 | // | |
9f95a23c | 230 | // TEST(TestSuite, TestDieOr12WorksInDgbAndOpt) { |
7c673cae FG |
231 | // int sideeffect = 0; |
232 | // // Only asserts in dbg. | |
233 | // EXPECT_DEBUG_DEATH(DieInDebugOr12(&sideeffect), "death"); | |
234 | // | |
235 | // #ifdef NDEBUG | |
236 | // // opt-mode has sideeffect visible. | |
237 | // EXPECT_EQ(12, sideeffect); | |
238 | // #else | |
239 | // // dbg-mode no visible sideeffect. | |
240 | // EXPECT_EQ(0, sideeffect); | |
241 | // #endif | |
242 | // } | |
243 | // | |
244 | // This will assert that DieInDebugReturn12InOpt() crashes in debug | |
245 | // mode, usually due to a DCHECK or LOG(DFATAL), but returns the | |
246 | // appropriate fallback value (12 in this case) in opt mode. If you | |
247 | // need to test that a function has appropriate side-effects in opt | |
248 | // mode, include assertions against the side-effects. A general | |
249 | // pattern for this is: | |
250 | // | |
251 | // EXPECT_DEBUG_DEATH({ | |
252 | // // Side-effects here will have an effect after this statement in | |
253 | // // opt mode, but none in debug mode. | |
254 | // EXPECT_EQ(12, DieInDebugOr12(&sideeffect)); | |
255 | // }, "death"); | |
256 | // | |
257 | # ifdef NDEBUG | |
258 | ||
259 | # define EXPECT_DEBUG_DEATH(statement, regex) \ | |
260 | GTEST_EXECUTE_STATEMENT_(statement, regex) | |
261 | ||
262 | # define ASSERT_DEBUG_DEATH(statement, regex) \ | |
263 | GTEST_EXECUTE_STATEMENT_(statement, regex) | |
264 | ||
265 | # else | |
266 | ||
267 | # define EXPECT_DEBUG_DEATH(statement, regex) \ | |
268 | EXPECT_DEATH(statement, regex) | |
269 | ||
270 | # define ASSERT_DEBUG_DEATH(statement, regex) \ | |
271 | ASSERT_DEATH(statement, regex) | |
272 | ||
273 | # endif // NDEBUG for EXPECT_DEBUG_DEATH | |
274 | #endif // GTEST_HAS_DEATH_TEST | |
275 | ||
9f95a23c TL |
276 | // This macro is used for implementing macros such as |
277 | // EXPECT_DEATH_IF_SUPPORTED and ASSERT_DEATH_IF_SUPPORTED on systems where | |
278 | // death tests are not supported. Those macros must compile on such systems | |
279 | // if and only if EXPECT_DEATH and ASSERT_DEATH compile with the same parameters | |
280 | // on systems that support death tests. This allows one to write such a macro on | |
281 | // a system that does not support death tests and be sure that it will compile | |
282 | // on a death-test supporting system. It is exposed publicly so that systems | |
283 | // that have death-tests with stricter requirements than GTEST_HAS_DEATH_TEST | |
284 | // can write their own equivalent of EXPECT_DEATH_IF_SUPPORTED and | |
285 | // ASSERT_DEATH_IF_SUPPORTED. | |
286 | // | |
287 | // Parameters: | |
288 | // statement - A statement that a macro such as EXPECT_DEATH would test | |
289 | // for program termination. This macro has to make sure this | |
290 | // statement is compiled but not executed, to ensure that | |
291 | // EXPECT_DEATH_IF_SUPPORTED compiles with a certain | |
292 | // parameter if and only if EXPECT_DEATH compiles with it. | |
293 | // regex - A regex that a macro such as EXPECT_DEATH would use to test | |
294 | // the output of statement. This parameter has to be | |
295 | // compiled but not evaluated by this macro, to ensure that | |
296 | // this macro only accepts expressions that a macro such as | |
297 | // EXPECT_DEATH would accept. | |
298 | // terminator - Must be an empty statement for EXPECT_DEATH_IF_SUPPORTED | |
299 | // and a return statement for ASSERT_DEATH_IF_SUPPORTED. | |
300 | // This ensures that ASSERT_DEATH_IF_SUPPORTED will not | |
301 | // compile inside functions where ASSERT_DEATH doesn't | |
302 | // compile. | |
303 | // | |
304 | // The branch that has an always false condition is used to ensure that | |
305 | // statement and regex are compiled (and thus syntactically correct) but | |
306 | // never executed. The unreachable code macro protects the terminator | |
307 | // statement from generating an 'unreachable code' warning in case | |
308 | // statement unconditionally returns or throws. The Message constructor at | |
309 | // the end allows the syntax of streaming additional messages into the | |
310 | // macro, for compilational compatibility with EXPECT_DEATH/ASSERT_DEATH. | |
311 | # define GTEST_UNSUPPORTED_DEATH_TEST(statement, regex, terminator) \ | |
312 | GTEST_AMBIGUOUS_ELSE_BLOCKER_ \ | |
313 | if (::testing::internal::AlwaysTrue()) { \ | |
314 | GTEST_LOG_(WARNING) \ | |
315 | << "Death tests are not supported on this platform.\n" \ | |
316 | << "Statement '" #statement "' cannot be verified."; \ | |
317 | } else if (::testing::internal::AlwaysFalse()) { \ | |
318 | ::testing::internal::RE::PartialMatch(".*", (regex)); \ | |
319 | GTEST_SUPPRESS_UNREACHABLE_CODE_WARNING_BELOW_(statement); \ | |
320 | terminator; \ | |
321 | } else \ | |
322 | ::testing::Message() | |
323 | ||
7c673cae FG |
324 | // EXPECT_DEATH_IF_SUPPORTED(statement, regex) and |
325 | // ASSERT_DEATH_IF_SUPPORTED(statement, regex) expand to real death tests if | |
326 | // death tests are supported; otherwise they just issue a warning. This is | |
327 | // useful when you are combining death test assertions with normal test | |
328 | // assertions in one test. | |
329 | #if GTEST_HAS_DEATH_TEST | |
330 | # define EXPECT_DEATH_IF_SUPPORTED(statement, regex) \ | |
331 | EXPECT_DEATH(statement, regex) | |
332 | # define ASSERT_DEATH_IF_SUPPORTED(statement, regex) \ | |
333 | ASSERT_DEATH(statement, regex) | |
334 | #else | |
335 | # define EXPECT_DEATH_IF_SUPPORTED(statement, regex) \ | |
9f95a23c | 336 | GTEST_UNSUPPORTED_DEATH_TEST(statement, regex, ) |
7c673cae | 337 | # define ASSERT_DEATH_IF_SUPPORTED(statement, regex) \ |
9f95a23c | 338 | GTEST_UNSUPPORTED_DEATH_TEST(statement, regex, return) |
7c673cae FG |
339 | #endif |
340 | ||
341 | } // namespace testing | |
342 | ||
343 | #endif // GTEST_INCLUDE_GTEST_GTEST_DEATH_TEST_H_ |