com.google.common.truth

Class IterableSubject

java.lang.Object

com.google.common.truth.Subject<IterableSubject,Iterable<?>>

com.google.common.truth.IterableSubject

Direct Known Subclasses:

MultisetSubject, SortedSetSubject

public class IterableSubject
extends Subject<IterableSubject,Iterable<?>>

Propositions for Iterable subjects.

Note:

• Assertions may iterate through the given Iterable more than once. If you have an unusual implementation of Iterable which does not support multiple iterations (sometimes known as a "one-shot iterable"), you must copy your iterable into a collection which does (e.g. ImmutableList.copyOf(iterable) or, if your iterable may contain null, newArrayList(iterable)). If you don't, you may see surprising failures.
• Assertions may also require that the elements in the given Iterable implement Object.hashCode() correctly.

Author:

Kurt Alfred Kluever, Pete Gillin

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IterableSubject.UsingCorrespondence<A,E> 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.

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	IterableSubject(FailureMetadata metadata, Iterable<?> iterable) Constructor for use by subclasses.

Method Summary

Modifier and Type	Method and Description
protected String	actualCustomStringRepresentation() Supplies the direct string representation of the actual value to other methods which may prefix or otherwise position it in an error message.
<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.
void	contains(Object element) Checks (with a side-effect failure) that the subject contains the supplied item.
Ordered	containsAllIn(Iterable<?> expectedIterable) 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 the actual iterable contains none of the elements contained in the excluded iterable or fails.
void	containsNoneIn(Object[] excluded) Checks that the actual iterable contains none of the elements contained in the excluded array or fails.
void	containsNoneOf(Object firstExcluded, Object secondExcluded, Object... restOfExcluded) Checks that a actual iterable contains none of the excluded objects or 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.
void	isEmpty() Fails if the subject is not empty.
void	isNoneOf(Object first, Object second, Object... rest) Deprecated. You probably meant to call containsNoneOf(java.lang.Object, java.lang.Object, java.lang.Object...) instead.
void	isNotEmpty() Fails if the subject is empty.
void	isNotIn(Iterable<?> iterable) Deprecated. You probably meant to call containsNoneIn(java.lang.Iterable<?>) instead.
void	isOrdered() Fails if the iterable is not ordered, according to the natural ordering of its elements.
void	isOrdered(Comparator<?> comparator) Fails if the iterable is not ordered, according to the given comparator.
void	isStrictlyOrdered() Fails if the iterable is not strictly ordered, according to the natural ordering of its elements.
void	isStrictlyOrdered(Comparator<?> comparator) Fails if the iterable is not strictly ordered, according to the given comparator.

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

actual, actualAsString, 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, isNotEqualTo, isNotInstanceOf, isNotNull, isNotSameAs, isNull, isSameAs, named, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

IterableSubject

protected IterableSubject(FailureMetadata metadata,
                          @NullableDecl
                          Iterable<?> iterable)

Constructor for use by subclasses. If you want to create an instance of this class itself, call Subject.check().that(actual).

Method Detail

actualCustomStringRepresentation

protected String actualCustomStringRepresentation()

Description copied from class: Subject

Supplies the direct string representation of the actual value to other methods which may prefix or otherwise position it in an error message. This should only be overridden to provide an improved string representation of the value under test, as it would appear in any given error message, and should not be used for additional prefixing.

Subjects should override this with care.

By default, this returns String.ValueOf(getActualValue()).

Overrides:

actualCustomStringRepresentation in class Subject<IterableSubject,Iterable<?>>

isEmpty

public final void isEmpty()

Fails if the subject is not empty.

isNotEmpty

public final void isNotEmpty()

Fails if the subject is empty.

hasSize

public final void hasSize(int expectedSize)

Fails if the subject does not have the given size.

contains

public final void contains(@NullableDecl
                           Object element)

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

doesNotContain

public final void doesNotContain(@NullableDecl
                                 Object element)

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

containsNoDuplicates

public final void containsNoDuplicates()

Checks that the subject does not contain duplicate elements.

containsAnyOf

public final 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 final void containsAnyIn(Iterable<?> expected)

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

containsAnyIn

public final 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 final 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 final Ordered containsAllIn(Iterable<?> expectedIterable)

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 final 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 final 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 final 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 final 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 array 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 final 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 final void containsNoneIn(Iterable<?> excluded)

Checks that the 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 final void containsNoneIn(Object[] excluded)

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

isStrictlyOrdered

public final void isStrictlyOrdered()

Fails if the iterable is not strictly ordered, according to the natural ordering of its elements. 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

NullPointerException - if any element is null

isStrictlyOrdered

public final 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 final void isOrdered()

Fails if the iterable is not ordered, according to the natural ordering of its elements. 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

NullPointerException - if any element is null

isOrdered

public final 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

isNoneOf

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

Deprecated. You probably meant to call containsNoneOf(java.lang.Object, java.lang.Object, java.lang.Object...) instead.

Description copied from class: Subject

Fails if the subject is equal to any of the given elements.

Overrides:

isNoneOf in class Subject<IterableSubject,Iterable<?>>

isNotIn

@Deprecated
public void isNotIn(Iterable<?> iterable)

Deprecated. You probably meant to call containsNoneIn(java.lang.Iterable<?>) instead.

Description copied from class: Subject

Fails if the subject is equal to any element in the given iterable.

Overrides:

isNotIn in class Subject<IterableSubject,Iterable<?>>

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.