com.google.common.truth.extensions.proto

Class MapWithProtoValuesSubject<S extends MapWithProtoValuesSubject<S,K,M,C>,K,M extends com.google.protobuf.Message,C extends Map<K,M>>

java.lang.Object

com.google.common.truth.Subject<S,C>

com.google.common.truth.extensions.proto.MapWithProtoValuesSubject<S,K,M,C>

Direct Known Subclasses:

MapWithProtoValuesSubject.MapWithMessageValuesSubject

public class MapWithProtoValuesSubject<S extends MapWithProtoValuesSubject<S,K,M,C>,K,M extends com.google.protobuf.Message,C extends Map<K,M>>
extends Subject<S,C>

Truth subject for maps with protocol buffers for values.

ProtoTruth.assertThat(actual).containsExactlyEntriesIn(expected) performs the same assertion as Truth.assertThat(actual).containsExactlyEntriesIn(expected). 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().containsExactly(expected).

Floating-point fields are compared using exact equality, which is probably not what you want if the values are the results of some arithmetic. Support for approximate equality may be added in a later version.

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MapWithProtoValuesSubject.MapWithMessageValuesSubject<K,M extends com.google.protobuf.Message> Default implementation of MapWithProtoValuesSubject.

Nested classes/interfaces inherited from class com.google.common.truth.Subject

Subject.Factory<SubjectT extends Subject<SubjectT,ActualT>,ActualT>

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MapWithProtoValuesSubject(FailureMetadata failureMetadata, C map)

Method Summary

Modifier and Type	Method and Description
MapWithProtoValuesFluentAssertion<M>	comparingExpectedFieldsOnlyForValues() Limits the comparison of Protocol buffers to the fields set in the expected proto(s).
<A,E> MapSubject.UsingCorrespondence<A,E>	comparingValuesUsing(Correspondence<A,E> correspondence) Starts a method chain for a check in which the actual values (i.e.
void	containsEntry(Object key, Object value) Fails if the map does not contain the given entry.
Ordered	containsExactly() Fails if the map is not empty.
Ordered	containsExactly(Object k0, Object v0, Object... rest) Fails if the map does not contain exactly the given set of key/value pairs.
Ordered	containsExactlyEntriesIn(Map<?,?> expectedMap) Fails if the map does not contain exactly the given set of entries in the given map.
void	containsKey(Object key) Fails if the map does not contain the given key.
void	doesNotContainEntry(Object key, Object value) Fails if the map contains the given entry.
void	doesNotContainKey(Object key) Fails if the map contains the given key.
void	hasSize(int expectedSize) Fails if the map does not have the given size.
MapWithProtoValuesFluentAssertion<M>	ignoringExtraRepeatedFieldElementsForValues() 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.
MapWithProtoValuesFluentAssertion<M>	ignoringFieldAbsenceForValues() Specifies that the 'has' bit of individual fields should be ignored when comparing for equality.
MapWithProtoValuesFluentAssertion<M>	ignoringFieldDescriptorsForValues(com.google.protobuf.Descriptors.FieldDescriptor firstFieldDescriptor, com.google.protobuf.Descriptors.FieldDescriptor... rest) Excludes all message fields matching the given Descriptors.FieldDescriptors from the comparison.
MapWithProtoValuesFluentAssertion<M>	ignoringFieldDescriptorsForValues(Iterable<com.google.protobuf.Descriptors.FieldDescriptor> fieldDescriptors) Excludes all message fields matching the given Descriptors.FieldDescriptors from the comparison.
MapWithProtoValuesFluentAssertion<M>	ignoringFieldScopeForValues(FieldScope fieldScope) Excludes all specific field paths under the argument FieldScope from the comparison.
MapWithProtoValuesFluentAssertion<M>	ignoringFieldsForValues(int firstFieldNumber, int... rest) Excludes the top-level message fields with the given tag numbers from the comparison.
MapWithProtoValuesFluentAssertion<M>	ignoringFieldsForValues(Iterable<Integer> fieldNumbers) Excludes the top-level message fields with the given tag numbers from the comparison.
MapWithProtoValuesFluentAssertion<M>	ignoringRepeatedFieldOrderForValues() Specifies that the ordering of repeated fields, at all levels, should be ignored when comparing for equality.
void	isEmpty() Fails if the map is not empty.
void	isEqualTo(Object other) Fails if the subject is not equal to the given object.
void	isNotEmpty() Fails if the map is empty.
MapWithProtoValuesFluentAssertion<M>	reportingMismatchesOnlyForValues() 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.
MapWithProtoValuesFluentAssertion<M>	usingDoubleToleranceForValues(double tolerance) Compares double fields as equal if they are both finite and their absolute difference is less than or equal to tolerance.
MapWithProtoValuesFluentAssertion<M>	usingFloatToleranceForValues(float tolerance) Compares float fields as equal if they are both finite and their absolute difference is less than or equal to tolerance.
MapWithProtoValuesFluentAssertion<M>	withPartialScopeForValues(FieldScope fieldScope) Limits the comparison of Protocol buffers to the defined FieldScope.

Methods inherited from class com.google.common.truth.Subject

actual, actualAsString, actualCustomStringRepresentation, check, check, equals, fail, fail, fail, failComparing, failComparing, failWithActual, failWithActual, failWithBadResults, failWithCustomSubject, failWithoutActual, failWithoutActual, failWithoutSubject, failWithRawMessage, failWithRawMessageAndCause, getSubject, hashCode, ignoreCheck, internalCustomName, isAnyOf, isIn, isInstanceOf, isNoneOf, isNotEqualTo, isNotIn, isNotInstanceOf, isNotNull, isNotSameAs, isNull, isSameAs, named, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MapWithProtoValuesSubject

protected MapWithProtoValuesSubject(FailureMetadata failureMetadata,
                                    @NullableDecl
                                    C map)

Method Detail

isEqualTo

public void isEqualTo(@NullableDecl
                      Object other)

Fails if the subject is not equal to the given object.

Overrides:

isEqualTo in class Subject<S extends MapWithProtoValuesSubject<S,K,M,C>,C extends Map<K,M>>

isEmpty

public void isEmpty()

Fails if the map is not empty.

isNotEmpty

public void isNotEmpty()

Fails if the map is empty.

hasSize

public void hasSize(int expectedSize)

Fails if the map does not have the given size.

containsKey

public void containsKey(@NullableDecl
                        Object key)

Fails if the map does not contain the given key.

doesNotContainKey

public void doesNotContainKey(@NullableDecl
                              Object key)

Fails if the map contains the given key.

containsEntry

public void containsEntry(@NullableDecl
                          Object key,
                          @NullableDecl
                          Object value)

Fails if the map does not contain the given entry.

doesNotContainEntry

public void doesNotContainEntry(@NullableDecl
                                Object key,
                                @NullableDecl
                                Object value)

Fails if the map contains the given entry.

containsExactly

@CanIgnoreReturnValue
public Ordered containsExactly()

Fails if the map is not empty.

containsExactly

@CanIgnoreReturnValue
public Ordered containsExactly(@NullableDecl
                                                     Object k0,
                                                     @NullableDecl
                                                     Object v0,
                                                     Object... rest)

Fails if the map does not contain exactly the given set of key/value pairs.

Warning: the use of varargs means that we cannot guarantee an equal number of key/value pairs at compile time. Please make sure you provide varargs in key/value pairs!

containsExactlyEntriesIn

@CanIgnoreReturnValue
public Ordered containsExactlyEntriesIn(Map<?,?> expectedMap)

Fails if the map does not contain exactly the given set of entries in the given map.

comparingValuesUsing

public <A,E> MapSubject.UsingCorrespondence<A,E> comparingValuesUsing(Correspondence<A,E> correspondence)

Starts a method chain for a check in which the actual values (i.e. the values of the Map under test) are compared to expected values using the given Correspondence. The actual values must be of type A, the expected values must be of type E. The check is actually executed by continuing the method chain. For example:

 assertThat(actualMap)
   .comparingValuesUsing(correspondence)
   .containsEntry(expectedKey, expectedValue);
 

where actualMap is a Map<?, A> (or, more generally, a Map<?, ? extends A>), correspondence is a Correspondence<A, E>, and expectedValue is an E.

Note that keys will always be compared with regular object equality (Object.equals(java.lang.Object)).

Any of the methods on the returned object may throw ClassCastException if they encounter an actual value that is not of type A or an expected value that is not of type E.

Note that the MapWithProtoValuesSubject is designed to save you from having to write your own Correspondence. The configuration methods, such as ignoringRepeatedFieldOrderForValues() will construct a Correspondence under the hood which performs protobuf comparisons with ProtoSubject.ignoringRepeatedFieldOrder().

ignoringFieldAbsenceForValues

public MapWithProtoValuesFluentAssertion<M> ignoringFieldAbsenceForValues()

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 primitive 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 has no effect. Primitive fields set to their default value are indistinguishable from unset fields in proto 3. Proto 3 also eliminates unknown fields, so this setting has no effect there either.

ignoringRepeatedFieldOrderForValues

public MapWithProtoValuesFluentAssertion<M> ignoringRepeatedFieldOrderForValues()

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 ignoringRepeatedFieldOrderForValues(), 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.

ignoringExtraRepeatedFieldElementsForValues

public MapWithProtoValuesFluentAssertion<M> ignoringExtraRepeatedFieldElementsForValues()

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 comparingExpectedFieldsOnlyForValues().

This rule is applied independently from ignoringRepeatedFieldOrderForValues(). 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.)

