Matchers Reference

A matcher matches a single argument. You can use it inside ON_CALL() or EXPECT_CALL(), or use it to validate a value directly using two macros:

WARNING: Equality matching via EXPECT_THAT(actual_value, expected_value) is supported, however note that implicit conversions can cause surprising results. For example, EXPECT_THAT(some_bool, "some string") will compile and may pass unintentionally.

BEST PRACTICE: Prefer to make the comparison explicit via EXPECT_THAT(actual_value, Eq(expected_value)) or EXPECT_EQ(actual_value, expected_value).

Built-in matchers (where argument is the function argument, e.g. actual_value in the example above, or when used in the context of EXPECT_CALL(mock_object, method(matchers)), the arguments of method) are divided into several categories. All matchers are defined in the ::testing namespace unless otherwise noted.

Wildcard

Generic Comparison

Except Ref(), these matchers make a copy of value in case it’s modified or destructed later. If the compiler complains that value doesn’t have a public copy constructor, try wrap it in std::ref(), e.g. Eq(std::ref(non_copyable_value)). If you do that, make sure non_copyable_value is not changed afterwards, or the meaning of your matcher will be changed.

IsTrue and IsFalse are useful when you need to use a matcher, or for types that can be explicitly converted to Boolean, but are not implicitly converted to Boolean. In other cases, you can use the basic EXPECT_TRUE and EXPECT_FALSE assertions.

Floating-Point Matchers

The above matchers use ULP-based comparison (the same as used in googletest). They automatically pick a reasonable error bound based on the absolute value of the expected value. DoubleEq() and FloatEq() conform to the IEEE standard, which requires comparing two NaNs for equality to return false. The NanSensitive* version instead treats two NaNs as equal, which is often what a user wants.

String Matchers

The argument can be either a C string or a C++ string object:

ContainsRegex() and MatchesRegex() take ownership of the RE object. They use the regular expression syntax defined here. All of these matchers, except ContainsRegex() and MatchesRegex() work for wide strings as well.

Container Matchers

Most STL-style containers support ==, so you can use Eq(expected_container) or simply expected_container to match a container exactly. If you want to write the elements in-line, match them more flexibly, or get more informative messages, you can use:

Notes:

• These matchers can also match:
  1. a native array passed by reference (e.g. in Foo(const int (&a)[5])), and
  2. an array passed as a pointer and a count (e.g. in Bar(const T* buffer, int len) – see Multi-argument Matchers).
• The array being matched may be multi-dimensional (i.e. its elements can be arrays).

• m in Pointwise(m, ...) and UnorderedPointwise(m, ...) should be a matcher for ::std::tuple<T, U> where T and U are the element type of the actual container and the expected container, respectively. For example, to compare two Foo containers where Foo doesn’t support operator==, one might write:

  MATCHER(FooEq, "") {
    return std::get<0>(arg).Equals(std::get<1>(arg));
  }
  ...
  EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos));

Member Matchers

Notes:

• You can use FieldsAre() to match any type that supports structured bindings, such as std::tuple, std::pair, std::array, and aggregate types. For example:

  std::tuple<int, std::string> my_tuple{7, "hello world"};
  EXPECT_THAT(my_tuple, FieldsAre(Ge(0), HasSubstr("hello")));
  struct MyStruct {
    int value = 42;
    std::string greeting = "aloha";
  };
  MyStruct s;
  EXPECT_THAT(s, FieldsAre(42, "aloha"));

• Don’t use Property() against member functions that you do not own, because taking addresses of functions is fragile and generally not part of the contract of the function.

Matching the Result of a Function, Functor, or Callback

Pointer Matchers

Multi-argument Matchers

Technically, all matchers match a single value. A “multi-argument” matcher is just one that matches a tuple. The following matchers can be used to match a tuple (x, y):

You can use the following selectors to pick a subset of the arguments (or reorder them) to participate in the matching:

Composite Matchers

You can make a matcher from one or more other matchers:

Adapters for Matchers

AddressSatisfies(callback) and Truly(callback) take ownership of callback, which must be a permanent callback.

Using Matchers as Predicates

Defining Matchers

Notes:

1. The MATCHER* macros cannot be used inside a function or class.
2. The matcher body must be purely functional (i.e. it cannot have any side effect, and the result must not depend on anything other than the value being matched and the matcher parameters).
3. You can use PrintToString(x) to convert a value x of any type to a string.

4. You can use ExplainMatchResult() in a custom matcher to wrap another matcher, for example:

   MATCHER_P(NestedPropertyMatches, matcher, "") {
     return ExplainMatchResult(matcher, arg.nested().property(), result_listener);
   }