Common Built-In Container Matchers in GoogleTest: ElementsAre, UnorderedElementsAre, and More

GoogleTest provides seven built-in container matchers—including ElementsAre, UnorderedElementsAre, IsSubsetOf, and UnorderedPointwise—that enable precise, order-aware or order-agnostic validation of STL containers and custom ranges without writing explicit iteration logic.

The GoogleTest framework (via Google Mock) ships with a comprehensive matching library defined primarily in googlemock/include/gmock/gmock-matchers.h. These built-in container matchers allow developers to write declarative assertions about vector, list, map, and set contents directly in unit tests using the testing:: namespace.

Ordered Element Matching

When you need to verify that a container contains specific elements in an exact sequence, GoogleTest provides matchers that check both the values and their positions.

ElementsAre

The ElementsAre matcher verifies that a container has exactly the given number of elements in order and that each element matches the supplied sub-matchers. According to the google/googletest source code, this is implemented in [gmock-matchers.h at line 3653](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock-matchers.h#L3653).

std::vector<int> v{1, 2, 3};
EXPECT_THAT(v, ElementsAre(1, 2, 3));  // Passes
EXPECT_THAT(v, ElementsAre(3, 2, 1));  // Fails: wrong order

ElementsAreArray

ElementsAreArray functions identically to ElementsAre but accepts an iterator range or initializer list of matchers. As implemented in the same header at line 4606, it creates a copy of the matcher sequence before performing the match, ensuring stability during comparison.

std::vector<int> v{1, 2, 3};
EXPECT_THAT(v, ElementsAreArray({1, 2, 3}));  // Uses initializer list

Unordered Container Matchers

For containers where element position is irrelevant, GoogleTest offers matchers that verify contents regardless of sequence.

UnorderedElementsAre

The UnorderedElementsAre matcher checks that a container contains the given elements in any order, with all supplied matchers satisfied exactly once. The implementation at line 4150 handles the permutation logic internally.

std::vector<std::string> fruits{"apple", "banana", "cherry"};
EXPECT_THAT(fruits, UnorderedElementsAre("cherry", "banana", "apple"));  // Passes

UnorderedElementsAreArray

Similar to its ordered counterpart, UnorderedElementsAreArray accepts an iterator range or initializer list. Found at line 4205, this matcher is useful when the expected values are stored in a separate container.

std::vector<std::string> actual{"banana", "apple"};
std::vector<std::string> expected{"apple", "banana"};
EXPECT_THAT(actual, UnorderedElementsAreArray(expected));

Set Relationship Matchers

GoogleTest includes matchers for verifying subset and superset relationships without requiring manual container intersection logic.

IsSubsetOf

IsSubsetOf asserts that every element of the actual container appears in the expected container, ignoring order and allowing extra elements in the expected set. The implementation resides at line 5326.

std::vector<int> actual{1, 3, 5};
EXPECT_THAT(actual, IsSubsetOf(1, 3, 5, 7, 9));  // Passes: actual ⊆ expected

IsSupersetOf

Conversely, IsSupersetOf verifies that the actual container contains all elements of the expected container (again ignoring order). This matcher is located at line 5366.

std::vector<int> actual{5, 1, 3, 9};
EXPECT_THAT(actual, IsSupersetOf(1, 3, 5));  // Passes: actual ⊇ expected

Advanced Container Matching

UnorderedPointwise

The UnorderedPointwise matcher verifies a one-to-one correspondence between two containers where the order of the actual container is irrelevant. Each pair of elements is matched by a supplied binary matcher. As noted in the source at line 4251, this is internally built on UnorderedElementsAreArray.

using ::testing::Pair;
std::map<int, std::string> actual{{1, "one"}, {2, "two"}};
EXPECT_THAT(actual, UnorderedPointwise(Pair(), std::vector<std::pair<int, std::string>>{{2, "two"}, {1, "one"}}));

Complete Usage Examples

The following example demonstrates practical applications of the primary GoogleTest container matchers in a single test suite:

#include <gmock/gmock.h>
using ::testing::ElementsAre;
using ::testing::ElementsAreArray;
using ::testing::UnorderedElementsAre;
using ::testing::UnorderedElementsAreArray;
using ::testing::IsSubsetOf;
using ::testing::IsSupersetOf;

TEST(ContainerMatchersDemo, OrderedElements) {
  std::vector<int> v{1, 2, 3};
  EXPECT_THAT(v, ElementsAre(1, 2, 3));               // exact order required
  EXPECT_THAT(v, ElementsAreArray({1, 2, 3}));        // same using initializer list
}

TEST(ContainerMatchersDemo, UnorderedElements) {
  std::vector<std::string> v{"apple", "banana", "cherry"};
  EXPECT_THAT(v, UnorderedElementsAre("cherry", "banana", "apple"));
  EXPECT_THAT(v, UnorderedElementsAreArray({"banana", "apple", "cherry"}));
}

TEST(ContainerMatchersDemo, SubsetAndSuperset) {
  std::vector<int> actual{5, 1, 3, 9};
  EXPECT_THAT(actual, IsSubsetOf(1, 3, 5, 7, 9));    // actual ⊆ expected
  EXPECT_THAT(actual, IsSupersetOf(1, 3, 5, 9));     // actual ⊇ expected
}

Implementation and Testing

The container matcher logic is centralized in the Google Mock subsystem. The primary definitions reside in:

• googlemock/include/gmock/gmock-matchers.h: Contains the template classes and ElementsAre, UnorderedElementsAre, IsSubsetOf, and UnorderedPointwise implementations referenced above.
• googlemock/src/gmock-matchers.cc: Provides the underlying matching logic, description generation, and failure message formatting.
• googlemock/test/gmock-matchers-containers_test.cc: Validates all container matcher behaviors against STL containers and edge cases.

These files constitute the core of GoogleTest's container validation capabilities and are maintained under the google/googletest repository.

Summary

• Use ElementsAre when container order matters and you need exact positional matching.
• Use UnorderedElementsAre when verifying contents without regard to sequence.
• Use IsSubsetOf and IsSupersetOf to validate containment relationships without manual set operations.
• Use UnorderedPointwise for element-by-element comparison using custom binary matchers on unordered data.
• Include gmock/gmock.h to access the testing:: namespace where all container matchers reside.

Frequently Asked Questions

How do I check if a vector contains specific elements in any order?

Use the UnorderedElementsAre matcher. It verifies that all supplied matchers match distinct elements in the container, regardless of their positions. This is defined in gmock-matchers.h at line 4150 and handles permutation matching automatically.

What is the difference between ElementsAre and ElementsAreArray?

ElementsAre accepts a variadic list of matchers directly, while ElementsAreArray accepts an iterator range or initializer list. According to the source at line 4606, ElementsAreArray creates a copy of the matcher sequence before matching, making it safer when the expected values are stored in a container that might be modified.

Can I verify that one container is a subset of another?

Yes. Use the IsSubsetOf matcher, which checks that every element in the actual container exists in the expected container. The implementation at line 5326 ignores order and allows the expected container to contain additional elements not present in the actual container.

Do these matchers work with custom container types?

Yes. All built-in container matchers in GoogleTest work with any container that supports begin() and end() iterators, including custom range types. The matchers use template-based duck typing rather than requiring specific STL interfaces, as evidenced by the generic implementations in gmock-matchers.h.

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