# Where to Find GoogleTest Documentation for Assertions: The Complete Guide

> Find the complete GoogleTest documentation for assertions in the official repository. Explore EXPECT_* and ASSERT_* macros for effective C++ testing.

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

---

**The authoritative GoogleTest documentation for assertions is located in the repository's [`docs/reference/assertions.md`](https://github.com/google/googletest/blob/main/docs/reference/assertions.md) file, which catalogs all `EXPECT_*` and `ASSERT_*` macros alongside their failure behaviors and usage patterns.**

The `google/googletest` repository maintains comprehensive assertion references directly within its source tree. Locating the correct **GoogleTest documentation for assertions** ensures you access the most current macro specifications, failure message formats, and matcher syntax without relying on outdated external guides.

## Locating the Official Reference Materials

The repository organizes documentation in the `docs/` directory, with assertion-specific references separated from general primers.

### The Assertions Reference Page

The definitive source for built-in macro syntax is [`docs/reference/assertions.md`](https://github.com/google/googletest/blob/main/docs/reference/assertions.md). This file enumerates all `EXPECT_*`, `ASSERT_*`, and Boolean assertion variants, detailing their parameter signatures and failure behaviors. According to the google/googletest source code, this reference also explains when to choose non-fatal checks over fatal aborts.

### The Testing Primer

For conceptual context on how assertions integrate into test suites, see [`docs/primer.md`](https://github.com/google/googletest/blob/main/docs/primer.md). This document explains the execution flow when assertions fail and provides guidance on structuring test cases that utilize multiple assertion statements.

## Core Implementation Headers

Understanding the underlying headers helps when debugging assertion failures or extending the framework.

### Primary Public Header

All standard assertion macros are defined in [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h). This header pulls in the complete assertion API, including the streaming syntax for custom failure messages using the `<<` operator.

### AssertionResult Interface

Custom assertion development requires [`include/gtest/assertion_result.h`](https://github.com/google/googletest/blob/main/include/gtest/assertion_result.h), which defines the `::testing::AssertionResult` type. This class represents the return value of predicate assertions and enables the creation of domain-specific checks that integrate seamlessly with GoogleTest's output formatting.

## Assertion Categories and Usage Examples

GoogleTest provides distinct assertion families for different failure semantics.

### Non-Fatal Expectations

Use `EXPECT_*` macros when you want the test to continue executing after reporting a failure. These are defined in the main header and collect multiple independent failure points within a single test case.

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

TEST(MathTest, MultipleChecks) {
  int result = 2 + 2;
  EXPECT_EQ(result, 4);               // Reports failure but continues
  EXPECT_NE(result, 5);               // Also executes regardless of previous failure
}

```

### Fatal Assertions

`ASSERT_*` macros abort the current test function immediately upon failure. According to the implementation in [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h), these are essential for preconditions that would cause undefined behavior if execution continued.

```cpp
TEST(MathTest, FatalPrecondition) {
  int denominator = 0;
  ASSERT_NE(denominator, 0) << "Denominator must be non-zero";
  // Execution stops here if the assertion fails
}

```

### Matcher-Based Assertions

For expressive, readable checks on containers and complex objects, use `EXPECT_THAT` and `ASSERT_THAT` documented in [`docs/reference/matchers.md`](https://github.com/google/googletest/blob/main/docs/reference/matchers.md). These matchers provide semantic clarity beyond simple equality checks.

```cpp
#include <vector>

TEST(ContainerTest, MatcherSyntax) {
  std::vector<int> values = {1, 2, 3, 4};
  EXPECT_THAT(values, ::testing::Contains(3));
  EXPECT_THAT(values, ::testing::ElementsAre(1, 2, 3, 4));
}

```

## Summary

- The primary **GoogleTest documentation for assertions** is [`docs/reference/assertions.md`](https://github.com/google/googletest/blob/main/docs/reference/assertions.md) in the repository root.
- Implementation details reside in [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h) for macros and [`include/gtest/assertion_result.h`](https://github.com/google/googletest/blob/main/include/gtest/assertion_result.h) for custom extension points.
- **Non-fatal `EXPECT_*` macros** allow tests to continue and report multiple failures, while **fatal `ASSERT_*` macros** terminate immediately.
- **Matcher-based assertions** (`EXPECT_THAT`) provide readable syntax for complex validations and are documented separately in [`docs/reference/matchers.md`](https://github.com/google/googletest/blob/main/docs/reference/matchers.md).

## Frequently Asked Questions

### Where exactly is the GoogleTest assertion documentation located?

The authoritative documentation is stored at [`docs/reference/assertions.md`](https://github.com/google/googletest/blob/main/docs/reference/assertions.md) within the `google/googletest` repository on GitHub. This Markdown file contains the complete reference for all built-in assertion macros, their parameters, and failure behaviors.

### What is the difference between EXPECT and ASSERT macros in GoogleTest?

**`EXPECT_*` macros** generate non-fatal failures that allow the test to continue executing subsequent statements, while **`ASSERT_*` macros** abort the test function immediately upon failure. According to the source in [`include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/include/gtest/gtest.h), ASSERT variants are implemented to throw a special exception that terminates the current test scope.

### How do I write custom assertions in GoogleTest?

Custom assertions return a `::testing::AssertionResult` object defined in [`include/gtest/assertion_result.h`](https://github.com/google/googletest/blob/main/include/gtest/assertion_result.h). You construct success results with `AssertionSuccess()` and failures with `AssertionFailure() << "message"`, allowing seamless integration with GoogleTest's failure reporting and streaming syntax.

### Where can I find documentation for the EXPECT_THAT matcher syntax?

Matcher-based assertions are documented in [`docs/reference/matchers.md`](https://github.com/google/googletest/blob/main/docs/reference/matchers.md), which covers the `::testing` namespace matchers like `Contains`, `ElementsAre`, and `Eq`. This file complements the main assertions reference by providing patterns for more readable, domain-specific validation logic.