Add function on EitherAssert for chaining Left and Right into Non Empty Lists

[jdsatlin]

While converting some more tests, I encountered another use case that feels like it could be a bit more accessible.

When you have code that uses NonEmptyLists inside Eithers, it's not terribly idiomatic to get them out in order to assert on them. For example

fun returnsNel(): Either<NonEmptyList<String>, Int> {
    return nonEmptyListOf("error", "other error")
}

@Test
fun assertOverLeftNel() {
    val result = returnsNel()

    // either assert
    assertThat(result).isLeft()
    val unwrappedResult = result.leftOrNull()!!

    // non empty list assert
    assertThat(unwrappedResult).contains("error", "other error")
}

either assert asLeft / containsLeftInstanceOf will give you an object assertion for the NonEmptyList, but there's no easy way to get to the underlying object in order to begin a NonEmptyList assertion. If you just want to do an assertion on the full list using equality you can do a assertThat(result).containsOnLeft(nonEmptyListOf("error", "other error") - but that's it, we're missing many of the other tools for NonEmptyList asserts such as just matching one element, matching on some elements, checking for sorting. I think combining Eithers/raises that then contain NonEmptyLists on the left side is a particularly common usecase in Arrow, see aliases such as EitherNel, and functions like bindNel

This is sort of also a limitation on the base library, as there's not really a super easy way to extract out a property of a complex object and get to its relevant special case assertions, however in practice I think this is particularly a bit more of pain here due to the ubiquitously wrapped nature of Eithers, that try to enforce safety.

I can think of two possible solutions for this, one would be to offer some shortcuts into the special case assertions, something like a asLeftNel() and asRightNel() option that would verify the Either had the appropriate side, was of type NonEmptyList, and launch right into the NonEmptyList assertions. So that would be used something like assertThat(result).asLeftNel().isSorted()

The other option would be a value that allows for assigning from an asLeft or asRight call. This could be a new method, like asLeftValue(), or an extension property on AbstractObjectAssertion like .value

I haven't directly encountered this for Raise, but given the Raise works with all the same orAccumulate patterns, I think it likely makes sense to complete a similar solution there.

At first blush I think I might lean towards the special case for NonEmptyLists of asLeftNel() - but would be open to input on what you think might make the most sense. I'm happy to work towards an implementation if this makes sense to you. Thanks!

[rcardin]

Hey, @jdsatlin. Sorry for the delay in my responses. Tough days 😅
IMO, result.leftOrNull() is quite idiomatic indeed.

The fact that you can't find an elegant proposal to implement the use case is a symptom that maybe "easy is better".
Kotlin strives for simplicity.

What do you think?

[jdsatlin]

Sorry @rcardin , no worries on the response it also took me much longer to respond than I had hoped. I think the wrapped nature of Eithers make contents much harder to access than usual for testing assertions, and I think the strength of this library is easing that and making the tests read more clearly, so you can focus on the actual logic.

I think the best case I've got for this is code like the below, which our code bases are full of

data class ServiceError(val errorMessage: String, val errorType: ErrorType, val location: String)
    enum class ErrorType {
        VALIDATION,
        UNEXPECTED,
        RETRIABLE,
    }

    @Test
    internal fun `nel test as is`() {
        val errorOne = ServiceError(errorMessage = "LatLong does not match country", errorType = ErrorType.VALIDATION, location = "LatLong")
        val errorTwo = ServiceError(errorMessage = "Your zip code was invalid", errorType = ErrorType.VALIDATION, location = "ZipCode")
        val errorThree = ServiceError(errorMessage = "Your contact phone number was an invalid length", errorType = ErrorType.VALIDATION, location = "Contact.PhoneNumber")
        val actual: Either<NonEmptyList<ServiceError>?, Int> = listOf(
            errorTwo,
            errorOne,
            errorThree
        ).shuffled().toNonEmptyListOrNull().left()

        // assertThat(actual).asLeft().isEqualTo(actual) // requires generating the entire list in an isEquals compatible way, losing the power of list asserts
        assertThat(actual).isLeft()
        val actualLeftNel = actual.leftOrNull()!!
        assertThat(actualLeftNel).hasSize(3)
        assertThat(actualLeftNel).containsExactlyInAnyOrder(errorOne, errorTwo, errorThree)

    }

    @Test
    internal fun `nel test with asLeftNel`() {
        val errorOne = ServiceError(errorMessage = "LatLong does not match country", errorType = ErrorType.VALIDATION, location = "LatLong")
        val errorTwo = ServiceError(errorMessage = "Your zip code was invalid", errorType = ErrorType.VALIDATION, location = "ZipCode")
        val errorThree = ServiceError(errorMessage = "Your contact phone number was an invalid length", errorType = ErrorType.VALIDATION, location = "Contact.PhoneNumber")
        val actual: Either<NonEmptyList<ServiceError>?, Int> = nonEmptyListOf(
            errorTwo,
            errorOne,
            errorThree
        ).shuffled().toNonEmptyListOrNull().left()

        assertThat(actual).asLeftNel().hasSize(3).containsExactlyInAnyOrder(errorOne, errorTwo, errorThree)
    }

(In production code I'd also prefer to avoid the .toNonEmptyListOrNull() preferring a .toNonEmptyListOrNone and handling the possibilities, but that wasn't the focus of this example)

I really do think that second one reads much more cleanly, and a NonEmptyList clearly has a place of importance in the base Arrow library given the presence of various aliases and functions such as Nel, EitherNel, .leftNel()

That said, this should be relatively straightforward to write as an extension function outside the library, so if you don't think it's a valuable feature it's relatively easy to accomplish what I'm hoping to do.

[rcardin]

@jdsatlin, I would rewrite the following code you shared:

assertThat(actual).isLeft()
        val actualLeftNel = actual.leftOrNull()!!
        assertThat(actualLeftNel).hasSize(3)
        assertThat(actualLeftNel).containsExactlyInAnyOrder(errorOne, errorTwo, errorThree)

as

assertThat(actual.leftOrNull())
        .hasSize(3)
        .containsExactlyInAnyOrder(errorOne, errorTwo, errorThree)

It's quite idiomatic to me 🤷‍♂️. If actual is not a "left" value, the assertions will fail in any case in a controlled way.