Apply renaming of with*FailureHint -> withHelpOn*Failure for issue #671 (#970)

2026-03-09 23:51:18 +00:00 · 2021-08-30 14:30:38 -06:00
parent f074b5d925
commit 50a28dce03
8 changed files with 116 additions and 28 deletions
--- a/core/atrium-core-common/src/main/kotlin/ch/tutteli/atrium/assertions/builders/descriptiveWithFailureHint.kt
+++ b/core/atrium-core-common/src/main/kotlin/ch/tutteli/atrium/assertions/builders/descriptiveWithFailureHint.kt
@@ -14,9 +14,22 @@ import ch.tutteli.atrium.reporting.translating.Translatable
 * Option to create a [DescriptiveAssertion] like assertion with an additional hint which might be shown if the
 * [Descriptive.DescriptionOption.test] fails.
 *
- * You can use [withFailureHintBasedOnSubject] or [withFailureHintBasedOnDefinedSubject]
+ * You can use [withHelpOnFailureBasedOnSubject] or [withHelpOnFailureBasedOnDefinedSubject]
 * in case your [DescriptiveAssertion] is based on the subject.
 */
+fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnFailure(
+    failureHintFactory: () -> Assertion
+): DescriptiveAssertionWithFailureHint.ShowOption =
+    DescriptiveAssertionWithFailureHint.ShowOption.create(test, failureHintFactory)
+
+/**
+ * Option to create a [DescriptiveAssertion] like assertion with an additional hint which might be shown if the
+ * [Descriptive.DescriptionOption.test] fails.
+ *
+ * You can use [withHelpOnFailureBasedOnSubject] or [withHelpOnFailureBasedOnDefinedSubject]
+ * in case your [DescriptiveAssertion] is based on the subject.
+ */
+@Deprecated("Use withHelpOnFailure; will be removed with 1.0.0")
 fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHint(
    failureHintFactory: () -> Assertion
 ): DescriptiveAssertionWithFailureHint.ShowOption =
