# How to Use ASSERT vs EXPECT Macros in GoogleTest: Fatal vs Non-Fatal Failures

> Learn the difference between ASSERT and EXPECT macros in GoogleTest. Understand fatal vs non-fatal failures to write effective C++ tests.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: deep-dive
- Published: 2026-08-31

---

**Use `ASSERT_*` macros to abort the test immediately when a precondition fails, and `EXPECT_*` macros to report a failure but continue evaluating subsequent assertions.**

GoogleTest provides two families of assertion macros that form the foundation of C++ unit testing in the `google/googletest` repository. Understanding how to use ASSERT vs EXPECT macros in GoogleTest is essential for writing reliable tests that either fail fast on critical errors or gather comprehensive failure reports. Both families share the same underlying predicate evaluation logic in [`gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/gtest_pred_impl.h) but differ fundamentally in how they handle test flow control.

## Core Differences Between ASSERT and EXPECT

The `ASSERT_*` and `EXPECT_*` macro families both eventually invoke the low-level helper `GTEST_ASSERT_`, but they pass different failure-type parameters that determine test behavior.

**`ASSERT_*` macros** pass `GTEST_FATAL_FAILURE_`, causing immediate test termination through `Test::Run()`.  
**`EXPECT_*` macros** pass `GTEST_NONFATAL_FAILURE_`, allowing continued execution to gather additional failure data.

The core implementation lives in [`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h) at lines 77-82:

```cpp
#define GTEST_ASSERT_(expression, on_failure)                   \
  GTEST_AMBIGUOUS_ELSE_BLOCKER_                                 \
  if (const ::testing::AssertionResult gtest_ar = (expression)) \
    ;                                                           \
  else                                                          \
    on_failure(gtest_ar.failure_message())

```

When an assertion fails, the `on_failure` functor is invoked with the failure message. The specific functor passed determines whether `UnitTest::AddTestPartResult` records a fatal or non-fatal error.

## How the Macros Work Under the Hood

### Macro Expansion and Failure Types

The public API in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) defines specific macros that wrap the core helper. For example, equality checks expand differently for fatal versus non-fatal failures:

```cpp
// ASSERT_EQ - fatal failure (gtest.h lines 1928-1932)
#define ASSERT_EQ(val1, val2) \
  GTEST_ASSERT_EQ(val1, val2)

// EXPECT_EQ - non-fatal failure (gtest.h line 1911)
#define EXPECT_EQ(val1, val2) \
  GTEST_PRED_FORMAT2_(::testing::internal::CmpHelperEQ, \
                      val1, val2, GTEST_NONFATAL_FAILURE_)

```

`ASSERT_EQ` eventually calls `GTEST_ASSERT_` with `GTEST_FATAL_FAILURE_`, while `EXPECT_EQ` uses `GTEST_NONFATAL_FAILURE_`.

### Test Flow Control Architecture

When `GTEST_FATAL_FAILURE_` is invoked, it triggers `UnitTest::AddTestPartResult` with `TestPartResult::kFatalFailure`. This sets a fatal-failure flag inside the test runner. The `Test::Run()` loop checks this flag after each assertion; encountering it causes an immediate return from the test body, skipping all remaining statements.

Conversely, `GTEST_NONFATAL_FAILURE_` reports `TestPartResult::kNonFatalFailure` without setting the fatal flag, allowing the test to continue executing subsequent code and gather comprehensive diagnostic data.

## When to Use ASSERT vs EXPECT

Choose the appropriate macro based on whether subsequent test logic depends on the current assertion:

- **Critical preconditions** that must hold for remaining test logic (e.g., validating a pointer before dereferencing) require **`ASSERT_*`**.
- **Multiple independent checks** where you want a complete failure report rather than stopping at the first error favor **`EXPECT_*`**.
- **Resource-intensive operations** that should be skipped after setup failures use **`ASSERT_*`** to avoid wasted computation.
- **Post-condition verification** of multiple object properties benefits from **`EXPECT_*`** to identify all assertion violations in a single run.

## Practical Code Examples

