#660 add except because (#666)

* add because method for documenting the reason for the following assertion/s

Co-authored-by: Valefant <valentino.bernardo_ciddio@smail.th-koeln.de>

The format in this commit is not yet correct

misc/specs/atrium-specs-common/src/main/kotlin/ch/tutteli/atrium/specs/integration/AnyAssertionsSpec.kt

@@ -40,6 +40,9 @@ abstract class AnyAssertionsSpec(
     isNotInDataClass: Fun1<DataClass, Iterable<DataClass>>,
     isNotInNullableInt: Fun1<Int?, Iterable<Int?>>,
     isNotInNullableDataClass: Fun1<DataClass?, Iterable<DataClass?>>,
+    because: Fun2<String, String, Expect<String>.() -> Unit>,
+    becauseInt: Fun2<Int, String, Expect<Int>.() -> Unit>,
+    informationBulletPoint: String,
 
     toBeNull: Fun0<Int?>,
     toBeNullIfNullGivenElse: Fun1<Int?, (Expect<Int>.() -> Unit)?>,
@@ -690,7 +693,6 @@ abstract class AnyAssertionsSpec(
         }
 
         context("subject is a subtype") {
-
             val isASuperTypeFunctions = unifySignatures<Any?, SuperType>(isASuperTypeFeature, isASuperType)
 
             context("it allows to perform sub assertions") {
@@ -732,7 +734,6 @@ abstract class AnyAssertionsSpec(
         }
     }
 
-
     prefixedDescribe("property `${andPair.name}` immediate") {
         it("returns the same container") {
             val container = expect(1)
@@ -746,6 +747,43 @@ abstract class AnyAssertionsSpec(
         }
     }
 
+    prefixedDescribe("because") {
+        val becauseFun = because.lambda
+        val becauseFunForInt = becauseInt.lambda
+
+        it("the test on the supplied subject is not throwing an assertion error") {
+            expect("filename")
+                .becauseFun("? is not allowed in file names on Windows") {
+                    containsNot("?")
+                }
+        }
+
+        it("provoke the failing of one assertion") {
+            expect {
+                expect("filename?")
+                    .becauseFun("? is not allowed in file names on Windows") {
+                        containsNot("?")
+                        startsWith("f")
+                    }
+            }.toThrow<AssertionError> {
+                messageContains("${informationBulletPoint}${String.format(BECAUSE.getDefault(), "? is not allowed in file names on Windows")}")
+            }
+        }
+
+        it("provoke the failing of two assertions") {
+            expect {
+                expect(21)
+                    .becauseFunForInt("we use the definition that teens are between 12 and 18 years old") {
+                        isGreaterThanOrEqual(12)
+                        isLessThan(18)
+                        isNoneOf(21)
+                    }
+            }.toThrow<AssertionError> {
+                messageContains("${informationBulletPoint}${String.format(BECAUSE.getDefault(), "we use the definition that teens are between 12 and 18 years old")}")
+            }
+        }
+    }
+
 }) {
     data class DataClass(val isWhatever: Boolean)
     open class SuperType

misc/specs/atrium-specs-common/src/main/kotlin/ch/tutteli/atrium/specs/reporting/AssertionFormatterControllerSpec.kt

@@ -31,6 +31,7 @@ abstract class AssertionFormatterControllerSpec(
     val testee = testeeFactory()
     val arrow = "  >>"
     val warning = "  !!"
+    val information = "ℹ"
     val bulletPoint = "*"
     val listBulletPoint = "=="
     val successfulBulletPoint = "(check)"
@@ -141,6 +142,14 @@ abstract class AssertionFormatterControllerSpec(
                             listOf(failingAssertion)
                         ),
                         warning
+                    ),
+                    Triple(
+                        "$groupName with type ${InformationAssertionGroupType::class.simpleName}",
+                        factory(InformationAssertionGroupType, listOf(holdingAssertion)) to factory(
+                            InformationAssertionGroupType,
+                            listOf(failingAssertion)
+                        ),
+                        information
                     )
                 ).forEach { (description, factories, prefix) ->
                     val (holdingGroup, failingGroup) = factories

misc/specs/atrium-specs-common/src/main/kotlin/ch/tutteli/atrium/specs/reporting/TextInformationAssertionGroupFormatterSpec.kt

@@ -0,0 +1,19 @@
+package ch.tutteli.atrium.specs.reporting
+
+import ch.tutteli.atrium.assertions.BulletPointIdentifier
+import ch.tutteli.atrium.assertions.InformationAssertionGroupType
+import ch.tutteli.atrium.assertions.builders.assertionBuilder
+import ch.tutteli.atrium.reporting.AssertionFormatter
+import ch.tutteli.atrium.reporting.AssertionFormatterController
+import kotlin.reflect.KClass
+
+abstract class TextInformationAssertionGroupFormatterSpec(
+    testeeFactory: (Map<KClass<out BulletPointIdentifier>, String>, AssertionFormatterController) -> AssertionFormatter,
+    describePrefix: String = "[Atrium] "
+) : TextExplanatoryBasedAssertionGroupFormatterSpec<InformationAssertionGroupType>(
+    testeeFactory,
+    InformationAssertionGroupType::class,
+    InformationAssertionGroupType,
+    { assertionBuilder.explanatoryGroup.withInformationType.withAssertions(it).build() },
+    describePrefix
+)

misc/specs/atrium-specs-common/src/main/kotlin/ch/tutteli/atrium/specs/testutils/AsciiBulletPointReporterFactory.kt

@@ -24,7 +24,8 @@ class AsciiBulletPointReporterFactory : ReporterFactory {
                 PrefixFeatureAssertionGroupHeader::class to ">> ",
                 PrefixSuccessfulSummaryAssertion::class to "(/) ",
                 PrefixFailingSummaryAssertion::class to "(x) ",
-                WarningAssertionGroupType::class to "(!) "
+                WarningAssertionGroupType::class to "(!) ",
+                InformationAssertionGroupType::class to "(i) "
             )
             .withNoOpAtriumErrorAdjuster()
             .withOnlyFailureReporter()