Add samples for infix throwable expectations (#1002)

apis/infix-en_GB/atrium-api-infix-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/infix/en_GB/throwableAssertions.kt

@@ -14,6 +14,8 @@ import kotlin.reflect.KClass
  * creates an [Expect] for it and returns it.
  *
  * @return The newly created [Expect] for the property [Throwable.message] of the subject of `this` expectation.
+ *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.ThrowableExpectationSamples.messageFeature
  */
 val <T : Throwable> Expect<T>.message: Expect<String>
     get() = it feature Throwable::message notToEqualNull o
@@ -25,6 +27,8 @@ val <T : Throwable> Expect<T>.message: Expect<String>
  * returns an [Expect] for the current subject of `this` expectation.
  *
  * @return an [Expect] for the subject of `this` expectation.
+ *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.ThrowableExpectationSamples.message
  */
 infix fun <T : Throwable> Expect<T>.message(assertionCreator: Expect<String>.() -> Unit): Expect<T> =
     it feature of(Throwable::message) { it notToEqualNull assertionCreator }
@@ -78,6 +82,8 @@ infix fun <T : Throwable> Expect<T>.messageContains(values: Values<Any>): Expect
  *
  * @return The newly created [Expect] for the property [Throwable.cause] of the subject of `this` expectation
  *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.ThrowableExpectationSamples.causeFeature
+ *
  * @since 0.12.0
  */
 inline fun <reified TExpected : Throwable> Expect<out Throwable>.cause(): Expect<TExpected> =
@@ -101,6 +107,8 @@ internal fun <TExpected : Throwable> Expect<out Throwable>.causeIsA(
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.ThrowableExpectationSamples.cause
+ *
  * @since 0.12.0
  */
 inline infix fun <reified TExpected : Throwable> Expect<out Throwable>.cause(

apis/infix-en_GB/atrium-api-infix-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/infix/en_GB/throwableExpectations.kt

@@ -18,6 +18,8 @@ import kotlin.reflect.KClass
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.ThrowableExpectationSamples.messageToContain
+ *
  * @since 0.17.0
  */
 infix fun <T : Throwable> Expect<T>.messageToContain(expected: CharSequenceOrNumberOrChar): Expect<T> =
@@ -35,6 +37,8 @@ infix fun <T : Throwable> Expect<T>.messageToContain(expected: CharSequenceOrNum
  *
  * @return an [Expect] for the subject of `this` expectation.
  *
+ * @sample ch.tutteli.atrium.api.infix.en_GB.samples.ThrowableExpectationSamples.messageFeature
+ *
  * @since 0.17.0
  */
 infix fun <T : Throwable> Expect<T>.messageToContain(values: Values<Any>): Expect<T> =

apis/infix-en_GB/atrium-api-infix-en_GB-common/src/test/kotlin/ch/tutteli/atrium/api/infix/en_GB/samples/ThrowableExpectationSamples.kt

@@ -0,0 +1,68 @@
+package ch.tutteli.atrium.api.infix.en_GB.samples
+
+import ch.tutteli.atrium.api.infix.en_GB.*
+import ch.tutteli.atrium.api.verbs.internal.expect
+import kotlin.test.Test
+
+class ThrowableExpectationSamples {
+
+    @Test
+    fun messageToContain() {
+        expect(RuntimeException("abc")) messageToContain "b"
+
+        fails {
+            expect(RuntimeException("abc")) messageToContain "d"
+        }
+    }
+
+    @Test
+    fun messageFeature() {
+        expect(RuntimeException("abc")).message toContain "a"
+        //                                 | subject is now of type String
+
+        fails {
+            expect(RuntimeException("abc")).message toContain "d"
+            //                                 | subject is now of type String
+        }
+    }
+
+    @Test
+    fun message() {
+        expect(RuntimeException("abc")) message { // subject inside this block is of type String (actually "abc")
+            toContain("a")
+        }
+
+        fails {
+            expect(RuntimeException("abc")) message { // subject inside this block is of type String (actually "abc")
+                toContain("d")
+            }
+        }
+    }
+
+    @Test
+    fun causeFeature() {
+        expect(IllegalStateException(IndexOutOfBoundsException("abc")))
+            .cause<IndexOutOfBoundsException>() messageToContain "b"
+        //     | subject is now of type IndexOutOfBoundsException
+
+        fails {
+            expect(IllegalStateException(IndexOutOfBoundsException("abc")))
+                .cause<IllegalStateException>() messageToContain "d" // not shown in reporting as `cause<IllegalStateException>()` already fails
+
+        }
+    }
+
+    @Test
+    fun cause() {
+        expect(IllegalStateException(IndexOutOfBoundsException("abc")))
+            .cause<IndexOutOfBoundsException> { // subject is now of type IndexOutOfBoundsException
+                it messageToContain "b"
+            }
+
+        fails { // because wrong type expected (IllegalStateException instead of IndexOutOfBoundsException), but since we use a block...
+            expect(IllegalStateException(IndexOutOfBoundsException("abc"))).cause<IllegalStateException> {
+                it messageToContain "b" // ... reporting mentions that subject's message was expected `to contain: "b"`
+            }
+        }
+    }
+}