From 16ff13b6b017598ed1e7b9782c988e3cc7d994b3 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Tue, 21 Oct 2025 17:12:18 +0200 Subject: [PATCH 01/18] Add note duplicate test execution with @Suite Users are surprised to see that their tests are executed twice[1]. This is the natural consequence of using a test engine to define a suite. We can at least let them know in the documentation. 1. https://github.com/junit-team/junit-framework/discussions/4327 --- .../advanced-topics/junit-platform-suite-engine.adoc | 11 +++++++++-- .../main/java/org/junit/platform/suite/api/Suite.java | 8 +++++++- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index 366d4854abb6..341f5db2103d 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -1,8 +1,8 @@ [[junit-platform-suite-engine]] === JUnit Platform Suite Engine -The JUnit Platform supports the declarative definition and execution of suites of tests -from _any_ test engine using the JUnit Platform. +The Suite Engine supports the declarative selection and execution of tests from +_any_ test engine using the JUnit Platform. [[junit-platform-suite-engine-setup]] ==== Setup @@ -48,6 +48,13 @@ NOTE: There are numerous configuration options for discovering and filtering tes test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full list of supported annotations and further details. +.Duplicate test execution +NOTE: Tests in a suite are executed in addition to the tests executed by every other test +engine, so it is possible to for the same test to be executed twice. A common solution is +to use a naming pattern. Name all suites `*Suite` and all tests `*Test` and configure your +build tool to only include the former. Alternatively, consider +<> to select specific groups of tests. + ==== @BeforeSuite and @AfterSuite `@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a diff --git a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java index c44c5d9a6bc8..24903bf9b51e 100644 --- a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java +++ b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java @@ -26,7 +26,7 @@ * {@code @Suite} marks a class as a test suite on the JUnit Platform. * *

Selector and filter annotations are used to control the contents of the - * suite. Additionally configuration can be passed to the suite via the + * suite. Additionally, configuration can be passed to the suite via the * configuration annotations. * *

When the {@link IncludeClassNamePatterns @IncludeClassNamePatterns} @@ -44,6 +44,12 @@ * annotation disables the latter as a source of parameters so that only explicit * configuration parameters are taken into account. * + *

Note: Tests in a suite are executed in addition to the tests executed by every + * other test engine, so it is possible to for the same test to be executed twice. A + * common solution is to use a naming pattern. Name all suites {@code *Suite} and all + * tests {@code *Test} and configure your build tool to only include the former. + * Alternatively, consider using tags to select specific groups of tests. + * * @since 1.8 * @see Select * @see SelectClasses From c0a8776abc951655a864eaee1b7a5aba993f909b Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Tue, 21 Oct 2025 17:32:39 +0200 Subject: [PATCH 02/18] Update pointers and commands in readme --- CONTRIBUTING.md | 4 ++-- documentation/README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b5fd3cd1caa..462c2cbef8d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -177,8 +177,8 @@ To deprecate an item: ## Building the Project -Please refer to [the readme](README.md#building-from-source) for the most common -build commands. +Please refer to [the readme](README.md#building-from-source) and [the documentation readme](documentation/README.md) for +the most common build commands. ### Build Parameters diff --git a/documentation/README.md b/documentation/README.md index 873a2ff282f6..acb46649d9d5 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -18,7 +18,7 @@ This following Gradle command generates the HTML version of the User Guide as `build/docs/asciidoc/user-guide/index.html`. ``` -gradlew asciidoctor +./gradlew asciidoctor ``` On Linux operating systems, the `graphviz` package providing `/usr/bin/dot` must be @@ -30,5 +30,5 @@ This following Gradle command generates the PDF version of the User Guide to `build/docs/asciidocPdf/user-guide/index.pdf`. ``` -gradlew asciidoctorPdf +./gradlew asciidoctorPdf ``` From 8546b9796dce8f179064ae87c3607efb0e55afc5 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Tue, 21 Oct 2025 18:54:06 +0200 Subject: [PATCH 03/18] Extract and update note to independent section --- .../junit-platform-suite-engine.adoc | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index 341f5db2103d..5a9bc18a055e 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -31,6 +31,18 @@ on `junit-platform-suite-api` and `junit-platform-suite-engine`. * `junit-platform-commons` in _test_ scope * `opentest4j` in _test_ scope +[[junit-platform-suite-engine-setup-duplicate-test-execution]] +===== Duplicate test execution + +Tests in a suite are executed in addition to the tests executed by every other test +engine. This can result in the same tests being executed twice. + +This can be prevented by configuring your build tool to only include the +`junit-platform-suite` engine. Or by using a naming pattern. For example name all suites +`*Suite` and all tests `*Test` and configure your build tool to only include the former. + +Alternatively, consider <> to select specific groups of tests. + [[junit-platform-suite-engine-example]] ==== @Suite Example @@ -48,13 +60,6 @@ NOTE: There are numerous configuration options for discovering and filtering tes test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full list of supported annotations and further details. -.Duplicate test execution -NOTE: Tests in a suite are executed in addition to the tests executed by every other test -engine, so it is possible to for the same test to be executed twice. A common solution is -to use a naming pattern. Name all suites `*Suite` and all tests `*Test` and configure your -build tool to only include the former. Alternatively, consider -<> to select specific groups of tests. - ==== @BeforeSuite and @AfterSuite `@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a From 6f2dacd612ded359827fddcf1ef4b2940039f532 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Tue, 21 Oct 2025 23:08:53 +0200 Subject: [PATCH 04/18] Update Suite annotation to match --- .../main/java/org/junit/platform/suite/api/Suite.java | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java index 24903bf9b51e..39a207b72502 100644 --- a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java +++ b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java @@ -45,10 +45,12 @@ * configuration parameters are taken into account. * *

