From 777501481f24d24a010329f46bd3aa7748e6cdbc Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 3 Mar 2025 09:27:51 +0100 Subject: [PATCH 1/8] Overhaul Gradle section regarding dependency alignment Resolves #4343. --- .../asciidoc/user-guide/running-tests.adoc | 107 +++++++++++++----- 1 file changed, 77 insertions(+), 30 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index dfd49d779a28..dce14a4e34ab 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -13,11 +13,6 @@ however, that it is recommended to use IDEA 2017.3 or newer since more recent ve IDEA download the following JARs automatically based on the API version used in the project: `junit-platform-launcher`, `junit-jupiter-engine`, and `junit-vintage-engine`. -WARNING: IntelliJ IDEA releases prior to IDEA 2017.3 bundle specific versions of JUnit 5. -Thus, if you want to use a newer version of JUnit Jupiter, execution of tests within the -IDE might fail due to version conflicts. In such cases, please follow the instructions -below to use a newer version of JUnit 5 than the one bundled with IntelliJ IDEA. - In order to use a different JUnit 5 version (e.g., {jupiter-version}), you may need to include the corresponding versions of the `junit-platform-launcher`, `junit-jupiter-engine`, and `junit-vintage-engine` JARs in the classpath. @@ -27,9 +22,7 @@ include the corresponding versions of the `junit-platform-launcher`, [subs=attributes+] ---- testImplementation(platform("org.junit:junit-bom:{bom-version}")) -testRuntimeOnly("org.junit.platform:junit-platform-launcher") { - because("Only needed to run tests in a version of IntelliJ IDEA that bundles older versions") -} +testRuntimeOnly("org.junit.platform:junit-platform-launcher") testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine") testRuntimeOnly("org.junit.vintage:junit-vintage-engine") ---- @@ -40,7 +33,6 @@ testRuntimeOnly("org.junit.vintage:junit-vintage-engine") ---- - org.junit.platform junit-platform-launcher @@ -156,43 +148,46 @@ for a comprehensive list of options. [[running-tests-build-gradle-bom]] ===== Aligning dependency versions +TIP: See <> for details on how to override the version +of JUnit used in your Spring Boot application. + Unless you're using Spring Boot which defines its own way of managing dependencies, it is recommended to use the JUnit Platform BOM to align the versions of all JUnit 5 artifacts. [source,groovy,indent=0] [subs=attributes+] +.Explicit platform dependency on the BOM ---- dependencies { testImplementation(platform("org.junit:junit-bom:{bom-version}")) + testImplementation("org.junit.jupiter:junit-jupiter") + testRuntimeOnly("org.junit.platform:junit-platform-launcher") } ---- Using the BOM allows you to omit the version when declaring dependencies on all artifacts with the `org.junit.platform`, `org.junit.jupiter`, and `org.junit.vintage` group IDs. -TIP: See <> for details on how to override the version -of JUnit used in your Spring Boot application. - -[[running-tests-build-gradle-config-params]] -===== Configuration Parameters - -The standard Gradle `test` task currently does not provide a dedicated DSL to set JUnit -Platform <> to influence test -discovery and execution. However, you can provide configuration parameters within the -build script via system properties (as shown below) or via the -`junit-platform.properties` file. +Since all JUnit artifacts declare a +https://docs.gradle.org/current/userguide/platforms.html[platform] dependency on the BOM, +you usually don't need to declare an explicit dependency on it yourself. Instead, it's +sufficient to declare one dependency including a version to be able to omit the version +for all other JUnit artifacts. [source,groovy,indent=0] +[subs=attributes+] +.Implicit platform dependency on the BOM ---- -test { - // ... - systemProperty("junit.jupiter.conditions.deactivate", "*") - systemProperty("junit.jupiter.extensions.autodetection.enabled", true) - systemProperty("junit.jupiter.testinstance.lifecycle.default", "per_class") - // ... +dependencies { + testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") + testRuntimeOnly("org.junit.platform:junit-platform-launcher") } ---- +WARNING: Even though pre-8.0 versions of Gradle don't require declaring an explicit +dependency on `junit-platform-launcher`, it is recommended to do so to ensure the versions +of JUnit artifacts on the test runtime classpath are aligned. + [[running-tests-build-gradle-engines-configure]] ===== Configuring Test Engines @@ -205,7 +200,38 @@ on the dependency-aggregating JUnit Jupiter artifact similar to the following. [subs=attributes+] ---- dependencies { - testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") // version can be omitted when using the BOM + testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") + testRuntimeOnly("org.junit.platform:junit-platform-launcher") +} +---- + +Alternatively, you can use Gradle's +https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html[JVM Test Suite] +support. + +[source,groovy,indent=0] +[subs=attributes+] +.Kotlin DSL +---- +testing { + suites { + named("test") { + useJUnitJupiter("{jupiter-version}") + } + } +} +---- + +[source,groovy,indent=0] +[subs=attributes+] +.Groovy DSL +---- +testing { + suites { + test { + useJUnitJupiter("{jupiter-version}") + } + } } ---- @@ -218,7 +244,28 @@ implementation similar to the following. ---- dependencies { testImplementation("junit:junit:{junit4-version}") - testRuntimeOnly("org.junit.vintage:junit-vintage-engine:{vintage-version}") // version can be omitted when using the BOM + testRuntimeOnly("org.junit.vintage:junit-vintage-engine:{vintage-version}") + testRuntimeOnly("org.junit.platform:junit-platform-launcher") +} +---- + +[[running-tests-build-gradle-config-params]] +===== Configuration Parameters + +The standard Gradle `test` task currently does not provide a dedicated DSL to set JUnit +Platform <> to influence test +discovery and execution. However, you can provide configuration parameters within the +build script via system properties (as shown below) or via the +`junit-platform.properties` file. + +[source,groovy,indent=0] +---- +test { + // ... + systemProperty("junit.jupiter.conditions.deactivate", "*") + systemProperty("junit.jupiter.extensions.autodetection.enabled", true) + systemProperty("junit.jupiter.testinstance.lifecycle.default", "per_class") + // ... } ---- @@ -248,8 +295,8 @@ test { Other logging frameworks provide different means to redirect messages logged using `java.util.logging`. For example, for {Logback} you can use the -https://www.slf4j.org/legacy.html#jul-to-slf4j[JUL to SLF4J Bridge] by adding an -additional dependency to the runtime classpath. +https://www.slf4j.org/legacy.html#jul-to-slf4j[JUL to SLF4J Bridge] by adding it as a +dependency to the test runtime classpath. [[running-tests-build-maven]] ==== Maven From 5fb94bb12c5dffeec9da0840e4f0c7ad9aadc0f4 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 3 Mar 2025 18:39:50 +0100 Subject: [PATCH 2/8] Use "kotlin" for Kotlin DSL Co-authored-by: Sam Brannen <104798+sbrannen@users.noreply.github.com> --- documentation/src/docs/asciidoc/user-guide/running-tests.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index dce14a4e34ab..cbf7049f6db5 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -209,7 +209,7 @@ Alternatively, you can use Gradle's https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html[JVM Test Suite] support. -[source,groovy,indent=0] +[source,kotlin,indent=0] [subs=attributes+] .Kotlin DSL ---- From 1a45f17813d102746c1e9797b57cc03159d7e414 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 3 Mar 2025 18:41:56 +0100 Subject: [PATCH 3/8] Use tabs for indentation --- .../asciidoc/user-guide/running-tests.adoc | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index cbf7049f6db5..d55f3ad8a9e7 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -160,8 +160,8 @@ recommended to use the JUnit Platform BOM to align the versions of all JUnit 5 a ---- dependencies { testImplementation(platform("org.junit:junit-bom:{bom-version}")) - testImplementation("org.junit.jupiter:junit-jupiter") - testRuntimeOnly("org.junit.platform:junit-platform-launcher") + testImplementation("org.junit.jupiter:junit-jupiter") + testRuntimeOnly("org.junit.platform:junit-platform-launcher") } ---- @@ -179,8 +179,8 @@ for all other JUnit artifacts. .Implicit platform dependency on the BOM ---- dependencies { - testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") - testRuntimeOnly("org.junit.platform:junit-platform-launcher") + testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") + testRuntimeOnly("org.junit.platform:junit-platform-launcher") } ---- @@ -200,8 +200,8 @@ on the dependency-aggregating JUnit Jupiter artifact similar to the following. [subs=attributes+] ---- dependencies { - testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") - testRuntimeOnly("org.junit.platform:junit-platform-launcher") + testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") + testRuntimeOnly("org.junit.platform:junit-platform-launcher") } ---- @@ -214,11 +214,11 @@ support. .Kotlin DSL ---- testing { - suites { - named("test") { - useJUnitJupiter("{jupiter-version}") - } - } + suites { + named("test") { + useJUnitJupiter("{jupiter-version}") + } + } } ---- @@ -227,11 +227,11 @@ testing { .Groovy DSL ---- testing { - suites { - test { - useJUnitJupiter("{jupiter-version}") - } - } + suites { + test { + useJUnitJupiter("{jupiter-version}") + } + } } ---- @@ -245,7 +245,7 @@ implementation similar to the following. dependencies { testImplementation("junit:junit:{junit4-version}") testRuntimeOnly("org.junit.vintage:junit-vintage-engine:{vintage-version}") - testRuntimeOnly("org.junit.platform:junit-platform-launcher") + testRuntimeOnly("org.junit.platform:junit-platform-launcher") } ---- From 26829cce41ecd32f16382521fa59495465ce1c67 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 3 Mar 2025 18:51:13 +0100 Subject: [PATCH 4/8] Expand acronym and link to BOM section --- .../src/docs/asciidoc/user-guide/running-tests.adoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index d55f3ad8a9e7..af50b594f3f1 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -152,7 +152,8 @@ TIP: See <> for details on how to override the of JUnit used in your Spring Boot application. Unless you're using Spring Boot which defines its own way of managing dependencies, it is -recommended to use the JUnit Platform BOM to align the versions of all JUnit 5 artifacts. +recommended to use the JUnit Platform <> to align the +versions of all JUnit 5 artifacts. [source,groovy,indent=0] [subs=attributes+] @@ -335,7 +336,8 @@ Maven build as follows. ===== Aligning dependency versions Unless you're using Spring Boot which defines its own way of managing dependencies, it is -recommended to use the JUnit Platform BOM to align the versions of all JUnit 5 artifacts. +recommended to use the JUnit Platform <> to align the +versions of all JUnit 5 artifacts. [source,xml,indent=0] [subs=attributes+] @@ -627,8 +629,8 @@ managing the version of JUnit used in your project. In addition, the Jupiter, AssertJ, Mockito, etc. If your build relies on dependency management support from Spring Boot, you should not -import the <> in your build script since that -will result in duplicate (and potentially conflicting) management of JUnit dependencies. +import JUnit's <> in your build script since that would +result in duplicate (and potentially conflicting) management of JUnit dependencies. If you need to override the version of a dependency used in your Spring Boot application, you have to override the exact name of the From 779b984bd50d4d86ce24837406a340d0f23540e9 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 3 Mar 2025 18:51:19 +0100 Subject: [PATCH 5/8] Update link --- documentation/src/docs/asciidoc/user-guide/running-tests.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index af50b594f3f1..6a6cd899d80f 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -142,7 +142,7 @@ test { ---- Please refer to the -https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_test[official Gradle documentation] +https://docs.gradle.org/current/userguide/java_testing.html#java_testing[official Gradle documentation] for a comprehensive list of options. [[running-tests-build-gradle-bom]] From 0f96d0ba59c60cf6c7dd98f787d9b6ba7533eca1 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 3 Mar 2025 18:56:22 +0100 Subject: [PATCH 6/8] Remove superfluous anchor from link --- documentation/src/docs/asciidoc/user-guide/running-tests.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index 6a6cd899d80f..0faee94e88a4 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -142,7 +142,7 @@ test { ---- Please refer to the -https://docs.gradle.org/current/userguide/java_testing.html#java_testing[official Gradle documentation] +https://docs.gradle.org/current/userguide/java_testing.html[official Gradle documentation] for a comprehensive list of options. [[running-tests-build-gradle-bom]] From e709a0ae8e2a535a8827aaa66f505825b6c9915f Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 3 Mar 2025 18:58:04 +0100 Subject: [PATCH 7/8] Expand paragraph about automatic alignment in Gradle --- .../src/docs/asciidoc/user-guide/running-tests.adoc | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index 0faee94e88a4..323b9d451ab0 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -172,18 +172,21 @@ with the `org.junit.platform`, `org.junit.jupiter`, and `org.junit.vintage` grou Since all JUnit artifacts declare a https://docs.gradle.org/current/userguide/platforms.html[platform] dependency on the BOM, you usually don't need to declare an explicit dependency on it yourself. Instead, it's -sufficient to declare one dependency including a version to be able to omit the version -for all other JUnit artifacts. +sufficient to declare _one_ regular dependency that includes a version number. Gradle will +then pull in the BOM automatically so you can omit the version for all other JUnit 5 +artifacts. [source,groovy,indent=0] [subs=attributes+] .Implicit platform dependency on the BOM ---- dependencies { - testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") - testRuntimeOnly("org.junit.platform:junit-platform-launcher") + testImplementation("org.junit.jupiter:junit-jupiter:{jupiter-version}") // <1> + testRuntimeOnly("org.junit.platform:junit-platform-launcher") // <2> } ---- +<1> Dependency declaration with explicit version. Pulls in the `junit-bom` automatically. +<2> Dependency declaration without version. The version is supplied by the `junit-bom`. WARNING: Even though pre-8.0 versions of Gradle don't require declaring an explicit dependency on `junit-platform-launcher`, it is recommended to do so to ensure the versions From 7bd9721e4ea2ddb1707dce4450650c9717e6cbeb Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 3 Mar 2025 19:07:17 +0100 Subject: [PATCH 8/8] Expand warning block to mention IDEs --- .../src/docs/asciidoc/user-guide/running-tests.adoc | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index 323b9d451ab0..db03995cb078 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -188,10 +188,18 @@ dependencies { <1> Dependency declaration with explicit version. Pulls in the `junit-bom` automatically. <2> Dependency declaration without version. The version is supplied by the `junit-bom`. -WARNING: Even though pre-8.0 versions of Gradle don't require declaring an explicit +[WARNING] +.Declaring a dependency on junit-platform-launcher +==== +Even though pre-8.0 versions of Gradle don't require declaring an explicit dependency on `junit-platform-launcher`, it is recommended to do so to ensure the versions of JUnit artifacts on the test runtime classpath are aligned. +Moreover, doing so is recommended and in some cases even required when importing the +project into an IDE like <> or +<>. +==== + [[running-tests-build-gradle-engines-configure]] ===== Configuring Test Engines