com.google.common.truth.extensions.proto

Class IterableOfProtosSubject<S extends IterableOfProtosSubject<S,M,C>,M extends com.google.protobuf.Message,C extends Iterable<M>>

java.lang.Object

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

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

Direct Known Subclasses:

IterableOfProtosSubject.IterableOfMessagesSubject

public class IterableOfProtosSubject<S extends IterableOfProtosSubject<S,M,C>,M extends com.google.protobuf.Message,C extends Iterable<M>>
extends Subject<S,C>

Truth subject for the iterables of protocol buffers.

ProtoTruth.assertThat(actual).containsExactly(expected) performs the same assertion as Truth.assertThat(actual).containsExactly(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().containsExactlyEntriesIn(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	IterableOfProtosSubject.IterableOfMessagesSubject<M extends com.google.protobuf.Message> Default implementation of IterableOfProtosSubject.

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	IterableOfProtosSubject(FailureMetadata failureMetadata, C messages)

Method Summary

Modifier and Type	Method and Description
<A,E> IterableSubject.UsingCorrespondence<A,E>	comparingElementsUsing(Correspondence<A,E> correspondence) Starts a method chain for a check in which the actual elements (i.e.
IterableOfProtosFluentAssertion<M>	comparingExpectedFieldsOnly() Limits the comparison of Protocol buffers to the fields set in the expected proto(s).
void	contains(Object element) Checks (with a side-effect failure) that the subject contains the supplied item.
Ordered	containsAllIn(Iterable<?> expected) Checks that the actual iterable contains at least all of the expected elements or fails.
Ordered	containsAllIn(Object[] expected) Checks that the actual iterable contains at least all of the expected elements or fails.
Ordered	containsAllOf(Object firstExpected, Object secondExpected, Object... restOfExpected) Checks that the actual iterable contains at least all of the expected elements or fails.
void	containsAnyIn(Iterable<?> expected) Checks that the subject contains at least one of the objects contained in the provided collection or fails.
void	containsAnyIn(Object[] expected) Checks that the subject contains at least one of the objects contained in the provided array or fails.
void	containsAnyOf(Object first, Object second, Object... rest) Checks that the subject contains at least one of the provided objects or fails.
Ordered	containsExactly(Object... varargs) Checks that a subject contains exactly the provided objects or fails.
Ordered	containsExactlyElementsIn(Iterable<?> expected) Checks that a subject contains exactly the provided objects or fails.
Ordered	containsExactlyElementsIn(Object[] expected) Checks that a subject contains exactly the provided objects or fails.
void	containsNoDuplicates() Checks that the subject does not contain duplicate elements.
void	containsNoneIn(Iterable<?> excluded) Checks that a actual iterable contains none of the elements contained in the excluded iterable or fails.
void	containsNoneIn(Object[] excluded) Checks that a actual iterable contains none of the elements contained in the excluded iterable or fails.
void	containsNoneOf(Object firstExcluded, Object secondExcluded, Object... restOfExcluded) Checks that a actual iterable contains none of the excluded objects or fails.
IterableOfProtosUsingCorrespondence<M>	displayingDiffsPairedBy(Function<? super M,?> keyFunction) Specifies a way to pair up unexpected and missing elements in the message when an assertion fails.
void	doesNotContain(Object element) Checks (with a side-effect failure) that the subject does not contain the supplied item.
void	hasSize(int expectedSize) Fails if the subject does not have the given size.
IterableOfProtosFluentAssertion<M>	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.
IterableOfProtosFluentAssertion<M>	ignoringFieldAbsence() Specifies that the 'has' bit of individual fields should be ignored when comparing for equality.
IterableOfProtosFluentAssertion<M>	ignoringFieldDescriptors(com.google.protobuf.Descriptors.FieldDescriptor firstFieldDescriptor, com.google.protobuf.Descriptors.FieldDescriptor... rest) Excludes all message fields matching the given Descriptors.FieldDescriptors from the comparison.
IterableOfProtosFluentAssertion<M>	ignoringFieldDescriptors(Iterable<com.google.protobuf.Descriptors.FieldDescriptor> fieldDescriptors) Excludes all message fields matching the given Descriptors.FieldDescriptors from the comparison.
IterableOfProtosFluentAssertion<M>	ignoringFields(int firstFieldNumber, int... rest) Excludes the top-level message fields with the given tag numbers from the comparison.
IterableOfProtosFluentAssertion<M>	ignoringFields(Iterable<Integer> fieldNumbers) Excludes the top-level message fields with the given tag numbers from the comparison.
IterableOfProtosFluentAssertion<M>	ignoringFieldScope(FieldScope fieldScope) Excludes all specific field paths under the argument FieldScope from the comparison.
IterableOfProtosFluentAssertion<M>	ignoringRepeatedFieldOrder() Specifies that the ordering of repeated fields, at all levels, should be ignored when comparing for equality.
void	isEmpty() Fails if the subject is not empty.
void	isNotEmpty() Fails if the subject is empty.
void	isOrdered(Comparator<?> comparator) Fails if the iterable is not ordered, according to the given comparator.
void	isStrictlyOrdered(Comparator<?> comparator) Fails if the iterable is not strictly ordered, according to the given comparator.
IterableOfProtosFluentAssertion<M>	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.
IterableOfProtosFluentAssertion<M>	usingDoubleTolerance(double tolerance) Compares double fields as equal if they are both finite and their absolute difference is less than or equal to tolerance.
IterableOfProtosFluentAssertion<M>	usingFloatTolerance(float tolerance) Compares float fields as equal if they are both finite and their absolute difference is less than or equal to tolerance.
IterableOfProtosFluentAssertion<M>	withPartialScope(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, isEqualTo, 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

IterableOfProtosSubject

protected IterableOfProtosSubject(FailureMetadata failureMetadata,
                                  @NullableDecl
                                  C messages)

Method Detail

isEmpty

public void isEmpty()

Fails if the subject is not empty.

isNotEmpty

public void isNotEmpty()

Fails if the subject is empty.

hasSize

public void hasSize(int expectedSize)

Fails if the subject does not have the given size.

contains

public void contains(@NullableDecl
                     Object element)

Checks (with a side-effect failure) that the subject contains the supplied item.

doesNotContain

public void doesNotContain(@NullableDecl
                           Object element)

Checks (with a side-effect failure) that the subject does not contain the supplied item.

containsNoDuplicates

public void containsNoDuplicates()

Checks that the subject does not contain duplicate elements.

containsAnyOf

public void containsAnyOf(@NullableDecl
                          Object first,
                          @NullableDecl
                          Object second,
                          @NullableDecl
                          Object... rest)

Checks that the subject contains at least one of the provided objects or fails.

containsAnyIn

public void containsAnyIn(Iterable<?> expected)

Checks that the subject contains at least one of the objects contained in the provided collection or fails.

containsAnyIn

public void containsAnyIn(Object[] expected)

Checks that the subject contains at least one of the objects contained in the provided array or fails.

containsAllOf

@CanIgnoreReturnValue
public Ordered containsAllOf(@NullableDecl
                                                   Object firstExpected,
                                                   @NullableDecl
                                                   Object secondExpected,
                                                   @NullableDecl
                                                   Object... restOfExpected)

Checks that the actual iterable contains at least all of the expected elements or fails. If an element appears more than once in the expected elements to this call then it must appear at least that number of times in the actual elements.

To also test that the contents appear in the given order, make a call to inOrder() on the object returned by this method. The expected elements must appear in the given order within the actual elements, but they are not required to be consecutive.

containsAllIn

@CanIgnoreReturnValue
public Ordered containsAllIn(Iterable<?> expected)

Checks that the actual iterable contains at least all of the expected elements or fails. If an element appears more than once in the expected elements then it must appear at least that number of times in the actual elements.

To also test that the contents appear in the given order, make a call to inOrder() on the object returned by this method. The expected elements must appear in the given order within the actual elements, but they are not required to be consecutive.

containsAllIn

@CanIgnoreReturnValue
public Ordered containsAllIn(Object[] expected)

Checks that the actual iterable contains at least all of the expected elements or fails. If an element appears more than once in the expected elements then it must appear at least that number of times in the actual elements.

To also test that the contents appear in the given order, make a call to inOrder() on the object returned by this method. The expected elements must appear in the given order within the actual elements, but they are not required to be consecutive.

containsExactly

@CanIgnoreReturnValue
public Ordered containsExactly(@NullableDecl
                                                     Object... varargs)

Checks that a subject contains exactly the provided objects or fails.

Multiplicity is respected. For example, an object duplicated exactly 3 times in the parameters asserts that the object must likewise be duplicated exactly 3 times in the subject.

To also test that the contents appear in the given order, make a call to inOrder() on the object returned by this method.

To test that the iterable contains the same elements as an array, prefer containsExactlyElementsIn(Object[]). It makes clear that the given array is a list of elements, not an element itself. This helps human readers and avoids a compiler warning.

containsExactlyElementsIn

@CanIgnoreReturnValue
public Ordered containsExactlyElementsIn(Iterable<?> expected)

Checks that a subject contains exactly the provided objects or fails.

Multiplicity is respected. For example, an object duplicated exactly 3 times in the Iterable parameter asserts that the object must likewise be duplicated exactly 3 times in the subject.

To also test that the contents appear in the given order, make a call to inOrder() on the object returned by this method.

containsExactlyElementsIn

@CanIgnoreReturnValue
public Ordered containsExactlyElementsIn(Object[] expected)

Checks that a subject contains exactly the provided objects or fails.

Multiplicity is respected. For example, an object duplicated exactly 3 times in the Iterable parameter asserts that the object must likewise be duplicated exactly 3 times in the subject.

To also test that the contents appear in the given order, make a call to inOrder() on the object returned by this method.

containsNoneOf

public void containsNoneOf(@NullableDecl
                           Object firstExcluded,
                           @NullableDecl
                           Object secondExcluded,
                           @NullableDecl
                           Object... restOfExcluded)

Checks that a actual iterable contains none of the excluded objects or fails. (Duplicates are irrelevant to this test, which fails if any of the actual elements equal any of the excluded.)

containsNoneIn

public void containsNoneIn(Iterable<?> excluded)

Checks that a actual iterable contains none of the elements contained in the excluded iterable or fails. (Duplicates are irrelevant to this test, which fails if any of the actual elements equal any of the excluded.)

containsNoneIn

public void containsNoneIn(Object[] excluded)

Checks that a actual iterable contains none of the elements contained in the excluded iterable or fails. (Duplicates are irrelevant to this test, which fails if any of the actual elements equal any of the excluded.)

isStrictlyOrdered

public void isStrictlyOrdered(Comparator<?> comparator)

Fails if the iterable is not strictly ordered, according to the given comparator. Strictly ordered means that each element in the iterable is strictly greater than the element that preceded it.

Throws:

ClassCastException - if any pair of elements is not mutually Comparable

isOrdered

public void isOrdered(Comparator<?> comparator)

Fails if the iterable is not ordered, according to the given comparator. Ordered means that each element in the iterable is greater than or equal to the element that preceded it.

Throws:

ClassCastException - if any pair of elements is not mutually Comparable

comparingElementsUsing

public <A,E> IterableSubject.UsingCorrespondence<A,E> comparingElementsUsing(Correspondence<A,E> correspondence)

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

 assertThat(actualIterable).comparingElementsUsing(correspondence).contains(expected);
 

where actualIterable is an Iterable<A> (or, more generally, an Iterable<? extends A>), correspondence is a Correspondence<A, E>, and expected is an E.

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

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

displayingDiffsPairedBy

public IterableOfProtosUsingCorrespondence<M> displayingDiffsPairedBy(Function<? super M,?> keyFunction)

Specifies a way to pair up unexpected and missing elements in the message when an assertion fails. For example:

 assertThat(actualFoos)
     .ignoringRepeatedFieldOrder()
     .ignoringFields(Foo.BAR_FIELD_NUMBER)
     .displayingDiffsPairedBy(Foo::getId)
     .containsExactlyElementsIn(expectedFoos);
 

On assertions where it makes sense to do so, the elements are paired as follows: they are keyed by keyFunction, and if an unexpected element and a missing element have the same non-null key then the they are paired up. (Elements with null keys are not paired.) The failure message will show paired elements together, and a diff will be shown.

The expected elements given in the assertion should be uniquely keyed by keyFunction. If multiple missing elements have the same key then the pairing will be skipped.

Useful key functions will have the property that key equality is less strict than the already specified equality rules; i.e. given actual and expected values with keys actualKey and expectedKey, if actual and expected compare equal given the rest of the directives such as ignoringRepeatedFieldOrder and ignoringFields, then it is guaranteed that actualKey is equal to expectedKey, but there are cases where actualKey is equal to expectedKey but the direct comparison fails.

Note that calling this method makes no difference to whether a test passes or fails, it just improves the message if it fails.

ignoringFieldAbsence

public IterableOfProtosFluentAssertion<M> 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 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.

ignoringRepeatedFieldOrder

public IterableOfProtosFluentAssertion<M> 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.

ignoringExtraRepeatedFieldElements

public IterableOfProtosFluentAssertion<M> 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.)

usingDoubleTolerance

public IterableOfProtosFluentAssertion<M> 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.

usingFloatTolerance

public IterableOfProtosFluentAssertion<M> 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.

comparingExpectedFieldsOnly

public IterableOfProtosFluentAssertion<M> 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 method in IterableOfProtosUsingCorrespondence at the end of the call-chain.

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 IterableOfProtosFluentAssertion<M> 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 IterableOfProtosFluentAssertion<M> 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 IterableOfProtosFluentAssertion<M> 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 IterableOfProtosFluentAssertion<M> ignoringFieldDescriptors(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.

ignoringFieldDescriptors

public IterableOfProtosFluentAssertion<M> ignoringFieldDescriptors(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.

ignoringFieldScope

public IterableOfProtosFluentAssertion<M> 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 IterableOfProtosFluentAssertion<M> 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.