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

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 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.

#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.

#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.

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.

#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.

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 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.

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 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, 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}