@@ -27,20 +40,50 @@ fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHint(
 * which is based on the subject of the expectation and
 * which is only shown the subject is defined.
 *
- * You can use [withFailureHintBasedOnSubject] in case you want to:
+ * You can use [withHelpOnFailureBasedOnSubject] in case you want to:
 * - provide a hint also if the subject is absent.
 * - do not show the hint in certain cases even if the subject is defined
 *
- * Or use [withFailureHint] which does not expect a [subjectProvider] in case your [DescriptiveAssertion] is not based
+ * Or use [withHelpOnFailure] which does not expect a [subjectProvider] in case your [DescriptiveAssertion] is not based
 * on the subject of the expectation.
 */
 //TODO if we introduce Record or something else as replacement for Assertion then not but if we keep Assertion
 // then move to logic and expect ProofContainer with 0.18.0
+fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnFailureBasedOnDefinedSubject(
+    expect: Expect<T>,
+    failureHintFactory: (T) -> Assertion
+): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> {
+    return withHelpOnFailureBasedOnSubject(expect) {
+        ifDefined(failureHintFactory)
+            .ifAbsent {
+                assertionBuilder.explanatoryGroup
+                    .withWarningType
+                    .withExplanatoryAssertion(Text(SHOULD_NOT_BE_SHOWN_TO_THE_USER_BUG))
+                    .build()
+            }
+    }.showOnlyIfSubjectDefined(expect)
+}
+
+/**
+ * Option to create a [DescriptiveAssertion] like assertion with an additional hint
+ * which is based on the subject of the expectation and
+ * which is only shown the subject is defined.
+ *
+ * You can use [withHelpOnFailureBasedOnSubject] in case you want to:
+ * - provide a hint also if the subject is absent.
+ * - do not show the hint in certain cases even if the subject is defined
+ *
+ * Or use [withHelpOnFailure] which does not expect a [subjectProvider] in case your [DescriptiveAssertion] is not based
+ * on the subject of the expectation.
+ */
+//TODO if we introduce Record or something else as replacement for Assertion then not but if we keep Assertion
+// then move to logic and expect ProofContainer with 0.18.0
+@Deprecated("Use withHelpOnFailureBasedOnDefinedSubject; will be removed with 1.0.0")
 fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHintBasedOnDefinedSubject(
    expect: Expect<T>,
    failureHintFactory: (T) -> Assertion
 ): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> {
-    return withFailureHintBasedOnSubject(expect) {
+    return withHelpOnFailureBasedOnSubject(expect) {
        ifDefined(failureHintFactory)
            .ifAbsent {
                assertionBuilder.explanatoryGroup
@@ -56,13 +99,33 @@ fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHintBase
 * (which is based on the subject of the expectation)
 * which might be shown if the [Descriptive.DescriptionOption.test] fails.
 *
- * You can use [withFailureHint] which does not expect a [expect] in case your [DescriptiveAssertion] is not based
+ * You can use [withHelpOnFailure] which does not expect a [expect] in case your [DescriptiveAssertion] is not based
 * on the subject of the expectation.
 */
+fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnFailureBasedOnSubject(
+    expect: Expect<T>,
+    failureHintSubStep: DescriptiveAssertionWithFailureHint.FailureHintSubjectDefinedOption<T>.() -> Pair<() -> Assertion, (T) -> Assertion>
+): DescriptiveAssertionWithFailureHint.ShowOption = withHelpOnFailure {
+    SubjectBasedOption(
+        expect,
+        failureHintSubStep,
+        DescriptiveAssertionWithFailureHint.FailureHintSubjectDefinedOption.Companion::create
+    )
+}
+
+/**
+ * Option to create a [DescriptiveAssertion] like assertion with an additional hint
+ * (which is based on the subject of the expectation)
+ * which might be shown if the [Descriptive.DescriptionOption.test] fails.
+ *
+ * You can use [withHelpOnFailure] which does not expect a [expect] in case your [DescriptiveAssertion] is not based
+ * on the subject of the expectation.
+ */
+@Deprecated("Use withHelpOnFailureBasedOnSubject; will be removed with 1.0.0")
 fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHintBasedOnSubject(
    expect: Expect<T>,
    failureHintSubStep: DescriptiveAssertionWithFailureHint.FailureHintSubjectDefinedOption<T>.() -> Pair<() -> Assertion, (T) -> Assertion>
-): DescriptiveAssertionWithFailureHint.ShowOption = withFailureHint {
+): DescriptiveAssertionWithFailureHint.ShowOption = withHelpOnFailure {
    SubjectBasedOption(
        expect,
        failureHintSubStep,
--- a/core/atrium-core-common/src/main/kotlin/ch/tutteli/atrium/creating/impl/CollectingExpectImpl.kt
+++ b/core/atrium-core-common/src/main/kotlin/ch/tutteli/atrium/creating/impl/CollectingExpectImpl.kt
@@ -40,7 +40,7 @@ internal class CollectingExpectImpl<T>(
        } else {
            allAssertions.add(assertionBuilder.descriptive
                .failing
-                .withFailureHint {
+                .withHelpOnFailure {
                    assertionBuilder.explanatoryGroup
                        .withDefaultType
                        .withAssertions(
--- a/core/atrium-core-common/src/test/kotlin/ch/tutteli/atrium/assertions/builders/DescriptiveWithBasedOnSubjectSpec.kt
+++ b/core/atrium-core-common/src/test/kotlin/ch/tutteli/atrium/assertions/builders/DescriptiveWithBasedOnSubjectSpec.kt
@@ -20,17 +20,17 @@ class DescriptiveWithBasedOnSubjectSpec : Spek({
                .withDescriptionAndRepresentation("what ever", 1)
                .build()
        },
-        "withFailureHintBasedOnDefinedSubject" to addDescriptive { expect, builder ->
+        "withHelpOnFailureBasedOnDefinedSubject" to addDescriptive { expect, builder ->
            builder.failing
-                .withFailureHintBasedOnDefinedSubject(expect) {
+                .withHelpOnFailureBasedOnDefinedSubject(expect) {
                    assertionBuilder.explanatory.withExplanation("asdf").build()
                }
                .withDescriptionAndRepresentation("what ever", 1)
                .build()
        },
-        "withFailureHintBasedOnSubject" to addDescriptive { expect, builder ->
+        "withHelpOnFailureBasedOnSubject" to addDescriptive { expect, builder ->
            builder.failing
-                .withFailureHintBasedOnSubject(expect) {
+                .withHelpOnFailureBasedOnSubject(expect) {
                    ifDefined {
                        assertionBuilder.explanatory.withExplanation("asdf").build()
                    } ifAbsent {
@@ -43,7 +43,7 @@ class DescriptiveWithBasedOnSubjectSpec : Spek({
        },
        "showOnlyIf" to addDescriptive { expect, builder ->
            builder.failing
-                .withFailureHint { assertionBuilder.explanatory.withExplanation("any hint").build() }
+                .withHelpOnFailure { assertionBuilder.explanatory.withExplanation("any hint").build() }
                .showBasedOnSubjectOnlyIf(expect) {
                    ifDefined {
                        it < 3
@@ -54,14 +54,14 @@ class DescriptiveWithBasedOnSubjectSpec : Spek({
        },
        "showOnlyIfSubjectDefined" to addDescriptive { expect, builder ->
            builder.failing
-                .withFailureHint { assertionBuilder.explanatory.withExplanation("any hint").build() }
+                .withHelpOnFailure { assertionBuilder.explanatory.withExplanation("any hint").build() }
                .showOnlyIfSubjectDefined(expect)
                .withDescriptionAndRepresentation("what ever", 1)
                .build()
        },
        "showBasedOnDefinedSubjectOnlyIf" to addDescriptive { expect, builder ->
            builder.failing
-                .withFailureHint { assertionBuilder.explanatory.withExplanation("any hint").build() }
+                .withHelpOnFailure { assertionBuilder.explanatory.withExplanation("any hint").build() }
                .showBasedOnDefinedSubjectOnlyIf(expect) { it < 3 }
                .withDescriptionAndRepresentation("what ever", 1)
                .build()
--- a/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultFloatingPointAssertions.kt
+++ b/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultFloatingPointAssertions.kt
@@ -3,7 +3,7 @@ package ch.tutteli.atrium.logic.impl
 import ch.tutteli.atrium.assertions.Assertion
 import ch.tutteli.atrium.assertions.ExplanatoryAssertion
 import ch.tutteli.atrium.assertions.builders.assertionBuilder
-import ch.tutteli.atrium.assertions.builders.withFailureHintBasedOnDefinedSubject
+import ch.tutteli.atrium.assertions.builders.withHelpOnFailureBasedOnDefinedSubject
 import ch.tutteli.atrium.core.polyfills.formatFloatingPointNumber
 import ch.tutteli.atrium.core.polyfills.fullName
 import ch.tutteli.atrium.creating.AssertionContainer
@@ -74,7 +74,7 @@ internal fun <T : Comparable<T>> toBeWithErrorTolerance(
 ): Assertion =
    assertionBuilder.descriptive
    .withTest(container.toExpect()) { absDiff(it) <= tolerance }
-    .withFailureHintBasedOnDefinedSubject(container.toExpect()) { subject ->
+    .withHelpOnFailureBasedOnDefinedSubject(container.toExpect()) { subject ->
        //TODO 0.18.0 that's not nice in case we use it in an Iterable contains assertion, for instance contains...entry { toBeWithErrorTolerance(x, 0.01) }
        //we do not want to see the failure nor the exact check in the 'an entry which...' part
        //same problematic applies to feature assertions within an identification lambda
--- a/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultIterableLikeAssertions.kt
+++ b/logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultIterableLikeAssertions.kt
@@ -134,7 +134,7 @@ class DefaultIterableLikeAssertions : IterableLikeAssertions {
                val (element, indices) = pair
                assertionBuilder.descriptive
                    .failing
-                    .withFailureHint {
+                    .withHelpOnFailure {
                        assertionBuilder.explanatoryGroup
                            .withDefaultType
                            .withExplanatoryAssertion(
--- a/logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/creating/filesystem/hints/hints.kt
+++ b/logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/creating/filesystem/hints/hints.kt
@@ -22,21 +22,46 @@ import java.nio.file.Path
 import java.nio.file.attribute.*
 import java.util.*

-inline fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withIOExceptionFailureHint(
+inline fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnIOExceptionFailure(
    expect: Expect<IoResult<T>>,
    crossinline f: (Path, IOException) -> Assertion?
 ): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
-    withFailureHintBasedOnDefinedSubject(expect) { result ->
+    withHelpOnFailureBasedOnDefinedSubject(expect) { result ->
        explainForResolvedLink(result.path) { realPath ->
            val exception = (result as Failure).exception
            f(realPath, exception) ?: hintForIoException(realPath, exception)
        }
    }

+@Deprecated("Use withHelpOnIOExceptionFailure; will be removed with 1.0.0")
+inline fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withIOExceptionFailureHint(
+    expect: Expect<IoResult<T>>,
+    crossinline f: (Path, IOException) -> Assertion?
+): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
+    withHelpOnFailureBasedOnDefinedSubject(expect) { result ->
+        explainForResolvedLink(result.path) { realPath ->
+            val exception = (result as Failure).exception
+            f(realPath, exception) ?: hintForIoException(realPath, exception)
+        }
+    }
+
+fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnFileAttributesFailure(
+    expect: Expect<IoResult<BasicFileAttributes>>
+): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
+    withHelpOnFailureBasedOnDefinedSubject(expect) { result ->
+        explainForResolvedLink(result.path) { realPath ->
+            when (result) {
+                is Success -> describeWas(result.value.fileType)
+                is Failure -> hintForIoException(realPath, result.exception)
+            }
+        }
+    }
+
+@Deprecated("Use withHelpOnFileAttributesFailure; will be removed with 1.0.0")
 fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withFileAttributesFailureHint(
    expect: Expect<IoResult<BasicFileAttributes>>
 ): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
-    withFailureHintBasedOnDefinedSubject(expect) { result ->
+    withHelpOnFailureBasedOnDefinedSubject(expect) { result ->
        explainForResolvedLink(result.path) { realPath ->
            when (result) {
                is Success -> describeWas(result.value.fileType)
--- a/logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultBigDecimalAssertions.kt
+++ b/logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultBigDecimalAssertions.kt
@@ -8,7 +8,7 @@ package ch.tutteli.atrium.logic.impl
 import ch.tutteli.atrium.assertions.Assertion
 import ch.tutteli.atrium.assertions.builders.assertionBuilder
 import ch.tutteli.atrium.assertions.builders.withExplanatoryAssertion
-import ch.tutteli.atrium.assertions.builders.withFailureHint
+import ch.tutteli.atrium.assertions.builders.withHelpOnFailure
 import ch.tutteli.atrium.creating.AssertionContainer
 import ch.tutteli.atrium.logic.BigDecimalAssertions
 import ch.tutteli.atrium.logic.createDescriptiveAssertion
@@ -37,7 +37,7 @@ class DefaultBigDecimalAssertions : BigDecimalAssertions {
    ): Assertion =
        assertionBuilder.descriptive
            .withTest(container.toExpect()) { it == expected }
-            .withFailureHint {
+            .withHelpOnFailure {
                assertionBuilder.explanatoryGroup
                    .withInformationType(withIndent = true)
                    .withExplanatoryAssertion(
--- a/logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultPathAssertions.kt
+++ b/logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultPathAssertions.kt
@@ -8,7 +8,7 @@ package ch.tutteli.atrium.logic.impl
 import ch.tutteli.atrium.assertions.Assertion
 import ch.tutteli.atrium.assertions.builders.assertionBuilder
 import ch.tutteli.atrium.assertions.builders.invisibleGroup
-import ch.tutteli.atrium.assertions.builders.withFailureHintBasedOnDefinedSubject
+import ch.tutteli.atrium.assertions.builders.withHelpOnFailureBasedOnDefinedSubject
 import ch.tutteli.atrium.core.None
 import ch.tutteli.atrium.core.Some
 import ch.tutteli.atrium.creating.AssertionContainer
@@ -63,7 +63,7 @@ class DefaultPathAssertions : PathAssertions {
        changeSubjectToFileAttributes(container, linkOption) { fileAttributesExpect ->
            assertionBuilder.descriptive
                .withTest(fileAttributesExpect) { it is Success }
-                .withIOExceptionFailureHint(fileAttributesExpect) { realPath, exception ->
+                .withHelpOnIOExceptionFailure(fileAttributesExpect) { realPath, exception ->
                    when (exception) {
                        // TODO remove group once https://github.com/robstoll/atrium-roadmap/issues/1 is implemented
                        is NoSuchFileException -> assertionBuilder.explanatoryGroup
@@ -82,7 +82,7 @@ class DefaultPathAssertions : PathAssertions {
        changeSubjectToFileAttributes(container, linkOption) { fileAttributesExpect ->
            assertionBuilder.descriptive
                .withTest(fileAttributesExpect) { it is Failure && it.exception is NoSuchFileException }
-                .withFileAttributesFailureHint(fileAttributesExpect)
+                .withHelpOnFileAttributesFailure(fileAttributesExpect)
                .withDescriptionAndRepresentation(DescriptionBasic.NOT_TO, EXIST)
                .build()
        }
@@ -130,7 +130,7 @@ class DefaultPathAssertions : PathAssertions {
    }.let { checkAccessResultExpect ->
        assertionBuilder.descriptive
            .withTest(checkAccessResultExpect) { it is Success }
-            .withIOExceptionFailureHint(checkAccessResultExpect) { realPath, exception ->
+            .withHelpOnIOExceptionFailure(checkAccessResultExpect) { realPath, exception ->
                when (exception) {
                    is AccessDeniedException -> findHintForProblemWithParent(realPath)
                        ?: assertionBuilder.explanatoryGroup
@@ -155,7 +155,7 @@ class DefaultPathAssertions : PathAssertions {
    ) = changeSubjectToFileAttributes(container, linkOption) { fileAttributesExpect ->
        assertionBuilder.descriptive
            .withTest(fileAttributesExpect) { it is Success && typeTest(it.value) }
-            .withFileAttributesFailureHint(fileAttributesExpect)
+            .withHelpOnFileAttributesFailure(fileAttributesExpect)
            .withDescriptionAndRepresentation(DescriptionBasic.IS, typeName)
            .build()
    }
@@ -204,7 +204,7 @@ class DefaultPathAssertions : PathAssertions {
            }.let { expectResult ->
                assertionBuilder.descriptive
                    .withTest(expectResult) { it is Success && it.value.isEmpty() }
-                    .withFailureHintBasedOnDefinedSubject(expectResult) { ioResult ->
+                    .withHelpOnFailureBasedOnDefinedSubject(expectResult) { ioResult ->
                        explainForResolvedLink(ioResult.path) { realPath ->
                            when (ioResult) {
                                is Success -> {