com.google.common.truth

Class IterableSubject.UsingCorrespondence<A,E>

java.lang.Object

com.google.common.truth.IterableSubject.UsingCorrespondence<A,E>

Direct Known Subclasses:

PrimitiveDoubleArraySubject.DoubleArrayAsIterable, PrimitiveFloatArraySubject.FloatArrayAsIterable

Enclosing class:

IterableSubject

public static class IterableSubject.UsingCorrespondence<A,E>
extends Object

A partially specified check in which the actual elements (normally the elements of the Iterable under test) are compared to expected elements using a Correspondence. The expected elements are of type E. Call methods on this object to actually execute the check.

Method Summary

Modifier and Type	Method and Description
void	contains(E expected) Checks that the subject contains at least one element that corresponds to the given expected element.
void	containsAnyIn(E[] expected) Checks that the subject contains at least one element that corresponds to at least one of the expected elements.
void	containsAnyIn(Iterable<? extends E> expected) Checks that the subject contains at least one element that corresponds to at least one of the expected elements.
void	containsAnyOf(E first, E second, E... rest) Checks that the subject contains at least one element that corresponds to at least one of the expected elements.
Ordered	containsAtLeast(E first, E second, E... rest) Checks that the subject contains elements that corresponds to all of the expected elements, i.e.
Ordered	containsAtLeastElementsIn(E[] expected) Checks that the subject contains elements that corresponds to all of the expected elements, i.e.
Ordered	containsAtLeastElementsIn(Iterable<? extends E> expected) Checks that the subject contains elements that corresponds to all of the expected elements, i.e.
Ordered	containsExactly(E... expected) Checks that subject contains exactly elements that correspond to the expected elements, i.e.
Ordered	containsExactlyElementsIn(E[] expected) Checks that subject contains exactly elements that correspond to the expected elements, i.e.
Ordered	containsExactlyElementsIn(Iterable<? extends E> expected) Checks that subject contains exactly elements that correspond to the expected elements, i.e.
void	containsNoneIn(E[] excluded) Checks that the subject contains no elements that correspond to any of the given elements.
void	containsNoneIn(Iterable<? extends E> excluded) Checks that the subject contains no elements that correspond to any of the given elements.
void	containsNoneOf(E firstExcluded, E secondExcluded, E... restOfExcluded) Checks that the subject contains no elements that correspond to any of the given elements.
IterableSubject.UsingCorrespondence<A,E>	displayingDiffsPairedBy(Function<? super A,?> actualKeyFunction, Function<? super E,?> expectedKeyFunction) Specifies a way to pair up unexpected and missing elements in the message when an assertion fails.
IterableSubject.UsingCorrespondence<A,E>	displayingDiffsPairedBy(Function<? super E,?> keyFunction) Specifies a way to pair up unexpected and missing elements in the message when an assertion fails.
void	doesNotContain(E excluded) Checks that none of the actual elements correspond to the given element.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

displayingDiffsPairedBy

public IterableSubject.UsingCorrespondence<A,E> displayingDiffsPairedBy(Function<? super E,?> keyFunction)

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

 assertThat(actualRecords)
     .comparingElementsUsing(RECORD_CORRESPONDENCE)
     .displayingDiffsPairedBy(Record::getId)
     .containsExactlyElementsIn(expectedRecords);
 

Important: The {code keyFunction} function must be able to accept both the actual and the unexpected elements, i.e. it must satisfy Function<? super A, ?> as well as Function<? super E, ?>. If that constraint is not met then a subsequent method may throw ClassCastException. Use the two-parameter overload if you need to specify different key functions for the actual and expected elements.

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 if the Correspondence.formatDiff(A, E) method returns non-null.

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 correspondence, i.e. given actual and expected values with keys actualKey and expectedKey, if correspondence.compare(actual, expected) is true then it is guaranteed that actualKey is equal to expectedKey, but there are cases where actualKey is equal to expectedKey but correspondence.compare(actual, expected) is false.

If the apply method on the key function throws an exception then the element will be treated as if it had a null key and not paired. (The first such exception will be noted in the failure message.)

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

displayingDiffsPairedBy

public IterableSubject.UsingCorrespondence<A,E> displayingDiffsPairedBy(Function<? super A,?> actualKeyFunction,
                                                                        Function<? super E,?> expectedKeyFunction)

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

 assertThat(actualFoos)
     .comparingElementsUsing(FOO_BAR_CORRESPONDENCE)
     .displayingDiffsPairedBy(Foo::getId, Bar::getFooId)
     .containsExactlyElementsIn(expectedBar);
 

