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

> Discover common GoogleTest container matchers like ElementsAre and UnorderedElementsAre. Validate STL containers efficiently without manual iteration. Learn more now.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: deep-dive
- Published: 2026-08-30

---

**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`](https://github.com/google/googletest/blob/main/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`](https://github.com/google/googletest/blob/main/gmock-matchers.h) at line 3653](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock-matchers.h#L3653).

```cpp
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](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock-matchers.h#L4606), it creates a copy of the matcher sequence before performing the match, ensuring stability during comparison.

```cpp
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](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock-matchers.h#L4150) handles the permutation logic internally.

```cpp
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](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock-matchers.h#L4205), this matcher is useful when the expected values are stored in a separate container.

```cpp
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](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock-matchers.h#L5326).

```cpp
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](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock-matchers.h#L5366).

```cpp
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](https://github.com/google/googletest/blob/main/googlemock/include/gmock/gmock-matchers.h#L4251), this is internally built on `UnorderedElementsAreArray`.

```cpp
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:

```cpp
#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`](https://github.com/google/googletest/blob/main/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`](https://github.com/google/googletest/blob/main/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`](https://github.com/google/googletest/blob/main/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`](https://github.com/google/googletest/blob/main/gmock-matchers.h).