Introduce junit-platform-suite-engine (#2416)

Implements a test engine that allows declarative execution of test suites using
the `@Suite` annotation.

Internally the Suite Engine uses the JUnit Platform Launcher. The engine works
adding the test descriptors of the discovered engines and tests as children to its
own test descriptor.

```java
package org.junit.platform.suite;

import org.junit.platform.suite.api.SelectPackages;

@suite
@SelectPackages("org.junit.suite.testcases")
class SelectPackageSuite {

}
```

Is equivalent to:

```java
import org.junit.platform.engine.discovery.DiscoverySelectors;
import org.junit.platform.launcher.Launcher;
import org.junit.platform.launcher.LauncherDiscoveryRequest;
import org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;
import org.junit.platform.launcher.core.LauncherFactory;

public class Main {

    public static void main(String[] args) {
        Launcher launcher = LauncherFactory.create();
        LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
                .selectors(DiscoverySelectors.selectPackage("org.junit.suite.testcases"))
                .build();
        launcher.execute(request);
    }
}
```

Resolves #744.

Author: mpkorstanje

build.gradle.kts

@@ -42,7 +42,10 @@ val platformProjects by extra(listOf(
 		project(":junit-platform-launcher"),
 		project(":junit-platform-reporting"),
 		project(":junit-platform-runner"),
+		project(":junit-platform-suite"),
 		project(":junit-platform-suite-api"),
+		project(":junit-platform-suite-commons"),
+		project(":junit-platform-suite-engine"),
 		project(":junit-platform-testkit")
 ))
 
@@ -76,6 +79,8 @@ val jacocoTestProjects = listOf(
 		project(":junit-jupiter-migrationsupport"),
 		project(":junit-jupiter-params"),
 		project(":junit-platform-runner"),
+		project(":junit-platform-suite-commons"),
+		project(":junit-platform-suite-engine"),
 		project(":junit-vintage-engine"),
 		project(":platform-tests")
 )

documentation/documentation.gradle.kts

@@ -41,6 +41,7 @@ dependencies {
 	testImplementation(project(":junit-jupiter-migrationsupport"))
 	testImplementation(project(":junit-platform-console"))
 	testImplementation(project(":junit-platform-runner"))
+	testImplementation(project(":junit-platform-suite"))
 	testImplementation(project(":junit-platform-testkit"))
 	testImplementation("org.jetbrains.kotlin:kotlin-stdlib")
 

documentation/src/docs/asciidoc/link-attributes.adoc

@@ -43,8 +43,9 @@ endif::[]
 :LegacyXmlReportGeneratingListener:          {javadoc-root}/org.junit.platform.reporting/org/junit/platform/reporting/legacy/xml/LegacyXmlReportGeneratingListener.html[LegacyXmlReportGeneratingListener]
 // Platform Runner
 :JUnitPlatform-Runner:                       {javadoc-root}/org.junit.platform.runnner/org/junit/platform/runner/JUnitPlatform.html[JUnitPlatform]
-// Platform Suite API
+// Platform Suite
 :suite-api-package:                          {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/package-summary.html[org.junit.platform.suite.api]
+:junit-platform-suite-engine                 {javadoc-root}/org.junit.platform.suite.engine/org/junit/platform/suite/engine/package-summary.html[junit-platform-suite-engine]
 // Platform Test Kit
 :testkit-engine-package:                     {javadoc-root}/org.junit.platform.testkit/org/junit/platform/testkit/engine/package-summary.html[org.junit.platform.testkit.engine]
 :EngineExecutionResults:                     {javadoc-root}/org.junit.platform.testkit/org/junit/platform/testkit/engine/EngineExecutionResults.html[EngineExecutionResults]

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

@@ -45,7 +45,9 @@ on GitHub.
   `LauncherSession` in order to allow for executing global setup and teardown code exactly
   once via the new `LauncherSessionListener` interface that can be registered via Java’s
   `{ServiceLoader}` mechanism.
-
+* New `junit-platform-suite-engine` to execute declarative test suites using the JUnit
+  Platform Launcher.
+* Added additional selectors to the `junit-platform-suite-api`
 
 [[release-notes-5.8.0-M1-junit-jupiter]]
 === JUnit Jupiter

documentation/src/docs/asciidoc/user-guide/advanced-topics.adoc

@@ -3,6 +3,8 @@
 
 include::launcher-api.adoc[]
 
+include::junit-platform-suite-engine.adoc[]
+
 include::testkit.adoc[]
 
 ////

documentation/src/docs/asciidoc/user-guide/appendix.adoc

@@ -50,10 +50,17 @@ artifacts are deployed to Sonatype's {snapshot-repo}[snapshots repository] under
   `junit-platform-runner`::
     Runner for executing tests and test suites on the JUnit Platform in a JUnit 4
     environment. See <<running-tests-junit-platform-runner>> for details.
+  `junit-platform-suite`::
+    JUnit Platform Suite artifact that transitively pulls in dependencies on
+    `junit-platform-suite-api`, `junit-platform-suite-engine` for simplified
+    dependency management in build tools such as Gradle and Maven.
   `junit-platform-suite-api`::
     Annotations for configuring test suites on the JUnit Platform. Supported by the
-    <<running-tests-junit-platform-runner,JUnitPlatform runner>> and possibly by
-    third-party `TestEngine` implementations.
+    <<junit-platform-suite-engine,JUnit Platform Suite Engine>> and
+    <<running-tests-junit-platform-runner,JUnitPlatform runner>>.
+  `junit-platform-suite-engine`::
+    Engine to execute suites on the JUnit Platform. See
+    <<junit-platform-suite-engine,JUnit Platform Suite Engine>> for details.
   `junit-platform-testkit`::
      Provides support for executing a test plan for a given `TestEngine` and then
      accessing the results via a fluent API to verify the expected results.
@@ -148,7 +155,10 @@ package org.junit.platform {
     [junit-platform-launcher] as launcher
     [junit-platform-reporting] as reporting
     [junit-platform-runner] as runner
+    [junit-platform-suite] as suite
     [junit-platform-suite-api] as suite_api
+    [junit-platform-suite-commons] as suite_commons
+    [junit-platform-suite-engine] as suite_engine
     [junit-platform-testkit] as testkit
 }
 
@@ -173,15 +183,15 @@ jupiter ..> jupiter_api
 jupiter ..> jupiter_params
 jupiter ..> jupiter_engine
 
-jupiter_api ..> opentest4j
-jupiter_api ..> commons
+jupiter_api ....> opentest4j
+jupiter_api ...> commons
 
-jupiter_engine ..> engine
+jupiter_engine ...> engine
 jupiter_engine ..> jupiter_api
 
 jupiter_params ..> jupiter_api
 jupiter_migration_support ..> jupiter_api
-jupiter_migration_support ..> junit4
+jupiter_migration_support ...> junit4
 
 console ..> launcher
 console ..> reporting
@@ -190,18 +200,25 @@ launcher ..> engine
 
 jfr ..> launcher
 
-engine ..> opentest4j
+engine ....> opentest4j
 engine ..> commons
 
 reporting ..> launcher
 
-runner ..> launcher
-runner ..> suite_api
-runner ..> junit4
+runner ..> suite_commons
+runner ...> junit4
 
-testkit ..> opentest4j
+suite ..> suite_api
+suite ..> suite_engine
+
+suite_engine ..> suite_commons
+
+suite_commons ..> launcher
+suite_commons ..> suite_api
+
+testkit ....> opentest4j
 testkit ..> launcher
 
-vintage_engine ..> engine
+vintage_engine ...> engine
 vintage_engine ..> junit4
 ----

documentation/src/docs/asciidoc/user-guide/junit-platform-suite-engine.adoc

@@ -0,0 +1,45 @@
+[[junit-platform-suite-engine]]
+=== JUnit Platform Suite Engine
+
+The JUnit Platform supports declarative definition and execution of suites of tests from
+_any_ test engine using the Junit Platform.
+
+==== Setup
+
+In addition to _at least one_ other test engine, you need the following artifacts and
+their dependencies on the classpath. See <<dependency-metadata>> for details regarding
+group IDs, artifact IDs, and versions.
+
+===== Explicit Dependencies
+
+* `junit-platform-suite-api` in _test_ scope
+* `junit-platform-suite-engine` in _test runtime_ scope: implementation of the
+                                `TestEngine` API for the declarative Junit Platform
+                                Suites
+
+NOTE: Both dependencies are aggregated in `junit-platform-suite` which can be used in
+_test_ scope.
+
+===== Transitive Dependencies
+
+* `junit-platform-suite-commons` in _test_ scope
+* `junit-platform-launcher` in _test_ scope
+* `junit-platform-engine` in _test_ scope
+* `junit-platform-commons` in _test_ scope
+* `opentest4j` in _test_ scope
+
+==== Test Suite
+
+By annotating a class with `@Suite` it is marked as a test suite on the JUnit Platform.
+As seen in the following example, selector and filter annotations can then be used to
+control the contents of the suite.
+
+[source,java,indent=0]
+----
+include::{testDir}/example/SuiteDemo.java[tags=user_guide]
+----
+
+.Additional Configuration Options
+NOTE: There are more configuration options for discovering and filtering tests than just
+`@SelectPackages`. Please consult the Javadoc of the `{suite-api-package}` package for
+further details.

documentation/src/docs/asciidoc/user-guide/launcher-api.adoc

@@ -77,6 +77,9 @@ JUnit currently provides two `{TestEngine}` implementations.
 * `{junit-jupiter-engine}`: The core of JUnit Jupiter.
 * `{junit-vintage-engine}`: A thin layer on top of JUnit 4 to allow running _vintage_
   tests with the launcher infrastructure.
+* `{junit-platform-suite-engine}`: To execute declarative suites of tests with the
+  launcher infrastructure.
+
 
 Third parties may also contribute their own `TestEngine` by implementing the interfaces
 in the {junit-platform-engine} module and _registering_ their engine. By default, engine

documentation/src/docs/asciidoc/user-guide/running-tests.adoc

@@ -630,6 +630,7 @@ You need the following artifacts and their dependencies on the classpath. See
 ===== Transitive Dependencies
 
 * `junit-platform-suite-api` in _test_ scope
+* `junit-platform-suite-commons` in _test_ scope
 * `junit-platform-launcher` in _test_ scope
 * `junit-platform-engine` in _test_ scope
 * `junit-platform-commons` in _test_ scope

documentation/src/test/java/example/SuiteDemo.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2015-2021 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
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package example;
+
+//tag::user_guide[]
+import org.junit.platform.suite.api.SelectPackages;
+import org.junit.platform.suite.api.Suite;
+import org.junit.platform.suite.api.SuiteDisplayName;
+
+@Suite
+@SuiteDisplayName("JUnit Platform Suite Demo")
+@SelectPackages("example")
+//end::user_guide[]
+@org.junit.platform.suite.api.ExcludeTags("exclude")
+//tag::user_guide[]
+public class SuiteDemo {
+}
+//end::user_guide[]