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. 29 // 30 // Author: wan@google.com (Zhanyong Wan) 31 // 32 // The Google C++ Testing Framework (Google Test) 33 // 34 // This header file defines the public API for death tests. It is 35 // #included by gtest.h so a user doesn't need to include this 36 // directly. 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 #ifdef GTEST_HAS_DEATH_TEST 53 54 // The following macros are useful for writing death tests. 55 56 // Here's what happens when an ASSERT_DEATH* or EXPECT_DEATH* is 57 // executed: 58 // 59 // 1. The assertion fails immediately if there are more than one 60 // active threads. This is because it's safe to fork() only when 61 // there is a single thread. 62 // 63 // 2. The parent process forks a sub-process and runs the death test 64 // in it; the sub-process exits with code 0 at the end of the death 65 // test, if it hasn't exited already. 66 // 67 // 3. The parent process waits for the sub-process to terminate. 68 // 69 // 4. The parent process checks the exit code and error message of 70 // the sub-process. 71 // 72 // Note: 73 // 74 // It's not safe to call exit() if the current process is forked from 75 // a multi-threaded process, so people usually call _exit() instead in 76 // such a case. However, we are not concerned with this as we run 77 // death tests only when there is a single thread. Since exit() has a 78 // cleaner semantics (it also calls functions registered with atexit() 79 // and on_exit()), this macro calls exit() instead of _exit() to 80 // terminate the child process. 81 // 82 // Examples: 83 // 84 // ASSERT_DEATH(server.SendMessage(56, "Hello"), "Invalid port number"); 85 // for (int i = 0; i < 5; i++) { 86 // EXPECT_DEATH(server.ProcessRequest(i), 87 // "Invalid request .* in ProcessRequest()") 88 // << "Failed to die on request " << i); 89 // } 90 // 91 // ASSERT_EXIT(server.ExitNow(), ::testing::ExitedWithCode(0), "Exiting"); 92 // 93 // bool KilledBySIGHUP(int exit_code) { 94 // return WIFSIGNALED(exit_code) && WTERMSIG(exit_code) == SIGHUP; 95 // } 96 // 97 // ASSERT_EXIT(client.HangUpServer(), KilledBySIGHUP, "Hanging up!"); 98 99 // Asserts that a given statement causes the program to exit, with an 100 // integer exit status that satisfies predicate, and emitting error output 101 // that matches regex. 102 #define ASSERT_EXIT(statement, predicate, regex) \ 103 GTEST_DEATH_TEST(statement, predicate, regex, GTEST_FATAL_FAILURE) 104 105 // Like ASSERT_EXIT, but continues on to successive tests in the 106 // test case, if any: 107 #define EXPECT_EXIT(statement, predicate, regex) \ 108 GTEST_DEATH_TEST(statement, predicate, regex, GTEST_NONFATAL_FAILURE) 109 110 // Asserts that a given statement causes the program to exit, either by 111 // explicitly exiting with a nonzero exit code or being killed by a 112 // signal, and emitting error output that matches regex. 113 #define ASSERT_DEATH(statement, regex) \ 114 ASSERT_EXIT(statement, ::testing::internal::ExitedUnsuccessfully, regex) 115 116 // Like ASSERT_DEATH, but continues on to successive tests in the 117 // test case, if any: 118 #define EXPECT_DEATH(statement, regex) \ 119 EXPECT_EXIT(statement, ::testing::internal::ExitedUnsuccessfully, regex) 120 121 // Two predicate classes that can be used in {ASSERT,EXPECT}_EXIT*: 122 123 // Tests that an exit code describes a normal exit with a given exit code. 124 class ExitedWithCode { 125 public: 126 explicit ExitedWithCode(int exit_code); 127 bool operator()(int exit_status) const; 128 private: 129 const int exit_code_; 130 }; 131 132 // Tests that an exit code describes an exit due to termination by a 133 // given signal. 134 class KilledBySignal { 135 public: 136 explicit KilledBySignal(int signum); 137 bool operator()(int exit_status) const; 138 private: 139 const int signum_; 140 }; 141 142 // EXPECT_DEBUG_DEATH asserts that the given statements die in debug mode. 143 // The death testing framework causes this to have interesting semantics, 144 // since the sideeffects of the call are only visible in opt mode, and not 145 // in debug mode. 146 // 147 // In practice, this can be used to test functions that utilize the 148 // LOG(DFATAL) macro using the following style: 149 // 150 // int DieInDebugOr12(int* sideeffect) { 151 // if (sideeffect) { 152 // *sideeffect = 12; 153 // } 154 // LOG(DFATAL) << "death"; 155 // return 12; 156 // } 157 // 158 // TEST(TestCase, TestDieOr12WorksInDgbAndOpt) { 159 // int sideeffect = 0; 160 // // Only asserts in dbg. 161 // EXPECT_DEBUG_DEATH(DieInDebugOr12(&sideeffect), "death"); 162 // 163 // #ifdef NDEBUG 164 // // opt-mode has sideeffect visible. 165 // EXPECT_EQ(12, sideeffect); 166 // #else 167 // // dbg-mode no visible sideeffect. 168 // EXPECT_EQ(0, sideeffect); 169 // #endif 170 // } 171 // 172 // This will assert that DieInDebugReturn12InOpt() crashes in debug 173 // mode, usually due to a DCHECK or LOG(DFATAL), but returns the 174 // appropriate fallback value (12 in this case) in opt mode. If you 175 // need to test that a function has appropriate side-effects in opt 176 // mode, include assertions against the side-effects. A general 177 // pattern for this is: 178 // 179 // EXPECT_DEBUG_DEATH({ 180 // // Side-effects here will have an effect after this statement in 181 // // opt mode, but none in debug mode. 182 // EXPECT_EQ(12, DieInDebugOr12(&sideeffect)); 183 // }, "death"); 184 // 185 #ifdef NDEBUG 186 187 #define EXPECT_DEBUG_DEATH(statement, regex) \ 188 do { statement; } while (false) 189 190 #define ASSERT_DEBUG_DEATH(statement, regex) \ 191 do { statement; } while (false) 192 193 #else 194 195 #define EXPECT_DEBUG_DEATH(statement, regex) \ 196 EXPECT_DEATH(statement, regex) 197 198 #define ASSERT_DEBUG_DEATH(statement, regex) \ 199 ASSERT_DEATH(statement, regex) 200 201 #endif // NDEBUG for EXPECT_DEBUG_DEATH 202 #endif // GTEST_HAS_DEATH_TEST 203 } // namespace testing 204 205 #endif // GTEST_INCLUDE_GTEST_GTEST_DEATH_TEST_H_ 206