googletest/googlemock/g3doc/includes/g3_proto_matchers.md

Protocol Buffer Matchers

(go/protomatchers)

In the following, argument can be either a protocol buffer (version 1 or version 2) or a pointer to it, and proto can be either a protocol buffer or a human-readable ASCII string representing it (e.g. "foo: 5"). If you need help writing the ASCII string, read go/textformat. "Fully-initialized" below means all required fields are set.

`EqualsInitializedProto(proto)`	`argument` is fully-initialized and equal to `proto`.
`EqualsProto(proto)`	`argument` is equal to `proto`. Can also be used as a multi-argument matcher; see below.
`EquivToInitializedProto(proto)`	`argument` is fully-initialized and equivalent to `proto`.
`EquivToProto(proto)`	`argument` is equivalent to `proto`. Can also be used as a multi-argument matcher; see below.
`IsInitializedProto()`	`argument` is a fully-initialized protocol buffer.

Both Equiv and Equal matchers checks that two protocol buffers have identical values, however only Equal matchers ensure that the protocol buffers fields were set the same way (explicitly or through their default value).

When these matchers are given a string parameter, they optionally accept the type of the protocol buffer as a template argument, e.g. EqualsProto<MyPB>("bar: 'xyz'").

The following protocol buffer matcher transformers in namespace ::testing::proto change the behavior of a matcher:

`Approximately(proto_matcher)`	The same as `proto_matcher` except that it compares floating-point fields approximately.
`Approximately(proto_matcher, margin)`	The same as `Approximately(proto_matcher)` except that two floating-point fields are considered equal if their absolute difference is <= `margin`.
`Approximately(proto_matcher, margin, fraction)`	The same as `Approximately(proto_matcher)` except that two floating-point fields are considered equal if their absolute difference is <= `margin` or their fractional difference is <= `fraction`.
`TreatingNaNsAsEqual(proto_matcher)`	The same as `proto_matcher` except that two floating-point fields are considered equal if both are NaN, matching the behavior of `NanSensitiveDoubleEq()`.
`IgnoringRepeatedFieldOrdering(proto_matcher)`	The same as `proto_matcher` except that it ignores ordering of elements within repeated fields (see `proto2::MessageDifferencer::TreatAsSet()` for more details).
`IgnoringFieldPaths({"some_field.subfield"}, proto_matcher)`	The same as `proto_matcher` except that it ignores the value of field `subfield` in field `some_field`.
`Partially(proto_matcher)`	The same as `proto_matcher` except that only fields present in the expected protocol buffer are considered.
`WhenDeserialized(typed_proto_matcher)`	`argument` is a string in the protocol buffer binary format that can be deserialized to a protocol buffer matching `typed_proto_matcher`.
`WhenDeserializedAs(matcher)`	`argument` is a string in the protocol buffer binary format that can be deserialized to a protocol buffer of type `PB` that matches `matcher`.
`WhenParsedFromProtoText(typed_proto_matcher)`	`argument` is a string in the protocol buffer text format that can be parsed to a protocol buffer matching `typed_proto_matcher`.
`WhenParsedFromProtoTextAs(matcher)`	`argument` is a string in the protocol buffer text format that can be parsed to a protocol buffer of type `PB` that matches `matcher`.
`WhenUnpacked(typed_proto_matcher)`	`argument` is a `google.protobuf.Any` that can be unpacked into a protocol buffer of the type of `typed_proto_matcher` that matches that matcher.
`WhenUnpackedTo(matcher)`	`argument` is a `google.protobuf.Any` that can be unpacked into a protocol buffer of type `PB` that matches `matcher`.

where:

• proto_matcher can be any of the Equals* and EquivTo* protocol buffer matchers above,
• typed_proto_matcher can be an Equals* or EquivTo* protocol buffer matcher where the type of the expected protocol buffer is known at run time (e.g. EqualsProto(expected_pb) or EqualsProto<MyPB>("bar: 'xyz'")).
• matcher can be any matcher that can be used to match a PB value, e.g. EqualsProto("bar: 'xyz'"), Not(EqualsProto(my_pb)).

Approximately(), Partially(), and TreatingNaNsAsEqual() can be combined, e.g. Partially(Approximately(EqualsProto(foo))).

Note that EqualsProto() and EquivToProto() can be used as multi-argument matchers that match a 2-tuple of protos. The following example shows how to compare two vectors of protos.

vector<MyProto> actual;
vector<MyProto> expected;
...  // Fill vectors with data
EXPECT_THAT(actual, Pointwise(EqualsProto(), expected));

Similarly, they can be used to compare a vector of protos against a vector of strings.

vector<MyProto> actual;
...  // Fill 'actual' with data
vector<string> expected {"foo:<bar:1>", "foo:<bar:2>"};
EXPECT_THAT(actual, Pointwise(EqualsProto(), expected));
// Or, concisely:
EXPECT_THAT(actual, Pointwise(EqualsProto(), {"foo:<bar:1>", "foo:<bar:2>"}));

`EqualsProto()`	`x.Equals(y)`
`EquivToProto()`	`x.Equivalent(y)`