# How to Use EXPECT_* vs ASSERT_* Macros in GoogleTest

> Learn the difference between EXPECT_* and ASSERT_* macros in GoogleTest. Understand how to use non-fatal vs fatal failures to improve your C++ test execution and debugging.

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

---

**EXPECT_* macros record non-fatal failures and allow the test to continue executing subsequent statements, while ASSERT_* macros generate fatal failures that immediately abort the current test function.**

The `google/googletest` framework provides these two assertion families to give developers precise control over failure handling during C++ unit testing. Understanding **EXPECT_* vs ASSERT_* macros** is essential for writing maintainable tests that either aggregate multiple independent failures or halt immediately when prerequisites fail. Both macro families ultimately delegate to the same underlying `GTEST_ASSERT_` machinery but pass different failure handlers that determine whether the test runner continues or terminates.

## Core Architectural Differences

Both macro families expand to the same low-level helper, but they pass distinct failure handlers that determine the test execution flow. In [`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h), the implementation differentiates between non-fatal and fatal assertions through the `GTEST_PRED_FORMAT2_` macro.

### Non-Fatal Assertions (EXPECT_*)

When an `EXPECT_*` macro fails, it creates a `TestPartResult` with status `kNonFatalFailure` and passes it to `UnitTest::AddTestPartResult`. The macro expands using `GTEST_NONFATAL_FAILURE_`:

```cpp
#define EXPECT_PRED_FORMAT2(pred_format, v1, v2) \
  GTEST_PRED_FORMAT2_(pred_format, v1, v2, GTEST_NONFATAL_FAILURE_)

```

This allows the test to record the failure while continuing execution of remaining test statements.

### Fatal Assertions (ASSERT_*)

Conversely, `ASSERT_*` macros use `GTEST_FATAL_FAILURE_`, which generates a `TestPartResult::kFatalFailure`. As implemented in [`googletest/include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-internal.h) approximately line 250, `UnitTest::AddTestPartResult` receives this fatal status and causes the test runner to short-circuit the current test body immediately:

```cpp
#define ASSERT_PRED_FORMAT2(pred_format, v1, v2) \
  GTEST_PRED_FORMAT2_(pred_format, v1, v2, GTEST_FATAL_FAILURE_)

```

## Source Code Implementation Details

The macro definitions in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) demonstrate how the public API maps to these internal handlers. Both families provide the same comparison functionality but route failures differently.

### Macro Definitions in gtest.h

The `EXPECT_EQ` macro wraps predicate helpers with non-fatal semantics:

```cpp
#define EXPECT_EQ(val1, val2) \
  EXPECT_PRED_FORMAT2(::testing::internal::EqHelper::Compare, val1, val2)

```

Meanwhile, `ASSERT_EQ` delegates to a fatal variant:

```cpp
#define ASSERT_EQ(val1, val2) \
  GTEST_ASSERT_EQ(val1, val2)

```

### Predicate Helper Architecture

Both macros ultimately invoke predicate helpers like `EqHelper::Compare` to generate detailed failure messages. The key distinction occurs in [`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h), where `EXPECT_PRED_FORMAT2` and `ASSERT_PRED_FORMAT2` expand to `GTEST_PRED_FORMAT2_` with their respective failure handlers. This design ensures that argument evaluation and message formatting remain identical between the two families, differing only in the final failure recording step.

## When to Use EXPECT_* vs ASSERT_*

Selecting the appropriate macro family depends on whether subsequent test code depends on the assertion passing.

- **Use `EXPECT_*`** when verifying multiple independent properties in a single test. This collects all failures before reporting, providing complete diagnostic information.
- **Use `ASSERT_*`** when the assertion establishes a prerequisite for subsequent operations. If dereferencing a pointer or accessing data depends on a condition, use `ASSERT_*` to prevent undefined behavior in the test body.

## Practical Code Examples

The following examples demonstrate the behavioral differences between the two macro families.

### Non-Fatal EXPECT_* Usage

This test continues execution even after individual expectations fail:

```cpp
TEST(FooTest, NonFatalChecks) {
  // The test will continue after each failure.
  EXPECT_EQ(ComputeAnswer(), 42);
  EXPECT_TRUE(IsValid(state));
  // Even if the above expectations fail, the following code runs.
  EXPECT_NE(GetCount(), 0);
}

```

### Fatal ASSERT_* Usage

This test aborts immediately if the pointer is null, preventing a segfault:

```cpp
TEST(BarTest, FatalPrerequisite) {
  // If `ptr` is null, the test aborts here.
  ASSERT_NE(ptr, nullptr);
  // Safe to dereference `ptr` because the previous ASSERT guarantees it.
  EXPECT_EQ(ptr->value, 5);
}

```

## Summary

- **EXPECT_* macros** record failures via `GTEST_NONFATAL_FAILURE_` and create `TestPartResult::kNonFatalFailure` objects, allowing tests to continue execution.
- **ASSERT_* macros** trigger `GTEST_FATAL_FAILURE_` and generate `TestPartResult::kFatalFailure`, causing immediate test termination via `UnitTest::AddTestPartResult`.
- Both families guarantee single argument evaluation and use predicate helpers like `EqHelper::Compare` for consistent failure messaging.
- Use **EXPECT_*** for independent checks and **ASSERT_*** for safety prerequisites that guard subsequent test logic.
- Implementation resides primarily in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) and [`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h).

## Frequently Asked Questions

### What is the difference between EXPECT_* and ASSERT_* macros in GoogleTest?

**EXPECT_* macros record non-fatal failures that allow the test to continue, while ASSERT_* macros generate fatal failures that abort the current test immediately.** According to the source code in [`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h), both expand to `GTEST_PRED_FORMAT2_` but pass different failure handlers: `GTEST_NONFATAL_FAILURE_` for EXPECT and `GTEST_FATAL_FAILURE_` for ASSERT.

### Can a test continue after an ASSERT_* failure?

No. When an `ASSERT_*` macro fails, it creates a `TestPartResult::kFatalFailure` that causes `UnitTest::AddTestPartResult` to short-circuit the test body. The remaining statements in that test function are skipped entirely, though other tests in the same test case will still execute.

### Are arguments to EXPECT_* and ASSERT_* macros evaluated multiple times?

No. As documented in the comments around line 1889 of [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h), both macro families guarantee that each argument is evaluated exactly once, regardless of whether the assertion passes or fails. This prevents side effects from causing unexpected behavior during test execution.

### When should I use ASSERT_* instead of EXPECT_*?

Use **`ASSERT_*`** when subsequent test code depends on the assertion being true, such as checking that a pointer is non-null before dereferencing it. Use **`EXPECT_*`** when verifying multiple independent conditions where you want to see all failures at once, such as validating various properties of a returned object.