Make all extracting, flatExtracting and filteredOn to return a list a…

…ssertions with the method results.

MAke soft assertions and assumptions work with extracting, flatExtracting and filteredOn methods.
Add javadoc warning for methods not working with soft assertions and assumptions

src/main/java/org/assertj/core/api/AbstractIterableAssert.java

@@ -139,7 +139,6 @@ protected static <T> Iterable<T> toLazyIterable(Iterator<T> actual) {
    * @return a new {@link AbstractListAssert}.
    */
   protected <E> AbstractListAssert<?, List<? extends E>, E, ObjectAssert<E>> newListAssertInstance(List<? extends E> newActual) {
-    // this might not be the best implementation (SoftAssertion needs to override this).
     return new ListAssert<>(newActual);
   }
 
@@ -1355,7 +1354,7 @@ public AbstractListAssert<?, List<? extends Object>, Object, ObjectAssert<Object
     List<Object> result = actualStream.flatMap(element -> Stream.of(extractors)
                                                                 .map(extractor -> extractor.extract(element)))
                                       .collect(Collectors.toList());
-    return new ListAssert<>(result);
+    return newListAssertInstance(result);
   }
 
   /**
@@ -1399,7 +1398,7 @@ public <EXCEPTION extends Exception> AbstractListAssert<?, List<? extends Object
     List<Object> result = actualStream.flatMap(element -> Stream.of(extractors)
                                                                 .map(extractor -> extractor.extract(element)))
                                       .collect(Collectors.toList());
-    return new ListAssert<>(result);
+    return newListAssertInstance(result);
   }
 
   /**
@@ -2077,9 +2076,11 @@ public AbstractListAssert<?, List<? extends ELEMENT>, ELEMENT, ObjectAssert<ELEM
    */
   @CheckReturnValue
   public AbstractListAssert<?, List<? extends ELEMENT>, ELEMENT, ObjectAssert<ELEMENT>> filteredOnNull(String propertyOrFieldName) {
-    // need to cast nulll to Object otherwise it calls :
-    // filteredOn(String propertyOrFieldName, FilterOperation<?> filterOperation)
-    return filteredOn(propertyOrFieldName, (Object) null);
+    // can't call filteredOn(String propertyOrFieldName, null) as it does not work with soft assertions proxying
+    // mechanism, it would lead to double proxying which is not handle properly (improvements needed in our proxy mechanism)
+    Filters<? extends ELEMENT> filter = filter((Iterable<? extends ELEMENT>) actual);
+    Iterable<? extends ELEMENT> filteredIterable = filter.with(propertyOrFieldName, null).get();
+    return newListAssertInstance(newArrayList(filteredIterable));
   }
 
   /**
@@ -2234,6 +2235,8 @@ public AbstractListAssert<?, List<? extends ELEMENT>, ELEMENT, ObjectAssert<ELEM
    * // assertion fails
    * assertThat(hobbits, StringAssert.class).first()
    *                                        .startsWith("pip");</code></pre>
+   * <p>
+   * <b>Warning: this method does not work with soft assertions or assumptions.</b> 
    *
    * @return the assertion on the first element
    * @throws AssertionError if the actual {@link Iterable} is empty.
@@ -2281,6 +2284,8 @@ public ELEMENT_ASSERT first() {
    * // assertion fails
    * assertThat(hobbits, StringAssert.class).last()
    *                                        .startsWith("fro");</code></pre>
+   * <p>
+   * <b>Warning: this method does not work with soft assertions or assumptions.</b> 
    *
    * @return the assertion on the first element
    * @throws AssertionError if the actual {@link Iterable} is empty.
@@ -2341,6 +2346,8 @@ private ELEMENT lastElement() {
    * // assertion fails
    * assertThat(hobbits, StringAssert.class).element(1)
    *                                        .startsWith("fro");</code></pre>
+   * <p>
+   * <b>Warning: this method does not work with soft assertions or assumptions.</b> 
    *
    * @param index the element's index
    * @return the assertion on the given element
@@ -2401,7 +2408,7 @@ private static String removeAssert(String text) {
    */
   public AbstractListAssert<?, List<? extends ELEMENT>, ELEMENT, ObjectAssert<ELEMENT>> filteredOn(Predicate<? super ELEMENT> predicate) {
     checkArgument(predicate != null, "The filter predicate should not be null");
-    return new ListAssert<>(stream(actual.spliterator(), false).filter(predicate).collect(toList()));
+    return newListAssertInstance(stream(actual.spliterator(), false).filter(predicate).collect(toList()));
   }
 
   /**
@@ -2680,6 +2687,8 @@ public SELF withThreadDumpOnError() {
    *
    * // assertion will fail:
    * assertThat(elvesRings).size().isGreaterThan(3);</code></pre>
+   * <p>
+   * <b>Warning: this method does not work with soft assertions or assumptions.</b> 
    *
    * @return AbstractIterableSizeAssert built with the {@code Iterable}'s size.
    * @throws NullPointerException if the given {@code Iterable} is {@code null}.

src/main/java/org/assertj/core/api/AbstractMapAssert.java

@@ -13,7 +13,9 @@
 package org.assertj.core.api;
 
 import static org.assertj.core.data.MapEntry.entry;
+import static org.assertj.core.description.Description.mostRelevantDescription;
 import static org.assertj.core.extractor.Extractors.byName;
+import static org.assertj.core.extractor.Extractors.extractedDescriptionOf;
 import static org.assertj.core.util.Arrays.array;
 import static org.assertj.core.util.Arrays.isArray;
 import static org.assertj.core.util.IterableUtil.toCollection;
@@ -1191,6 +1193,8 @@ public SELF withThreadDumpOnError() {
    * 
    * // assertion will fail:
    * assertThat(ringBearers).size().isGreaterThan(5);</code></pre>
+   * <p>
+   * <b>Warning: this method does not work with soft assertions or assumptions.</b> 
    *
    * @return a {@link AbstractMapSizeAssert} to allow assertions on the the number of key-value mappings in this map
    * @throws NullPointerException if the given map is {@code null}.
@@ -1229,7 +1233,7 @@ public AbstractMapSizeAssert<SELF, ACTUAL, K, V> size() {
    */
   @CheckReturnValue
   @Override
