ADD: samples of iterableSubjectChangers in api-infix and api-fluent (#…

…1155)

* ADD: samples for iterableSubjectChangers in api-infix and api-fluent

* MOD: rename sample files and add comments

* MOD: rename method paths of @sample tag

* MOD: align spaces

* MOD: align spaces

* move the comment

apis/fluent-en_GB/atrium-api-fluent-en_GB/src/commonMain/kotlin/ch/tutteli/atrium/api/fluent/en_GB/iterableSubjectChangers.kt

@@ -12,6 +12,8 @@ import ch.tutteli.atrium.logic.changeSubject
  *
  * @return The newly created [Expect] for the transformed subject.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableSubjectChangerSamples.asListFeature
+ *
  * @since 0.14.0
  */
 fun <E, T : Iterable<E>> Expect<T>.asList(): Expect<List<E>> = _logic.changeSubject.unreported { it.toList() }
@@ -25,6 +27,8 @@ fun <E, T : Iterable<E>> Expect<T>.asList(): Expect<List<E>> = _logic.changeSubj
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.IterableSubjectChangerSamples.asList
+ *
  * @since 0.14.0
  */
 fun <E, T : Iterable<E>> Expect<T>.asList(assertionCreator: Expect<List<E>>.() -> Unit): Expect<T> =

apis/fluent-en_GB/atrium-api-fluent-en_GB/src/commonTest/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/IterableSubjectChangerSamples.kt

@@ -0,0 +1,44 @@
+package ch.tutteli.atrium.api.fluent.en_GB.samples
+
+import ch.tutteli.atrium.api.fluent.en_GB.asList
+import ch.tutteli.atrium.api.fluent.en_GB.toContain
+import ch.tutteli.atrium.api.fluent.en_GB.toEqual
+import ch.tutteli.atrium.api.verbs.internal.expect
+import kotlin.test.Test
+
+class IterableSubjectChangerSamples {
+    @Test
+    fun asListFeature() {
+        expect(0..2)
+            .asList()  // subject is now of type List<Int>
+            .toEqual(listOf(0, 1, 2))
+
+        fails {
+            expect(0..2)
+                .asList()  // subject is now of type List<Int>
+                .toContain(3)  // fails
+                .toContain(4)  // not evaluated/reported because above `toContain` already fails
+            //                    use `.asList { ... }` if you want that all expectations are evaluated
+        }
+    }
+
+    @Test
+    fun asList() {
+        expect(0..2)  // subject within this expectation-group is of type List<Int>
+            .asList {
+                toEqual(listOf(0, 1, 2))
+            }  // subject here is back to type IntRange
+
+        fails {
+            // all expectations inside an expectation-group are evaluated together; for more details see:
+            // https://github.com/robstoll/atrium#define-single-expectations-or-an-expectation-group
+
+            expect(0..2)
+                .asList {
+                    toContain(3)  // fails
+                    toContain(4)  // still evaluated even though above `toContain` already fails
+                    //               use `.asList().` if you want a fail fast behaviour
+                }
+        }
+    }
+}

apis/infix-en_GB/atrium-api-infix-en_GB/src/commonMain/kotlin/ch/tutteli/atrium/api/infix/en_GB/iterableSubjectChangers.kt

@@ -13,6 +13,8 @@ import kotlin.jvm.JvmName
  *
  * @return The newly created [Expect] for the transformed subject.
  *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.IterableSubjectChangerSamples.asListFeature
+ *
  * @since 0.14.0
  */
 infix fun <E, T : Iterable<E>> Expect<T>.asList(
@@ -28,6 +30,8 @@ infix fun <E, T : Iterable<E>> Expect<T>.asList(
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.IterableSubjectChangerSamples.asList
+ *
  * @since 0.14.0
  */
 infix fun <E, T : Iterable<E>> Expect<T>.asList(assertionCreator: Expect<List<E>>.() -> Unit): Expect<T> =

apis/infix-en_GB/atrium-api-infix-en_GB/src/commonTest/kotlin/ch/tutteli/atrium/api/infix/en_GB/samples/IterableSubjectChangerSamples.kt

@@ -0,0 +1,40 @@
+package ch.tutteli.atrium.api.infix.en_GB.samples
+
+import ch.tutteli.atrium.api.infix.en_GB.asList
+import ch.tutteli.atrium.api.infix.en_GB.it
+import ch.tutteli.atrium.api.infix.en_GB.o
+import ch.tutteli.atrium.api.infix.en_GB.toContain
+import ch.tutteli.atrium.api.infix.en_GB.toEqual
+import ch.tutteli.atrium.api.verbs.internal.expect
+import kotlin.test.Test
+
+class IterableSubjectChangerSamples {
+    @Test
+    fun asListFeature() {
+        expect(0..2) asList o toEqual listOf(0, 1, 2)
+        //              | subject is now of type List<Int>
+
+        fails {
+            expect(0..2) asList o toContain 3 toContain 4
+        }
+    }
+
+    @Test
+    fun asList() {
+        expect(0..2)
+            .asList { // subject within this expectation-group is of type List<Int>
+                it toEqual listOf(0, 1, 2)
+            }  // subject here is back to type IntRange
+
+        fails {
+            // all expectations inside an expectation-group are evaluated together; for more details see:
+            // https://github.com/robstoll/atrium#define-single-expectations-or-an-expectation-group
+            expect(0..2)
+                .asList {
+                    it toContain 3  // fails
+                    it toContain 4  // still evaluated even though above `toContain` already fails
+                    //                 use `asList o` if you want a fail fast behaviour
+                }
+        }
+    }
+}