usingDoubleToleranceForValues

public MapWithProtoValuesFluentAssertion<M> usingDoubleToleranceForValues(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.

usingFloatToleranceForValues

public MapWithProtoValuesFluentAssertion<M> usingFloatToleranceForValues(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.

comparingExpectedFieldsOnlyForValues

public MapWithProtoValuesFluentAssertion<M> comparingExpectedFieldsOnlyForValues()

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 method at the end of the call chain, such as containsEntry(java.lang.Object, java.lang.Object) or containsExactlyEntriesIn(java.util.Map<?, ?>).

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.

withPartialScopeForValues

public MapWithProtoValuesFluentAssertion<M> withPartialScopeForValues(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, MapWithProtoValuesFluentAssertion is constrained to FieldScopes.all(), that is, no fields are excluded from comparison.

ignoringFieldsForValues

public MapWithProtoValuesFluentAssertion<M> ignoringFieldsForValues(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.

ignoringFieldsForValues

public MapWithProtoValuesFluentAssertion<M> ignoringFieldsForValues(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.

ignoringFieldDescriptorsForValues

public MapWithProtoValuesFluentAssertion<M> ignoringFieldDescriptorsForValues(com.google.protobuf.Descriptors.FieldDescriptor firstFieldDescriptor,
                                                                              com.google.protobuf.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.

ignoringFieldDescriptorsForValues

public MapWithProtoValuesFluentAssertion<M> ignoringFieldDescriptorsForValues(Iterable<com.google.protobuf.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.

ignoringFieldScopeForValues

public MapWithProtoValuesFluentAssertion<M> ignoringFieldScopeForValues(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.

reportingMismatchesOnlyForValues

public MapWithProtoValuesFluentAssertion<M> reportingMismatchesOnlyForValues()

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.