Clarify containsOnly and containsExactly javadoc

assertj · Dec 28, 2017 · 6983158 · 6983158
1 parent 7bb3911
commit 6983158
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 40 deletions.
diff --git a/src/main/java/org/assertj/core/api/AbstractObjectArrayAssert.java b/src/main/java/org/assertj/core/api/AbstractObjectArrayAssert.java
@@ -225,15 +225,23 @@ public SELF contains(@SuppressWarnings("unchecked") ELEMENT... values) {
   }
 
   /**
-   * Verifies that the actual group contains only the given values and nothing else, <b>in any order</b>.
+   * Verifies that the actual group contains only the given values and nothing else, in any order and with possibly duplicates.
    * <p>
+   * If you need to check exactly the elements and their duplicates use:
+   * <ul>
+   * <li>{@link #containsExactly(Object...) containsExactly(Object...)} if the order does matter</li>
+   * <li>{@link #containsExactlyInAnyOrder(Object...) containsExactlyInAnyOrder(Object...)} if the order does not matter</li>
+   * </ul>
    * Example :
    * <pre><code class='java'> String[] abc = {"a", "b", "c"};
    *
-   * // assertions will pass
+   * // assertions succeed
    * assertThat(abc).containsOnly("c", "b", "a");
+   * // duplicates are ignored   
    * assertThat(abc).containsOnly("a", "a", "b", "c", "c");
-   * assertThat(new String[] { "a", "a", "b" }).containsOnly("a", "b");
+   * // ... on both actual and expected values 
+   * assertThat(new String[] { "a", "a", "b" }).containsOnly("a", "b")
+   *                                           .containsOnly("a", "a", "b", "b");
    *
    * // assertion will fail because the given values do not contain "c"
    * assertThat(abc).containsOnly("a", "b");
@@ -359,7 +367,7 @@ public SELF containsOnlyOnce(@SuppressWarnings("unchecked") ELEMENT... values) {
   }
 
   /**
-   * Verifies that the actual array contains only the given values and nothing else, <b>in order</b>.<br>
+   * Verifies that the actual array contains exactly the given values and nothing else, <b>in order</b>.<br>
    * <p>
    * Example :
    * <pre><code class='java'> Ring[] elvesRings = {vilya, nenya, narya};
@@ -401,7 +409,7 @@ public SELF containsExactlyInAnyOrderElementsOf(Iterable<? extends ELEMENT> valu
 
   /**
    * Same as {@link #containsExactly(Object...)} but handles the {@link Iterable} to array conversion : verifies that
-   * actual contains all elements of the given {@code Iterable} and nothing else <b>in the same order</b>.
+   * actual contains exactly the elements of the given {@code Iterable} and nothing else <b>in the same order</b>.
    * <p>
    * Example :
    * <pre><code class='java'> Ring[] elvesRings = {vilya, nenya, narya};

diff --git a/src/main/java/org/assertj/core/api/ObjectEnumerableAssert.java b/src/main/java/org/assertj/core/api/ObjectEnumerableAssert.java
@@ -36,7 +36,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the actual group contains the given values, in any order.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    * 
    * // assertions will pass
@@ -58,14 +58,24 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   SELF contains(@SuppressWarnings("unchecked") ELEMENT... values);
 
   /**
-   * Verifies that the actual group contains only the given values and nothing else, in any order.
+   * Verifies that the actual group contains only the given values and nothing else, in any order and with possibly duplicates.
+   * <p>
+   * If you need to check exactly the elements and their duplicates use:
+   * <ul>
+   * <li>{@link #containsExactly(Object...) containsExactly(Object...)} if the order does matter</li>
+   * <li>{@link #containsExactlyInAnyOrder(Object...) containsExactlyInAnyOrder(Object...)} if the order does not matter</li>
+   * </ul>
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    *
-   * // assertions will pass
+   * // assertions will pass as order does not matter
    * assertThat(abc).containsOnly("c", "b", "a");
-   * assertThat(newArrayList("a", "a", "b")).containsOnly("a", "b");
+   * // 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");
@@ -89,7 +99,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the actual group contains only null elements and nothing else.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // assertion will pass
    * Iterable&lt;String&gt; items = Arrays.asList(null, null, null);
    * assertThat(items).containsOnlyNulls();
@@ -135,11 +145,11 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   SELF containsOnlyOnce(@SuppressWarnings("unchecked") ELEMENT... values);
 
   /**
-   * Verifies that the actual group contains only the given values and nothing else, <b>in order</b>.<br>
+   * Verifies that the actual group contains exactly the given values and nothing else, <b>in order</b>.<br>
    * This assertion should only be used with groups that have a consistent iteration order (i.e. don't use it with
    * {@link HashSet}, prefer {@link #containsOnly(Object...)} in that case).
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // an Iterable is used in the example but it would also work with an array
    * Iterable&lt;Ring&gt; elvesRings = newArrayList(vilya, nenya, narya);
    * 
@@ -165,7 +175,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
    * Verifies that the actual group contains exactly the given values and nothing else, <b>in any order</b>.<br>
    *
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // an Iterable is used in the example but it would also work with an array
    * Iterable&lt;Ring&gt; elvesRings = newArrayList(vilya, nenya, narya, vilya);
    *
@@ -188,9 +198,8 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
 
   /**
    * Verifies that the actual group contains exactly the given values and nothing else, <b>in any order</b>.<br>
-   *
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // an Iterable is used in the example but it would also work with an array
    * Iterable&lt;Ring&gt; elvesRings = newArrayList(vilya, nenya, narya, vilya);
    * Iterable&lt;Ring&gt; elvesRingsSomeMissing = newArrayList(vilya, nenya, narya);
@@ -424,7 +433,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the actual group does not contain the given values.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // an Iterable is used in the example but it would also work with an array
    * Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    *
@@ -451,7 +460,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the actual group does not contain duplicates.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // an Iterable is used in the example but it would also work with an array
    * Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    * Iterable&lt;String&gt; lotsOfAs = newArrayList("a", "a", "a");
@@ -473,7 +482,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
    * Similar to <code>{@link #containsSequence(Object...)}</code>, but it also verifies that the first element in the
    * sequence is also first element of the actual group.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // an Iterable is used in the example but it would also work with an array
    * Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    *
@@ -498,7 +507,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
    * Similar to <code>{@link #containsSequence(Object...)}</code>, but it also verifies that the last element in the
    * sequence is also last element of the actual group.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // an Iterable is used in the example but it would also work with an array
    * Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    *
@@ -524,7 +533,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
    * Similar to <code>{@link #containsSequence(Object...)}</code>, but it also verifies that the last element in the
    * sequence is also last element of the actual group.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> // an Iterable is used in the example but it would also work with an array
    * Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    *
@@ -548,7 +557,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the actual group contains at least a null element.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    * Iterable&lt;String&gt; abNull = newArrayList("a", "b", null);
    *
@@ -567,7 +576,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the actual group does not contain null elements.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    * Iterable&lt;String&gt; abNull = newArrayList("a", "b", null);
    *
@@ -586,7 +595,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that each element value satisfies the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc  = newArrayList("a", "b", "c");
    * Iterable&lt;String&gt; abcc = newArrayList("a", "b", "cc");
    *
@@ -613,7 +622,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that each element value does not satisfy the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    * Iterable&lt;String&gt; abcc = newArrayList("a", "b", "cc");
    *
@@ -640,7 +649,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that all elements satisfy the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    * Iterable&lt;String&gt; abcc = newArrayList("a", "b", "cc");
    *
@@ -667,7 +676,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that all elements do not satisfy the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = newArrayList("a", "b", "c");
    * Iterable&lt;String&gt; abcc = newArrayList("a", "b", "cc");
    *
@@ -694,7 +703,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that there are <b>at least</b> <i>n</i> elements in the actual group satisfying the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;Integer&gt; oneTwoThree = newArrayList(1, 2, 3);
    *
    * Condition&lt;Integer&gt; oddNumber = new Condition&lt;Integer&gt;() {
@@ -736,7 +745,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that there are <b>at most</b> <i>n</i> elements in the actual group satisfying the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;Integer&gt; oneTwoThree = newArrayList(1, 2, 3);
    *
    * Condition&lt;Integer&gt; oddNumber = new Condition&lt;Integer&gt;() {
@@ -764,7 +773,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that there are <b>exactly</b> <i>n</i> elements in the actual group satisfying the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;Integer&gt; oneTwoThree = newArrayList(1, 2, 3);
    *
    * Condition&lt;Integer&gt; odd = new Condition&lt;Integer&gt;() {
@@ -809,7 +818,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that there are <b>at least <i>n</i></b> elements in the actual group satisfying the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;Integer&gt; oneTwoThree = newArrayList(1, 2, 3);
    *
    * Condition&lt;Integer&gt; oddNumber = new Condition&lt;Integer&gt;() {
@@ -835,7 +844,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that there are <b>at most</b> <i>n</i> elements in the actual group satisfying the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;Integer&gt; oneTwoThree = newArrayList(1, 2, 3);
    *
    * Condition&lt;Integer&gt; oddNumber = new Condition&lt;Integer&gt;() {
@@ -862,7 +871,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that there are <b>exactly</b> <i>n</i> elements in the actual group satisfying the given condition.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;Integer&gt; oneTwoThree = newArrayList(1, 2, 3);
    *
    * Condition&lt;Integer&gt; oddNumber = new Condition&lt;Integer&gt;() {
@@ -889,7 +898,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the actual group contains all the elements of given {@code Iterable}, in any order.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = Arrays.asList("a", "b", "c");
    * 
    * // assertions will pass
@@ -913,7 +922,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that all elements of the actual group are instances of the given types.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;? extends Object&gt; objects = Arrays.asList("foo", new StringBuilder());
    * 
    * // assertions will pass
@@ -996,9 +1005,9 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
 
   /**
    * Same as {@link #containsExactly(Object...)} but handle the {@link Iterable} to array conversion : verifies that
-   * actual contains all the elements of the given iterable and nothing else <b>in the same order</b>.
+   * actual contains exactly the elements of the given iterable and nothing else <b>in the same order</b>.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;Ring&gt; elvesRings = newArrayList(vilya, nenya, narya);
    * 
    * // assertion will pass
@@ -1021,7 +1030,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
    * <p>
    * Use {@link #isSubsetOf(Iterable)} to check that actual is a subset of given iterable
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;Ring&gt; rings = newArrayList(nenya, vilya);
    * 
    * // assertion will pass
@@ -1139,7 +1148,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the actual {@link Iterable} contains at least one of the given values.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = Arrays.asList("a", "b", "c");
    *
    * // assertions will pass
@@ -1168,7 +1177,7 @@ public interface ObjectEnumerableAssert<SELF extends ObjectEnumerableAssert<SELF
   /**
    * Verifies that the {@link Iterable} under test contains at least one of the given {@link Iterable} elements.
    * <p>
-   * Example :
+   * Example:
    * <pre><code class='java'> Iterable&lt;String&gt; abc = Arrays.asList("a", "b", "c");
    *
    * // assertions will pass