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 43namespace 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. 50GTEST_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. 124class 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. 134class 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