- Direct Known Subclasses:
PrimitiveDoubleArraySubject.DoubleArrayAsIterable
,PrimitiveFloatArraySubject.FloatArrayAsIterable
- Enclosing class:
IterableSubject
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.- Author:
- Kurt Alfred Kluever, Pete Gillin
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Checks that the actual iterable contains at least one element that corresponds to the given expected element.void
containsAnyIn
(E @Nullable [] expected) Checks that the actual iterable contains at least one element that corresponds to at least one of the expected elements.void
containsAnyIn
(Iterable<? extends E> expected) Checks that the actual iterable contains at least one element that corresponds to at least one of the expected elements.final void
containsAnyOf
(E first, E second, E @Nullable ... rest) Checks that the actual iterable contains at least one element that corresponds to at least one of the expected elements.final Ordered
containsAtLeast
(E first, E second, E @Nullable ... rest) Checks that the actual iterable contains elements that correspond to all 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.containsAtLeastElementsIn
(E @Nullable [] expected) Checks that the actual iterable contains elements that correspond to all 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.containsAtLeastElementsIn
(Iterable<? extends E> expected) Checks that the actual iterable contains elements that correspond to all 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.final Ordered
containsExactly
(@Nullable E @Nullable ... expected) Checks that actual iterable 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.containsExactlyElementsIn
(E @Nullable [] expected) Checks that actual iterable 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.containsExactlyElementsIn
(@Nullable Iterable<? extends E> expected) Checks that actual iterable 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.void
containsNoneIn
(E @Nullable [] 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 actual iterable contains no elements that correspond to any of the given elements.final void
containsNoneOf
(E first, E second, E @Nullable ... rest) Checks that the actual iterable contains no elements that correspond to any of the given elements.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.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 element) Checks that none of the actual elements correspond to the given element.final boolean
Deprecated.final int
hashCode()
Deprecated.Object.hashCode()
is not supported on Truth types.final String
toString()
Deprecated.Object.toString()
is not supported on Truth subjects.
-
Method Details
-
equals
Deprecated.Object.equals(Object)
is not supported on Truth subjects or intermediate classes. If you are writing a test assertion (actual vs. expected), use methods likscontainsExactlyElementsIn(Iterable)
instead.- Overrides:
equals
in classObject
- Throws:
UnsupportedOperationException
- always
-
hashCode
Deprecated.Object.hashCode()
is not supported on Truth types.- Overrides:
hashCode
in classObject
- Throws:
UnsupportedOperationException
- always
-
toString
Deprecated.Object.toString()
is not supported on Truth subjects.- Overrides:
toString
in classObject
- Throws:
UnsupportedOperationException
- always
-
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(MyRecord::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 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(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 byexpectedKeyFunction
, and if an unexpected element and a missing element have the same non-null key then 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
Checks that the actual iterable contains at least one element that corresponds to the given expected element. -
doesNotContain
Checks that none of the actual elements correspond to the given element. -
containsExactly
@SafeVarargs @CanIgnoreReturnValue public final Ordered containsExactly(@Nullable E @Nullable ... expected) Checks that actual iterable 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(@Nullable Iterable<? extends E> expected) Checks that actual iterable 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
Checks that actual iterable 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(E first, E second, E @Nullable ... rest) Checks that the actual iterable contains elements that correspond to all 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 actual iterable, but they are not required to be consecutive. -
containsAtLeastElementsIn
Checks that the actual iterable contains elements that correspond to all 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 actual iterable, but they are not required to be consecutive. -
containsAtLeastElementsIn
Checks that the actual iterable contains elements that correspond to all 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 actual iterable, but they are not required to be consecutive. -
containsAnyOf
Checks that the actual iterable contains at least one element that corresponds to at least one of the expected elements. -
containsAnyIn
-
containsAnyIn
-
containsNoneOf
Checks that the actual iterable contains no elements that correspond to any of the given elements. -
containsNoneIn
-
containsNoneIn
-
Object.equals(Object)
is not supported on Truth subjects or intermediate classes.