# How to Use Matchers with EXPECT_THAT in GoogleTest

> Learn how to use matchers with EXPECT_THAT in GoogleTest. This powerful assertion macro provides detailed failure messages for precise testing.

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

---

**`EXPECT_THAT`** is the generalized assertion macro that evaluates a value against a **matcher** object, producing detailed, human-readable failure messages when the matcher does not accept the value.

The `google/googletest` repository provides `EXPECT_THAT` as a flexible alternative to traditional boolean assertions. When you write tests using matchers, you gain composable logic and superior diagnostics that tell you exactly why a value failed to meet expectations.

## How EXPECT_THAT Works

`EXPECT_THAT` (and its fatal-failure counterpart **`ASSERT_THAT`**) lives in the assertions reference documentation at [`docs/reference/assertions.md`](https://github.com/google/googletest/blob/main/docs/reference/assertions.md). When you invoke:

```cpp
EXPECT_THAT(value, matcher);

```

GoogleTest evaluates `value` once, passes it to the matcher, and prints a detailed failure message if the matcher rejects the value. The underlying matcher infrastructure is defined in **[`googletest/include/gtest/gtest-matchers.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-matchers.h)**, which implements the `Matcher<T>` template and the `MatcherInterface<T>` base class that all matchers implement.

## Built-in Matchers Available in GoogleTest

GoogleTest ships with a rich vocabulary of matchers covering strings, numerics, containers, and pointers. These are declared in **[`googlemock/include/gmock/gmock.h`](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock.h)** and documented in [`docs/reference/matchers.md`](https://github.com/google/googletest/blob/main/docs/reference/matchers.md).

### String Matchers

Verify text content using pattern matchers:

- **`StartsWith`** – checks that a string begins with a specific substring.
- **`MatchesRegex`** – validates against regular expressions.

```cpp
#include <gmock/gmock.h>
using ::testing::StartsWith;
using ::testing::MatchesRegex;

std::string value1 = "Hello, world!";
EXPECT_THAT(value1, StartsWith("Hello"));

std::string value2 = "Line 42";
EXPECT_THAT(value2, MatchesRegex(R"(Line \d+)"));

```

### Numeric and Comparison Matchers

Combine relational operators using logical composers:

- **`Gt`**, **`Lt`**, **`Ge`**, **`Le`**, **`Eq`**, **`Ne`** – realize standard comparisons.
- **`AllOf`**, **`AnyOf`**, **`Not`** – compose matchers with boolean logic.

```cpp
using ::testing::AllOf;
using ::testing::Gt;
using ::testing::Lt;

int value = 7;
EXPECT_THAT(value, AllOf(Gt(5), Lt(10)));

```

### Container Matchers

Inspect C++ containers element-by-element:

- **`ElementsAre`** – verifies that a container matches an ordered list of matchers.
- **`UnorderedElementsAre`** – checks membership regardless of order.
- **`Pointwise`** – applies a matcher to corresponding elements of two containers.

```cpp
using ::testing::ElementsAre;

std::vector<int> vec = {1, 2, 3};
EXPECT_THAT(vec, ElementsAre(1, 2, 3));

```

### Pointer Matchers

Handle raw pointers and null checks:

- **`IsNull`** – asserts that a pointer is null.
- You can also use **`nullptr`** directly as a matcher shorthand.

```cpp
int* p = nullptr;
EXPECT_THAT(p, nullptr);   // Equivalent to IsNull()

```

## Creating Custom Matchers

When built-in matchers are insufficient, you can define custom ones in two ways.

### Using the MATCHER Macro

The simplest method uses the **`MATCHER`** or **`MATCHER_P`** helper macros defined in [`googlemock/include/gmock/gmock.h`](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock.h). These generate a class that implements the required interface:

```cpp
MATCHER(IsEven, "is an even number") {
  return (arg % 2) == 0;
}

int n = 4;
EXPECT_THAT(n, IsEven());

```

### Inheriting from MatcherInterface

For complex logic requiring state or parameterization, inherit from **`MatcherInterface<T>`** in [`googletest/include/gtest/gtest-matchers.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-matchers.h) and implement `MatchAndExplain` and `DescribeTo`.

## Summary

- **`EXPECT_THAT`** and **`ASSERT_THAT`** are defined in [`docs/reference/assertions.md`](https://github.com/google/googletest/blob/main/docs/reference/assertions.md) and provide the main interface for matcher-based assertions.
- The matcher base architecture lives in **[`googletest/include/gtest/gtest-matchers.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-matchers.h)**, defining `Matcher<T>` and `MatcherInterface<T>`.
- Rich built-in matchers (strings, containers, numerics) are provided in **[`googlemock/include/gmock/gmock.h`](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock.h)**.
- Matchers are **composable**: use `AllOf`, `AnyOf`, and `Not` to build complex validation logic.
- Custom matchers can be written quickly with the **`MATCHER`** macro or by implementing `MatcherInterface<T>`.

## Frequently Asked Questions

### What is the difference between EXPECT_THAT and ASSERT_THAT?

**`EXPECT_THAT`** generates a non-fatal failure and continues executing the current test function, while **`ASSERT_THAT`** produces a fatal failure and immediately aborts the current test. Use `ASSERT_THAT` when subsequent assertions depend on the current value being valid.

### Do I need to link against Google Mock to use EXPECT_THAT?

The core `EXPECT_THAT` macro and basic matchers reside in the Google Test library; however, the majority of practical matchers (including `MATCHER` macros, `StartsWith`, `ElementsAre`, etc.) are defined in **[`googlemock/include/gmock/gmock.h`](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock.h)**. You must include this header and typically link against the Google Mock library to access the full matcher ecosystem.

### How do I combine multiple conditions in a single assertion?

Use the logical composition matchers **`AllOf`**, **`AnyOf`**, or **`Not`**. For example, `EXPECT_THAT(value, AllOf(Gt(5), Lt(10)))` asserts that a value falls within a range. These are variadic templates that accept any number of matcher arguments.

### Why does my custom matcher produce cryptic error messages?

Ensure your custom matcher implements the `DescribeTo` method (or use the `MATCHER` macro which generates this automatically). The description string is embedded in failure messages by the machinery in [`gtest-matchers.h`](https://github.com/google/googletest/blob/main/gtest-matchers.h). If you inherit directly from `MatcherInterface<T>`, you must override both `MatchAndExplain` and `DescribeTo` to provide meaningful diagnostics.