Package com.google.common.truth

Class IterableSubject

  • Direct Known Subclasses:
    IterableOfProtosSubject, MultisetSubject
    public class IterableSubject
extends Subject
    A subject for Iterable values.

    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.

    • Constructor Detail

      • IterableSubject

        protected IterableSubject​(FailureMetadata metadata,
                          @Nullable Iterable<?> actual)
        The constructor is for use by subclasses only. If you want to create an instance of this class itself, call check(...).that(actual).

    • Method Detail

      • actualCustomStringRepresentation

        protected String actualCustomStringRepresentation()
        Description copied from class: Subject
        Returns a string representation of the actual value for inclusion in failure messages.

        Subjects should override this with care.

        By default, this method returns String.valueOf(getActualValue()) for most types. It does have some special logic for a few cases, like arrays.

        Overrides:
        actualCustomStringRepresentation in class Subject

      • isEqualTo

        public void isEqualTo​(@Nullable Object expected)
        Description copied from class: Subject
        Checks that the value under test is equal to the given object. For the purposes of this comparison, two objects are equal if any of the following is true:

        Note: This method does not test the Object.equals(java.lang.Object) implementation itself; it assumes that method is functioning correctly according to its contract. Testing an equals implementation requires a utility such as guava-testlib's EqualsTester.

        In some cases, this method might not even call equals. It may instead perform other tests that will return the same result as long as equals is implemented according to the contract for its type.

        Overrides:
        isEqualTo in class Subject

      • isEmpty

        public final void isEmpty()
        Checks that the actual iterable is empty.

      • isNotEmpty

        public final void isNotEmpty()
        Checks that the actual iterable is not empty.

      • hasSize

        public final void hasSize​(int size)
        Checks that the actual iterable has the given size.

      • contains

        public final void contains​(@Nullable Object element)
        Checks that the actual iterable contains the supplied item.

      • doesNotContain

        public final void doesNotContain​(@Nullable Object element)
        Checks that the actual iterable does not contain the supplied item.

      • containsNoDuplicates

        public final void containsNoDuplicates()
        Checks that the actual iterable does not contain duplicate elements.

      • containsAnyIn

        public final void containsAnyIn​(@Nullable Iterable<?> expected)
        Checks that the actual iterable contains at least one of the objects contained in the provided collection.

      • containsAnyIn

        public final void containsAnyIn​(@Nullable Object @Nullable [] expected)
        Checks that the actual iterable contains at least one of the objects contained in the provided array.

      • containsAtLeast

        @CanIgnoreReturnValue
public final Ordered containsAtLeast​(@Nullable Object first,
                                     @Nullable Object second,
                                     @Nullable Object @Nullable ... rest)
        Checks that the actual iterable contains at least all the expected elements. 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.

      • containsAtLeastElementsIn

        @CanIgnoreReturnValue
public final Ordered containsAtLeastElementsIn​(@Nullable Iterable<?> expected)
        Checks that the actual iterable contains at least all the expected elements. 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.

      • containsAtLeastElementsIn

        @CanIgnoreReturnValue
public final Ordered containsAtLeastElementsIn​(@Nullable Object @Nullable [] expected)
        Checks that the actual iterable contains at least all the expected elements. 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​(@Nullable Object @Nullable ... expected)
        Checks that the actual iterable contains exactly the provided objects.

        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 actual iterable.

        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​(@Nullable Iterable<?> expected)
        Checks that the actual iterable contains exactly the provided objects.

        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 actual iterable.

        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​(@Nullable Object @Nullable [] expected)
        Checks that the actual iterable contains exactly the provided objects.

        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 actual iterable.

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

      • containsNoneIn

        public final void containsNoneIn​(@Nullable Iterable<?> excluded)
        Checks that the actual iterable contains none of the elements contained in the excluded iterable.

      • containsNoneIn

        public final void containsNoneIn​(@Nullable Object @Nullable [] excluded)
        Checks that the actual iterable contains none of the elements contained in the excluded array.

      • isInStrictOrder

        public void isInStrictOrder()
        Checks that the actual iterable is 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

      • isInStrictOrder

        public final void isInStrictOrder​(@Nullable Comparator<?> comparator)
        Checks that the actual iterable is 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

      • isInOrder

        public void isInOrder()
        Checks that the actual iterable is 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

      • isInOrder

        public final void isInOrder​(@Nullable Comparator<?> comparator)
        Checks that the actual iterable is 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 extends @Nullable Object,​E extends @Nullable Object> IterableSubject.UsingCorrespondence<A,​E> comparingElementsUsing​(Correspondence<? super A,​? super 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.