From a2b8e2b8782ad36110e79d71c0c19541d6a751d0 Mon Sep 17 00:00:00 2001 From: Robert Stoll Date: Fri, 11 Aug 2023 23:10:54 +0200 Subject: [PATCH] discourage usage of expect(BigDecimal).notToEqual except for null moreover: - improve the samples, include a `fails` case --- .../fluent/en_GB/bigDecimalExpectations.kt | 28 ++++++++--- .../samples/BigDecimalExpectationSamples.kt | 50 +++++++++++++------ .../api/infix/en_GB/bigDecimalExpectations.kt | 26 ++++++++-- .../samples/BigDecimalExpectationSamples.kt | 22 ++++++-- 4 files changed, 95 insertions(+), 31 deletions(-) diff --git a/apis/fluent/atrium-api-fluent/src/jvmMain/kotlin/ch/tutteli/atrium/api/fluent/en_GB/bigDecimalExpectations.kt b/apis/fluent/atrium-api-fluent/src/jvmMain/kotlin/ch/tutteli/atrium/api/fluent/en_GB/bigDecimalExpectations.kt index a094abb950..da37719a32 100644 --- a/apis/fluent/atrium-api-fluent/src/jvmMain/kotlin/ch/tutteli/atrium/api/fluent/en_GB/bigDecimalExpectations.kt +++ b/apis/fluent/atrium-api-fluent/src/jvmMain/kotlin/ch/tutteli/atrium/api/fluent/en_GB/bigDecimalExpectations.kt @@ -23,7 +23,7 @@ import java.math.BigDecimal "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.", ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)") ) -@Suppress("UNUSED_PARAMETER", "unused") +@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter") fun Expect.toEqual(expected: T): Nothing = throw PleaseUseReplacementException( "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" + @@ -42,7 +42,7 @@ fun Expect.toEqual(expected: T): Nothing = * * @since 0.17.0 */ -@Suppress("UNUSED_PARAMETER", "unused") +//TODO rename to toEqualNullable with 2.0.0 @JvmName("toBeNullable") @Deprecated( "Use `toEqualNumerically` if you expect that the following assertion holds:\n" + @@ -50,6 +50,7 @@ fun Expect.toEqual(expected: T): Nothing = "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.", ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)") ) +@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter") fun Expect.toEqual(expected: T): Nothing = throw PleaseUseReplacementException( "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" + @@ -61,10 +62,11 @@ fun Expect.toEqual(expected: T): Nothing = * * @return an [Expect] for the subject of `this` expectation. * - * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.BigDecimalExpectationSamples.toEqual + * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.BigDecimalExpectationSamples.toEqualNull * * @since 0.17.0 */ +//TODO rename to toEqualNul with 2.0.0 @JvmName("toBeNull") fun Expect.toEqual(expected: Nothing?): Expect = _logicAppend { toBe(expected) } @@ -79,8 +81,6 @@ fun Expect.toEqual(expected: Nothing?): Expect = * ``` * However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use [notToEqualIncludingScale]. * - * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.BigDecimalExpectationSamples.notToEqual - * * @since 0.17.0 */ @Deprecated( @@ -89,13 +89,27 @@ fun Expect.toEqual(expected: Nothing?): Expect = "However, if you expect it to hold (because `BigDecimal.scale` differ), then use `notToEqualIncludingScale`.", ReplaceWith("notToEqualNumerically(expected) or notToEqualIncludingScale(expected)") ) -@Suppress("UNUSED_PARAMETER", "unused") -fun Expect.notToEqual(expected: T): Nothing = +@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter") +fun Expect.notToEqual(expected: T): Nothing = throw PleaseUseReplacementException( "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" + "If you know it and want that `scale` is included in the comparison, then use `notToEqualIncludingScale`." ) +/** + * Expects that the subject of `this` expectation (a [BigDecimal]) is not `null`. + * + * @return an [Expect] for the subject of `this` expectation. + * + * @sample ch.tutteli.atrium.api.fluent.en_GB.samples.BigDecimalExpectationSamples.notToEqualNull + * + * @since 1.1.0 + */ +@JvmName("notToEqualNull") +fun Expect.notToEqual(expected: Nothing?): Expect = + _logicAppend { notToBe(expected) }._logic.changeSubject.unreported { it!! } + + /** * Expects that the subject of `this` expectation (a [BigDecimal]) is numerically equal to [expected]. * diff --git a/apis/fluent/atrium-api-fluent/src/jvmTest/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/BigDecimalExpectationSamples.kt b/apis/fluent/atrium-api-fluent/src/jvmTest/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/BigDecimalExpectationSamples.kt index a66979d897..d68f91e365 100644 --- a/apis/fluent/atrium-api-fluent/src/jvmTest/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/BigDecimalExpectationSamples.kt +++ b/apis/fluent/atrium-api-fluent/src/jvmTest/kotlin/ch/tutteli/atrium/api/fluent/en_GB/samples/BigDecimalExpectationSamples.kt @@ -8,26 +8,27 @@ import kotlin.test.Test class BigDecimalExpectationSamples { @Test - fun toEqual() { - // only use toEqual to check against null, otherwise use toEqualNumerically or toEqualIncludingScale + fun toEqualNull() { + // Use toEqual only to check against null if your subject is a BigDecimal + // Use toEqualNumerically or toEqualIncludingScale if you want to compare it against another BigDecimal expect(null as BigDecimal?).toEqual(null) - } + fails { + expect(BigDecimal("-12345.6789") as BigDecimal?).toEqual(null) + } + } @Test - fun notToEqual() { - // only use notToEqual to check against null, otherwise use notToEqualNumerically or notToEqualIncludingScale - expect(null as BigDecimal?).notToEqual(BigDecimal("-12345.6789")) - expect(null as BigDecimal?).notToEqual(BigDecimal("1.0")) - expect(null as BigDecimal?).notToEqual(BigDecimal("25.0")) - - - expect(null as BigDecimal?).notToEqual(BigDecimal(-12345.6789)) - expect(null as BigDecimal?).notToEqual(BigDecimal(1.0)) - expect(null as BigDecimal?).notToEqual(BigDecimal(25.0)) + fun notToEqualNull() { + // Use notToEqual only to check against null if your subject is a BigDecimal + // Use notToEqualNumerically or notToEqualIncludingScale if you want to compare it against another BigDecimal + expect(BigDecimal("-12345.6789") as BigDecimal?).notToEqual(null) + + fails { + expect(null as BigDecimal?).notToEqual(null) + } } - @Test fun toEqualNumerically() { expect(BigDecimal("10")).toEqualNumerically(BigDecimal("10.0")) @@ -38,6 +39,10 @@ class BigDecimalExpectationSamples { expect(BigDecimal(10)).toEqualNumerically(BigDecimal(10.0)) expect(BigDecimal(1213669989183)).toEqualNumerically(BigDecimal(1213669989183)) expect(BigDecimal(1238126387123)).toEqualNumerically(BigDecimal(1238126387123)) + + fails { + expect(BigDecimal(10)).toEqualNumerically(BigDecimal(10.1)) + } } @@ -50,6 +55,12 @@ class BigDecimalExpectationSamples { expect(BigDecimal(10)).notToEqualNumerically(BigDecimal(1213669989183)) expect(BigDecimal(1213669989183)).notToEqualNumerically(BigDecimal(10)) expect(BigDecimal(1238126387123)).notToEqualNumerically(BigDecimal(-1.0)) + + fails { + // because is numerically the same + // use notToEqualIncludingScale if you want to compare the scale as well + expect(BigDecimal("10")).notToEqualNumerically(BigDecimal("10.0")) + } } @@ -61,6 +72,11 @@ class BigDecimalExpectationSamples { expect(BigDecimal(10.0)).toEqualIncludingScale(BigDecimal(10.0)) expect(BigDecimal(456.0)).toEqualIncludingScale(BigDecimal(456.0)) + + fails { + // because scale is different, use toEqualNumerically if you want to ignore the scale + expect(BigDecimal("10")).toEqualIncludingScale(BigDecimal("10.0")) + } } @@ -73,7 +89,9 @@ class BigDecimalExpectationSamples { expect(BigDecimal(10)).notToEqualIncludingScale(BigDecimal(10.01)) expect(BigDecimal(456.01)).notToEqualIncludingScale(BigDecimal(456)) expect(BigDecimal(-1.456)).notToEqualIncludingScale(BigDecimal(-1.45)) - } - + fails { + expect(BigDecimal("10.0")).notToEqualIncludingScale(BigDecimal("10.0")) + } + } } diff --git a/apis/infix/atrium-api-infix/src/jvmMain/kotlin/ch/tutteli/atrium/api/infix/en_GB/bigDecimalExpectations.kt b/apis/infix/atrium-api-infix/src/jvmMain/kotlin/ch/tutteli/atrium/api/infix/en_GB/bigDecimalExpectations.kt index 92845c3094..dc7bce6fc1 100644 --- a/apis/infix/atrium-api-infix/src/jvmMain/kotlin/ch/tutteli/atrium/api/infix/en_GB/bigDecimalExpectations.kt +++ b/apis/infix/atrium-api-infix/src/jvmMain/kotlin/ch/tutteli/atrium/api/infix/en_GB/bigDecimalExpectations.kt @@ -23,7 +23,7 @@ import java.math.BigDecimal "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.", ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)") ) -@Suppress("UNUSED_PARAMETER", "unused") +@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter") infix fun Expect.toEqual(expected: T): Nothing = throw PleaseUseReplacementException( "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" + @@ -42,7 +42,7 @@ infix fun Expect.toEqual(expected: T): Nothing = * * @since 0.17.0 */ -@Suppress("UNUSED_PARAMETER", "unused") +//TODO rename to toEqualNullable with 2.0.0 @JvmName("toBeNullable") @Deprecated( "Use `toEqualNumerically` if you expect that the following assertion holds:\n" + @@ -50,6 +50,7 @@ infix fun Expect.toEqual(expected: T): Nothing = "However, if you expect it to be wrong (because `BigDecimal.scale` differ), then use `toEqualIncludingScale`.", ReplaceWith("toEqualNumerically(expected) or toEqualIncludingScale(expected)") ) +@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter") infix fun Expect.toEqual(expected: T): Nothing = throw PleaseUseReplacementException( "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" + @@ -61,10 +62,11 @@ infix fun Expect.toEqual(expected: T): Nothing = * * @return an [Expect] for the subject of `this` expectation. * - * @sample ch.tutteli.atrium.api.infix.en_GB.samples.BigDecimalExpectationSamples.toEqual + * @sample ch.tutteli.atrium.api.infix.en_GB.samples.BigDecimalExpectationSamples.toEqualNull * * @since 0.17.0 */ +//TODO rename to toEqualNul with 2.0.0 @JvmName("toBeNull") infix fun Expect.toEqual(expected: Nothing?): Expect = _logicAppend { toBe(expected) } @@ -87,13 +89,27 @@ infix fun Expect.toEqual(expected: Nothing?): Expect = "However, if you expect it to hold (because `BigDecimal.scale` differ), then use `notToEqualIncludingScale`.", ReplaceWith("notToEqualNumerically(expected) or notToEqualIncludingScale(expected)") ) -@Suppress("UNUSED_PARAMETER", "unused") -infix fun Expect.notToEqual(expected: T): Nothing = +@Suppress("UNUSED_PARAMETER", "UnusedReceiverParameter") +infix fun Expect.notToEqual(expected: T): Nothing = throw PleaseUseReplacementException( "BigDecimal.equals() compares also BigDecimal.scale, which you might not be aware of.\n" + "If you know it and want that `scale` is included in the comparison, then use `notToEqualIncludingScale`." ) +/** + * Expects that the subject of `this` expectation (a [BigDecimal]) is not `null`. + * + * @return an [Expect] for the subject of `this` expectation. + * + * @sample ch.tutteli.atrium.api.infix.en_GB.samples.BigDecimalExpectationSamples.notToEqualNull + * + * @since 1.1.0 + */ +@JvmName("notToEqualNull") +infix fun Expect.notToEqual(expected: Nothing?): Expect = + _logicAppend { notToBe(expected) }._logic.changeSubject.unreported { it!! } + + /** * Expects that the subject of `this` expectation (a [BigDecimal]) is numerically equal to [expected]. * diff --git a/apis/infix/atrium-api-infix/src/jvmTest/kotlin/ch/tutteli/atrium/api/infix/en_GB/samples/BigDecimalExpectationSamples.kt b/apis/infix/atrium-api-infix/src/jvmTest/kotlin/ch/tutteli/atrium/api/infix/en_GB/samples/BigDecimalExpectationSamples.kt index 72d25d7f7e..d94c65ff5b 100644 --- a/apis/infix/atrium-api-infix/src/jvmTest/kotlin/ch/tutteli/atrium/api/infix/en_GB/samples/BigDecimalExpectationSamples.kt +++ b/apis/infix/atrium-api-infix/src/jvmTest/kotlin/ch/tutteli/atrium/api/infix/en_GB/samples/BigDecimalExpectationSamples.kt @@ -8,8 +8,24 @@ import kotlin.test.Test class BigDecimalExpectationSamples { @Test - fun toEqual() { - // only use toEqual to check against null, otherwise use toEqualNumerically or toEqualIncludingScale - expect(null as BigDecimal?).toEqual(null) + fun toEqualNull() { + // Use toEqual only to check against null if your subject is a BigDecimal + // Use toEqualNumerically or toEqualIncludingScale if you want to compare it against another BigDecimal + expect(null as BigDecimal?) toEqual null + + fails { + expect(BigDecimal("-12345.6789") as BigDecimal?) toEqual null + } + } + + @Test + fun notToEqualNull() { + // Use notToEqual only to check against null if your subject is a BigDecimal + // Use notToEqualNumerically or notToEqualIncludingScale if you want to compare it against another BigDecimal + expect(BigDecimal("-12345.6789") as BigDecimal?) notToEqual null + + fails { + expect(null as BigDecimal?) notToEqual null + } } }