Merge pull request #3189 from ellert:gtest-help-test-GNU/kFreeBSD
PiperOrigin-RevId: 349349288
This commit is contained in:
Derek Mauro
148
googlemock/g3doc/includes/g3_proto_matchers.md
Normal file
148
googlemock/g3doc/includes/g3_proto_matchers.md
Normal file
@@ -0,0 +1,148 @@
|
||||
### Protocol Buffer Matchers {#ProtoMatchers}
|
||||
|
||||
(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.
|
||||
|
||||
<a name="table15"></a>
|
||||
<table border="1" cellspacing="0" cellpadding="1">
|
||||
<tr>
|
||||
<td> `EqualsInitializedProto(proto)` </td>
|
||||
<td> `argument` is fully-initialized and equal to `proto`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `EqualsProto(proto)` </td>
|
||||
<td> `argument` is equal to `proto`. Can also be used as a multi-argument matcher; see below. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `EquivToInitializedProto(proto)` </td>
|
||||
<td> `argument` is fully-initialized and equivalent to `proto`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `EquivToProto(proto)` </td>
|
||||
<td> `argument` is equivalent to `proto`. Can also be used as a multi-argument matcher; see below. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `IsInitializedProto()` </td>
|
||||
<td> `argument` is a fully-initialized protocol buffer. </td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
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:
|
||||
|
||||
<a name="table16"></a>
|
||||
<table border="1" cellspacing="0" cellpadding="1">
|
||||
<tr>
|
||||
<td> `Approximately(proto_matcher)` </td>
|
||||
<td> The same as `proto_matcher` except that it compares floating-point fields approximately. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `Approximately(proto_matcher, margin)` </td>
|
||||
<td> The same as `Approximately(proto_matcher)` except that two floating-point fields are considered equal if their absolute difference is <= `margin`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `Approximately(proto_matcher, margin, fraction)` </td>
|
||||
<td> 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`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `TreatingNaNsAsEqual(proto_matcher)` </td>
|
||||
<td> The same as `proto_matcher` except that two floating-point fields are considered equal if both are NaN, matching the behavior of `NanSensitiveDoubleEq()`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `IgnoringRepeatedFieldOrdering(proto_matcher)` </td>
|
||||
<td> The same as `proto_matcher` except that it ignores ordering of elements within repeated fields (see `proto2::MessageDifferencer::TreatAsSet()` for more details). </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `IgnoringFieldPaths({"some_field.subfield"}, proto_matcher)` </td>
|
||||
<td> The same as `proto_matcher` except that it ignores the value of field `subfield` in field `some_field`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `Partially(proto_matcher)` </td>
|
||||
<td> The same as `proto_matcher` except that only fields present in the expected protocol buffer are considered. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `WhenDeserialized(typed_proto_matcher)` </td>
|
||||
<td> `argument` is a string in the protocol buffer binary format that can be deserialized to a protocol buffer matching `typed_proto_matcher`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `WhenDeserializedAs<PB>(matcher)` </td>
|
||||
<td> `argument` is a string in the protocol buffer binary format that can be deserialized to a protocol buffer of type `PB` that matches `matcher`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `WhenParsedFromProtoText(typed_proto_matcher)` </td>
|
||||
<td> `argument` is a string in the protocol buffer text format that can be parsed to a protocol buffer matching `typed_proto_matcher`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `WhenParsedFromProtoTextAs<PB>(matcher)` </td>
|
||||
<td> `argument` is a string in the protocol buffer text format that can be parsed to a protocol buffer of type `PB` that matches `matcher`. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `WhenUnpacked(typed_proto_matcher)` </td>
|
||||
<td> `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. </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `WhenUnpackedTo<PB>(matcher)` </td>
|
||||
<td> `argument` is a `google.protobuf.Any` that can be unpacked into a protocol buffer of type `PB` that matches `matcher`. </td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
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.
|
||||
|
||||
```cpp
|
||||
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.
|
||||
|
||||
```cpp
|
||||
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>"}));
|
||||
```
|
||||
|
||||
<a name="table17"></a>
|
||||
<table border="1" cellspacing="0" cellpadding="1">
|
||||
<tr>
|
||||
<td> `EqualsProto()` </td>
|
||||
<td> `x.Equals(y)` </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> `EquivToProto()` </td>
|
||||
<td> `x.Equivalent(y)` </td>
|
||||
</tr>
|
||||
</table>
|
||||
Reference in New Issue
Block a user