Skip to content

Add Kotlin contracts to exposed Kotlin APIΒ #1866

Description

@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

Activity

  1. added this to the milestone on Apr 18, 2019
  2. stale commented on May 13, 2021

    @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.

  3. jbduncan commented on May 13, 2021

    @jbduncan
    Contributor

    This sounds like a useful usability feature!

  4. removed this from the milestone on Jun 19, 2021
  5. stale commented on Jun 19, 2022

    @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.

  6. ephemient commented on Jun 20, 2022

    @ephemient

    Please do this.

  7. stale commented on Jul 11, 2022

    @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.

  8. 37 remaining items

  9. added this to the 5.12 milestone on Feb 2, 2024
  10. modified the milestones: 5.11 M2, 5.11 M3 on May 17, 2024
  11. removed this from the 5.11 M3 milestone on Jul 5, 2024
  12. added this to the 5.12 M1 milestone on Nov 25, 2024
  13. added a commit that references this issue on Dec 5, 2024
    3580f04
  14. github-actions commented on May 4, 2026

    @github-actions

    This issue was resolved and the conversation been locked due to inactivity.

    The JUnit team generally speaking doesn't look at resolved issues. If you do have a similar request or problem, please create a new issue. You can include a reference to this issue to provide additional context.

  15. locked as resolved and limited conversation to collaborators on May 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions