Add Kotlin contracts to exposed Kotlin API

[JLLeitschuh]

Foreward

First off, I want to thank the Junit 5 team from being so willing to officially support Kotlin as a first-class citizen in the Junit 5 library. It has been absolutely wonderful being able to use my own contributions in all of my Kotlin projects.

Feature Request

I believe that this API can be further enhanced with the new Kotlin 1.3 feature, Contracts.

Contracts are making guarantees to the compiler that various methods have certain characteristics.

Here's an example from the Kotlin Std-Lib:

/**
 * Throws an [IllegalStateException] if the [value] is null. Otherwise
 * returns the not null value.
 *
 * @sample samples.misc.Preconditions.failCheckWithLazyMessage
 */
@kotlin.internal.InlineOnly
public inline fun <T : Any> checkNotNull(value: T?): T {
    contract {
        returns() implies (value != null)
    }
    return checkNotNull(value) { "Required value was null." }
}

Before Kotlin Contracts, the following code wouldn't have compiled:

fun validateString(aString: String?): String {
    checkNotNull(aString)
    return aString
}

I believe that JUnit 5 has a few places where these contracts would be valuable.

Examples

assertNotNull

@ExperimentalContracts
fun <T: Any> assertNonNull(actual: T?, message: String): T {
    contract {
        returns() implies (actual != null)
    }
    Assertions.assertNotNull(actual, message)
    return actual!!
}

The above would allow something like this:

val exception = assertThrows<IllegalStateException { /** whatever **/}
val message = exception.message
assertNotNull(message)
assertTrue(message.contains("some expected substring")) 

Alternatively, it would also allow for this sort of use case:

val message = assertNotNull(exception.message)

assertThrows / assertDoesNotThrow

Since the callable passed to assertThrows is only ever called once, we can expose that in the contract.

@ExperimentalContracts
inline fun <reified T : Throwable> assertThrows(noinline message: () -> String, noinline executable: () -> Unit): T {
    contract {
        callsInPlace(executable, InvocationKind.EXACTLY_ONCE)
    }
    return Assertions.assertThrows(T::class.java, Executable(executable), Supplier(message))
}

Similar

This would for something like this:

val something: Int
val somethingElse: String
assertDoesNotThrow {
    something = somethingThatDoesntThrow()
    somethingElse = gettingSomethingElse()
}

Caveats

Kotlin Contracts are only supported in Kotlin 1.3 and higher.
This would require a discussion regarding what version of Kotlin the Junit 5 team want's to officially support.

Deliverables

• Add Kotlin method assertNotNull
• Add Contracts to Kotlin method assertNotNull
• Add Contracts to Kotlin method assertThrows
• Add Contracts to Kotlin method assertDoesNotThrow

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Given the limited bandwidth of the team, it will be automatically closed if no further activity occurs. Thank you for your contribution.

[jbduncan]

This sounds like a useful usability feature!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Given the limited bandwidth of the team, it will be automatically closed if no further activity occurs. Thank you for your contribution.

[ephemient]

Please do this.

[stale]

This issue has been automatically closed due to inactivity. If you have a good use case for this feature, please feel free to reopen the issue.

[TWiStErRob]

@junit-team What is missing to move this forward?

@JLLeitschuh I think these might also be deliverables for full coverage:

• assertNull to get Kotlin compilation protection for val actual = ...; assertNull(actual); actual.foo()
  (.foo() would be a 100% NPE with current solution and it wouldn't compile with contracts)
• assertInstanceOf (similar to non-null, but with implies (actualValue is T))

[awelless]

Is anyone working on this issue?

[JLLeitschuh]

Not currently, but I figure at this point it would be safe to do so as Kotlin 1.3 is pretty EOL as of 2 years ago: https://endoflife.date/kotlin

[JLLeitschuh]

Also, this library currently supports Kotlin versions 1.3 and above, so it would now be safe to add:

junit5/gradle/plugins/common/src/main/kotlin/junitbuild.kotlin-library-conventions.gradle.kts

Lines 8 to 14 in e188b1e

	tasks.withType<KotlinCompile>().configureEach {
	kotlinOptions {
	apiVersion = "1.3"
	languageVersion = "1.3"
	allWarningsAsErrors = false
	}
	}

If someone wants to open a pull request to add support for this, I'm more than happy to review it

[awelless]

Okay.
I could start working on it. However, it might take some time

[TWiStErRob]

@JLLeitschuh how can this be tested with automation? Because contracts should induce Kotlin compilation failures. I guess the positive cases of smart casts as results of contract can be tested:

val foo: String? = ...
assertNotNull(foo)
assertEquals(1, foo.size)

(if the contracts stop working, the above test will not compile)

[JLLeitschuh]

As you suggested, I would use the compiler as your validation

[awelless]

Since kotlin version has been bumped to 1.6, it should be possible to implement assertInstanceOf with a contract specified