Matcher

Google Mock - a framework for writing C++ mock classes. The MATCHER* family of macros can be used in a namespace scope to define custom matchers easily.

The syntax

MATCHER(name, description_string) { statements; }

defines a matcher with the given name that executes the statements, which must return a bool to indicate if the match succeeds. Inside the statements, you can refer to the value being matched by 'arg', and refer to its type by 'arg_type'.

The description string documents what the matcher does, and is used to generate the failure message when the match fails. Since a MATCHER() is usually defined in a header file shared by multiple C++ source files, we require the description to be a C-string literal to avoid possible side effects. It can be empty, in which case we'll use the sequence of words in the matcher name as the description.

For example:

  MATCHER(IsEven, "") { return (arg % 2) == 0; }

allows you to write

  // Expects mock_foo.Bar(n) to be called where n is even.
  EXPECT_CALL(mock_foo, Bar(IsEven()));

or,

  // Verifies that the value of some_expression is even.
  EXPECT_THAT(some_expression, IsEven());

If the above assertion fails, it will print something like:

Value of: some_expression Expected: is even Actual: 7

where the description "is even" is automatically calculated from the matcher name IsEven.