### Fatal Assertions with ASSERT

Use `ASSERT_NE`, `ASSERT_TRUE`, and other `ASSERT_*` variants when the test cannot meaningfully continue after a failure:

```cpp
TEST(DatabaseTest, ConnectionRequired) {
  Database* db = CreateConnection();
  
  // Abort immediately if connection fails
  ASSERT_NE(db, nullptr) << "Database connection failed";
  
  // Safe to proceed - db is guaranteed non-null here
  EXPECT_TRUE(db->IsConnected());
  ASSERT_EQ(db->GetVersion(), 42);
  
  // This code only runs if all above assertions pass
  db->ExecuteQuery("SELECT * FROM users");
}

```

*Implementation reference:* `ASSERT_NE` expands to `GTEST_ASSERT_NE`, which invokes `GTEST_ASSERT_` with `GTEST_FATAL_FAILURE_` (see [`gtest.h`](https://github.com/google/googletest/blob/main/gtest.h) lines 1929-1932).

### Non-Fatal Checks with EXPECT

Use `EXPECT_*` macros to validate multiple properties without early termination:

```cpp
TEST(UserTest, ValidateProperties) {
  User user = LoadUser(123);
  
  // All three checks run regardless of individual failures
  EXPECT_EQ(user.name, "Alice");
  EXPECT_TRUE(user.IsActive());
  EXPECT_GT(user.last_login.days_ago(), 0);
  
  // Additional diagnostics run even if previous expectations failed
  if (user.email.empty()) {
    EXPECT_FALSE(user.notifications_enabled);
  }
}

```

*Implementation reference:* `EXPECT_EQ` expands to `GTEST_PRED_FORMAT2_` passing `GTEST_NONFATAL_FAILURE_` as the failure handler (see [`gtest.h`](https://github.com/google/googletest/blob/main/gtest.h) line 1911).

## Summary

- **`ASSERT_*` macros** immediately abort the current test function using `GTEST_FATAL_FAILURE_`, preventing execution of subsequent statements via a return from `Test::Run()`.
- **`EXPECT_*` macros** record failures via `GTEST_NONFATAL_FAILURE_` but allow the test to continue, providing comprehensive failure reports through `UnitTest::AddTestPartResult`.
- Both macro families share the `GTEST_ASSERT_` implementation in [`gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/gtest_pred_impl.h), differing only in the failure handler passed to the helper.
- Use `ASSERT_*` for preconditions required for test validity and `EXPECT_*` for independent post-condition checks where multiple failures provide better debugging information.

## Frequently Asked Questions

### What happens to code after an ASSERT failure?

Code after a failed `ASSERT_*` macro never executes. The macro invokes `GTEST_FATAL_FAILURE_`, which calls `UnitTest::AddTestPartResult` with `TestPartResult::kFatalFailure`. This sets a fatal flag that causes `Test::Run()` to return immediately from the test body, skipping all remaining statements in that test function.

### Can I mix ASSERT and EXPECT in the same test?

Yes, mixing `ASSERT_*` and `EXPECT_*` macros in the same test is a common and recommended practice. Use `ASSERT_*` for early validation of preconditions (like null pointer checks), then use `EXPECT_*` for the bulk of your assertions once the test is in a valid state. This prevents cascades of meaningless failures while still gathering multiple independent validation errors.

### Do ASSERT and EXPECT produce different error messages?

No, both macro families produce identical diagnostic messages because they share the same underlying assertion logic in `GTEST_ASSERT_`. The only difference is the failure type (`GTEST_FATAL_FAILURE_` vs `GTEST_NONFATAL_FAILURE_`) passed to the helper, which controls test flow rather than message formatting. Both report the same file, line number, and predicate description.

### Which header files define these macros?

The primary definitions reside in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) (public API) and [`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h) (core `GTEST_ASSERT_` helper). Internal failure handlers like `GTEST_FATAL_FAILURE_` are defined in [`googletest/include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-internal.h). The implementation of failure recording and test flow control lives in `googletest/src/gtest.cc`.