[MERGE FOR 5.2] Feature/add equals verifier concept

[pelletier197]

Proof of concept using Comparators concept. I have not pushed the concept very far at first, since I wanted to get feedback on the idea first.

I will add more unit tests to this if you like the idea.

What Comparators can bring to Kotest is more flexible matching on list elements and reduced redundancy. The interface is quite similar to the Matcher interface, but in the difference that it takes two parameters instead of one. Therefore, allowing for more complex pre-defined implementations.

The goal could be in long term to help reduce the number of required functions in the library. For instance:

fun <T : Any> T.shouldBeEqualToIgnoringFields(other: T, property: KProperty<*>, vararg others: KProperty<*>) 
// and
fun <T : Any> T.shouldBeEqualToIgnoringFields(other: T, ignorePrivateFields: Boolean, property: KProperty<*>, vararg others: KProperty<*>)
// and
fun <T : Any> T.shouldBeEqualToUsingFields(other: T, vararg properties: KProperty<*>) 
// and many other functions like these

could become a single function that takes in parameter configurable implementations of Comparator

fun <T : Any> T.shouldBe(other: T, comparator: Comparator<T>) 

which could be used like this for instance

a.shouldBe(b, comparator=Comparators.reflectionIgnoringFields(B::test))

a.shouldBe(b, comparator=Comparators.reflectionIgnoringFields(B::test).includingPrivateFields())

a.shouldBe(b, comparator=Comparators.reflectionUsingFields(B::test))

The same would apply for collections (which currently do not support matchers ignoring fields)

listOf(a).shouldContain(b, comparator=Comparators.reflectionIgnoringFields(B::test))

So in term, it would simplify the library a lot by removing many redundant functions, and would easily allow people to implement their own comparators.

Let me know what you think!

[sksamuel]

Love the idea.

I would change Comparator to be Equals and have the function return a boolean. Then it's easier to resuse later for other matchers, such as contains in order, etc.

Other than that, looks awesome.

[pelletier197]

I would change Comparator to be Equals

Agree with that

and have the function return a boolean.

I agree that reusing the matcher was maybe not the best approach. I wanted to reuse what was there, but it doesn't fit much.

Tho, not a fan of returning simply a boolean, because it offers no detail as of why the equality check failed. It could be nice to have details for field by field comparison for instance.

I'll try creating another object. Something like "EqualityResult".

Thanks for the feedback!

[sksamuel]

Ok EqualityResult seems good.

[pelletier197]

Hi @sksamuel I modified the Comparator to EqualityVerifier. A bit long, but I feel like Equals alone was a weird class name.

I tried to keep my changes short for this first one, but my long term goal would be to use these verifiers for the matchers of shouldBe, shouldContain. That would move the static eq function, into various verifiers. This would allow to easily re-use the exact same equality methods for shouldBe and shouldContain etc.

Let me know what you think!

[sksamuel]

I like the idea. A lot of reuse.

On the naming, I think EqualityVerifier is a bit verbose. equals and verify is kinda the same thing. What about just Equality? Typeclasses like this tend to be single words - Comparator, Applicative etc.

[pelletier197]

I agree that the name is verbose.

How do you see this? Could keep the interface named this way:

interface EqualityVerifier<T: Any?> {
   fun name(): String

   fun verify(actual: T, expected: T) : EqualityResult
}

but call the factory object like this?

object Equality {
   fun <T> default() = objectEquality<T>()
}

This would make it less verbose to use. I don't think users would call these verifier constructors directly. They would use the factory class. So they would not really have to worry about the interface, except if they implement their own verifier.

Otherwise, If we call the interface Equality, what would be the name of the factory object? Equalities? Doesn't that look a little weird? Or would you implement the factory in a different way?

[sksamuel]

Can interfaces have companion objects? Also your suggestion is ok.

…

On Sat, 29 Jan 2022, 11:24 Sunny Pelletier, ***@***.***> wrote: I agree that the name is verbose. How do you see this? Could keep the interface named this way: interface EqualityVerifier<T: Any?> { fun name(): String fun verify(actual: T, expected: T) : EqualityResult } but call the factory object like this? object Equality { fun <T> default() = objectEquality<T>() } This would make it less verbose to use. I don't think users would call these verifier constructors directly. They would use the factory class. Otherwise, If we call the interface Equality, what would be the name of the factory object? Equalities? Or would you implement the factory in a different way? — Reply to this email directly, view it on GitHub <#2795 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFVSGQYGH2YYKGAXJTYGATUYQPDRANCNFSM5MSCLK7Q> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[pelletier197]

I went with the companion object as you proposed. It's great 💯

[sksamuel]

This looks awesome.

[sksamuel]

I'll merge this once 5.1.1 is out and master becomes the 5.2 build.