Class ProtoSubject

java.lang.Object
com.google.common.truth.Subject
com.google.common.truth.extensions.proto.LiteProtoSubject
com.google.common.truth.extensions.proto.ProtoSubject
public class ProtoSubject extends LiteProtoSubject
Truth subject for the full version of Protocol Buffers.

ProtoTruth.assertThat(actual).isEqualTo(expected) performs the same assertion as Truth.assertThat(actual).isEqualTo(expected), but with a better failure message. By default, the assertions are strict with respect to repeated field order, missing fields, etc. This behavior can be changed with the configuration methods on this subject, e.g. ProtoTruth.assertThat(actual).ignoringRepeatedFieldOrder().isEqualTo(expected).

By default, floating-point fields are compared using exact equality, which is probably not what you want if the values are the results of some arithmetic. To check for approximate equality, use usingDoubleTolerance(double), usingFloatTolerance(float), and their per-field equivalents.

Equality tests, and other methods, may yield slightly different behavior for versions 2 and 3 of Protocol Buffers. If testing protos of multiple versions, make sure you understand the behaviors of default and unknown fields so you don't under or over test.

  • Constructor Details

  • Method Details

    • ignoringFieldAbsence

      public ProtoFluentAssertion ignoringFieldAbsence()
      Specifies that the 'has' bit of individual fields should be ignored when comparing for equality.

      For version 2 Protocol Buffers, this setting determines whether two protos with the same value for a field compare equal if one explicitly sets the value, and the other merely implicitly uses the schema-defined default. This setting also determines whether unknown fields should be considered in the comparison. By ignoringFieldAbsence(), unknown fields are ignored, and value-equal fields as specified above are considered equal.

      For version 3 Protocol Buffers, this setting does not affect primitive fields, because their default value is indistinguishable from unset.

    • ignoringFieldAbsenceOfFields

      public ProtoFluentAssertion ignoringFieldAbsenceOfFields(int firstFieldNumber, int... rest)
      Specifies that the 'has' bit of these explicitly specified top-level field numbers should be ignored when comparing for equality. Sub-fields must be specified explicitly (via Descriptors.FieldDescriptor) if they are to be ignored as well.

      Use ignoringFieldAbsence() instead to ignore the 'has' bit for all fields.

      See Also:

    • ignoringFieldAbsenceOfFields

      public ProtoFluentAssertion ignoringFieldAbsenceOfFields(Iterable<Integer> fieldNumbers)
      Specifies that the 'has' bit of these explicitly specified top-level field numbers should be ignored when comparing for equality. Sub-fields must be specified explicitly (via Descriptors.FieldDescriptor) if they are to be ignored as well.

      Use ignoringFieldAbsence() instead to ignore the 'has' bit for all fields.

      See Also:

    • ignoringFieldAbsenceOfFieldDescriptors

      public ProtoFluentAssertion ignoringFieldAbsenceOfFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest)
      Specifies that the 'has' bit of these explicitly specified field descriptors should be ignored when comparing for equality. Sub-fields must be specified explicitly if they are to be ignored as well.

      Use ignoringFieldAbsence() instead to ignore the 'has' bit for all fields.

      See Also:

    • ignoringFieldAbsenceOfFieldDescriptors

      public ProtoFluentAssertion ignoringFieldAbsenceOfFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
      Specifies that the 'has' bit of these explicitly specified field descriptors should be ignored when comparing for equality. Sub-fields must be specified explicitly if they are to be ignored as well.

      Use ignoringFieldAbsence() instead to ignore the 'has' bit for all fields.

      See Also:

    • ignoringRepeatedFieldOrder

      public ProtoFluentAssertion ignoringRepeatedFieldOrder()
      Specifies that the ordering of repeated fields, at all levels, should be ignored when comparing for equality.

      This setting applies to all repeated fields recursively, but it does not ignore structure. For example, with ignoringRepeatedFieldOrder(), a repeated int32 field bar, set inside a repeated message field foo, the following protos will all compare equal: 

      
 message1: {
   foo: {
     bar: 1
     bar: 2
   }
   foo: {
     bar: 3
     bar: 4
   }
 }

 message2: {
   foo: {
     bar: 2
     bar: 1
   }
   foo: {
     bar: 4
     bar: 3
   }
 }

 message3: {
   foo: {
     bar: 4
     bar: 3
   }
   foo: {
     bar: 2
     bar: 1
   }
 }

      However, the following message will compare equal to none of these: 

      
 message4: {
   foo: {
     bar: 1
     bar: 3
   }
   foo: {
     bar: 2
     bar: 4
   }
 }

      This setting does not apply to map fields, for which field order is always ignored. The serialization order of map fields is undefined, and it may change from runtime to runtime.

    • ignoringRepeatedFieldOrderOfFields

      public ProtoFluentAssertion ignoringRepeatedFieldOrderOfFields(int firstFieldNumber, int... rest)
      Specifies that the ordering of repeated fields for these explicitly specified top-level field numbers should be ignored when comparing for equality. Sub-fields must be specified explicitly (via Descriptors.FieldDescriptor) if their orders are to be ignored as well.

      Use ignoringRepeatedFieldOrder() instead to ignore order for all fields.

      See Also:

    • ignoringRepeatedFieldOrderOfFields

      public ProtoFluentAssertion ignoringRepeatedFieldOrderOfFields(Iterable<Integer> fieldNumbers)
      Specifies that the ordering of repeated fields for these explicitly specified top-level field numbers should be ignored when comparing for equality. Sub-fields must be specified explicitly (via Descriptors.FieldDescriptor) if their orders are to be ignored as well.

      Use ignoringRepeatedFieldOrder() instead to ignore order for all fields.

      See Also:

    • ignoringRepeatedFieldOrderOfFieldDescriptors

      public ProtoFluentAssertion ignoringRepeatedFieldOrderOfFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest)
      Specifies that the ordering of repeated fields for these explicitly specified field descriptors should be ignored when comparing for equality. Sub-fields must be specified explicitly if their orders are to be ignored as well.

      Use ignoringRepeatedFieldOrder() instead to ignore order for all fields.

      See Also:

    • ignoringRepeatedFieldOrderOfFieldDescriptors

      public ProtoFluentAssertion ignoringRepeatedFieldOrderOfFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
      Specifies that the ordering of repeated fields for these explicitly specified field descriptors should be ignored when comparing for equality. Sub-fields must be specified explicitly if their orders are to be ignored as well.

      Use ignoringRepeatedFieldOrder() instead to ignore order for all fields.

      See Also:

    • ignoringExtraRepeatedFieldElements

      public ProtoFluentAssertion ignoringExtraRepeatedFieldElements()
      Specifies that, for all repeated and map fields, any elements in the 'actual' proto which are not found in the 'expected' proto are ignored, with the exception of fields in the expected proto which are empty. To ignore empty repeated fields as well, use comparingExpectedFieldsOnly().

      This rule is applied independently from ignoringRepeatedFieldOrder(). If ignoring repeated field order AND extra repeated field elements, all that is tested is that the expected elements comprise a subset of the actual elements. If not ignoring repeated field order, but still ignoring extra repeated field elements, the actual elements must contain a subsequence that matches the expected elements for the test to pass. (The subsequence rule does not apply to Map fields, which are always compared by key.)

    • ignoringExtraRepeatedFieldElementsOfFields

      public ProtoFluentAssertion ignoringExtraRepeatedFieldElementsOfFields(int firstFieldNumber, int... rest)
      Specifies that extra repeated field elements for these explicitly specified top-level field numbers should be ignored. Sub-fields must be specified explicitly (via Descriptors.FieldDescriptor) if their extra elements are to be ignored as well.

      Use ignoringExtraRepeatedFieldElements() instead to ignore these for all fields.

      See Also:

    • ignoringExtraRepeatedFieldElementsOfFields

      public ProtoFluentAssertion ignoringExtraRepeatedFieldElementsOfFields(Iterable<Integer> fieldNumbers)
      Specifies that extra repeated field elements for these explicitly specified top-level field numbers should be ignored. Sub-fields must be specified explicitly (via Descriptors.FieldDescriptor) if their extra elements are to be ignored as well.

      Use ignoringExtraRepeatedFieldElements() instead to ignore these for all fields.

      See Also:

    • ignoringExtraRepeatedFieldElementsOfFieldDescriptors

      public ProtoFluentAssertion ignoringExtraRepeatedFieldElementsOfFieldDescriptors(Descriptors.FieldDescriptor first, Descriptors.FieldDescriptor... rest)
      Specifies that extra repeated field elements for these explicitly specified field descriptors should be ignored. Sub-fields must be specified explicitly if their extra elements are to be ignored as well.

      Use ignoringExtraRepeatedFieldElements() instead to ignore these for all fields.

      See Also:

    • ignoringExtraRepeatedFieldElementsOfFieldDescriptors

      public ProtoFluentAssertion ignoringExtraRepeatedFieldElementsOfFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
      Specifies that extra repeated field elements for these explicitly specified field descriptors should be ignored. Sub-fields must be specified explicitly if their extra elements are to be ignored as well.

      Use ignoringExtraRepeatedFieldElements() instead to ignore these for all fields.

      See Also:

    • usingDoubleTolerance

      public ProtoFluentAssertion usingDoubleTolerance(double tolerance)
      Compares double fields as equal if they are both finite and their absolute difference is less than or equal to tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingDoubleToleranceForFields

      public ProtoFluentAssertion usingDoubleToleranceForFields(double tolerance, int firstFieldNumber, int... rest)
      Compares double fields with these explicitly specified top-level field numbers using the provided absolute tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingDoubleToleranceForFields

      public ProtoFluentAssertion usingDoubleToleranceForFields(double tolerance, Iterable<Integer> fieldNumbers)
      Compares double fields with these explicitly specified top-level field numbers using the provided absolute tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingDoubleToleranceForFieldDescriptors

      public ProtoFluentAssertion usingDoubleToleranceForFieldDescriptors(double tolerance, Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest)
      Compares double fields with these explicitly specified fields using the provided absolute tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingDoubleToleranceForFieldDescriptors

      public ProtoFluentAssertion usingDoubleToleranceForFieldDescriptors(double tolerance, Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
      Compares double fields with these explicitly specified fields using the provided absolute tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingFloatTolerance

      public ProtoFluentAssertion usingFloatTolerance(float tolerance)
      Compares float fields as equal if they are both finite and their absolute difference is less than or equal to tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingFloatToleranceForFields

      public ProtoFluentAssertion usingFloatToleranceForFields(float tolerance, int firstFieldNumber, int... rest)
      Compares float fields with these explicitly specified top-level field numbers using the provided absolute tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingFloatToleranceForFields

      public ProtoFluentAssertion usingFloatToleranceForFields(float tolerance, Iterable<Integer> fieldNumbers)
      Compares float fields with these explicitly specified top-level field numbers using the provided absolute tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingFloatToleranceForFieldDescriptors

      public ProtoFluentAssertion usingFloatToleranceForFieldDescriptors(float tolerance, Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest)
      Compares float fields with these explicitly specified fields using the provided absolute tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • usingFloatToleranceForFieldDescriptors

      public ProtoFluentAssertion usingFloatToleranceForFieldDescriptors(float tolerance, Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
      Compares float fields with these explicitly specified top-level field numbers using the provided absolute tolerance.
      Parameters:
      tolerance - A finite, non-negative tolerance.

    • comparingExpectedFieldsOnly

      public ProtoFluentAssertion comparingExpectedFieldsOnly()
      Limits the comparison of Protocol buffers to the fields set in the expected proto(s). When multiple protos are specified, the comparison is limited to the union of set fields in all the expected protos.

      The "expected proto(s)" are those passed to the void method at the end of the ProtoFluentAssertion call-chain: For example, isEqualTo(Message), or isNotEqualTo(Message).

      Fields not set in the expected proto(s) are ignored. In particular, proto3 fields which have their default values are ignored, as these are indistinguishable from unset fields. If you want to assert that a proto3 message has certain fields with default values, you cannot use this method.

    • withPartialScope

      public ProtoFluentAssertion withPartialScope(FieldScope fieldScope)
      Limits the comparison of Protocol buffers to the defined FieldScope.

      This method is additive and has well-defined ordering semantics. If the invoking ProtoFluentAssertion is already scoped to a FieldScope X, and this method is invoked with FieldScope Y, the resultant ProtoFluentAssertion is constrained to the intersection of FieldScopes X and Y.

      By default, ProtoFluentAssertion is constrained to FieldScopes.all(), that is, no fields are excluded from comparison.

    • ignoringFields

      public ProtoFluentAssertion ignoringFields(int firstFieldNumber, int... rest)
      Excludes the top-level message fields with the given tag numbers from the comparison.

      This method adds on any previous FieldScope related settings, overriding previous changes to ensure the specified fields are ignored recursively. All sub-fields of these field numbers are ignored, and all sub-messages of type M will also have these field numbers ignored.

      If an invalid field number is supplied, the terminal comparison operation will throw a runtime exception.

    • ignoringFields

      public ProtoFluentAssertion ignoringFields(Iterable<Integer> fieldNumbers)
      Excludes the top-level message fields with the given tag numbers from the comparison.

      This method adds on any previous FieldScope related settings, overriding previous changes to ensure the specified fields are ignored recursively. All sub-fields of these field numbers are ignored, and all sub-messages of type M will also have these field numbers ignored.

      If an invalid field number is supplied, the terminal comparison operation will throw a runtime exception.

    • ignoringFieldDescriptors

      public ProtoFluentAssertion ignoringFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest)
      Excludes all message fields matching the given Descriptors.FieldDescriptors from the comparison.

      This method adds on any previous FieldScope related settings, overriding previous changes to ensure the specified fields are ignored recursively. All sub-fields of these field descriptors are ignored, no matter where they occur in the tree.

      If a field descriptor which does not, or cannot occur in the proto structure is supplied, it is silently ignored.

    • ignoringFieldDescriptors

      public ProtoFluentAssertion ignoringFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
      Excludes all message fields matching the given Descriptors.FieldDescriptors from the comparison.

      This method adds on any previous FieldScope related settings, overriding previous changes to ensure the specified fields are ignored recursively. All sub-fields of these field descriptors are ignored, no matter where they occur in the tree.

      If a field descriptor which does not, or cannot occur in the proto structure is supplied, it is silently ignored.

    • ignoringFieldScope

      public ProtoFluentAssertion ignoringFieldScope(FieldScope fieldScope)
      Excludes all specific field paths under the argument FieldScope from the comparison.

      This method is additive and has well-defined ordering semantics. If the invoking ProtoFluentAssertion is already scoped to a FieldScope X, and this method is invoked with FieldScope Y, the resultant ProtoFluentAssertion is constrained to the subtraction of X - Y.

      By default, ProtoFluentAssertion is constrained to FieldScopes.all(), that is, no fields are excluded from comparison.

    • reportingMismatchesOnly

      public ProtoFluentAssertion reportingMismatchesOnly()
      If set, in the event of a comparison failure, the error message printed will list only those specific fields that did not match between the actual and expected values. Useful for very large protocol buffers.

      This a purely cosmetic setting, and it has no effect on the behavior of the test.

    • unpackingAnyUsing

      public ProtoFluentAssertion unpackingAnyUsing(TypeRegistry typeRegistry, ExtensionRegistry extensionRegistry)
      Specifies the TypeRegistry and ExtensionRegistry to use for Any messages.

      To compare the value of an Any message, ProtoTruth looks in the given type registry for a descriptor for the message's type URL:

      • If ProtoTruth finds a descriptor, it unpacks the value and compares it against the expected value, respecting any configuration methods used for the assertion.
      • If ProtoTruth does not find a descriptor (or if the value can't be deserialized with the descriptor), it compares the raw, serialized bytes of the expected and actual values.

      When ProtoTruth unpacks a value, it is parsing a serialized proto. That proto may contain extensions. To look up those extensions, ProtoTruth uses the provided ExtensionRegistry.

      Since:
      1.1

    • isEqualTo

      public void isEqualTo(@Nullable Object expected)
      Description copied from class: LiteProtoSubject
      Checks whether the MessageLite is equivalent to the argument, using the standard equals() implementation.
      Overrides:
      isEqualTo in class LiteProtoSubject

    • isNotEqualTo

      public void isNotEqualTo(@Nullable Object expected)
      Description copied from class: Subject
      Checks that the value under test is not equal to the given object. The meaning of equality is the same as for the Subject.isEqualTo(java.lang.Object) method.
      Overrides:
      isNotEqualTo in class LiteProtoSubject

    • hasAllRequiredFields

      public void hasAllRequiredFields()
      Description copied from class: LiteProtoSubject
      Checks whether the subject has all required fields set. Cannot fail for a proto built with build(), which itself fails if required fields aren't set.
      Overrides:
      hasAllRequiredFields in class LiteProtoSubject