Class IterableAssert<ELEMENT>

    • Constructor Detail

      • IterableAssert

        public IterableAssert​(java.lang.Iterable<? extends ELEMENT> actual)
    • Method Detail

      • toIterable

        static <T> java.lang.Iterable<T> toIterable​(java.util.Iterator<T> iterator)
      • containsOnly

        @SafeVarargs
        public final IterableAssert<ELEMENT> containsOnly​(ELEMENT... values)
        Description copied from class: AbstractIterableAssert
        Verifies that the actual group contains only the given values and nothing else, in any order and ignoring duplicates (i.e. once a value is found, its duplicates are also considered found).

        If you need to check exactly the elements and their duplicates use:

        Example:

         Iterable<String> abc = newArrayList("a", "b", "c");
        
         // assertions will pass as order does not matter
         assertThat(abc).containsOnly("c", "b", "a");
         // duplicates are ignored
         assertThat(abc).containsOnly("a", "a", "b", "c", "c");
         // ... on both actual and expected values
         assertThat(asList("a", "a", "b")).containsOnly("a", "b")
                                          .containsOnly("a", "a", "b", "b");
        
         // assertion will fail because "c" is missing in the given values
         assertThat(abc).containsOnly("a", "b");
         // assertion will fail because "d" is missing in abc (use isSubsetOf if you want this assertion to pass)
         assertThat(abc).containsOnly("a", "b", "c", "d");

        If you need to check that actual is a subset of the given values, use ObjectEnumerableAssert.isSubsetOf(Object...).

        If you want to specify the elements to check with an Iterable, use containsOnlyElementsOf(Iterable) instead.

        Specified by:
        containsOnly in interface ObjectEnumerableAssert<IterableAssert<ELEMENT>,​ELEMENT>
        Overrides:
        containsOnly in class AbstractIterableAssert<IterableAssert<ELEMENT>,​java.lang.Iterable<? extends ELEMENT>,​ELEMENT,​ObjectAssert<ELEMENT>>
        Parameters:
        values - the given values.
        Returns:
        this assertion object.
      • containsOnlyOnce

        @SafeVarargs
        public final IterableAssert<ELEMENT> containsOnlyOnce​(ELEMENT... values)
        Description copied from class: AbstractIterableAssert
        Verifies that the actual group contains the given values only once.

        Examples :

         // lists are used in the examples but it would also work with arrays
        
         // assertions will pass
         assertThat(newArrayList("winter", "is", "coming")).containsOnlyOnce("winter");
         assertThat(newArrayList("winter", "is", "coming")).containsOnlyOnce("coming", "winter");
        
         // assertions will fail
         assertThat(newArrayList("winter", "is", "coming")).containsOnlyOnce("Lannister");
         assertThat(newArrayList("Arya", "Stark", "daughter", "of", "Ned", "Stark")).containsOnlyOnce("Stark");
         assertThat(newArrayList("Arya", "Stark", "daughter", "of", "Ned", "Stark")).containsOnlyOnce("Stark", "Lannister", "Arya");
        Specified by:
        containsOnlyOnce in interface ObjectEnumerableAssert<IterableAssert<ELEMENT>,​ELEMENT>
        Overrides:
        containsOnlyOnce in class AbstractIterableAssert<IterableAssert<ELEMENT>,​java.lang.Iterable<? extends ELEMENT>,​ELEMENT,​ObjectAssert<ELEMENT>>
        Parameters:
        values - the given values.
        Returns:
        this assertion object.
      • isSubsetOf

        @SafeVarargs
        public final IterableAssert<ELEMENT> isSubsetOf​(ELEMENT... values)
        Description copied from class: AbstractIterableAssert
        Verifies that all the elements of actual are present in the given values.

        Example:

         // an Iterable is used in the example but it would also work with an array
         Iterable<Ring> elvesRings = newArrayList(vilya, nenya, narya);
        
         // assertions will pass:
         assertThat(elvesRings).isSubsetOf(vilya, nenya, narya)
                               .isSubsetOf(vilya, nenya, narya, dwarfRing);
        
         // assertions will fail:
         assertThat(elvesRings).isSubsetOf(vilya, nenya);
         assertThat(elvesRings).isSubsetOf(vilya, nenya, dwarfRing);

        If you want to specify the set of elements an Iterable, use isSubsetOf(Iterable) instead.

        Specified by:
        isSubsetOf in interface ObjectEnumerableAssert<IterableAssert<ELEMENT>,​ELEMENT>
        Overrides:
        isSubsetOf in class AbstractIterableAssert<IterableAssert<ELEMENT>,​java.lang.Iterable<? extends ELEMENT>,​ELEMENT,​ObjectAssert<ELEMENT>>
        Parameters:
        values - the values that should be used for checking the elements of actual.
        Returns:
        this assertion object.
      • flatExtracting

        @SafeVarargs
        public final <EXCEPTION extends java.lang.Exception> AbstractListAssert<?,​java.util.List<?>,​java.lang.Object,​ObjectAssert<java.lang.Object>> flatExtracting​(ThrowingExtractor<? super ELEMENT,​?,​EXCEPTION>... extractors)
        Description copied from class: AbstractIterableAssert
        Extract multiple values from each Iterable's element according to the given ThrowingExtractors and concatenate/flatten the extracted values in a list that is used as the new object under test.

        If extracted values were not flattened, instead of a simple list like (given 2 extractors) :

        element1.value1, element1.value2, element2.value1, element2.value2, ...  
        we would get a list of list like :
        list(element1.value1, element1.value2), list(element2.value1, element2.value2), ...  

        Code example:

         // fellowshipOfTheRing is a List<TolkienCharacter>
        
         // values are extracted in order and flattened : age1, name1, age2, name2, age3 ...
         assertThat(fellowshipOfTheRing).flatExtracting(input -> {
           if (input.getAge() < 20) {
             throw new Exception("age < 20");
           }
           return input.getName();
         }, input2 -> {
           if (input2.getAge() < 20) {
             throw new Exception("age < 20");
           }
           return input2.getAge();
         }).contains(33 ,"Frodo",
             1000, "Legolas",
             87, "Aragorn");
        The resulting extracted values list is ordered by Iterable's element first and then extracted values, this is why is in the example that age values come before names.
        Overrides:
        flatExtracting in class AbstractIterableAssert<IterableAssert<ELEMENT>,​java.lang.Iterable<? extends ELEMENT>,​ELEMENT,​ObjectAssert<ELEMENT>>
        Type Parameters:
        EXCEPTION - the exception type of ThrowingExtractor
        Parameters:
        extractors - all the extractors to apply on each actual Iterable's elements
        Returns:
        a new assertion object whose object under test is a flattened list of all extracted values.
      • flatExtracting

        @SafeVarargs
        public final AbstractListAssert<?,​java.util.List<?>,​java.lang.Object,​ObjectAssert<java.lang.Object>> flatExtracting​(java.util.function.Function<? super ELEMENT,​?>... extractors)
        Description copied from class: AbstractIterableAssert
        Extract multiple values from each Iterable's element according to the given Functions and concatenate/flatten the extracted values in a list that is used as the new object under test.

        If extracted values were not flattened, instead of a simple list like (given 2 extractors) :

        element1.value1, element1.value2, element2.value1, element2.value2, ...  
        we would get a list of list like :
        list(element1.value1, element1.value2), list(element2.value1, element2.value2), ...  

        Code example:

         // fellowshipOfTheRing is a List<TolkienCharacter>
        
         // values are extracted in order and flattened : age1, name1, age2, name2, age3 ...
         assertThat(fellowshipOfTheRing).flatExtracting(TolkienCharacter::getAge,
                                                        TolkienCharacter::getName)
                                        .contains(33 ,"Frodo",
                                                  1000, "Legolas",
                                                  87, "Aragorn");
        The resulting extracted values list is ordered by Iterable's element first and then extracted values, this is why is in the example that age values come before names.
        Overrides:
        flatExtracting in class AbstractIterableAssert<IterableAssert<ELEMENT>,​java.lang.Iterable<? extends ELEMENT>,​ELEMENT,​ObjectAssert<ELEMENT>>
        Parameters:
        extractors - all the extractors to apply on each actual Iterable's elements
        Returns:
        a new assertion object whose object under test is a flattened list of all extracted values.
      • extracting

        @SafeVarargs
        public final AbstractListAssert<?,​java.util.List<? extends Tuple>,​Tuple,​ObjectAssert<Tuple>> extracting​(java.util.function.Function<? super ELEMENT,​?>... extractors)
        Description copied from class: AbstractIterableAssert
        Use the given Functions to extract the values from the Iterable's elements into a new Iterable composed of Tuples (a simple data structure containing the extracted values), this new Iterable becoming the object under test.

        It allows you to test values from the Iterable's elements instead of testing the elements themselves, which sometimes can be much less work!

        The Tuple data corresponds to the extracted values from the Iterable's elements, for instance if you pass functions extracting "id", "name" and "email" values then each Tuple data will be composed of an id, a name and an email extracted from the element of the initial Iterable (the Tuple's data order is the same as the given functions order).

        Let's take a look at an example to make things clearer :

         // Build a list of TolkienCharacter, a TolkienCharacter has a name, and age and a Race (a specific class)
         // they can be public field or properties, both can be extracted.
         List<TolkienCharacter> fellowshipOfTheRing = new ArrayList<TolkienCharacter>();
        
         fellowshipOfTheRing.add(new TolkienCharacter("Frodo", 33, HOBBIT));
         fellowshipOfTheRing.add(new TolkienCharacter("Sam", 38, HOBBIT));
         fellowshipOfTheRing.add(new TolkienCharacter("Gandalf", 2020, MAIA));
         fellowshipOfTheRing.add(new TolkienCharacter("Legolas", 1000, ELF));
         fellowshipOfTheRing.add(new TolkienCharacter("Pippin", 28, HOBBIT));
         fellowshipOfTheRing.add(new TolkienCharacter("Gimli", 139, DWARF));
         fellowshipOfTheRing.add(new TolkienCharacter("Aragorn", 87, MAN);
         fellowshipOfTheRing.add(new TolkienCharacter("Boromir", 37, MAN));
        
         // let's verify 'name', 'age' and Race of some TolkienCharacter in fellowshipOfTheRing :
         assertThat(fellowshipOfTheRing).extracting(TolkienCharacter::getName,
                                                    character -> character.getAge(),
                                                    TolkienCharacter::getRace)
                                        .containsOnly(tuple("Frodo", 33, HOBBIT),
                                                      tuple("Sam", 38, HOBBIT),
                                                      tuple("Gandalf", 2020, MAIA),
                                                      tuple("Legolas", 1000, ELF),
                                                      tuple("Pippin", 28, HOBBIT),
                                                      tuple("Gimli", 139, DWARF),
                                                      tuple("Aragorn", 87, MAN),
                                                      tuple("Boromir", 37, MAN));
        You can use lambda expression or a method reference to extract the expected values.

        Use Tuple.tuple(Object...) to initialize the expected values.

        Note that the order of the extracted tuples list is consistent with the iteration order of the Iterable under test, for example if it's a HashSet, you won't be able to make any assumptions on the extracted tuples order.

        Overrides:
        extracting in class AbstractIterableAssert<IterableAssert<ELEMENT>,​java.lang.Iterable<? extends ELEMENT>,​ELEMENT,​ObjectAssert<ELEMENT>>
        Parameters:
        extractors - the extractor functions to extract a value from an element of the Iterable under test.
        Returns:
        a new assertion object whose object under test is the list of Tuples containing the extracted values.