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 java.lang.Object
A partially specified check in which the actual elements (normally the elements of theIterable
under test) are compared to expected elements using aCorrespondence
. The expected elements are of typeE
. Call methods on this object to actually execute the check.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private class
IterableSubject.UsingCorrespondence.Pairer
A class which knows how to pair the actual and expected elements (seedisplayingDiffsPairedBy(com.google.common.base.Function<? super E, ?>)
).private class
IterableSubject.UsingCorrespondence.Pairing
An description of a pairing between expected and actual values.
-
Field Summary
Fields Modifier and Type Field Description private Correspondence<? super A,? super E>
correspondence
private com.google.common.base.Optional<IterableSubject.UsingCorrespondence.Pairer>
pairer
private IterableSubject
subject
-
Constructor Summary
Constructors Constructor Description UsingCorrespondence(IterableSubject subject, Correspondence<? super A,? super E> correspondence)
UsingCorrespondence(IterableSubject subject, Correspondence<? super A,? super E> correspondence, IterableSubject.UsingCorrespondence.Pairer pairer)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
contains(E expected)
Checks that the subject contains at least one element that corresponds to the given expected element.private void
containsAny(java.lang.String failVerb, java.lang.Iterable<? extends E> expected)
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(java.lang.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(java.lang.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(java.lang.Iterable<? extends E> expected)
Checks that subject contains exactly elements that correspond to the expected elements, i.e.private void
containsNone(java.lang.String excludedPrefix, java.lang.Iterable<? extends E> excluded)
void
containsNoneIn(E[] excluded)
Checks that the subject contains no elements that correspond to any of the given elements.void
containsNoneIn(java.lang.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.private boolean
correspondInOrderAllIn(java.util.Iterator<? extends A> actual, java.util.Iterator<? extends E> expected)
Returns whether all the elements of the expected iterator and any subset of the elements of the actual iterator can be paired up in order, such that every pair of actual and expected elements satisfies the correspondence.private boolean
correspondInOrderExactly(java.util.Iterator<? extends A> actual, java.util.Iterator<? extends E> expected)
Returns whether the actual and expected iterators have the same number of elements and, when iterated pairwise, every pair of actual and expected values satisfies the correspondence.private java.lang.String
describeAnyMatchesByKey(IterableSubject.UsingCorrespondence.Pairing pairing, Correspondence.ExceptionStore exceptions)
private java.lang.String
describeMissing(java.util.List<? extends E> missing, java.util.List<? extends A> extra, Correspondence.ExceptionStore exceptions)
Given a list of missing elements, which must be non-empty, and a list of extra elements, returns a verb phrase (suitable for appearing after the subject of the verb) describing the missing elements, diffing against the extra ones where appropriate.private java.lang.String
describeMissingOrExtra(java.util.List<? extends E> missing, java.util.List<? extends A> extra, Correspondence.ExceptionStore exceptions)
Given a list of missing elements and a list of extra elements, at least one of which must be non-empty, returns a verb phrase (suitable for appearing after the subject of the verb) describing them.private java.lang.String
describeMissingOrExtraWithoutPairing(java.lang.String verb, java.util.List<? extends E> missing, java.util.List<? extends A> extra)
private java.lang.String
describeMissingOrExtraWithPairing(IterableSubject.UsingCorrespondence.Pairing pairing, Correspondence.ExceptionStore exceptions)
private java.lang.String
describeMissingWithoutPairing(java.lang.String verb, java.util.List<? extends E> missing)
private java.lang.String
describeMissingWithPairing(IterableSubject.UsingCorrespondence.Pairing pairing, Correspondence.ExceptionStore exceptions)
IterableSubject.UsingCorrespondence<A,E>
displayingDiffsPairedBy(com.google.common.base.Function<? super A,?> actualKeyFunction, com.google.common.base.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(com.google.common.base.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.private boolean
failIfCandidateMappingHasMissing(java.util.List<? extends A> actual, java.util.List<? extends E> expected, com.google.common.collect.ImmutableSetMultimap<java.lang.Integer,java.lang.Integer> mapping, Correspondence.ExceptionStore exceptions)
Given a list of actual elements, a list of expected elements, and a many:many mapping between actual and expected elements specified as a multimap of indexes into an actual list to indexes into the expected list, checks that every expected element maps to at least one actual element, and fails if this is not the case.private boolean
failIfCandidateMappingHasMissingOrExtra(java.util.List<? extends A> actual, java.util.List<? extends E> expected, com.google.common.collect.ImmutableSetMultimap<java.lang.Integer,java.lang.Integer> mapping, Correspondence.ExceptionStore exceptions)
Given a list of actual elements, a list of expected elements, and a many:many mapping between actual and expected elements specified as a multimap of indexes into the actual list to indexes into the expected list, checks that every actual element maps to at least one expected element and vice versa, and fails if this is not the case.private boolean
failIfOneToOneMappingHasMissing(java.util.List<? extends A> actual, java.util.List<? extends E> expected, com.google.common.collect.BiMap<java.lang.Integer,java.lang.Integer> mapping, Correspondence.ExceptionStore exceptions)
Given a list of expected elements, and a 1:1 mapping between actual and expected elements specified as a bimap of indexes into an actual list to indexes into the expected list, checks that every expected element maps to an actual element.private boolean
failIfOneToOneMappingHasMissingOrExtra(java.util.List<? extends A> actual, java.util.List<? extends E> expected, com.google.common.collect.BiMap<java.lang.Integer,java.lang.Integer> mapping, Correspondence.ExceptionStore exceptions)
Given a list of actual elements, a list of expected elements, and a 1:1 mapping between actual and expected elements specified as a bimap of indexes into the actual list to indexes into the expected list, checks that every actual element maps to an expected element and vice versa, and fails if this is not the case.private com.google.common.collect.ImmutableSetMultimap<java.lang.Integer,java.lang.Integer>
findCandidateMapping(java.util.List<? extends A> actual, java.util.List<? extends E> expected, Correspondence.ExceptionStore exceptions)
Given a list of actual elements and a list of expected elements, finds a many:many mapping between actual and expected elements where a pair of elements maps if it satisfies the correspondence.private boolean
findCorresponding(java.util.Iterator<? extends A> actual, E expectedElement, Correspondence.ExceptionStore exceptions)
Advances the actual iterator looking for an element which corresponds to the expected element.private com.google.common.collect.ImmutableBiMap<java.lang.Integer,java.lang.Integer>
findMaximalOneToOneMapping(com.google.common.collect.ImmutableMultimap<java.lang.Integer,java.lang.Integer> edges)
Given a many:many mapping between actual elements and expected elements, finds a 1:1 mapping which is the subset of that many:many mapping which includes the largest possible number of elements.private <T> java.util.List<T>
findNotIndexed(java.util.List<T> list, java.util.Set<java.lang.Integer> indexes)
Returns all the elements of the given list other than those with the given indexes.private Facts
formatExtras(java.lang.String label, E missing, java.util.List<? extends A> extras, Correspondence.ExceptionStore exceptions)
private java.util.List<java.lang.Object>
formatExtrasInline(E missing, java.util.List<? extends A> extras, Correspondence.ExceptionStore exceptions)
private java.lang.String
formatMissing(java.util.List<?> missing)
Returns a description of the missing items suitable for inclusion in failure messages.private java.lang.Iterable<A>
getCastActual()
-
-
-
Field Detail
-
subject
private final IterableSubject subject
-
correspondence
private final Correspondence<? super A,? super E> correspondence
-
pairer
private final com.google.common.base.Optional<IterableSubject.UsingCorrespondence.Pairer> pairer
-
-
Constructor Detail
-
UsingCorrespondence
UsingCorrespondence(IterableSubject subject, Correspondence<? super A,? super E> correspondence)
-
UsingCorrespondence
UsingCorrespondence(IterableSubject subject, Correspondence<? super A,? super E> correspondence, IterableSubject.UsingCorrespondence.Pairer pairer)
-
-
Method Detail
-
displayingDiffsPairedBy
public IterableSubject.UsingCorrespondence<A,E> displayingDiffsPairedBy(com.google.common.base.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 asFunction<? super E, ?>
. If that constraint is not met then a subsequent method may throwClassCastException
. 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 theCorrespondence.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
andexpected
values with keysactualKey
andexpectedKey
, ifcorrespondence.compare(actual, expected)
is true then it is guaranteed thatactualKey
is equal toexpectedKey
, but there are cases whereactualKey
is equal toexpectedKey
butcorrespondence.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(com.google.common.base.Function<? super A,?> actualKeyFunction, com.google.common.base.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 byexpectedKeyFunction
, 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 theCorrespondence.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
andexpected
values with keysactualKey
andexpectedKey
, ifcorrespondence.compare(actual, expected)
is true then it is guaranteed thatactualKey
is equal toexpectedKey
, but there are cases whereactualKey
is equal toexpectedKey
butcorrespondence.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(E expected)
Checks that the subject contains at least one element that corresponds to the given expected element.
-
doesNotContain
public void doesNotContain(E excluded)
Checks that none of the actual elements correspond to the given element.
-
containsExactly
@SafeVarargs public final Ordered containsExactly(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
public Ordered containsExactlyElementsIn(java.lang.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
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.
-
correspondInOrderExactly
private boolean correspondInOrderExactly(java.util.Iterator<? extends A> actual, java.util.Iterator<? extends E> expected)
Returns whether the actual and expected iterators have the same number of elements and, when iterated pairwise, every pair of actual and expected values satisfies the correspondence. Returns false if any comparison threw an exception.
-
findCandidateMapping
private com.google.common.collect.ImmutableSetMultimap<java.lang.Integer,java.lang.Integer> findCandidateMapping(java.util.List<? extends A> actual, java.util.List<? extends E> expected, Correspondence.ExceptionStore exceptions)
Given a list of actual elements and a list of expected elements, finds a many:many mapping between actual and expected elements where a pair of elements maps if it satisfies the correspondence. Returns this mapping as a multimap where the keys are indexes into the actual list and the values are indexes into the expected list. Any exceptions are treated as if the elements did not correspond, and the exception added to the store.
-
failIfCandidateMappingHasMissingOrExtra
private boolean failIfCandidateMappingHasMissingOrExtra(java.util.List<? extends A> actual, java.util.List<? extends E> expected, com.google.common.collect.ImmutableSetMultimap<java.lang.Integer,java.lang.Integer> mapping, Correspondence.ExceptionStore exceptions)
Given a list of actual elements, a list of expected elements, and a many:many mapping between actual and expected elements specified as a multimap of indexes into the actual list to indexes into the expected list, checks that every actual element maps to at least one expected element and vice versa, and fails if this is not the case. Returns whether the assertion failed.
-
describeMissingOrExtra
private java.lang.String describeMissingOrExtra(java.util.List<? extends E> missing, java.util.List<? extends A> extra, Correspondence.ExceptionStore exceptions)
Given a list of missing elements and a list of extra elements, at least one of which must be non-empty, returns a verb phrase (suitable for appearing after the subject of the verb) describing them. Exceptions from callingCorrespondence.formatDiff(A, E)
are stored inexceptions
.
-
describeMissingOrExtraWithoutPairing
private java.lang.String describeMissingOrExtraWithoutPairing(java.lang.String verb, java.util.List<? extends E> missing, java.util.List<? extends A> extra)
-
describeMissingOrExtraWithPairing
private java.lang.String describeMissingOrExtraWithPairing(IterableSubject.UsingCorrespondence.Pairing pairing, Correspondence.ExceptionStore exceptions)
-
formatExtras
private Facts formatExtras(java.lang.String label, E missing, java.util.List<? extends A> extras, Correspondence.ExceptionStore exceptions)
-
formatExtrasInline
private java.util.List<java.lang.Object> formatExtrasInline(E missing, java.util.List<? extends A> extras, Correspondence.ExceptionStore exceptions)
-
findNotIndexed
private <T> java.util.List<T> findNotIndexed(java.util.List<T> list, java.util.Set<java.lang.Integer> indexes)
Returns all the elements of the given list other than those with the given indexes. Assumes that all the given indexes really are valid indexes into the list.
-
formatMissing
private java.lang.String formatMissing(java.util.List<?> missing)
Returns a description of the missing items suitable for inclusion in failure messages. If there is a single item, returns"<item>"
. Otherwise, returns"each of <[item, item, item]>"
.
-
findMaximalOneToOneMapping
private com.google.common.collect.ImmutableBiMap<java.lang.Integer,java.lang.Integer> findMaximalOneToOneMapping(com.google.common.collect.ImmutableMultimap<java.lang.Integer,java.lang.Integer> edges)
Given a many:many mapping between actual elements and expected elements, finds a 1:1 mapping which is the subset of that many:many mapping which includes the largest possible number of elements. The input and output mappings are each described as a map or multimap where the keys are indexes into the actual list and the values are indexes into the expected list. If there are multiple possible output mappings tying for the largest possible, this returns an arbitrary one.
-
failIfOneToOneMappingHasMissingOrExtra
private boolean failIfOneToOneMappingHasMissingOrExtra(java.util.List<? extends A> actual, java.util.List<? extends E> expected, com.google.common.collect.BiMap<java.lang.Integer,java.lang.Integer> mapping, Correspondence.ExceptionStore exceptions)
Given a list of actual elements, a list of expected elements, and a 1:1 mapping between actual and expected elements specified as a bimap of indexes into the actual list to indexes into the expected list, checks that every actual element maps to an expected element and vice versa, and fails if this is not the case. Returns whether the assertion failed.
-
containsAtLeast
@SafeVarargs public final Ordered containsAtLeast(E first, E second, 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
public Ordered containsAtLeastElementsIn(java.lang.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
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.
-
correspondInOrderAllIn
private boolean correspondInOrderAllIn(java.util.Iterator<? extends A> actual, java.util.Iterator<? extends E> expected)
Returns whether all the elements of the expected iterator and any subset of the elements of the actual iterator can be paired up in order, such that every pair of actual and expected elements satisfies the correspondence. Returns false if any comparison threw an exception.
-
findCorresponding
private boolean findCorresponding(java.util.Iterator<? extends A> actual, E expectedElement, Correspondence.ExceptionStore exceptions)
Advances the actual iterator looking for an element which corresponds to the expected element. Returns whether or not it finds one.
-
failIfCandidateMappingHasMissing
private boolean failIfCandidateMappingHasMissing(java.util.List<? extends A> actual, java.util.List<? extends E> expected, com.google.common.collect.ImmutableSetMultimap<java.lang.Integer,java.lang.Integer> mapping, Correspondence.ExceptionStore exceptions)
Given a list of actual elements, a list of expected elements, and a many:many mapping between actual and expected elements specified as a multimap of indexes into an actual list to indexes into the expected list, checks that every expected element maps to at least one actual element, and fails if this is not the case. Actual elements which do not map to any expected elements are ignored.
-
describeMissing
private java.lang.String describeMissing(java.util.List<? extends E> missing, java.util.List<? extends A> extra, Correspondence.ExceptionStore exceptions)
Given a list of missing elements, which must be non-empty, and a list of extra elements, returns a verb phrase (suitable for appearing after the subject of the verb) describing the missing elements, diffing against the extra ones where appropriate.
-
describeMissingWithoutPairing
private java.lang.String describeMissingWithoutPairing(java.lang.String verb, java.util.List<? extends E> missing)
-
describeMissingWithPairing
private java.lang.String describeMissingWithPairing(IterableSubject.UsingCorrespondence.Pairing pairing, Correspondence.ExceptionStore exceptions)
-
failIfOneToOneMappingHasMissing
private boolean failIfOneToOneMappingHasMissing(java.util.List<? extends A> actual, java.util.List<? extends E> expected, com.google.common.collect.BiMap<java.lang.Integer,java.lang.Integer> mapping, Correspondence.ExceptionStore exceptions)
Given a list of expected elements, and a 1:1 mapping between actual and expected elements specified as a bimap of indexes into an actual list to indexes into the expected list, checks that every expected element maps to an actual element. Actual elements which do not map to any expected elements are ignored.
-
containsAnyOf
@SafeVarargs public final 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.
-
containsAnyIn
public void containsAnyIn(java.lang.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.
-
containsAny
private void containsAny(java.lang.String failVerb, java.lang.Iterable<? extends E> expected)
-
describeAnyMatchesByKey
private java.lang.String describeAnyMatchesByKey(IterableSubject.UsingCorrespondence.Pairing pairing, Correspondence.ExceptionStore exceptions)
-
containsNoneOf
@SafeVarargs public final void containsNoneOf(E firstExcluded, E secondExcluded, 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(java.lang.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.)
-
containsNone
private void containsNone(java.lang.String excludedPrefix, java.lang.Iterable<? extends E> excluded)
-
getCastActual
private java.lang.Iterable<A> getCastActual()
-
-