Class IterableSubject

  • Direct Known Subclasses:
    IterableOfProtosSubject, MultisetSubject

    public class IterableSubject
    extends Subject
    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 Description
      static class  IterableSubject.UsingCorrespondence<A extends @Nullable java.lang.Object,​E extends @Nullable java.lang.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.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected IterableSubject​(FailureMetadata metadata, @Nullable java.lang.Iterable<?> iterable)
      Constructor for use by subclasses.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected java.lang.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 extends @Nullable java.lang.Object,​E extends @Nullable java.lang.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.
      void contains​(@Nullable java.lang.Object element)
      Checks (with a side-effect failure) that the subject contains the supplied item.
      void containsAnyIn​(@Nullable java.lang.Iterable<?> expected)
      Checks that the subject contains at least one of the objects contained in the provided collection or fails.
      void containsAnyIn​(@Nullable java.lang.Object[] expected)
      Checks that the subject contains at least one of the objects contained in the provided array or fails.
      void containsAnyOf​(@Nullable java.lang.Object first, @Nullable java.lang.Object second, @Nullable java.lang.Object @Nullable ... rest)
      Checks that the subject contains at least one of the provided objects or fails.
      Ordered containsAtLeast​(@Nullable java.lang.Object firstExpected, @Nullable java.lang.Object secondExpected, @Nullable java.lang.Object @Nullable ... restOfExpected)
      Checks that the actual iterable contains at least all of the expected elements or fails.
      Ordered containsAtLeastElementsIn​(@Nullable java.lang.Object[] expected)
      Checks that the actual iterable contains at least all of the expected elements or fails.
      Ordered containsAtLeastElementsIn​(java.lang.Iterable<?> expectedIterable)
      Checks that the actual iterable contains at least all of the expected elements or fails.
      Ordered containsExactly​(@Nullable java.lang.Object @Nullable ... varargs)
      Checks that a subject contains exactly the provided objects or fails.
      Ordered containsExactlyElementsIn​(@Nullable java.lang.Iterable<?> expected)
      Checks that a subject contains exactly the provided objects or fails.
      Ordered containsExactlyElementsIn​(@Nullable java.lang.Object @Nullable [] 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​(@Nullable java.lang.Object[] excluded)
      Checks that the actual iterable contains none of the elements contained in the excluded array or fails.
      void containsNoneIn​(java.lang.Iterable<?> excluded)
      Checks that the actual iterable contains none of the elements contained in the excluded iterable or fails.
      void containsNoneOf​(@Nullable java.lang.Object firstExcluded, @Nullable java.lang.Object secondExcluded, @Nullable java.lang.Object @Nullable ... restOfExcluded)
      Checks that a actual iterable contains none of the excluded objects or fails.
      void doesNotContain​(@Nullable java.lang.Object element)
      Checks (with a side-effect failure) that the subject does not contain the supplied item.
      <T> IterableSubject.UsingCorrespondence<T,​T> formattingDiffsUsing​(Correspondence.DiffFormatter<? super T,​? super T> formatter)
      Starts a method chain for a check in which failure messages may use the given Correspondence.DiffFormatter to describe the difference between an actual elements (i.e.
      void hasSize​(int expectedSize)
      Fails if the subject does not have the given size.
      void isEmpty()
      Fails if the subject is not empty.
      void isEqualTo​(@Nullable java.lang.Object expected)
      Fails if the subject is not equal to the given object.
      void isInOrder()
      Fails if the iterable is not ordered, according to the natural ordering of its elements.
      void isInOrder​(java.util.Comparator<?> comparator)
      Fails if the iterable is not ordered, according to the given comparator.
      void isInStrictOrder()
      Fails if the iterable is not strictly ordered, according to the natural ordering of its elements.
      void isInStrictOrder​(java.util.Comparator<?> comparator)
      Fails if the iterable is not strictly ordered, according to the given comparator.
      void isNoneOf​(@Nullable java.lang.Object first, @Nullable java.lang.Object second, @Nullable java.lang.Object @Nullable ... rest)
      Deprecated.
      void isNotEmpty()
      Fails if the subject is empty.
      void isNotIn​(@Nullable java.lang.Iterable<?> iterable)
      Deprecated.
      You probably meant to call containsNoneIn(java.lang.Iterable<?>) instead.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • IterableSubject

        protected IterableSubject​(FailureMetadata metadata,
                                  @Nullable java.lang.Iterable<?> iterable)
        Constructor for use by subclasses. If you want to create an instance of this class itself, call check(...).that(actual).
    • Method Detail

      • actualCustomStringRepresentation

        protected java.lang.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
      • isEqualTo

        public void isEqualTo​(@Nullable java.lang.Object expected)
        Description copied from class: Subject
        Fails if the subject is not equal to the given object. For the purposes of this comparison, two objects are equal if any of the following is true:
        • they are equal according to Objects.equal(java.lang.Object, java.lang.Object)
        • they are arrays and are considered equal by the appropriate Arrays.equals(long[], long[]) overload
        • they are boxed integer types (Byte, Short, Character, Integer, or Long) and they are numerically equal when converted to Long.
        • the actual value is a boxed floating-point type (Double or Float), the expected value is an Integer, and the two are numerically equal when converted to Double. (This allows assertThat(someDouble).isEqualTo(0) to pass.)

        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()
        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​(@Nullable java.lang.Object element)
        Checks (with a side-effect failure) that the subject contains the supplied item.
      • doesNotContain

        public final void doesNotContain​(@Nullable java.lang.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​(@Nullable java.lang.Object first,
                                        @Nullable java.lang.Object second,
                                        @Nullable java.lang.Object @Nullable ... rest)
        Checks that the subject contains at least one of the provided objects or fails.
      • containsAnyIn

        public final void containsAnyIn​(@Nullable java.lang.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​(@Nullable java.lang.Object[] expected)
        Checks that the subject contains at least one of the objects contained in the provided array or fails.
      • containsAtLeast

        @CanIgnoreReturnValue
        public final Ordered containsAtLeast​(@Nullable java.lang.Object firstExpected,
                                             @Nullable java.lang.Object secondExpected,
                                             @Nullable java.lang.Object @Nullable ... 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.

      • containsAtLeastElementsIn

        @CanIgnoreReturnValue
        public final Ordered containsAtLeastElementsIn​(java.lang.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.

      • containsAtLeastElementsIn

        @CanIgnoreReturnValue
        public final Ordered containsAtLeastElementsIn​(@Nullable java.lang.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​(@Nullable java.lang.Object @Nullable ... 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​(@Nullable java.lang.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​(@Nullable java.lang.Object @Nullable [] 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​(@Nullable java.lang.Object firstExcluded,
                                         @Nullable java.lang.Object secondExcluded,
                                         @Nullable java.lang.Object @Nullable ... 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​(java.lang.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​(@Nullable java.lang.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.)
      • isInStrictOrder

        public void isInStrictOrder()
        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:
        java.lang.ClassCastException - if any pair of elements is not mutually Comparable
        java.lang.NullPointerException - if any element is null
      • isInStrictOrder

        public final void isInStrictOrder​(java.util.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:
        java.lang.ClassCastException - if any pair of elements is not mutually Comparable
      • isInOrder

        public void isInOrder()
        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:
        java.lang.ClassCastException - if any pair of elements is not mutually Comparable
        java.lang.NullPointerException - if any element is null
      • isInOrder

        public final void isInOrder​(java.util.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:
        java.lang.ClassCastException - if any pair of elements is not mutually Comparable
      • isNotIn

        @Deprecated
        public void isNotIn​(@Nullable java.lang.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
      • comparingElementsUsing

        public <A extends @Nullable java.lang.Object,​E extends @Nullable java.lang.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.

      • formattingDiffsUsing

        public <T> IterableSubject.UsingCorrespondence<T,​T> formattingDiffsUsing​(Correspondence.DiffFormatter<? super T,​? super T> formatter)
        Starts a method chain for a check in which failure messages may use the given Correspondence.DiffFormatter to describe the difference between an actual elements (i.e. an element of the Iterable under test) and the element it is expected to be equal to, but isn't. The actual and expected elements must be of type T. The check is actually executed by continuing the method chain. You may well want to use IterableSubject.UsingCorrespondence.displayingDiffsPairedBy(com.google.common.base.Function<? super E, ?>) to specify how the elements should be paired up for diffing. For example:
        
         assertThat(actualFoos)
             .formattingDiffsUsing(FooTestHelper::formatDiff)
             .displayingDiffsPairedBy(Foo::getId)
             .containsExactly(foo1, foo2, foo3);
         
        where actualFoos is an Iterable<Foo>, FooTestHelper.formatDiff is a static method taking two Foo arguments and returning a String, Foo.getId is a no-arg instance method returning some kind of ID, and foo1, {code foo2}, and foo3 are Foo instances.

        Unlike when using comparingElementsUsing(com.google.common.truth.Correspondence<? super A, ? super E>), the elements are still compared using object equality, so this method does not affect whether a test passes or fails.

        Any of the methods on the returned object may throw ClassCastException if they encounter an actual element that is not of type T.

        Since:
        1.1