# How to Write Death Tests in GoogleTest to Verify Process Termination

> Learn to write GoogleTest death tests to verify process termination with abort exit or signals. Assert expected output from dying processes effectively.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: how-to-guide
- Published: 2026-09-02

---

**GoogleTest provides a built-in death test framework that lets you assert that code terminates the process via `abort()`, `exit()`, or signals while optionally verifying the error output produced by the dying process.**

Death tests in GoogleTest (`google/googletest`) allow you to verify fatal error conditions by spawning your test code in a separate process and asserting that it crashes as expected. The public API lives in [[`googletest/include/gtest/gtest-death-test.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-death-test.h)](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-death-test.h), while the core implementation resides in [[`googletest/include/gtest/internal/gtest-death-test-internal.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-death-test-internal.h)](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-death-test-internal.h).

## Death Test Architecture and Internals

Understanding how GoogleTest implements death tests helps you write more reliable assertions and debug failures when tests do not behave as expected.

### The GTEST_DEATH_TEST_ Macro and Public API

All user-facing macros—`ASSERT_DEATH`, `EXPECT_DEATH`, `ASSERT_EXIT`, and `EXPECT_EXIT`—expand to the generic **`GTEST_DEATH_TEST_`** macro defined in [`gtest-death-test-internal.h`](https://github.com/google/googletest/blob/main/gtest-death-test-internal.h) (lines 26-56). This macro implements the complete lifecycle of a death test:

1. Creates a **death-test object** via `DeathTest::Create`
2. Determines whether the current process should **oversee** (`OVERSEE_TEST`) or **execute** (`EXECUTE_TEST`) the test
3. Runs the statement and collects exit status and stderr output
4. Validates results against the provided predicate and regex matcher

### DeathTest Factory and Process Roles

According to the source code in [`gtest-death-test-internal.h`](https://github.com/google/googletest/blob/main/gtest-death-test-internal.h), the `DeathTest` class uses a factory pattern where `DeathTest::Create` (lines 14-16) forwards to `DefaultDeathTestFactory`. The factory instantiates platform-specific implementations based on the `--gtest_death_test_style` flag, which supports two modes:

- **`fast`** – The parent process re-executes itself with special flags to run only the death test statement
- **`threadsafe`** – Uses `fork()` (POSIX) or `CreateProcess` (Windows) to spawn a true child process

Each `DeathTest` instance assumes a **role** via `AssumeRole()`:
- **OVERSEE_TEST**: The parent process waits for the child and collects exit status via `Wait()`
- **EXECUTE_TEST**: The child process executes the user statement directly

### Result Evaluation and Predicates

After the child process terminates, `Passed(predicate(gtest_dt->Wait()))` validates two conditions:

1. **Exit status**: Checked via predicates like `::testing::ExitedUnsuccessfully`, `ExitedWithCode`, or `KilledBySignal`
2. **Standard error**: Matched against the user-provided pattern using `MakeDeathTestMatcher` (lines 60-78), which converts legacy string arguments into `ContainsRegex` matchers

If the death test fails to terminate, the child calls `Abort(TEST_DID_NOT_DIE)` and the parent reports the failure through the `fail` argument of `GTEST_DEATH_TEST_`, accessible via `DeathTest::LastMessage()`.

## Writing Your First Death Test

Use `ASSERT_DEATH` when a fatal crash should abort the current test function, and `EXPECT_DEATH` when you want to continue testing after verifying the crash.

### Basic ASSERT_DEATH Usage

```cpp
#include <gtest/gtest.h>

// Verifies that MyClass::Process aborts when given invalid input
TEST(FooTest, DiesOnInvalidInput) {
  ASSERT_DEATH(MyClass::Process(-1), "CHECK failed: .*negative");
}

```

The first argument is the statement to execute; the second is a regular expression matching the stderr output. If `MyClass::Process(-1)` does not terminate or produces mismatched output, the test fails.

### EXPECT_DEATH for Non-Fatal Verification

```cpp
TEST(BarTest, MultipleBadRequests) {
  for (int i = 0; i < 3; ++i) {
    EXPECT_DEATH(Server::HandleRequest(i),
                 "Invalid request") << "Failed at iteration " << i;
  }
}

```

`EXPECT_DEATH` allows the test to continue checking remaining iterations even if one death test fails.

### Asserting Specific Exit Codes

When you need to verify the exact exit code rather than just "unsuccessful" termination, use `ASSERT_EXIT` with the `ExitedWithCode` predicate:

```cpp
TEST(BazTest, ExitCodeIsZero) {
  ASSERT_EXIT(MyApp::Run(), ::testing::ExitedWithCode(0), ".*");
}

```

Other available predicates include:
- **`::testing::KilledBySignal(int signal)`**: Verifies the process was terminated by a specific signal (POSIX)
- **`::testing::ExitedUnsuccessfully`**: Checks for any non-zero exit code or signal termination

## Advanced Death Test Patterns

### Platform-Conditional Tests with ASSERT_DEATH_IF_SUPPORTED

Not all platforms support death tests equally. Use `ASSERT_DEATH_IF_SUPPORTED` to skip death tests on platforms where they are unavailable:

```cpp
TEST(QuuxTest, Conditional) {
  ASSERT_DEATH_IF_SUPPORTED(Resource::Destroy(),
                            "Resource cleanup failed");
}

```

On unsupported platforms, this macro compiles to a no-op that does not fail the test.

### Debug-Only Death Tests

Use `EXPECT_DEBUG_DEATH` or `ASSERT_DEBUG_DEATH` to verify assertions that only fire in debug builds. These are defined in [`gtest-death-test.h`](https://github.com/google/googletest/blob/main/gtest-death-test.h) (lines 62-76) and expand to regular death tests in debug mode while becoming no-ops in release builds:

```cpp
TEST(DebugOnlyTest, CrashInDebug) {
  EXPECT_DEBUG_DEATH(DebugOnlyFunction(), "fatal error");
}

```

### Regex Syntax and Matchers

The death test framework supports a limited regex subset documented in [`gtest-death-test.h`](https://github.com/google/googletest/blob/main/gtest-death-test.h) (lines 106-146). You can also use GoogleMock matchers instead of regex strings:

```cpp
using ::testing::HasSubstr;
ASSERT_DEATH(MyFunction(), HasSubstr("specific error"));

```

This bypasses the regex engine entirely and uses `MakeDeathTestMatcher` to handle the matcher logic internally.

## Summary

- **Death tests** verify process termination by spawning code in a child process and checking exit status and stderr output
- The **public API** in [`gtest/gtest-death-test.h`](https://github.com/google/googletest/blob/main/gtest/gtest-death-test.h) provides `ASSERT_DEATH`, `EXPECT_DEATH`, `ASSERT_EXIT`, and `EXPECT_EXIT` macros
- **Internal implementation** in [`gtest/internal/gtest-death-test-internal.h`](https://github.com/google/googletest/blob/main/gtest/internal/gtest-death-test-internal.h) handles process forking, role management (`OVERSEE_TEST` vs `EXECUTE_TEST`), and the `GTEST_DEATH_TEST_` macro expansion
- Use **`ExitedWithCode`** and **`KilledBySignal`** predicates to verify specific termination conditions
- **`ASSERT_DEATH_IF_SUPPORTED`** ensures portability across platforms without death test support
- **`EXPECT_DEBUG_DEATH`** enables assertion checking only in debug builds

## Frequently Asked Questions

### What's the difference between ASSERT_DEATH and EXPECT_DEATH?

**ASSERT_DEATH** aborts the current test function immediately if the statement does not die or produces unexpected output, while **EXPECT_DEATH** continues execution after reporting the failure. Use `ASSERT_DEATH` when subsequent test logic depends on the death test passing, and `EXPECT_DEATH` when verifying multiple independent crash scenarios in a loop.

### How do death tests work internally?

According to the `google/googletest` source, death tests work by forking a child process (or re-executing the binary) to run the dangerous code. The parent process assumes the `OVERSEE_TEST` role and waits for the child (in `EXECUTE_TEST` role) to terminate. The exit status is captured via `Wait()` and validated against predicates like `ExitedUnsuccessfully` or `ExitedWithCode`.

### Can I use death tests on Windows?

Yes, the framework supports Windows through the `CreateProcess` API in `gtest-death-test.cc`, though you should use **`ASSERT_DEATH_IF_SUPPORTED`** for maximum portability. On Windows, the `KilledBySignal` predicate is not available, and you should rely on `ExitedWithCode` or `ExitedUnsuccessfully` instead.

### What regex syntax is supported in death tests?

GoogleTest death tests support a limited subset documented in [`gtest-death-test.h`](https://github.com/google/googletest/blob/main/gtest-death-test.h) lines 106-146, including `.` (any character), `*` (zero or more), `+` (one or more), `?` (optional), and character classes. For complex matching, use GoogleMock matchers like `HasSubstr` or `ContainsRegex` instead of raw strings to leverage the full matcher framework.