Add Kotlin contracts to exposed Kotlin API #1866

JLLeitschuh · 2019-04-17T14:18:23Z

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

The text was updated successfully, but these errors were encountered:

stale · 2021-05-13T19:47:36Z

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 · 2021-05-13T20:54:49Z

This sounds like a useful usability feature!

stale · 2022-06-19T20:11:49Z

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 · 2022-06-20T19:51:29Z

Please do this.

stale · 2022-07-11T20:21:06Z

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 · 2022-09-19T16:04:23Z

@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 · 2023-03-30T13:50:04Z

Is anyone working on this issue?

JLLeitschuh · 2023-03-30T14:16:07Z

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 · 2023-03-30T14:17:56Z

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 · 2023-03-30T16:58:34Z

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

TWiStErRob · 2023-03-30T17:48:37Z

@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 · 2023-03-31T02:46:04Z

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

Added assertNull and assertNotNull methods with contracts. Added contracts for assertThrows and assertDoesNotThrow methods. assertInstanceOf can be implemented only with kotlin 1.4, because refined generics [are not supported](https://youtrack.jetbrains.com/issue/KT-28298) in contracts for kotlin 1.3 yet. Issue: junit-team#1866

Issue: junit-team#1866

Kotlin assertNull and assertNotNull methods are marked as experimental. Issue: junit-team#1866

awelless · 2023-05-26T12:03:29Z

I think these might also be deliverables for full coverage:
...
* assertInstanceOf (similar to non-null, but with implies (actualValue is T))

Contracts with reified generics are supported only since kotlin 1.4. Therefore, assertInstanceOf can't be implemented for now

TWiStErRob · 2023-05-26T13:29:22Z

I wondered if the that error is suppressed will it emit 1.4 compatible bytecode for the contract? Therefore making it possible to use the same jar binary from both 1.3 and 1.4.

so I tested it... but doesn't seem so

(For reference the Kotlin version is declared in kotlin-library-conventions.gradle.kts)

// kotlinc -language-version 1.3 -api-version 1.3 -d assertIsInstance.jar -opt-in=kotlin.contracts.ExperimentalContracts assertIsInstance.kt
package test
import kotlin.contracts.contract
inline fun <reified T> assertIsInstance(value: Any?) {
    contract {
        returns() implies (value is @Suppress("ERROR_IN_CONTRACT_DESCRIPTION") T)
    }
    require(T::class.java.isInstance(value))
}

// kotlinc -language-version 1.4 -api-version 1.4 -cp assertIsInstance.jar usage.kt
import test.assertIsInstance
fun main() {
    val cs: CharSequence = ""
    assertIsInstance<String>(cs)
    val str: String = cs
    println(str)
}
// usage.kt:6:23: error: type mismatch: inferred type is CharSequence but String was expected
//    val str: String = cs
//                      ^

If the assertIsInstance.jar is compiled with 1.4, then usage.kt compiles as expected.

Funny thing: if assertIsInstance.jar is compiled with 1.4, but usage is compiled with 1.3, it works! So the 1.3 target understands the 1.4 contract, if it's correctly encoded in the .class file in the first place. In the end this information is really for the compiler to know which functions/types to bind to during compilation. It probably works this way because the actual kotlinc compiler I'm using is 1.7.10.

Lambda invoked in assertThrows is marked as being called UNKNOWN number of times, since contracts do nothing with exception suppression Issue: junit-team#1866

Created another fail method with a non-nullable lambda parameter Issue: junit-team#1866

Added assertNull and assertNotNull methods with contracts. Added contracts for assertThrows and assertDoesNotThrow methods. assertInstanceOf can be implemented only with kotlin 1.4, because refined generics [are not supported](https://youtrack.jetbrains.com/issue/KT-28298) in contracts for kotlin 1.3 yet. Issue: junit-team#1866

Kotlin assertNull and assertNotNull methods are marked as experimental. Issue: junit-team#1866

Lambda invoked in assertThrows is marked as being called UNKNOWN number of times, since contracts do nothing with exception suppression Issue: junit-team#1866

Created another fail method with a non-nullable lambda parameter Issue: junit-team#1866

awelless · 2023-08-10T07:17:41Z

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

Because of kotlin smart casts, there is no need to return a non-nullable value from `assertNotNull` methods Issue: junit-team#1866

Api version is increased to 5.11 for `assertNull` and `assertNotNull` methods Issue: junit-team#1866

Added `assertInstanceOf` assertions with upcasting contracts Issue: junit-team#1866

Issue: junit-team#1866

Invocation kind for the executable is UNKNOWN for assertTimeoutPreemptively methods Issue: junit-team#1866

Issue: junit-team#1866

marcphilipp added the status: team discussion label Apr 18, 2019

marcphilipp added this to the 5.5 Backlog milestone Apr 18, 2019

marcphilipp added component: Jupiter component: Kotlin theme: programming model type: enhancement labels Apr 18, 2019

stale bot added the status: stale label May 13, 2021

stale bot removed the status: stale label May 13, 2021

marcphilipp removed this from the 5.8 Backlog milestone Jun 19, 2021

stale bot added the status: stale label Jun 19, 2022

stale bot closed this as completed Jul 11, 2022

ephemient mentioned this issue Jul 11, 2022

Why was #1866 closed by stalebot even though the issue was commented on? #2977

Closed

sbrannen reopened this Jul 12, 2022

sbrannen removed the status: stale label Jul 12, 2022

awelless added a commit to awelless/junit5 that referenced this issue Apr 17, 2023

Added release notes for kotlin contracts

7c22c5f

Issue: junit-team#1866

awelless linked a pull request Apr 17, 2023 that will close this issue

Add Kotlin contracts to exposed Kotlin API #3259

Open

6 tasks

awelless added a commit to awelless/junit5 that referenced this issue Apr 23, 2023

Mark new kotlin assetion methods as experimental

3029054

Kotlin assertNull and assertNotNull methods are marked as experimental. Issue: junit-team#1866

marcphilipp mentioned this issue Apr 28, 2023

Add non-null return type to assertNotNull method #2477

Closed

awelless added a commit to awelless/junit5 that referenced this issue Jun 3, 2023

Adjust assertThrows contract

e3900cf

Lambda invoked in assertThrows is marked as being called UNKNOWN number of times, since contracts do nothing with exception suppression Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Jun 3, 2023

Add contract for fail

ed02ba8

Created another fail method with a non-nullable lambda parameter Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 10, 2023

Mark new kotlin assetion methods as experimental

252cad2

Kotlin assertNull and assertNotNull methods are marked as experimental. Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 10, 2023

Adjust assertThrows contract

1d5811b

Lambda invoked in assertThrows is marked as being called UNKNOWN number of times, since contracts do nothing with exception suppression Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 10, 2023

Add contract for fail

19922d6

Created another fail method with a non-nullable lambda parameter Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 25, 2023

Don't return a value from assertNotNull

eccb259

Because of kotlin smart casts, there is no need to return a non-nullable value from `assertNotNull` methods Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 25, 2023

Increase API version

e427978

Api version is increased to 5.11 for `assertNull` and `assertNotNull` methods Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 25, 2023

Add assertInstanceOf methods

544b4e1

Added `assertInstanceOf` assertions with upcasting contracts Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 25, 2023

assertInstanceOf methods accept nullable values

437d29e

Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 27, 2023

Test for assertInstanceOf nullable upcast

43c08ea

Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Aug 27, 2023

Specify lambda InvocationKind explicitly for assertThrows methods

ff9fd39

Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Sep 1, 2023

Rename variable names in new assertion examples

5a70965

Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Sep 1, 2023

Add API annotation for new fail assertion

666f73f

Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Sep 1, 2023

Make the comments be sentences

9920cf9

Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Sep 1, 2023

Adjust contract for assertTimeoutPreemptively

4d21486

Invocation kind for the executable is UNKNOWN for assertTimeoutPreemptively methods Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Sep 8, 2023

Removed contracts for methods where lambdas may throw exceptions

30b9b78

Issue: junit-team#1866

awelless added a commit to awelless/junit5 that referenced this issue Sep 23, 2023

Add more tests for methods with contracts

41f00c0

Issue: junit-team#1866

sbrannen changed the title ~~Add Kotlin Contracts to Exposed Kotlin API~~ Add Kotlin contracts to exposed Kotlin API Dec 16, 2023

marcphilipp added this to the 5.11 M1 milestone Dec 18, 2023

marcphilipp modified the milestones: 5.11 M1, 5.12 Feb 2, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Kotlin contracts to exposed Kotlin API #1866

Add Kotlin contracts to exposed Kotlin API #1866

JLLeitschuh commented Apr 17, 2019

stale bot commented May 13, 2021

jbduncan commented May 13, 2021

stale bot commented Jun 19, 2022

ephemient commented Jun 20, 2022

stale bot commented Jul 11, 2022

TWiStErRob commented Sep 19, 2022 •

edited

awelless commented Mar 30, 2023

JLLeitschuh commented Mar 30, 2023

JLLeitschuh commented Mar 30, 2023

awelless commented Mar 30, 2023

TWiStErRob commented Mar 30, 2023

JLLeitschuh commented Mar 31, 2023

awelless commented May 26, 2023

TWiStErRob commented May 26, 2023

awelless commented Aug 10, 2023

Add Kotlin contracts to exposed Kotlin API #1866

Add Kotlin contracts to exposed Kotlin API #1866

Comments

JLLeitschuh commented Apr 17, 2019

Foreward

Feature Request

Examples

assertNotNull

assertThrows / assertDoesNotThrow

Caveats

Deliverables

stale bot commented May 13, 2021

jbduncan commented May 13, 2021

stale bot commented Jun 19, 2022

ephemient commented Jun 20, 2022

stale bot commented Jul 11, 2022

TWiStErRob commented Sep 19, 2022 • edited

awelless commented Mar 30, 2023

JLLeitschuh commented Mar 30, 2023

JLLeitschuh commented Mar 30, 2023

awelless commented Mar 30, 2023

TWiStErRob commented Mar 30, 2023

JLLeitschuh commented Mar 31, 2023

awelless commented May 26, 2023

TWiStErRob commented May 26, 2023

awelless commented Aug 10, 2023

`assertNotNull`

`assertThrows` / `assertDoesNotThrow`

TWiStErRob commented Sep 19, 2022 •

edited