-  public AbstractObjectArrayAssert<?, Object> extracting(String... keys) {
+  public AbstractListAssert<?, List<? extends Object>, Object, ObjectAssert<Object>> extracting(String... keys) {
     return super.extracting(keys);
   }
 
@@ -1255,7 +1259,7 @@ public AbstractObjectArrayAssert<?, Object> extracting(String... keys) {
    * assertThat(map).flatExtracting("name","job","city", "rank")
    *                .containsExactly("Dave", "Jeff", 
    *                                 "Plumber", "Builder", 
-   *                                 "Dover", "Boston", "Paris"
+   *                                 "Dover", "Boston", "Paris",
    *                                 1, 2, 3);
    *                
    * // the order of values in the resulting array is the order of map keys then key values:                
@@ -1279,10 +1283,12 @@ public AbstractObjectArrayAssert<?, Object> extracting(String... keys) {
    * @return a new assertion object whose object under test is the array containing the extracted flattened map values
    */
   @CheckReturnValue
-  public AbstractObjectArrayAssert<?, Object> flatExtracting(String... keys) {
+  public AbstractListAssert<?, List<? extends Object>, Object, ObjectAssert<Object>> flatExtracting(String... keys) {
     Tuple values = byName(keys).extract(actual);
     List<Object> valuesFlattened = flatten(values.toList());
-    return extracting(valuesFlattened, keys);
+    String extractedPropertiesOrFieldsDescription = extractedDescriptionOf(keys);
+    String description = mostRelevantDescription(info.description(), extractedPropertiesOrFieldsDescription);
+    return newListAssertInstance(valuesFlattened).as(description);
   }
 
   private static List<Object> flatten(Iterable<Object> collectionToFlatten) {