On assertions where it makes sense to do so, the elements are paired as follows: the unexpected elements are keyed by actualKeyFunction, the missing elements are keyed by expectedKeyFunction, 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 if the Correspondence.formatDiff(A, E) method returns non-null.

The expected elements given in the assertion should be uniquely keyed by expectedKeyFunction. 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 correspondence, i.e. given actual and expected values with keys actualKey and expectedKey, if correspondence.compare(actual, expected) is true then it is guaranteed that actualKey is equal to expectedKey, but there are cases where actualKey is equal to expectedKey but correspondence.compare(actual, expected) is false.

If the apply method on either of the key functions throws an exception then the element will be treated as if it had a null key and not paired. (The first such exception will be noted in the failure message.)

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

contains

public void contains(@NullableDecl
                     E expected)

Checks that the subject contains at least one element that corresponds to the given expected element.

doesNotContain

public void doesNotContain(@NullableDecl
                           E excluded)

Checks that none of the actual elements correspond to the given element.

containsExactly

@SafeVarargs
 @CanIgnoreReturnValue
public final Ordered containsExactly(@NullableDecl
                                                                         E... expected)

Checks that subject contains exactly elements that correspond to the expected elements, i.e. that there is a 1:1 mapping between the actual elements and the expected elements where each pair of elements correspond.

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 elements corresponding to those in 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<? extends E> expected)

Checks that subject contains exactly elements that correspond to the expected elements, i.e. that there is a 1:1 mapping between the actual elements and the expected elements where each pair of elements correspond.

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(E[] expected)

Checks that subject contains exactly elements that correspond to the expected elements, i.e. that there is a 1:1 mapping between the actual elements and the expected elements where each pair of elements correspond.

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

containsAtLeast

@SafeVarargs
 @CanIgnoreReturnValue
public final Ordered containsAtLeast(@NullableDecl
                                                                         E first,
                                                                         @NullableDecl
                                                                         E second,
                                                                         @NullableDecl
                                                                         E... rest)

Checks that the subject contains elements that corresponds to all of the expected elements, i.e. that there is a 1:1 mapping between any subset of the actual elements and the expected elements where each pair of elements correspond.

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

containsAtLeastElementsIn

@CanIgnoreReturnValue
public Ordered containsAtLeastElementsIn(Iterable<? extends E> expected)

Checks that the subject contains elements that corresponds to all of the expected elements, i.e. that there is a 1:1 mapping between any subset of the actual elements and the expected elements where each pair of elements correspond.

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

containsAtLeastElementsIn

@CanIgnoreReturnValue
public Ordered containsAtLeastElementsIn(E[] expected)

Checks that the subject contains elements that corresponds to all of the expected elements, i.e. that there is a 1:1 mapping between any subset of the actual elements and the expected elements where each pair of elements correspond.

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

containsAnyOf

@SafeVarargs
public final void containsAnyOf(@NullableDecl
                                             E first,
                                             @NullableDecl
                                             E second,
                                             @NullableDecl
                                             E... rest)

Checks that the subject contains at least one element that corresponds to at least one of the expected elements.

containsAnyIn

public void containsAnyIn(Iterable<? extends E> expected)

Checks that the subject contains at least one element that corresponds to at least one of the expected elements.

containsAnyIn

public void containsAnyIn(E[] expected)

Checks that the subject contains at least one element that corresponds to at least one of the expected elements.

containsNoneOf

@SafeVarargs
public final void containsNoneOf(@NullableDecl
                                              E firstExcluded,
                                              @NullableDecl
                                              E secondExcluded,
                                              @NullableDecl
                                              E... restOfExcluded)

Checks that the subject contains no elements that correspond to any of the given elements. (Duplicates are irrelevant to this test, which fails if any of the subject elements correspond to any of the given elements.)

containsNoneIn

public void containsNoneIn(Iterable<? extends E> excluded)

Checks that the subject contains no elements that correspond to any of the given elements. (Duplicates are irrelevant to this test, which fails if any of the subject elements correspond to any of the given elements.)

containsNoneIn

public void containsNoneIn(E[] excluded)

Checks that the subject contains no elements that correspond to any of the given elements. (Duplicates are irrelevant to this test, which fails if any of the subject elements correspond to any of the given elements.)