Note: Tests in a suite are executed in addition to the tests executed by every - * other test engine, so it is possible to for the same test to be executed twice. A - * common solution is to use a naming pattern. Name all suites {@code *Suite} and all - * tests {@code *Test} and configure your build tool to only include the former. - * Alternatively, consider using tags to select specific groups of tests. + * other test engine. This can result in the same tests being executed twice. This can be + * prevented by configuring your build tool to only include the + * {@value org.junit.platform.suite.engine.SuiteEngineDescriptor#ENGINE_ID} engine. Or by + * using a naming pattern. For example name all suites {@code *Suite} and all tests + * {@code *Test} and configure your build tool to only include the former. Alternatively, + * consider using tags to select specific groups of tests. * * @since 1.8 * @see Select From f74202e51545194d4a6624e394c7037d84e18b35 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Wed, 22 Oct 2025 00:53:31 +0200 Subject: [PATCH 05/18] Update Suite annotation to match --- .../src/main/java/org/junit/platform/suite/api/Suite.java | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java index 39a207b72502..3571abab178a 100644 --- a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java +++ b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java @@ -46,8 +46,7 @@ * *

Note: Tests in a suite are executed in addition to the tests executed by every * other test engine. This can result in the same tests being executed twice. This can be - * prevented by configuring your build tool to only include the - * {@value org.junit.platform.suite.engine.SuiteEngineDescriptor#ENGINE_ID} engine. Or by + * prevented by configuring your build tool to only include the Suite Engine. Or by * using a naming pattern. For example name all suites {@code *Suite} and all tests * {@code *Test} and configure your build tool to only include the former. Alternatively, * consider using tags to select specific groups of tests. From 890a5b7f48aad0674bfca508599c2fa2bbfeeaee Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Thu, 30 Oct 2025 13:22:35 +0100 Subject: [PATCH 06/18] Update documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc Co-authored-by: Marc Philipp --- .../user-guide/advanced-topics/junit-platform-suite-engine.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index 5a9bc18a055e..d6c03dace250 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -38,7 +38,7 @@ Tests in a suite are executed in addition to the tests executed by every other t engine. This can result in the same tests being executed twice. This can be prevented by configuring your build tool to only include the -`junit-platform-suite` engine. Or by using a naming pattern. For example name all suites +`junit-platform-suite` engine. Or by using a naming pattern. For example, name all suites `*Suite` and all tests `*Test` and configure your build tool to only include the former. Alternatively, consider <> to select specific groups of tests. From c3a88d06e659a048f4eb01591e35839d1a635a54 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Thu, 30 Oct 2025 14:26:40 +0100 Subject: [PATCH 07/18] Draft diagrams --- documentation/documentation.gradle.kts | 13 +++++++- .../junit-platform-launcher-api-diagram.puml | 28 ++++++++++++++++ .../suite-engine-multiple-suites-diagram.puml | 32 +++++++++++++++++++ 3 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 documentation/src/plantuml/junit-platform-launcher-api-diagram.puml create mode 100644 documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml diff --git a/documentation/documentation.gradle.kts b/documentation/documentation.gradle.kts index 56032143508f..6d5400f773cb 100644 --- a/documentation/documentation.gradle.kts +++ b/documentation/documentation.gradle.kts @@ -268,7 +268,10 @@ tasks { outputs.cacheIf { true } } + // TODO: Loop? val componentDiagram = plantUml.flatMap { it.outputDirectory.file("component-diagram.svg") } + val junitPlatformLauncherApiDiagram = plantUml.flatMap { it.outputDirectory.file("junit-platform-launcher-api-diagram.svg") } + val suiteEngineMultipleSuitesDiagram = plantUml.flatMap { it.outputDirectory.file("suite-engine-multiple-suites-diagram.svg") } withType().configureEach { inputs.files( @@ -278,7 +281,9 @@ tasks { generateConsoleLauncherEnginesOptions, generateApiTables, generateStandaloneConsoleLauncherShadowedArtifactsFile, - componentDiagram + componentDiagram, + junitPlatformLauncherApiDiagram, + suiteEngineMultipleSuitesDiagram ) resources { @@ -289,6 +294,12 @@ tasks { from(componentDiagram) { into("user-guide/images") } + from(junitPlatformLauncherApiDiagram) { + into("user-guide/images") + } + from(suiteEngineMultipleSuitesDiagram) { + into("user-guide/images") + } } // Temporary workaround for https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/599 diff --git a/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml b/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml new file mode 100644 index 000000000000..7f5d1a9aa940 --- /dev/null +++ b/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml @@ -0,0 +1,28 @@ +@startuml +object "IDEs" +object "Build Tools" +object "Console Launcher" +object "JUnit Platform" + +object "Jupiter Test Engine" +object "Test Classes" + +object "Cucumber Test Engine" +object "Feature Files" + +object "Spock Test Engine" +object "Specifications" + + +"IDEs" --> "JUnit Platform": ... +"Build Tools" --> "JUnit Platform" : ... +"Console Launcher" --> "JUnit Platform" : requests discovery and execution +"JUnit Platform" --> "Jupiter Test Engine": ... +"Jupiter Test Engine" --> "Test Classes" : ... + +"JUnit Platform" --> "Cucumber Test Engine": ... +"Cucumber Test Engine" --> "Feature Files" : ... + +"JUnit Platform" --> "Spock Test Engine": forwards request +"Spock Test Engine" --> "Specifications" : discovers and executes +@enduml diff --git a/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml b/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml new file mode 100644 index 000000000000..e753be24e464 --- /dev/null +++ b/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml @@ -0,0 +1,32 @@ +@startuml +object IDE +object "Build Tools" +object "Console Launcher" +object "JUnit Platform" +object "Suite Test Engine" + +object "@Suite annotated class A" +object "JUnit Platform (A)" +object "JUpiter Test Engine (A)" +object "ExampleTest (A)" + +object "@Suite annotated class B" +object "JUnit Platform (B)" +object "JUpiter Test Engine (B)" +object "ExampleTest (B)" + +IDE --> "JUnit Platform": ... +"Build Tools" --> "JUnit Platform" : ... +"Console Launcher" --> "JUnit Platform" : requests discovery and execution +"JUnit Platform" --> "Suite Test Engine": forwards request + +"Suite Test Engine" --> "@Suite annotated class A" : ... +"@Suite annotated class A" --> "JUnit Platform (A)" : ... +"JUnit Platform (A)" --> "JUpiter Test Engine (A)" : ... +"JUpiter Test Engine (A)" --> "ExampleTest (A)" : ... + +"Suite Test Engine" --> "@Suite annotated class B" : discovers and executes +"@Suite annotated class B" --> "JUnit Platform (B)" : requests discovery and execution +"JUnit Platform (B)" --> "JUpiter Test Engine (B)" : forwards request +"JUpiter Test Engine (B)" --> "ExampleTest (B)" : discovers and executes +@enduml From fcd8f7e32dcfb4df92fb58b446d434af87020e18 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Thu, 30 Oct 2025 19:14:46 +0100 Subject: [PATCH 08/18] Rework, rewrite, revise --- documentation/documentation.gradle.kts | 17 ++-------- .../junit-platform-suite-engine.adoc | 32 +++++++++++-------- .../advanced-topics/launcher-api.adoc | 2 ++ .../junit-platform-launcher-api-diagram.puml | 9 ++---- ...gine-duplicate-test-execution-diagram.puml | 30 +++++++++++++++++ .../suite-engine-multiple-suites-diagram.puml | 18 +++++------ 6 files changed, 66 insertions(+), 42 deletions(-) create mode 100644 documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml diff --git a/documentation/documentation.gradle.kts b/documentation/documentation.gradle.kts index 6d5400f773cb..5acf6fd77cb1 100644 --- a/documentation/documentation.gradle.kts +++ b/documentation/documentation.gradle.kts @@ -268,10 +268,7 @@ tasks { outputs.cacheIf { true } } - // TODO: Loop? - val componentDiagram = plantUml.flatMap { it.outputDirectory.file("component-diagram.svg") } - val junitPlatformLauncherApiDiagram = plantUml.flatMap { it.outputDirectory.file("junit-platform-launcher-api-diagram.svg") } - val suiteEngineMultipleSuitesDiagram = plantUml.flatMap { it.outputDirectory.file("suite-engine-multiple-suites-diagram.svg") } + val plantUmlOutputDirectory = plantUml.flatMap { it.outputDirectory } withType().configureEach { inputs.files( @@ -281,9 +278,7 @@ tasks { generateConsoleLauncherEnginesOptions, generateApiTables, generateStandaloneConsoleLauncherShadowedArtifactsFile, - componentDiagram, - junitPlatformLauncherApiDiagram, - suiteEngineMultipleSuitesDiagram + plantUmlOutputDirectory ) resources { @@ -291,13 +286,7 @@ tasks { include("**/images/**/*.png") include("**/images/**/*.svg") } - from(componentDiagram) { - into("user-guide/images") - } - from(junitPlatformLauncherApiDiagram) { - into("user-guide/images") - } - from(suiteEngineMultipleSuitesDiagram) { + from(plantUmlOutputDirectory) { into("user-guide/images") } } diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index d6c03dace250..11a58cec40e6 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -2,7 +2,9 @@ === JUnit Platform Suite Engine The Suite Engine supports the declarative selection and execution of tests from -_any_ test engine using the JUnit Platform. +_any_ test engine on the JUnit Platform using the <>. + +image::suite-engine-multiple-suites-diagram.svg[] [[junit-platform-suite-engine-setup]] ==== Setup @@ -31,18 +33,6 @@ on `junit-platform-suite-api` and `junit-platform-suite-engine`. * `junit-platform-commons` in _test_ scope * `opentest4j` in _test_ scope -[[junit-platform-suite-engine-setup-duplicate-test-execution]] -===== Duplicate test execution - -Tests in a suite are executed in addition to the tests executed by every other test -engine. This can result in the same tests being executed twice. - -This can be prevented by configuring your build tool to only include the -`junit-platform-suite` engine. Or by using a naming pattern. For example, name all suites -`*Suite` and all tests `*Test` and configure your build tool to only include the former. - -Alternatively, consider <> to select specific groups of tests. - [[junit-platform-suite-engine-example]] ==== @Suite Example @@ -70,3 +60,19 @@ all tests of the test suite. ---- include::{testDir}/example/BeforeAndAfterSuiteDemo.java[tags=user_guide] ---- + +[[junit-platform-suite-engine-duplicate-test-execution]] +==== Duplicate test execution + +Depending on the declared test selection, different suites may contain the same tests, +potentially with different configurations. Moreover, tests in a suite are executed +in addition to the tests executed by every other test engine. This can result in the same +tests being executed twice. + +image::suite-engine-duplicate-test-execution-diagram.svg[] + +This can be prevented by configuring your build tool to only include the +`junit-platform-suite` engine. Or by using a naming pattern. For example, name all suites +`*Suite` and all tests `*Test` and configure your build tool to only include the former. + +Alternatively, consider <> to select specific groups of tests. diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc index da003aef2694..3b7a1e8b9659 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc @@ -14,6 +14,8 @@ tests. Moreover, third party test libraries – like Spock or Cucumber – can p JUnit Platform's launching infrastructure by providing a custom <>. +image::junit-platform-launcher-api-diagram.svg[] + The launcher API is in the `{junit-platform-launcher}` module. An example consumer of the launcher API is the `{ConsoleLauncher}` in the diff --git a/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml b/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml index 7f5d1a9aa940..32a1f08a66ca 100644 --- a/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml +++ b/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml @@ -3,17 +3,14 @@ object "IDEs" object "Build Tools" object "Console Launcher" object "JUnit Platform" - object "Jupiter Test Engine" -object "Test Classes" - +object "Suite Test Engine" object "Cucumber Test Engine" -object "Feature Files" - object "Spock Test Engine" +object "Test Classes" +object "Feature Files" object "Specifications" - "IDEs" --> "JUnit Platform": ... "Build Tools" --> "JUnit Platform" : ... "Console Launcher" --> "JUnit Platform" : requests discovery and execution diff --git a/documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml b/documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml new file mode 100644 index 000000000000..911bc579af0d --- /dev/null +++ b/documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml @@ -0,0 +1,30 @@ +@startuml +object "IDEs" +object "Build Tools" +object "Console Launcher" +object "JUnit Platform" +together { + object "Suite Test Engine" + object "Jupiter Test Engine" +} +object "@Suite annotated class" +object "JUnit Platform (@Suite)" +object "Jupiter Test Engine (@Suite)" +together { + object "Example Test A" + object "Example Test A (@Suite)" +} + +"IDEs" --> "JUnit Platform": ... +"Build Tools" --> "JUnit Platform" : ... +"Console Launcher" --> "JUnit Platform" : requests discovery and execution + +"JUnit Platform" --> "Suite Test Engine" : ... +"Suite Test Engine" --> "@Suite annotated class" : discovers and executes +"@Suite annotated class" --> "JUnit Platform (@Suite)" : requests discovery and execution +"JUnit Platform (@Suite)" --> "Jupiter Test Engine (@Suite)" : forwards request +"Jupiter Test Engine (@Suite)" --> "Example Test A (@Suite)" : discovers and executes + +"JUnit Platform" --> "Jupiter Test Engine": forwards request +"Jupiter Test Engine" --> "Example Test A" #line:red;line.bold;text:red : also discover and executes! +@enduml diff --git a/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml b/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml index e753be24e464..be8dbce885f6 100644 --- a/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml +++ b/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml @@ -1,21 +1,21 @@ @startuml -object IDE +object "IDEs" object "Build Tools" object "Console Launcher" + object "JUnit Platform" object "Suite Test Engine" object "@Suite annotated class A" -object "JUnit Platform (A)" -object "JUpiter Test Engine (A)" -object "ExampleTest (A)" - object "@Suite annotated class B" +object "JUnit Platform (A)" object "JUnit Platform (B)" +object "JUpiter Test Engine (A)" object "JUpiter Test Engine (B)" -object "ExampleTest (B)" +object "Tests in package A" +object "Tests in package B" -IDE --> "JUnit Platform": ... +"IDEs" --> "JUnit Platform": ... "Build Tools" --> "JUnit Platform" : ... "Console Launcher" --> "JUnit Platform" : requests discovery and execution "JUnit Platform" --> "Suite Test Engine": forwards request @@ -23,10 +23,10 @@ IDE --> "JUnit Platform": ... "Suite Test Engine" --> "@Suite annotated class A" : ... "@Suite annotated class A" --> "JUnit Platform (A)" : ... "JUnit Platform (A)" --> "JUpiter Test Engine (A)" : ... -"JUpiter Test Engine (A)" --> "ExampleTest (A)" : ... +"JUpiter Test Engine (A)" --> "Tests in package A" : ... "Suite Test Engine" --> "@Suite annotated class B" : discovers and executes "@Suite annotated class B" --> "JUnit Platform (B)" : requests discovery and execution "JUnit Platform (B)" --> "JUpiter Test Engine (B)" : forwards request -"JUpiter Test Engine (B)" --> "ExampleTest (B)" : discovers and executes +"JUpiter Test Engine (B)" --> "Tests in package B" : discovers and executes @enduml From 5e02295b798355560f95f14ddaa7a716e3005137 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Thu, 30 Oct 2025 19:21:42 +0100 Subject: [PATCH 09/18] Remove ellipsis, spell Jupiter correctly --- .../junit-platform-launcher-api-diagram.puml | 12 +++++------ ...gine-duplicate-test-execution-diagram.puml | 6 +++--- .../suite-engine-multiple-suites-diagram.puml | 20 +++++++++---------- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml b/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml index 32a1f08a66ca..b7b657d8b2d1 100644 --- a/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml +++ b/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml @@ -11,14 +11,14 @@ object "Test Classes" object "Feature Files" object "Specifications" -"IDEs" --> "JUnit Platform": ... -"Build Tools" --> "JUnit Platform" : ... +"IDEs" --> "JUnit Platform" +"Build Tools" --> "JUnit Platform" "Console Launcher" --> "JUnit Platform" : requests discovery and execution -"JUnit Platform" --> "Jupiter Test Engine": ... -"Jupiter Test Engine" --> "Test Classes" : ... +"JUnit Platform" --> "Jupiter Test Engine" +"Jupiter Test Engine" --> "Test Classes" -"JUnit Platform" --> "Cucumber Test Engine": ... -"Cucumber Test Engine" --> "Feature Files" : ... +"JUnit Platform" --> "Cucumber Test Engine" +"Cucumber Test Engine" --> "Feature Files" "JUnit Platform" --> "Spock Test Engine": forwards request "Spock Test Engine" --> "Specifications" : discovers and executes diff --git a/documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml b/documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml index 911bc579af0d..788985b78717 100644 --- a/documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml +++ b/documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml @@ -15,11 +15,11 @@ together { object "Example Test A (@Suite)" } -"IDEs" --> "JUnit Platform": ... -"Build Tools" --> "JUnit Platform" : ... +"IDEs" --> "JUnit Platform" +"Build Tools" --> "JUnit Platform" "Console Launcher" --> "JUnit Platform" : requests discovery and execution -"JUnit Platform" --> "Suite Test Engine" : ... +"JUnit Platform" --> "Suite Test Engine" "Suite Test Engine" --> "@Suite annotated class" : discovers and executes "@Suite annotated class" --> "JUnit Platform (@Suite)" : requests discovery and execution "JUnit Platform (@Suite)" --> "Jupiter Test Engine (@Suite)" : forwards request diff --git a/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml b/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml index be8dbce885f6..04ab91b565c0 100644 --- a/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml +++ b/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml @@ -10,23 +10,23 @@ object "@Suite annotated class A" object "@Suite annotated class B" object "JUnit Platform (A)" object "JUnit Platform (B)" -object "JUpiter Test Engine (A)" -object "JUpiter Test Engine (B)" +object "Jupiter Test Engine (A)" +object "Jupiter Test Engine (B)" object "Tests in package A" object "Tests in package B" -"IDEs" --> "JUnit Platform": ... -"Build Tools" --> "JUnit Platform" : ... +"IDEs" --> "JUnit Platform" +"Build Tools" --> "JUnit Platform" "Console Launcher" --> "JUnit Platform" : requests discovery and execution "JUnit Platform" --> "Suite Test Engine": forwards request -"Suite Test Engine" --> "@Suite annotated class A" : ... -"@Suite annotated class A" --> "JUnit Platform (A)" : ... -"JUnit Platform (A)" --> "JUpiter Test Engine (A)" : ... -"JUpiter Test Engine (A)" --> "Tests in package A" : ... +"Suite Test Engine" --> "@Suite annotated class A" +"@Suite annotated class A" --> "JUnit Platform (A)" +"JUnit Platform (A)" --> "Jupiter Test Engine (A)" +"Jupiter Test Engine (A)" --> "Tests in package A" "Suite Test Engine" --> "@Suite annotated class B" : discovers and executes "@Suite annotated class B" --> "JUnit Platform (B)" : requests discovery and execution -"JUnit Platform (B)" --> "JUpiter Test Engine (B)" : forwards request -"JUpiter Test Engine (B)" --> "Tests in package B" : discovers and executes +"JUnit Platform (B)" --> "Jupiter Test Engine (B)" : forwards request +"Jupiter Test Engine (B)" --> "Tests in package B" : discovers and executes @enduml From b822014170b6f877e696f2217a610ccd728fd6ba Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Thu, 30 Oct 2025 19:35:21 +0100 Subject: [PATCH 10/18] Rework, rewrite, revise --- .../junit-platform-suite-engine.adoc | 7 ++++--- .../org/junit/platform/suite/api/Suite.java | 17 +++++++++++------ 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index 11a58cec40e6..808b633dd5f9 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -65,9 +65,10 @@ include::{testDir}/example/BeforeAndAfterSuiteDemo.java[tags=user_guide] ==== Duplicate test execution Depending on the declared test selection, different suites may contain the same tests, -potentially with different configurations. Moreover, tests in a suite are executed -in addition to the tests executed by every other test engine. This can result in the same -tests being executed twice. +potentially with different configurations. + +Moreover, tests in a suite are executed in addition to the tests executed by every other +test engine. This can result in the same tests being executed twice. image::suite-engine-duplicate-test-execution-diagram.svg[] diff --git a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java index 3571abab178a..06e4acf9b606 100644 --- a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java +++ b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java @@ -44,12 +44,17 @@ * annotation disables the latter as a source of parameters so that only explicit * configuration parameters are taken into account. * - *

Note: Tests in a suite are executed in addition to the tests executed by every - * other test engine. This can result in the same tests being executed twice. This can be - * prevented by configuring your build tool to only include the Suite Engine. Or by - * using a naming pattern. For example name all suites {@code *Suite} and all tests - * {@code *Test} and configure your build tool to only include the former. Alternatively, - * consider using tags to select specific groups of tests. + *

Note: Depending on the declared test selection, different suites may contain the + * same tests, potentially with different configurations. + * + *

Moreover, tests in a suite are executed in addition to the tests executed by every + * other test engine. This can result in the same tests being executed twice and can be + * prevented by configuring your build tool to only include the + * {@code junit-platform-suite} engine. Or by using a naming pattern. For example name + * all suites {@code *Suite} and all tests {@code *Test} and configure your build tool + * to only include the former. + * + *

Alternatively, consider using tags to select specific groups of tests. * * @since 1.8 * @see Select From 4df8e8124516704f24d96f60c61d67543c233784 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Thu, 30 Oct 2025 19:40:03 +0100 Subject: [PATCH 11/18] Rename diagrams to match header ids --- .../advanced-topics/junit-platform-suite-engine.adoc | 4 ++-- .../asciidoc/user-guide/advanced-topics/launcher-api.adoc | 2 +- ...-diagram.puml => junit-platform-suite-engine-diagram.puml} | 0 ...atform-suite-engine-duplicate-test-execution-diagram.puml} | 0 ...rm-launcher-api-diagram.puml => launcher-api-diagram.puml} | 0 5 files changed, 3 insertions(+), 3 deletions(-) rename documentation/src/plantuml/{suite-engine-multiple-suites-diagram.puml => junit-platform-suite-engine-diagram.puml} (100%) rename documentation/src/plantuml/{suite-engine-duplicate-test-execution-diagram.puml => junit-platform-suite-engine-duplicate-test-execution-diagram.puml} (100%) rename documentation/src/plantuml/{junit-platform-launcher-api-diagram.puml => launcher-api-diagram.puml} (100%) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index 808b633dd5f9..34297c62e253 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -4,7 +4,7 @@ The Suite Engine supports the declarative selection and execution of tests from _any_ test engine on the JUnit Platform using the <>. -image::suite-engine-multiple-suites-diagram.svg[] +image::junit-platform-suite-engine-diagram.svg[] [[junit-platform-suite-engine-setup]] ==== Setup @@ -70,7 +70,7 @@ potentially with different configurations. Moreover, tests in a suite are executed in addition to the tests executed by every other test engine. This can result in the same tests being executed twice. -image::suite-engine-duplicate-test-execution-diagram.svg[] +image::junit-platform-suite-engine-duplicate-test-execution-diagram.svg[] This can be prevented by configuring your build tool to only include the `junit-platform-suite` engine. Or by using a naming pattern. For example, name all suites diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc index 3b7a1e8b9659..b4050330ebc9 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc @@ -14,7 +14,7 @@ tests. Moreover, third party test libraries – like Spock or Cucumber – can p JUnit Platform's launching infrastructure by providing a custom <>. -image::junit-platform-launcher-api-diagram.svg[] +image::launcher-api-diagram.svg[] The launcher API is in the `{junit-platform-launcher}` module. diff --git a/documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml b/documentation/src/plantuml/junit-platform-suite-engine-diagram.puml similarity index 100% rename from documentation/src/plantuml/suite-engine-multiple-suites-diagram.puml rename to documentation/src/plantuml/junit-platform-suite-engine-diagram.puml diff --git a/documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml b/documentation/src/plantuml/junit-platform-suite-engine-duplicate-test-execution-diagram.puml similarity index 100% rename from documentation/src/plantuml/suite-engine-duplicate-test-execution-diagram.puml rename to documentation/src/plantuml/junit-platform-suite-engine-duplicate-test-execution-diagram.puml diff --git a/documentation/src/plantuml/junit-platform-launcher-api-diagram.puml b/documentation/src/plantuml/launcher-api-diagram.puml similarity index 100% rename from documentation/src/plantuml/junit-platform-launcher-api-diagram.puml rename to documentation/src/plantuml/launcher-api-diagram.puml From aa2d0976b4a76ccd31c65aec380e1cc60fd0c2cf Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Fri, 31 Oct 2025 13:05:53 +0100 Subject: [PATCH 12/18] Update documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc Co-authored-by: Marc Philipp --- .../user-guide/advanced-topics/junit-platform-suite-engine.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index 34297c62e253..308163985d2c 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -66,7 +66,6 @@ include::{testDir}/example/BeforeAndAfterSuiteDemo.java[tags=user_guide] Depending on the declared test selection, different suites may contain the same tests, potentially with different configurations. - Moreover, tests in a suite are executed in addition to the tests executed by every other test engine. This can result in the same tests being executed twice. From bef798dc7da08af8e2bfc688c230389fd4c1c296 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Fri, 31 Oct 2025 13:06:13 +0100 Subject: [PATCH 13/18] Update documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc Co-authored-by: Marc Philipp --- .../user-guide/advanced-topics/junit-platform-suite-engine.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index 308163985d2c..c6a078aa6305 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -69,7 +69,7 @@ potentially with different configurations. Moreover, tests in a suite are executed in addition to the tests executed by every other test engine. This can result in the same tests being executed twice. -image::junit-platform-suite-engine-duplicate-test-execution-diagram.svg[] +image::junit-platform-suite-engine-duplicate-test-execution-diagram.svg[role=text-center] This can be prevented by configuring your build tool to only include the `junit-platform-suite` engine. Or by using a naming pattern. For example, name all suites From ed4a741aa66acd0e8b5b2511fa0d6517662a6d84 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Fri, 31 Oct 2025 13:06:38 +0100 Subject: [PATCH 14/18] Update documentation/src/plantuml/launcher-api-diagram.puml Co-authored-by: Marc Philipp --- documentation/src/plantuml/launcher-api-diagram.puml | 1 - 1 file changed, 1 deletion(-) diff --git a/documentation/src/plantuml/launcher-api-diagram.puml b/documentation/src/plantuml/launcher-api-diagram.puml index b7b657d8b2d1..10dc6ea4d8c5 100644 --- a/documentation/src/plantuml/launcher-api-diagram.puml +++ b/documentation/src/plantuml/launcher-api-diagram.puml @@ -4,7 +4,6 @@ object "Build Tools" object "Console Launcher" object "JUnit Platform" object "Jupiter Test Engine" -object "Suite Test Engine" object "Cucumber Test Engine" object "Spock Test Engine" object "Test Classes" From 05fb4fd65f08c34760f8d93bb8559db5d121f91d Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Fri, 31 Oct 2025 13:06:47 +0100 Subject: [PATCH 15/18] Update documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc Co-authored-by: Marc Philipp --- .../docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc index b4050330ebc9..434761485d2a 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc @@ -14,7 +14,7 @@ tests. Moreover, third party test libraries – like Spock or Cucumber – can p JUnit Platform's launching infrastructure by providing a custom <>. -image::launcher-api-diagram.svg[] +image::launcher-api-diagram.svg[role=text-center] The launcher API is in the `{junit-platform-launcher}` module. From c132c99f14979708356b6896c7f2a3bb810f6d93 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Fri, 31 Oct 2025 13:06:54 +0100 Subject: [PATCH 16/18] Update documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc Co-authored-by: Marc Philipp --- .../user-guide/advanced-topics/junit-platform-suite-engine.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc index c6a078aa6305..52e1a025af9a 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc @@ -4,7 +4,7 @@ The Suite Engine supports the declarative selection and execution of tests from _any_ test engine on the JUnit Platform using the <>. -image::junit-platform-suite-engine-diagram.svg[] +image::junit-platform-suite-engine-diagram.svg[role=text-center] [[junit-platform-suite-engine-setup]] ==== Setup From 970d710a69a2e1b17a32aaff35d3cd6d53c7bffa Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Fri, 31 Oct 2025 13:07:02 +0100 Subject: [PATCH 17/18] Update junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java Co-authored-by: Marc Philipp --- .../src/main/java/org/junit/platform/suite/api/Suite.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java index 06e4acf9b606..d491bf4df48a 100644 --- a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java +++ b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java @@ -50,7 +50,7 @@ *

Moreover, tests in a suite are executed in addition to the tests executed by every * other test engine. This can result in the same tests being executed twice and can be * prevented by configuring your build tool to only include the - * {@code junit-platform-suite} engine. Or by using a naming pattern. For example name + * {@code junit-platform-suite} engine. Or by using a naming pattern. For example, name * all suites {@code *Suite} and all tests {@code *Test} and configure your build tool * to only include the former. * From da41307d40e8b64535da6bf371d4750b3ee263ce Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Fri, 31 Oct 2025 13:10:39 +0100 Subject: [PATCH 18/18] Merge paragraphs --- .../src/main/java/org/junit/platform/suite/api/Suite.java | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java index d491bf4df48a..4edaa75c64f5 100644 --- a/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java +++ b/junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java @@ -46,8 +46,7 @@ * *

Note: Depending on the declared test selection, different suites may contain the * same tests, potentially with different configurations. - * - *

Moreover, tests in a suite are executed in addition to the tests executed by every + * Moreover, tests in a suite are executed in addition to the tests executed by every * other test engine. This can result in the same tests being executed twice and can be * prevented by configuring your build tool to only include the * {@code junit-platform-suite} engine. Or by using a naming pattern. For example, name