# How to Use Container Matchers in GoogleTest: A Complete Guide with Examples

> Master GoogleTest container matchers like ElementsAre Contains and Each to efficiently verify STL containers arrays and iterables Learn how to use these powerful tools with EXPECT_THAT and ASSERT_THAT for robust testing

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

---

**GoogleTest provides polymorphic container matchers like `ElementsAre`, `Contains`, and `Each` that integrate with `EXPECT_THAT` and `ASSERT_THAT` macros to verify STL containers, native arrays, and custom iterables with expressive, type-safe syntax.**

The `google/googletest` framework offers powerful container matchers in GoogleTest that extend beyond basic assertions, enabling precise validation of complex data structures. These matchers, defined in the `Matcher<T>` infrastructure, automatically adapt to any container exposing `begin()`/`end()` iterators or a `size()` method, allowing readable tests for vectors, maps, lists, and native arrays.

## Core Container Matchers API

The container matcher implementations live in [`googletest/include/gtest/gtest-matchers.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-matchers.h) with concrete logic in `googletest/src/gtest-matchers.cc`. These polymorphic matchers detect iterator support and size methods to apply verification logic across compatible container types.

### Exact Order Verification with ElementsAre

The **`ElementsAre(e0, e1, …)`** matcher verifies that a container contains exactly the specified elements in the exact order provided. Each argument can be either a literal value or another matcher.

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

using ::testing::ElementsAre;

TEST(ContainerMatchers, ElementsAre) {
  std::vector<int> v{1, 2, 3};
  EXPECT_THAT(v, ElementsAre(1, 2, 3));  // passes
}

```

### Order-Agnostic Matching with UnorderedElementsAre

When element order is irrelevant, use **`UnorderedElementsAre(e0, e1, …)`**. This matcher checks for the presence of all specified elements regardless of their sequence, as verified in `googlemock/test/gmock-matchers-containers_test.cc`.

```cpp
#include <list>

using ::testing::UnorderedElementsAre;

TEST(ContainerMatchers, UnorderedElementsAre) {
  std::list<int> l{3, 1, 2};
  EXPECT_THAT(l, UnorderedElementsAre(1, 2, 3));  // passes
}

```

### Existence and Universal Quantification

For partial matching, **`Contains(e)`** verifies that at least one element satisfies the given value or sub-matcher. Conversely, **`Each(e)`** requires every element to match the provided condition.

```cpp
using ::testing::Contains;
using ::testing::Each;
using ::testing::Gt;
using ::testing::Le;

TEST(ContainerMatchers, ContainsAndEach) {
  std::vector<int> v{5, 7, 9};
  EXPECT_THAT(v, Contains(Gt(6)));    // passes: 7 and 9 are > 6
  EXPECT_THAT(v, Each(Le(10)));       // passes: all elements ≤ 10
}

```

### Size and Transformative Matchers

Validate container cardinality with **`SizeIs(m)`**, where `m` is a matcher like `Eq(3)` or `Ge(2)`. To normalize ordering before comparison, use **`WhenSorted(m)`** with the default comparator or **`WhenSortedBy(comp, m)`** with a custom comparator.

```cpp
#include <map>

using ::testing::SizeIs;
using ::testing::WhenSorted;

TEST(ContainerMatchers, SizeAndSort) {
  std::map<int, std::string> m{{1, "a"}, {2, "b"}};
  EXPECT_THAT(m, SizeIs(::testing::Eq(2)));  // passes
  
  std::vector<int> v{3, 1, 2};
  EXPECT_THAT(v, WhenSorted(ElementsAre(1, 2, 3)));  // passes
}

```

### Pairwise Container Comparison

Compare two containers element-by-element using **`Pointwise(m, expected)`** for ordered comparison or **`UnorderedPointwise(m, expected)`** for order-agnostic matching. These matchers apply the binary matcher `m` between corresponding elements of the actual and expected containers.

```cpp
using ::testing::Pointwise;
using ::testing::Gt;

TEST(ContainerMatchers, Pointwise) {
  std::vector<int> actual{1, 4, 9};
  std::vector<int> expected{0, 3, 8};
  EXPECT_THAT(actual, Pointwise(Gt(), expected));  // each actual > corresponding expected
}

```

## Implementation Architecture in google/googletest

The header [`googletest/include/gtest/gtest-matchers.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-matchers.h) declares the public API and the `Matcher` template class, while `googletest/src/gtest-matchers.cc` contains the concrete logic that iterates over containers, checks sizes, performs sorting, and composes element-wise matchers. The implementation builds polymorphic matchers that delegate to the generic `Matcher<T>` infrastructure, detecting container capabilities through iterator support.

The comprehensive test suite in `googlemock/test/gmock-matchers-containers_test.cc` verifies each matcher against STL containers, native arrays, and custom types, ensuring correct behavior across edge cases including empty containers and duplicate elements. Reference documentation is generated from these definitions in [`docs/reference/matchers.md`](https://github.com/google/googletest/blob/main/docs/reference/matchers.md).

## Summary

- **Container matchers** in GoogleTest provide type-safe, polymorphic verification through `EXPECT_THAT` and `ASSERT_THAT` macros defined in the `google/googletest` repository.
- **Exact matching** uses `ElementsAre` for ordered verification and `UnorderedElementsAre` for order-agnostic checks.
- **Quantification matchers** include `Contains` for existential checks and `Each` for universal conditions across all elements.
- **Utility matchers** such as `SizeIs`, `WhenSorted`, and `Pointwise` enable size validation, pre-comparison sorting, and pairwise container comparisons.
- **Source files** implementing these features are located in [`googletest/include/gtest/gtest-matchers.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-matchers.h) and `googletest/src/gtest-matchers.cc`.

## Frequently Asked Questions

### What header file do I need for GoogleTest container matchers?

Include `<gmock/gmock.h>` to access container matchers like `ElementsAre`, `Contains`, and `Pointwise`. While the core `Matcher` class is defined in [`googletest/include/gtest/gtest-matchers.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest-matchers.h), the convenience functions and full macro integration require the GoogleMock header.

### Can I use container matchers with native C-style arrays?

Yes. GoogleTest container matchers work with any type providing `begin()` and `end()` iterators or a `size()` method. Native arrays are fully supported by `ElementsAre`, `UnorderedElementsAre`, and other matchers without requiring wrapper types or container adapters.

### How do I check if all elements in a container satisfy a condition?

Use the **`Each(e)`** matcher, which applies the sub-matcher `e` to every element in the container. For example, `EXPECT_THAT(v, Each(Gt(0)))` passes only if every element in vector `v` is greater than zero, as implemented in the `Each` function within [`gtest-matchers.h`](https://github.com/google/googletest/blob/main/gtest-matchers.h).

### What is the difference between `ElementsAre` and `UnorderedElementsAre`?

`ElementsAre` requires elements to appear in the exact specified order with no extra elements, while `UnorderedElementsAre` only verifies that the container contains exactly the specified elements regardless of their sequence. Both matchers require an exact count match with no surplus or missing elements, differing only in their order sensitivity.