[MERGE FOR 5.2] Feature/add equals verifier concept (kotest#2795)

* add base comparators

* convert contain methods using comparators

* fix tests

* add reflection comparison

* add map equals

* add map equality

* refactor object equality stuff

* add string diff

* edit regex

* add number equality

* fix iterable equality

* add iterable equality

* push

* simplify PR by removing extra equality checks

* add unit test for ignoring fields

* add unit tests

* add collections matcher

* fix failing test

* rename interface and use companion object as factory

* rename missing classes

* fix failing tests

Author: pelletier197

kotest-assertions/kotest-assertions-core/src/commonMain/kotlin/io/kotest/matchers/collections/contain.kt

@@ -1,45 +1,44 @@
 package io.kotest.matchers.collections
 
 import io.kotest.assertions.print.print
+import io.kotest.equals.Equality
 import io.kotest.matchers.Matcher
 import io.kotest.matchers.MatcherResult
 import io.kotest.matchers.should
 import io.kotest.matchers.shouldNot
 
-infix fun <T> Iterable<T>.shouldNotContain(t: T): Iterable<T> {
-   toList().shouldNotContain(t)
-   return this
-}
-
-infix fun <T> Array<T>.shouldNotContain(t: T): Array<T> {
-   asList().shouldNotContain(t)
-   return this
-}
+// Infix
+infix fun <T> Iterable<T>.shouldNotContain(t: T): Iterable<T> = shouldNotContain(t, Equality.default())
+infix fun <T> Array<T>.shouldNotContain(t: T): Array<T> = shouldNotContain(t, Equality.default())
+infix fun <T> Iterable<T>.shouldContain(t: T): Iterable<T> = shouldContain(t, Equality.default())
+infix fun <T> Array<T>.shouldContain(t: T): Array<T> = shouldContain(t, Equality.default())
 
-infix fun <T, C : Collection<T>> C.shouldNotContain(t: T): C {
-   this shouldNot contain(t)
-   return this
+// Should not
+fun <T> Iterable<T>.shouldNotContain(t: T, comparator: Equality<T>): Iterable<T> = apply {
+   toList() shouldNot contain(t, comparator)
 }
 
-infix fun <T> Iterable<T>.shouldContain(t: T): Iterable<T> {
-   toList().shouldContain(t)
-   return this
+fun <T> Array<T>.shouldNotContain(t: T, comparator: Equality<T>): Array<T> = apply {
+   asList().shouldNotContain(t, comparator)
 }
 
-infix fun <T> Array<T>.shouldContain(t: T): Array<T> {
-   asList().shouldContain(t)
-   return this
+// Should
+fun <T> Iterable<T>.shouldContain(t: T, comparator: Equality<T>): Iterable<T> = apply {
+   toList() should contain(t, comparator)
 }
 
-infix fun <T, C : Collection<T>> C.shouldContain(t: T): C {
-   this should contain(t)
-   return this
+fun <T> Array<T>.shouldContain(t: T, comparator: Equality<T>): Array<T> = apply {
+   asList().shouldContain(t, comparator)
 }
 
-fun <T, C : Collection<T>> contain(t: T) = object : Matcher<C> {
+// Matcher
+fun <T, C : Collection<T>> contain(t: T, verifier: Equality<T> = Equality.default()) = object : Matcher<C> {
    override fun test(value: C) = MatcherResult(
-      value.contains(t),
-      { "Collection should contain element ${t.print().value}; listing some elements ${value.take(5)}" },
-      { "Collection should not contain element ${t.print().value}" }
+      value.any { verifier.verify(it, t).areEqual() },
+      {
+         "Collection should contain element ${t.print().value} based on ${verifier.name()}; " +
+            "listing some elements ${value.take(5)}"
+      },
+      { "Collection should not contain element ${t.print().value} based on ${verifier.name()}" }
    )
 }

kotest-assertions/kotest-assertions-core/src/jvmMain/kotlin/io/kotest/equals/ReflectionIgnoringFieldsEquality.kt

@@ -0,0 +1,50 @@
+package io.kotest.equals
+
+import io.kotest.matchers.equality.beEqualToIgnoringFields
+import kotlin.reflect.KProperty
+
+class ReflectionIgnoringFieldsEquality<T : Any>(
+   private val property: KProperty<*>,
+   private val others: Array<out KProperty<*>>,
+   private val ignorePrivateFields: Boolean = true,
+) : Equality<T> {
+   override fun name(): String {
+      val plural = if (others.isNotEmpty()) "s" else ""
+      val ignoringPrivate = if (ignorePrivateFields) "ignoring" else "including"
+      return "reflection equality ignoring field$plural ${(listOf(property) + others).map { it.name }} and $ignoringPrivate private fields"
+   }
+
+   fun includingPrivateFields(): ReflectionIgnoringFieldsEquality<T> {
+      return withIgnorePrivateFields(false)
+   }
+
+   fun ignoringPrivateFields(): ReflectionIgnoringFieldsEquality<T> {
+      return withIgnorePrivateFields(true)
+   }
+
+   private fun withIgnorePrivateFields(value: Boolean): ReflectionIgnoringFieldsEquality<T> {
+      return ReflectionIgnoringFieldsEquality(
+         property = property,
+         others = others,
+         ignorePrivateFields = value,
+      )
+   }
+
+   override fun verify(actual: T, expected: T): EqualityResult {
+      val result = beEqualToIgnoringFields(expected, ignorePrivateFields, property, *others).test(actual)
+      if(result.passed()) return EqualityResult.equal(actual, expected, this)
+      return EqualityResult.notEqual(actual, expected, this).withDetails { result.failureMessage() }
+   }
+
+   override fun toString(): String = name()
+}
+
+fun <T : Any> Equality.Companion.byReflectionIgnoringFields(
+   property: KProperty<*>,
+   vararg others: KProperty<*>,
+   ignorePrivateFields: Boolean = true,
+) = ReflectionIgnoringFieldsEquality<T>(
+   property = property,
+   others = others,
+   ignorePrivateFields = ignorePrivateFields
+)

kotest-assertions/kotest-assertions-core/src/jvmMain/kotlin/io/kotest/equals/ReflectionUsingFieldsEquality.kt

@@ -0,0 +1,23 @@
+package io.kotest.equals
+
+import io.kotest.matchers.equality.beEqualToUsingFields
+import kotlin.reflect.KProperty
+
+class ReflectionUsingFieldsEquality<T : Any>(
+   private val fields: Array<out KProperty<*>>
+) : Equality<T> {
+   override fun name(): String {
+      return "reflection equality using fields ${fields.map { it.name }}"
+   }
+
+   override fun verify(actual: T, expected: T): EqualityResult {
+      val result = beEqualToUsingFields(expected, *fields).test(actual)
+      if (result.passed()) return EqualityResult.equal(actual, expected, this)
+      return EqualityResult.notEqual(actual, expected, this).withDetails { result.failureMessage() }
+   }
+
+   override fun toString(): String = name()
+}
+
+fun <T : Any> Equality.Companion.byReflectionUsingFields(vararg fields: KProperty<*>) =
+   ReflectionUsingFieldsEquality<T>(fields)

kotest-assertions/kotest-assertions-core/src/jvmMain/kotlin/io/kotest/matchers/equality/reflection.kt

@@ -294,9 +294,8 @@ fun <T : Any> beEqualToIgnoringFields(
       return MatcherResult(
          failed.isEmpty(),
          { "$value should be equal to $other ignoring fields $fieldsString; Failed for $failed" },
-         {
-            "$value should not be equal to $other ignoring fields $fieldsString"
-         })
+         { "$value should not be equal to $other ignoring fields $fieldsString" }
+      )
    }
 }
 

kotest-assertions/kotest-assertions-core/src/jvmTest/kotlin/com/sksamuel/kotest/matchers/collections/CollectionMatchersTest.kt

@@ -4,6 +4,8 @@ import io.kotest.assertions.shouldFail
 import io.kotest.assertions.throwables.shouldNotThrow
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.core.spec.style.WordSpec
+import io.kotest.equals.Equality
+import io.kotest.equals.types.byObjectEquality
 import io.kotest.matchers.collections.atLeastSize
 import io.kotest.matchers.collections.atMostSize
 import io.kotest.matchers.collections.beLargerThan
@@ -300,13 +302,31 @@ class CollectionMatchersTest : WordSpec() {
             val col = listOf(1, 2, 3)
 
             col should contain(2)
+            col should contain(2.0) // uses strict num equality = false
 
             shouldThrow<AssertionError> {
                col should contain(4)
-            }.shouldHaveMessage("Collection should contain element 4; listing some elements [1, 2, 3]")
+            }.shouldHaveMessage("Collection should contain element 4 based on object equality; listing some elements [1, 2, 3]")
          }
       }
 
+      "should contain element based on a custom equality object" should {
+         "test that a collection contains an element"  {
+            val col = listOf(1, 2, 3.0)
+
+
+            val verifier = Equality.byObjectEquality<Number>(strictNumberEquality = true)
+
+            col should contain(2, verifier)
+            col should contain(3.0, verifier)
+
+            shouldThrow<AssertionError> {
+               col should contain(3, verifier)
+            }.shouldHaveMessage("Collection should contain element 3 based on object equality; listing some elements [1, 2, 3.0]")
+         }
+      }
+
+
       "shouldBeLargerThan" should {
          "test that a collection is larger than another collection"  {
             val col1 = listOf(1, 2, 3)

kotest-assertions/kotest-assertions-core/src/jvmTest/kotlin/com/sksamuel/kotest/matchers/collections/ShouldContainTest.kt

@@ -2,44 +2,55 @@ package com.sksamuel.kotest.matchers.collections
 
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.core.spec.style.WordSpec
+import io.kotest.equals.Equality
+import io.kotest.equals.types.byObjectEquality
 import io.kotest.matchers.collections.contain
 import io.kotest.matchers.collections.shouldContain
 import io.kotest.matchers.should
 import io.kotest.matchers.throwable.shouldHaveMessage
 
-class ShouldContainTest : WordSpec() {
-
-   init {
-
-      "contain" should {
-         "test that a collection contains element x"  {
-            val col = listOf(1, 2, 3)
-            shouldThrow<AssertionError> {
-               col should contain(4)
-            }
-            shouldThrow<AssertionError> {
-               col.shouldContain(4)
-            }
-            col should contain(2)
-         }
-         "support infix shouldContain" {
-            val col = listOf(1, 2, 3)
-            col shouldContain (2)
+class ShouldContainTest : WordSpec({
+   "contain" should {
+      "test that a collection contains element x"  {
+         val col = listOf(1, 2, 3)
+         shouldThrow<AssertionError> {
+            col should contain(4)
          }
-         "support type inference for subtypes of collection" {
-            val tests = listOf(
-               TestSealed.Test1("test1"),
-               TestSealed.Test2(2)
-            )
-            tests should contain(TestSealed.Test1("test1"))
-            tests.shouldContain(TestSealed.Test2(2))
+         shouldThrow<AssertionError> {
+            col.shouldContain(4)
          }
+         col should contain(2)
+         col should contain(2.0)
+      }
+
+      "test that a collection contains element with a custom verifier"  {
+         val col = listOf(1, 2, 3)
+         val verifier = Equality.byObjectEquality<Number>(strictNumberEquality = true)
 
-         "print errors unambiguously"  {
-            shouldThrow<AssertionError> {
-               listOf<Any>(1, 2).shouldContain(listOf<Any>(1L, 2L))
-            }.shouldHaveMessage("Collection should contain element [1L, 2L]; listing some elements [1, 2]")
+         shouldThrow<AssertionError> {
+            col.shouldContain(2.0, verifier)
          }
+         col should contain(2, verifier)
+      }
+
+      "support infix shouldContain" {
+         val col = listOf(1, 2, 3)
+         col shouldContain (2)
+      }
+
+      "support type inference for subtypes of collection" {
+         val tests = listOf(
+            TestSealed.Test1("test1"),
+            TestSealed.Test2(2)
+         )
+         tests should contain(TestSealed.Test1("test1"))
+         tests.shouldContain(TestSealed.Test2(2))
+      }
+
+      "print errors unambiguously"  {
+         shouldThrow<AssertionError> {
+            listOf<Any>(1, 2).shouldContain(listOf<Any>(1L, 2L))
+         }.shouldHaveMessage("Collection should contain element [1L, 2L] based on object equality; listing some elements [1, 2]")
       }
    }
-}
+})

kotest-assertions/kotest-assertions-shared/src/commonMain/kotlin/io/kotest/assertions/eq/IterableEq.kt

@@ -5,6 +5,7 @@ import io.kotest.assertions.Expected
 import io.kotest.assertions.failure
 import io.kotest.assertions.print.Printed
 import io.kotest.assertions.print.print
+import kotlinx.coroutines.internal.LockFreeLinkedListHead
 
 object IterableEq : Eq<Iterable<*>> {
 
@@ -212,3 +213,4 @@ object IterableEq : Eq<Iterable<*>> {
 
    private fun generateError(actual: Any, expected: Any) = failure(Expected(expected.print()), Actual(actual.print()))
 }
+

kotest-assertions/kotest-assertions-shared/src/commonMain/kotlin/io/kotest/equals/Equality.kt

@@ -0,0 +1,13 @@
+package io.kotest.equals
+
+import io.kotest.equals.types.byObjectEquality
+
+interface Equality<T: Any?> {
+   fun name(): String
+
+   fun verify(actual: T, expected: T) : EqualityResult
+
+   companion object {
+      fun <T> default() = byObjectEquality<T>()
+   }
+}

kotest-assertions/kotest-assertions-shared/src/commonMain/kotlin/io/kotest/equals/EqualityResult.kt

@@ -0,0 +1,78 @@
+package io.kotest.equals
+
+import io.kotest.assertions.print.print
+
+interface EqualityResult {
+   fun areEqual(): Boolean
+
+   fun details(): EqualityResultDetails
+
+   companion object {
+      fun <T> equal(actual: T, expected: T, verifier: Equality<*>): SimpleEqualityResult {
+         return create(equal = true, actual = actual, expected = expected, verifier = verifier)
+      }
+
+      fun <T> notEqual(actual: T, expected: T, verifier: Equality<*>): SimpleEqualityResult {
+         return create(equal = false, actual = actual, expected = expected, verifier = verifier)
+      }
+
+      private fun <T> create(
+         equal: Boolean,
+         actual: T,
+         expected: T,
+         verifier: Equality<*>
+      ): SimpleEqualityResult {
+         return SimpleEqualityResult(
+            equal = equal,
+            detailsValue = SimpleEqualityResultDetail(
+               explainFn = {
+                  val expectedStr = expected.print().value
+                  val actualStr = actual.print().value
+                  return@SimpleEqualityResultDetail """
+                     | $expectedStr is ${if (equal) "" else "not "}equal to $actualStr by ${verifier.name()}
+                     | Expected: $expectedStr
+                     | Actual  : $actualStr
+                  """.trimMargin()
+               }
+            )
+         )
+      }
+   }
+}
+
+fun EqualityResult.areNotEqual() = !areEqual()
+
+interface EqualityResultDetails {
+   fun explain(): String
+
+   companion object {
+      fun create(reasonFn: () -> String): EqualityResultDetails {
+         return object : EqualityResultDetails {
+            override fun explain(): String = reasonFn()
+         }
+      }
+   }
+}
+
+data class SimpleEqualityResult(
+   val equal: Boolean,
+   val detailsValue: EqualityResultDetails,
+) : EqualityResult {
+   fun withDetails(details: EqualityResultDetails): SimpleEqualityResult {
+      return copy(detailsValue = details)
+   }
+
+   fun withDetails(explainFn: () -> String): SimpleEqualityResult {
+      return withDetails(SimpleEqualityResultDetail(explainFn))
+   }
+
+   override fun areEqual(): Boolean = equal
+
+   override fun details(): EqualityResultDetails = detailsValue
+}
+
+data class SimpleEqualityResultDetail(
+   val explainFn: () -> String
+) : EqualityResultDetails {
+   override fun explain(): String = explainFn()
+}