Add samples for iterableExpectations of api-fluent (#906)

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/fluent/en_GB/iterableExpectations.kt

@@ -14,6 +14,8 @@ import ch.tutteli.kbox.identity
  *
  * @return The newly created builder.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainBuilder
+ *
  * @since 0.17.0
  */
 val <E, T : Iterable<E>> Expect<T>.toContain: IterableLikeContains.EntryPointStep<E, T, NoOpSearchBehaviour>
@@ -25,6 +27,8 @@ val <E, T : Iterable<E>> Expect<T>.toContain: IterableLikeContains.EntryPointSte
  *
  * @return The newly created builder.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.notToContainBuilder
+ *
  * @since 0.17.0
  */
 val <E, T : Iterable<E>> Expect<T>.notToContain: NotCheckerStep<E, T, NotSearchBehaviour>
@@ -47,6 +51,8 @@ val <E, T : Iterable<E>> Expect<T>.notToContain: NotCheckerStep<E, T, NotSearchB
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainValues
+ *
  * @since 0.17.0
  */
 fun <E, T : Iterable<E>> Expect<T>.toContain(expected: E, vararg otherExpected: E): Expect<T> =
@@ -65,6 +71,8 @@ fun <E, T : Iterable<E>> Expect<T>.toContain(expected: E, vararg otherExpected:
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainAssertion
+ *
  * @since 0.17.0
  */
 fun <E : Any, T : Iterable<E?>> Expect<T>.toContain(assertionCreatorOrNull: (Expect<E>.() -> Unit)?): Expect<T> =
@@ -86,6 +94,8 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toContain(assertionCreatorOrNull: (Exp
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainAssertions
+ *
  * @since 0.17.0
  */
 fun <E : Any, T : Iterable<E?>> Expect<T>.toContain(
@@ -105,6 +115,8 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toContain(
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainExactlyValues
+ *
  * @since 0.17.0
  */
 fun <E, T : Iterable<E>> Expect<T>.toContainExactly(expected: E, vararg otherExpected: E): Expect<T> =
@@ -127,6 +139,8 @@ fun <E, T : Iterable<E>> Expect<T>.toContainExactly(expected: E, vararg otherExp
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainExactlyAssertion
+ *
  * @since 0.17.0
  */
 fun <E : Any, T : Iterable<E?>> Expect<T>.toContainExactly(assertionCreatorOrNull: (Expect<E>.() -> Unit)?): Expect<T> =
@@ -152,6 +166,8 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toContainExactly(assertionCreatorOrNul
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainExactlyAssertions
+ *
  * @since 0.17.0
  */
 fun <E : Any, T : Iterable<E?>> Expect<T>.toContainExactly(
@@ -174,6 +190,8 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toContainExactly(
  * @throws IllegalArgumentException in case [expectedIterableLike] is not an [Iterable], [Sequence] or one of the [Array] types or the given
  * [expectedIterableLike] does not have elements (is empty).
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainExactlyElementsOf
+ *
  * @since 0.17.0
  */
 inline fun <reified E, T : Iterable<E>> Expect<T>.toContainExactlyElementsOf(
@@ -193,6 +211,8 @@ inline fun <reified E, T : Iterable<E>> Expect<T>.toContainExactlyElementsOf(
  * @throws IllegalArgumentException in case [expectedIterableLike] is not an [Iterable], [Sequence] or one of the [Array] types or the given
  * [expectedIterableLike] does not have elements (is empty).
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toContainElementsOf
+ *
  * @since 0.17.0
  */
 inline fun <reified E, T : Iterable<E>> Expect<T>.toContainElementsOf(
@@ -207,6 +227,8 @@ inline fun <reified E, T : Iterable<E>> Expect<T>.toContainElementsOf(
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.notToContain
+ *
  * @since 0.17.0
  */
 fun <E, T : Iterable<E>> Expect<T>.notToContain(expected: E, vararg otherExpected: E): Expect<T> =
@@ -221,6 +243,8 @@ fun <E, T : Iterable<E>> Expect<T>.notToContain(expected: E, vararg otherExpecte
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toHaveElementsAndAny
+ *
  * @since 0.17.0
  */
 fun <E : Any, T : Iterable<E?>> Expect<T>.toHaveElementsAndAny(assertionCreatorOrNull: (Expect<E>.() -> Unit)?): Expect<T> =
@@ -235,6 +259,8 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toHaveElementsAndAny(assertionCreatorO
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toHaveElementsAndNone
+ *
  * @since 0.17.0
  */
 fun <E : Any, T : Iterable<E?>> Expect<T>.toHaveElementsAndNone(assertionCreatorOrNull: (Expect<E>.() -> Unit)?): Expect<T> =
@@ -247,6 +273,8 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toHaveElementsAndNone(assertionCreator
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toHaveElementsAndAll
+ *
  * @since 0.17.0
  */
 fun <E : Any, T : Iterable<E?>> Expect<T>.toHaveElementsAndAll(assertionCreatorOrNull: (Expect<E>.() -> Unit)?): Expect<T> =
@@ -258,6 +286,8 @@ fun <E : Any, T : Iterable<E?>> Expect<T>.toHaveElementsAndAll(assertionCreatorO
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.toHaveElements
+ *
  * @since 0.17.0
  */
 fun <E, T : Iterable<E>> Expect<T>.toHaveElements(): Expect<T> =
@@ -269,6 +299,8 @@ fun <E, T : Iterable<E>> Expect<T>.toHaveElements(): Expect<T> =
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.notToHaveElements
+ *
  * @since 0.17.0
  */
 fun <E, T : Iterable<E>> Expect<T>.notToHaveElements(): Expect<T> =
@@ -279,6 +311,8 @@ fun <E, T : Iterable<E>> Expect<T>.notToHaveElements(): Expect<T> =
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableExpectationSamples.notToContainDuplicates
+ *
  * @since 0.17.0
  */
 fun <E, T : Iterable<E>> Expect<T>.notToContainDuplicates(): Expect<T> =

apis/fluent-en_GB/atrium-api-fluent-en_GB-common/src/test/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/IterableExpectationSamples.kt

@@ -0,0 +1,241 @@
+package ch.tutteli.atrium.api.fluent.en_GB.samples
+
+import ch.tutteli.atrium.api.fluent.en_GB.*
+import ch.tutteli.atrium.api.verbs.internal.expect
+import kotlin.test.Test
+
+class IterableExpectationSamples {
+    @Test
+    fun toContainBuilder() {
+        expect(listOf("A", "B"))
+            .toContain
+            .inOrder // order specifier
+            .only
+            .values("A", "B")
+
+        fails {
+            expect(listOf(5, 3, 2, 2, 4))
+                .toContain
+                .inAnyOrder // order specifier
+                .atMost(2)
+                .entry { // assertion group about the entry
+                    toBeGreaterThan(2)
+                }
+        }
+    }
+
+    @Test
+    fun notToContainBuilder() {
+        expect(listOf("A", "B"))
+            .notToContain
+            .elementsOf(setOf("C", "D"))
+
+        fails {
+            expect(listOf(1, 8, 5))
+                .notToContain
+                .entry { // assertion group about the entry
+                    toBeGreaterThan(6)
+                }
+        }
+    }
+
+    @Test
+    fun toContainValues() {
+        expect(listOf("A", "B", "C")).toContain("B", "C")
+
+        fails {
+            expect(setOf(4, 2, 1)).toContain(3)
+        }
+    }
+
+    @Test
+    fun toContainAssertion() {
+        val list = listOf(1, 2, 2, 4)
+        expect(list).toContain { toBeGreaterThan(3) }
+
+        fails {
+            expect(list).toContain { toBeGreaterThan(4) }
+        }
+    }
+
+    @Test
+    fun toContainAssertions() {
+        expect(listOf(1, 2, 2, 4))
+            .toContain( // multiple assertion group entries are evaluated independently
+                { toBeLessThan(2) },
+                { toBeGreaterThan(3) }
+            )
+
+        fails {
+            expect(listOf(1, 2, 2, 4))
+                .toContain(
+                    { toEqual(3) }, // fails because no element in the list equals 3
+                    { toEqual(5) }  // still evaluated and also fails
+                )
+        }
+    }
+
+    @Test
+    fun toContainExactlyValues() {
+        expect(listOf(1, 2, 2, 4)).toContainExactly(1, 2, 2, 4)
+
+        fails {
+            expect(listOf("A", "B")).toContainExactly("A", "B", "C")
+        }
+
+        fails {
+            expect(listOf("A", "B")).toContainExactly("B", "A")
+        }
+    }
+
+    @Test
+    fun toContainExactlyAssertion() {
+        expect(listOf(4)).toContainExactly {
+            toBeLessThan(5)
+            toBeGreaterThan(3)
+        }
+
+        expect(listOf(null)).toContainExactly(null)
+
+        fails {
+            expect(listOf("A", "B")).toContainExactly {
+                toEqual("A")
+            }
+        }
+
+        fails {
+            expect(listOf(null, "B")).toContainExactly(null)
+        }
+    }
+
+    @Test
+    fun toContainExactlyAssertions() {
+        expect(listOf(3, 5, null)).toContainExactly(
+            { toEqual(3) },
+            { toBeLessThan(11) },
+            null
+        )
+
+        fails {
+            expect(listOf(3, 5, 7)).toContainExactly(
+                { toBeGreaterThan(2) },
+                { toBeLessThan(11) }
+            )
+        }
+
+        fails {
+            expect(listOf(3, 5)).toContainExactly(
+                { toEqual(1) }, // fails
+                { toBeLessThan(11) } // this assertion is not checked
+            )
+        }
+    }
+
+    @Test
+    fun toContainExactlyElementsOf() {
+        expect(listOf(1, 2, 2, 4)).toContainExactlyElementsOf(listOf(1, 2, 2, 4))
+
+        fails {
+            expect(listOf(2, 3, 4)).toContainExactlyElementsOf(listOf(2, 3, 4, 1))
+        }
+
+        fails {
+            expect(listOf(1, 2, 2, 4)).toContainExactlyElementsOf(listOf(1, 2, 4))
+        }
+    }
+
+    @Test
+    fun toContainElementsOf() {
+        expect(listOf(1, 2, 2, 4)).toContainElementsOf(listOf(1, 2, 4))
+
+        fails {
+            expect(listOf(1, 2, 2, 4)).toContainElementsOf(listOf(1, 2, 3))
+        }
+    }
+
+    @Test
+    fun notToContain() {
+        expect(listOf("A", "B", "C")).notToContain("D", "E")
+
+        fails {
+            expect(listOf("A", "B", "C")).notToContain("A", "D")
+        }
+    }
+
+    @Test
+    fun toHaveElementsAndAny() {
+        expect(listOf(1, 2, 2, 4)).toHaveElementsAndAny {
+            toBeGreaterThan(1)
+            toBeLessThan(3)
+        }
+
+        fails {
+            expect(emptyList<Int>()).toHaveElementsAndAny { toBeLessThan(11) }
+        }
+
+        fails {
+            expect(listOf(1, 2, 2, 4)).toHaveElementsAndAny {
+                toBeGreaterThan(5)
+            }
+        }
+    }
+
+    @Test
+    fun toHaveElementsAndNone() {
+        expect(listOf(1, 2, 2, 4)).toHaveElementsAndNone {
+            toEqual(3)
+        }
+
+        fails {
+            expect(emptyList<Int>()).toHaveElementsAndNone { toEqual(11) }
+        }
+
+        fails {
+            expect(listOf(1, 2, 2, 4)).toHaveElementsAndNone {
+                toBeLessThanOrEqualTo(1)
+            }
+        }
+    }
+
+    @Test
+    fun toHaveElementsAndAll() {
+        expect(listOf(1, 2, 2, 4)).toHaveElementsAndAll { toBeGreaterThan(0) }
+
+        fails {
+            expect(emptyList<Int>()).toHaveElementsAndAll { toBeGreaterThan(0) }
+        }
+
+        fails {
+            expect(listOf(1, 2, 2, 4)).toHaveElementsAndNone {
+                toBeLessThanOrEqualTo(1)
+            }
+        }
+    }
+
+    @Test
+    fun toHaveElements() {
+        expect(listOf("A", 1, 3f)).toHaveElements()
+
+        fails {
+            expect(emptyList<Int>()).toHaveElements()
+        }
+    }
+
+    @Test
+    fun notToHaveElements() {
+        expect(setOf<String>()).notToHaveElements()
+
+        fails {
+            expect(listOf("A", "B")).notToHaveElements()
+        }
+    }
+
+    @Test
+    fun notToContainDuplicates() {
+        expect(listOf("A", "B")).notToContainDuplicates()
+
+        fails {
+            expect(listOf("A", "B", "C", "A")).notToContainDuplicates()
+        }
+    }
+}