Add Kotlin specific assertion helpers

build.gradle

@@ -187,6 +187,12 @@ allprojects { subproj ->
  options.compilerArgs += '-parameters'
  }
 
+ tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile) {
+ kotlinOptions {
+ jvmTarget = '1.8'
+ }
+ }
+
  checkstyle {
  toolVersion = '7.6'
  }
@@ -537,6 +543,13 @@ subprojects { subproj ->
  replaceRegex 'Empty line between last method and class closure', /\n([\s]+)}\n}\n$/, '\n$1}\n\n}\n'
  replaceRegex 'Remove line breaks between consecutive closing parentheses', /\)\n[\s]+\)\n/, '))\n'
  }
+
+ kotlin {
+ ktlint("0.9.0")
+ licenseHeaderFile headerFile
+ trimTrailingWhitespace()
+ endWithNewline()
+ }
  }
 
  afterEvaluate {

documentation/documentation.gradle

@@ -39,6 +39,7 @@ dependencies {
  testImplementation(project(path: ':junit-jupiter-params', configuration: 'shadow'))
  testImplementation(project(':junit-platform-runner'))
  testImplementation(project(':junit-platform-launcher'))
+ testImplementation("org.jetbrains.kotlin:kotlin-stdlib")
 
  // Include junit-platform-console so that the JUnit Gradle plugin
  // uses the local version of the ConsoleLauncher.
@@ -91,6 +92,7 @@ asciidoctor {
  'revnumber' : project.version,
  'mainDir': project.sourceSets.main.java.srcDirs[0],
  'testDir': project.sourceSets.test.java.srcDirs[0],
+ 'kotlinTestDir' : project.sourceSets.test.kotlin.srcDirs[0],
  'generatedAsciiDocInputDir': generatedAsciiDocInputDir,
  'testResourcesDir': project.sourceSets.test.resources.srcDirs[0],
  'outdir': outputDir.absolutePath,

documentation/src/docs/asciidoc/release-notes-5.1.0-M1.adoc

@@ -3,7 +3,7 @@
 
 *Date of Release:* ❓
 
-*Scope:* ❓
+*Scope:* Addition of Kotlin assertion helpers.
 
 For a complete list of all _closed_ issues and pull requests for this release, consult the
 link:{junit5-repo}+/milestone/14?closed=1+[5.1 M1] milestone page in the JUnit repository
@@ -81,7 +81,9 @@ on GitHub.
  `store.getOrComputeIfAbsent(X.class, key \-> new X(), X.class)` can now replaced with
  `store.getOrComputeIfAbsent(X.class)`.
 * Support new JUnit Platform `ModuleSelector`.
-
+* New Kotlin friendly assertions added as top-level functions in the `org.junit.jupiter.api` package.
+** `assertAll` that takes `Stream<() -> Unit>` or `vararg () -> Unit`.
+** `assertThrow` that uses Kotlin reified generics.
 
 [[release-notes-5.1.0-junit-vintage]]
 ==== JUnit Vintage

documentation/src/docs/asciidoc/writing-tests.adoc

@@ -94,6 +94,16 @@ are `static` methods in the `{Assertions}` class.
 include::{testDir}/example/AssertionsDemo.java[tags=user_guide]
 ----
 
+Junit Jupiter also comes with a few assertion methods that lend themselves well to being
+used in https://kotlinlang.org/[Kotlin]. All JUnit Jupiter Kotlin assertions are top-level
+functions in the `org.junit.jupiter.api` package.
+
+// TODO: Change to using kotlin language highlighting after switch to rouge syntax highlighter
+[source,java,indent=0]
+----
+include::{kotlinTestDir}/example/AssertionsDemoKotlin.kt[tags=user_guide]
+----
+
 [[writing-tests-assertions-third-party]]
 ==== Third-party Assertion Libraries
 

documentation/src/test/java/example/AssertionsDemo.java

@@ -143,23 +143,3 @@ private static String greeting() {
 }
 // end::user_guide[]
 // @formatter:on
-
-class Person {
-
- private final String firstName;
- private final String lastName;
-
- Person(String firstName, String lastName) {
- this.firstName = firstName;
- this.lastName = lastName;
- }
-
- String getFirstName() {
- return firstName;
- }
-
- String getLastName() {
- return lastName;
- }
-
-}

documentation/src/test/kotlin/example/AssertionsDemoKotlin.kt

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2015-2017 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+package example
+
+// tag::user_guide[]
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertAll
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.assertThrows
+
+class AssertionsDemoKotlin {
+
+ // end::user_guide[]
+ val person = Person("John", "Doe")
+ val people = setOf(person, Person("James", "Doe"))
+
+ // tag::user_guide[]
+ @Test
+ fun `grouped assertions`() {
+ assertAll("person",
+ { assertEquals("John", person.firstName) },
+ { assertEquals("Doe", person.lastName) }
+ )
+ }
+
+ @Test
+ fun `exception testing`() {
+ val exception = assertThrows<IllegalArgumentException> ("Should throw an exception") {
+ throw IllegalArgumentException("a message")
+ }
+ assertEquals("a message", exception.message)
+ }
+
+ @Test
+ fun `assertions from a stream`() {
+ assertAll(
+ "people with name starting with J",
+ people
+ .stream()
+ .map {
+ // This mapping returns Stream<() -> Unit>
+ { assertTrue(it.firstName.startsWith("J")) }
+ }
+ )
+ }
+}
+// end::user_guide[]

documentation/src/test/kotlin/example/Person.kt

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2015-2017 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+package example
+
+data class Person(val firstName: String, val lastName: String)

junit-jupiter-api/junit-jupiter-api.gradle

@@ -1,12 +1,32 @@
 dependencies {
  api("org.opentest4j:opentest4j:${ota4jVersion}")
- api(project(':junit-platform-commons'))
+ api(project(":junit-platform-commons"))
+ compileOnly("org.jetbrains.kotlin:kotlin-stdlib")
 }
 
 jar {
  manifest {
  attributes(
- 'Automatic-Module-Name': 'org.junit.jupiter.api'
+  'Automatic-Module-Name': 'org.junit.jupiter.api'
  )
  }
 }
+
+configurations {
+ apiElements {
+ /*
+ * Needed to configure kotlin to work correctly with the "java-library" plugin.
+ * See:
+ * https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_known_issues
+ * https://youtrack.jetbrains.com/issue/KT-18497
+ */
+ outgoing
+ .variants
+ .getByName("classes")
+ .artifact(
+ "file" : compileKotlin.destinationDir,
+ "type" : "java-classes-directory",
+ "builtBy" : compileKotlin
+ )
+ }
+}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/Assertions.java

@@ -29,6 +29,9 @@
  * {@code Assertions} is a collection of utility methods that support asserting
  * conditions in tests.
  *
+ * <p>Additional <a href="https://kotlinlang.org/">Kotlin</a> assertions can be found
+ * as top-level functions on the {@link org.junit.jupiter.api} package.
+ *
  * <p>Unless otherwise noted, a <em>failed</em> assertion will throw an
  * {@link org.opentest4j.AssertionFailedError} or a subclass thereof.
  *

junit-jupiter-api/src/main/kotlin/org/junit/jupiter/api/Assertions.kt

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2015-2017 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+@file:API(status = EXPERIMENTAL, since = "5.1")
+package org.junit.jupiter.api
+
+import org.apiguardian.api.API
+import org.apiguardian.api.API.Status.EXPERIMENTAL
+import org.junit.jupiter.api.function.Executable
+import java.util.function.Supplier
+import java.util.stream.Stream
+
+/**
+ * [Stream] of functions to be executed.
+ */
+internal typealias ExecutableStream = Stream<() -> Unit>
+internal fun ExecutableStream.convert() = map { Executable(it) }
+
+/**
+ * @see Assertions.assertAll
+ */
+fun assertAll(executables: ExecutableStream) =
+ Assertions.assertAll(executables.convert())
+
+/**
+ * @see Assertions.assertAll
+ */
+fun assertAll(heading: String?, executables: ExecutableStream) =
+ Assertions.assertAll(heading, executables.convert())
+
+/**
+ * @see Assertions.assertAll
+ */
+fun assertAll(vararg executables: () -> Unit) =
+ assertAll(executables.toList().stream())
+
+/**
+ * @see Assertions.assertAll
+ */
+fun assertAll(heading: String?, vararg executables: () -> Unit) =
+ assertAll(heading, executables.toList().stream())
+
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrows<IllegalArgumentException> {
+ * throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ * @see Assertions.assertThrows
+ */
+inline fun <reified T : Throwable> assertThrows(noinline executable: () -> Unit): T =
+ Assertions.assertThrows(T::class.java, Executable(executable))
+
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrows<IllegalArgumentException>("Should throw an Exception") {
+ * throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ * @see Assertions.assertThrows
+ */
+inline fun <reified T : Throwable> assertThrows(message: String, noinline executable: () -> Unit): T =
+ assertThrows({ message }, executable)
+
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrows<IllegalArgumentException>({ "Should throw an Exception" }) {
+ * throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ * @see Assertions.assertThrows
+ */
+inline fun <reified T : Throwable> assertThrows(noinline message: () -> String, noinline executable: () -> Unit): T =
+ Assertions.assertThrows(T::class.java, Executable(executable), Supplier {
+ /*
+ * This is a hacky workaround due to a bug in how the JDK 9 JavaDoc code generator interacts with the
+ * generated Kotlin Bytecode.
+ * https://youtrack.jetbrains.com/issue/KT-20025
+ */
+ message()
+ })

junit-jupiter-engine/junit-jupiter-engine.gradle

@@ -47,7 +47,7 @@ dependencies {
  testImplementation(project(path: ':junit-platform-engine', configuration: 'testArtifacts'))
  testImplementation("org.assertj:assertj-core:${assertJVersion}")
  testImplementation("org.mockito:mockito-core:${mockitoVersion}")
- testImplementation("org.jetbrains.kotlin:kotlin-stdlib-jre8:${kotlinVersion}")
+ testImplementation("org.jetbrains.kotlin:kotlin-stdlib:${kotlinVersion}")
 
  // Include junit-platform-console so that the JUnit Gradle plugin
  // uses the local version of the ConsoleLauncher.

junit-jupiter-engine/src/test/java/org/junit/jupiter/api/AssertAllAssertionsTests.java

@@ -149,7 +149,7 @@ void assertAllWithExecutableThatThrowsBlacklistedException() {
  }
 
  @SafeVarargs
- private static void assertExpectedExceptionTypes(MultipleFailuresError multipleFailuresError,
+ static void assertExpectedExceptionTypes(MultipleFailuresError multipleFailuresError,
  Class<? extends Throwable>... exceptionTypes) {
 
  assertNotNull(multipleFailuresError, "MultipleFailuresError");