From 2270deb0c74faf73f85f781129305e77f6afe248 Mon Sep 17 00:00:00 2001 From: stevenlmcgraw Date: Fri, 27 Aug 2021 03:23:32 -0500 Subject: [PATCH] Apply renaming of `with*FailureHint` -> `withHelpOn*Failure` for issue #671 Update `assertions/builders/descriptiveWithFailureHint.kt`: - Add `withHelpOnFailure` and mark `withFailureHint` as deprecated - Add `withHelpOnFailureBasedOnSubject` and mark `withFailureHintBasedOnSubject` as deprecated - Add `withHelpOnFailureBasedOnDefinedSubject` and mark `withFailureHintBasedOnDefinedSubject` as deprecated Update `atrium/logic/creating/filesystem/hints/hints.kt`: - Add `withHelpOnIOExceptionFailure` and mark `withIOExceptionFailureHint` as deprecated - Add `withHelpOnFileAttributesFailure` and mark `withFileAttributesFailureHint` as deprecated Refactor all usages of `with*FailureHint` found to favor the `withHelpOn*Failure` version Update `assertions/builders/DescriptiveWithBasedOnSubjectSpec.kt`: - Refactor text referencing deprecated methods Update `atrium/logic/impl/DefaultFloatingPointAssertions.kt`: - Remove unused import for deprecated `with*FailureHint` method(s) Update `atrium/logic/impl/DefaultBigDecimalAssertions.kt`: - Remove unused import for deprecated `with*FailureHint` method(s) Update `atrium/logic/impl/DefaultPathAssertions.kt`: - Remove unused import for deprecated `with*FailureHint` method(s) --- .../builders/descriptiveWithFailureHint.kt | 75 +++++++++++++++++-- .../creating/impl/CollectingExpectImpl.kt | 2 +- .../DescriptiveWithBasedOnSubjectSpec.kt | 14 ++-- .../impl/DefaultFloatingPointAssertions.kt | 4 +- .../impl/DefaultIterableLikeAssertions.kt | 2 +- .../logic/creating/filesystem/hints/hints.kt | 29 ++++++- .../logic/impl/DefaultBigDecimalAssertions.kt | 4 +- .../logic/impl/DefaultPathAssertions.kt | 12 +-- 8 files changed, 115 insertions(+), 27 deletions(-) diff --git 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 index 41d94acc78..c2e7cc9754 100644 --- 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.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.withFailureHint( failureHintFactory: () -> Assertion ): DescriptiveAssertionWithFailureHint.ShowOption = @@ -27,20 +40,50 @@ fun Descriptive.DescriptionOption.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 Descriptive.DescriptionOption.withHelpOnFailureBasedOnDefinedSubject( + expect: Expect, + failureHintFactory: (T) -> Assertion +): Descriptive.DescriptionOption { + 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 Descriptive.DescriptionOption.withFailureHintBasedOnDefinedSubject( expect: Expect, failureHintFactory: (T) -> Assertion ): Descriptive.DescriptionOption { - return withFailureHintBasedOnSubject(expect) { + return withHelpOnFailureBasedOnSubject(expect) { ifDefined(failureHintFactory) .ifAbsent { assertionBuilder.explanatoryGroup @@ -56,13 +99,33 @@ fun Descriptive.DescriptionOption.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 Descriptive.DescriptionOption.withHelpOnFailureBasedOnSubject( + expect: Expect, + failureHintSubStep: DescriptiveAssertionWithFailureHint.FailureHintSubjectDefinedOption.() -> 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 Descriptive.DescriptionOption.withFailureHintBasedOnSubject( expect: Expect, failureHintSubStep: DescriptiveAssertionWithFailureHint.FailureHintSubjectDefinedOption.() -> Pair<() -> Assertion, (T) -> Assertion> -): DescriptiveAssertionWithFailureHint.ShowOption = withFailureHint { +): DescriptiveAssertionWithFailureHint.ShowOption = withHelpOnFailure { SubjectBasedOption( expect, failureHintSubStep, diff --git 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 index fbe9a55334..247bb50f8a 100644 --- 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( } else { allAssertions.add(assertionBuilder.descriptive .failing - .withFailureHint { + .withHelpOnFailure { assertionBuilder.explanatoryGroup .withDefaultType .withAssertions( diff --git 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 index 560425ede3..fdc177e7c0 100644 --- 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() diff --git 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 index f1e0a11b71..82ff9e324f 100644 --- 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 > 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 diff --git 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 index 9fd4f93f51..8590430dfd 100644 --- 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( diff --git 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 index 7dbd65dfa9..0d93bb6aa4 100644 --- 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 Descriptive.DescriptionOption.withHelpOnIOExceptionFailure( + expect: Expect>, + crossinline f: (Path, IOException) -> Assertion? +): Descriptive.DescriptionOption = + 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 Descriptive.DescriptionOption.withIOExceptionFailureHint( expect: Expect>, crossinline f: (Path, IOException) -> Assertion? ): Descriptive.DescriptionOption = - withFailureHintBasedOnDefinedSubject(expect) { result -> + withHelpOnFailureBasedOnDefinedSubject(expect) { result -> explainForResolvedLink(result.path) { realPath -> val exception = (result as Failure).exception f(realPath, exception) ?: hintForIoException(realPath, exception) } } +fun Descriptive.DescriptionOption.withHelpOnFileAttributesFailure( + expect: Expect> +): Descriptive.DescriptionOption = + 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.withFileAttributesFailureHint( expect: Expect> ): Descriptive.DescriptionOption = - withFailureHintBasedOnDefinedSubject(expect) { result -> + withHelpOnFailureBasedOnDefinedSubject(expect) { result -> explainForResolvedLink(result.path) { realPath -> when (result) { is Success -> describeWas(result.value.fileType) diff --git 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 index 0d4ee11abd..be25f78b7b 100644 --- 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( diff --git 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 index f225dceb55..c5edaf2df4 100644 --- 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 -> {