# How `HasNewFatalFailureHelper` Tracks Fatal Failures During Test Execution in GoogleTest

> Discover how HasNewFatalFailureHelper tracks fatal failures in GoogleTest. Learn its mechanism of replacing reporters and setting flags for accurate failure detection.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: internals
- Published: 2026-08-30

---

**The `HasNewFatalFailureHelper` class tracks fatal failures by temporarily replacing the current test-part result reporter, intercepting all failure reports via the `ReportTestPartResult` method, and setting an internal boolean flag when it encounters a result where `fatally_failed()` returns true.**

When writing unit tests with GoogleTest (`google/googletest`), the `ASSERT_NO_FATAL_FAILURE` and `EXPECT_NO_FATAL_FAILURE` macros rely on an internal utility to detect whether a statement generates a new fatal failure. This utility, `HasNewFatalFailureHelper`, operates as a scoped reporter interceptor that monitors test execution without permanently altering the framework's global reporting state.

## How HasNewFatalFailureHelper Intercepts Failure Reports

The helper implements the `TestPartResultReporterInterface` and acts as a middleware layer between your test code and GoogleTest's standard reporting mechanism. Its operation relies on three distinct lifecycle phases: installation, interception, and restoration.

### Installing the Helper as the Active Reporter

When a `HasNewFatalFailureHelper` object is instantiated, its constructor captures the currently active reporter and installs itself as the handler for the current thread. This mechanism is defined in `googletest/src/gtest-test-part.cc` at lines 88-92:

```cpp
HasNewFatalFailureHelper::HasNewFatalFailureHelper()
    : has_new_fatal_failure_(false),
      original_reporter_(
          GetUnitTestImpl()->GetTestPartResultReporterForCurrentThread()) {
  GetUnitTestImpl()->SetTestPartResultReporterForCurrentThread(this);
}

```

The constructor stores the previous reporter in `original_reporter_` and initializes `has_new_fatal_failure_` to `false`. By calling `SetTestPartResultReporterForCurrentThread(this)`, the helper ensures that all subsequent test-part results within its scope route through its implementation.

### Capturing Fatal Failures in Real Time

The core detection logic resides in the `ReportTestPartResult` method, which GoogleTest invokes for every assertion result. Located at lines 100-104 in `gtest-test-part.cc`, this method checks whether the reported result represents a fatal failure:

```cpp
void HasNewFatalFailureHelper::ReportTestPartResult(
    const TestPartResult& result) {
  if (result.fatally_failed()) has_new_fatal_failure_ = true;
  original_reporter_->ReportTestPartResult(result);
}

```

If `result.fatally_failed()` returns true, the helper flips `has_new_fatal_failure_` to `true`. Crucially, it then forwards the report to `original_reporter_` to ensure normal test-result processing continues uninterrupted.

### Restoring the Original Reporter on Destruction

To prevent side effects from leaking outside the macro's evaluation scope, the helper's destructor restores the previous reporter. This cleanup code appears at lines 95-98 in `gtest-test-part.cc`:

```cpp
HasNewFatalFailureHelper::~HasNewFatalFailureHelper() {
  GetUnitTestImpl()->SetTestPartResultReporterForCurrentThread(
      original_reporter_);
}

```

This pattern ensures that even if an exception occurs or the test block exits early, the reporting infrastructure returns to its original state.

## Querying the Detection Result

After the monitored statement executes, macros like `ASSERT_NO_FATAL_FAILURE` query the helper's state through the `has_new_fatal_failure()` accessor. This inline method is declared in [`googletest/include/gtest/gtest-test-part.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-test-part.h) at lines 177-178:

```cpp
bool HasNewFatalFailureHelper::has_new_fatal_failure() const {
  return has_new_fatal_failure_;
}

```

If this method returns `true`, the macro knows that a fatal failure occurred during the statement's execution and can trigger the appropriate test failure response.

## Practical Usage Examples

While most developers interact with this class through macros, understanding its manual usage clarifies its behavior:

```cpp
// Standard macro usage (recommended)
TEST(FooTest, NoFatalFailure) {
  // Creates HasNewFatalFailureHelper internally
  ASSERT_NO_FATAL_FAILURE(DoSomethingThatMightFail());
}

// Manual usage for custom validation logic
TEST(FooTest, ManualHelper) {
  testing::internal::HasNewFatalFailureHelper helper;
  DoSomethingThatMightFail();
  // Original reporter restored when helper goes out of scope
  EXPECT_FALSE(helper.has_new_fatal_failure())
      << "A fatal failure occurred inside the tested function";
}

```

## Source File Locations and Implementation Details

The complete implementation spans two primary files in the `google/googletest` repository:

- **[`googletest/include/gtest/gtest-test-part.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-test-part.h)**: Contains the class declaration, including the `has_new_fatal_failure()` getter and the `has_new_fatal_failure_` boolean member.
- **`googletest/src/gtest-test-part.cc`**: Houses the constructor, destructor, and `ReportTestPartResult` implementation that enable the interception mechanism.

## Summary

- **Reporter Interception**: The helper installs itself as the current thread's test-part result reporter during construction, saving the original reporter for later restoration.
- **Fatal Detection**: It intercepts every `TestPartResult` via `ReportTestPartResult`, setting an internal flag when `result.fatally_failed()` is true.
- **State Restoration**: The destructor guarantees the original reporter is restored, preventing interference with subsequent test assertions.
- **Macro Integration**: `ASSERT_NO_FATAL_FAILURE` and `EXPECT_NO_FATAL_FAILURE` instantiate this helper internally to validate that code blocks execute without generating new fatal failures.

## Frequently Asked Questions

### What is the difference between `HasNewFatalFailureHelper` and a custom `TestPartResultReporter`?

`HasNewFatalFailureHelper` is a specialized implementation of `TestPartResultReporterInterface` designed specifically for scoped fatal-failure detection. Unlike general custom reporters that might log results or modify behavior, this helper focuses exclusively on detecting whether a *new* fatal failure occurred during a specific execution window and forwarding results to the previous reporter.

### Can I use `HasNewFatalFailureHelper` outside of the `ASSERT_NO_FATAL_FAILURE` macro?

While the class resides in the `testing::internal` namespace and is primarily intended for framework internals, you can instantiate it manually for advanced testing scenarios. However, this requires careful management of the object's lifetime to ensure the original reporter is properly restored, making it unsuitable for most standard test writing.

### Why does the helper forward reports to `original_reporter_` instead of consuming them?

The helper forwards reports to ensure that GoogleTest's standard failure processing—including logging, failure counting, and test termination logic—continues normally. If the helper consumed reports without forwarding, fatal failures would disappear from the test output, making debugging impossible while allowing the test to continue running erroneously.

### Is `HasNewFatalFailureHelper` thread-safe?

The helper interacts with thread-local storage via `GetTestPartResultReporterForCurrentThread` and `SetTestPartResultReporterForCurrentThread`. While this makes it safe to use across different threads (each thread maintains its own reporter stack), you should not share a single `HasNewFatalFailureHelper` instance across multiple threads simultaneously, as the internal `has_new_fatal_failure_` flag lacks synchronization mechanisms for concurrent access.