# How to Use Predicate Assertions in GoogleTest for Better Error Messages

> Master GoogleTest predicate assertions to create custom Boolean checks with clear error messages showing expression strings and runtime values. Improve your testing today.

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

---

**GoogleTest predicate assertions evaluate custom Boolean predicates while automatically generating detailed failure messages that include both the expression strings and actual runtime values of the arguments.**

The **google/googletest** framework provides predicate assertion macros that replace opaque `EXPECT_TRUE` calls with self-diagnosing tests. Unlike basic assertions, these utilities capture the expression text and argument values, emitting precise failure diagnostics that show exactly why a custom validation rule failed.

## Understanding Predicate Assertion Macros

The predicate assertion machinery lives in **[`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h)**, which defines two families of macros: `EXPECT_PREDn` for simple predicates and `EXPECT_PRED_FORMATn` for custom formatters. These macros support one through five arguments.

**`EXPECT_PREDn`** wraps a plain Boolean function. When the predicate returns `false`, GoogleTest prints the expression and evaluates to `false`, but cannot describe the specific values involved beyond what the default formatter extracts.

**`EXPECT_PRED_FORMATn`** accepts a *predicate-format function* that you write. This function receives stringified expressions followed by the actual values, letting you embed the runtime data directly into the failure message via `::testing::AssertionResult`.

The public header **[`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h)** re-exports these macros, so including [`gtest/gtest.h`](https://github.com/google/googletest/blob/main/gtest/gtest.h) is sufficient for most user code.

## Writing Custom Predicate-Format Functions

A predicate-format function must match the signature pattern used by the macro size you need. For a single argument, the signature is:

```cpp
::testing::AssertionResult FunctionName(const char* expr1, const T1& v1);

```

For multiple arguments, the expression strings precede the values in order:

```cpp
::testing::AssertionResult FunctionName(const char* expr1, const char* expr2,
                                        const T1& v1, const T2& v2);

```

The function returns **`::testing::AssertionSuccess()`** on pass, or **`::testing::AssertionFailure() << "message"`** on fail. The `AssertionResult` class is defined in **[`googletest/include/gtest/gtest-assertion-result.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-assertion-result.h)**, which provides the stream insertion operator for building custom diagnostics.

Because the macro forwards the original source expressions as the initial `const char*` parameters, your failure message can quote the exact code that was evaluated alongside the computed values.

## GoogleTest Predicate Assertion Examples

### Single-Argument Predicates with EXPECT_PRED1

Use **`EXPECT_PRED1`** when a simple Boolean function validates one value. The default formatter prints the predicate call and the Boolean result.

```cpp
// Predicate function
bool IsEven(int n) { return n % 2 == 0; }

TEST(MathTest, EvenCheck) {
  int x = 3;
  EXPECT_PRED1(IsEven, x);
}

```

Failure output:

```

Value of: IsEven(x)
  Actual: false
Expected: true

```

### Multi-Argument Predicates with EXPECT_PRED2 and EXPECT_PRED3

For predicates requiring multiple inputs, use **`EXPECT_PRED2`**, **`EXPECT_PRED3`**, **`EXPECT_PRED4`**, or **`EXPECT_PRED5`** according to the argument count.

```cpp
bool InRange(int value, int low, int high) {
  return low <= value && value <= high;
}

TEST(RangeTest, SimpleBounds) {
  EXPECT_PRED3(InRange, 5, 1, 10);   // Checks 5 ∈ [1,10]
}

```

If the check fails, the message displays the full invocation, though the default formatter does not expand the individual bound values.

### Custom Formatters for Detailed Failure Messages

To expose the actual numeric values that violated the rule, implement a predicate-format function and invoke it with **`EXPECT_PRED_FORMAT1`**, **`EXPECT_PRED_FORMAT2`**, or the variant matching your argument count.

```cpp
::testing::AssertionResult IsEvenFormat(const char* expr, int n) {
  if (n % 2 == 0) return ::testing::AssertionSuccess();
  return ::testing::AssertionFailure()
         << expr << " is " << n << ", which is not even";
}

TEST(MathTest, EvenCheckVerbose) {
  int x = 3;
  EXPECT_PRED_FORMAT1(IsEvenFormat, x);
}

```

Failure output:

```

x is 3, which is not even

```

For three arguments, the pattern expands accordingly:

```cpp
::testing::AssertionResult InRangeFormat(const char* expr_val,
                                         const char* expr_low,
                                         const char* expr_high,
                                         int value,
                                         int low,
                                         int high) {
  if (low <= value && value <= high) return ::testing::AssertionSuccess();
  return ::testing::AssertionFailure()
         << value << " is outside the range [" << low << ", " << high << "]";
}

TEST(RangeTest, VerboseBounds) {
  EXPECT_PRED_FORMAT3(InRangeFormat, 20, 1, 10);
}

```

### Working with User-Defined Types

Predicate assertions work with any CopyConstructible type. GoogleTest prints the value using its default printer or your custom `operator<<` overload.

```cpp
struct Point { int x, y; };

bool IsOrigin(const Point& p) { return p.x == 0 && p.y == 0; }

TEST(PointTest, OriginCheck) {
  Point p{3, 4};
  EXPECT_PRED1(IsOrigin, p);
}

```

If `p` is not the origin, the failure message includes the pretty-printed `Point` representation alongside the expression `IsOrigin(p)`.

## Summary

- **Predicate assertions** (`EXPECT_PREDn` and `EXPECT_PRED_FORMATn`) provide richer diagnostics than `EXPECT_TRUE` for custom validation logic.
- **Macro definitions** reside in [`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h) and support one through five arguments.
- **Custom formatters** receive both expression strings and value references, enabling failure messages that state exactly which values violated the predicate.
- **AssertionResult** (from [`gtest-assertion-result.h`](https://github.com/google/googletest/blob/main/gtest-assertion-result.h)) provides `AssertionSuccess()` and `AssertionFailure()` for constructing formatter return values.
- **User-defined types** integrate seamlessly; define `operator<<` to control how values appear in failure logs.

## Frequently Asked Questions

### What is the difference between EXPECT_PRED1 and EXPECT_PRED_FORMAT1?

**`EXPECT_PRED1`** accepts a simple Boolean predicate and uses a default formatter that prints the expression and the Boolean result. **`EXPECT_PRED_FORMAT1`** accepts a function returning `::testing::AssertionResult` that receives the expression string and the value, letting you embed the actual data into the failure message rather than just printing `true` or `false`.

### How many arguments can a GoogleTest predicate assertion handle?

GoogleTest defines predicate macros for one through five arguments: `EXPECT_PRED1` through `EXPECT_PRED5` and `EXPECT_PRED_FORMAT1` through `EXPECT_PRED_FORMAT5`. The implementation in [`gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/gtest_pred_impl.h) generates these variants using preprocessor repetition to maintain consistent behavior across arity levels.

### Where are predicate assertion macros defined in the GoogleTest source code?

The macros are defined in **[`googletest/include/gtest/gtest_pred_impl.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest_pred_impl.h)**. The public face of these macros is exposed through **[`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h)**, which is the header you include in test files. The `AssertionResult` type used by custom formatters is declared in **[`googletest/include/gtest/gtest-assertion-result.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-assertion-result.h)**.

### How do I include custom values in my predicate assertion failure messages?

Write a predicate-format function that takes `const char*` expression parameters followed by `const T&` value parameters, then return `::testing::AssertionFailure() << "your message"` with the values inserted into the stream. Pass this function to `EXPECT_PRED_FORMATn` (where *n* matches your argument count) rather than using the plain `EXPECT_PREDn` macro.