Introduce parseable DiscoverySelector representations

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

@@ -22,9 +22,35 @@ endif::[]
 // Platform Engine
 :junit-platform-engine:                      {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/package-summary.html[junit-platform-engine]
 :junit-platform-engine-support-discovery:    {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/support/discovery/package-summary.html[org.junit.platform.engine.support.discovery]
-:DiscoverySelectors_selectMethod:            {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectMethod-java.lang.String-[selectMethod(String) in DiscoverySelectors]
+:ClasspathResourceSelector:                  {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ClasspathResourceSelector.html[ClasspathResourceSelector]
+:ClasspathRootSelector:                      {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ClasspathRootSelector.html[ClasspathRootSelector]
+:ClassSelector:                              {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ClassSelector.html[ClassSelector]
+:DirectorySelector:                          {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DirectorySelector.html[DirectorySelector]
+:DiscoverySelectors:                         {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html[DiscoverySelectors]
+:DiscoverySelectors_selectClasspathResource: {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectClasspathResource(java.lang.String)[selectClasspathResource]
+:DiscoverySelectors_selectClasspathRoots:    {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectClasspathRoots(java.util.Set)[selectClasspathRoots]
+:DiscoverySelectors_selectClass:             {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectClass(java.lang.String)[selectClass]
+:DiscoverySelectors_selectDirectory:         {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectDirectory(java.lang.String)[selectDirectory]
+:DiscoverySelectors_selectFile:              {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectFile(java.lang.String)[selectFile]
+:DiscoverySelectors_selectIteration:         {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectIteration(org.junit.platform.engine.DiscoverySelector,int\...)[selectIteration]
+:DiscoverySelectors_selectMethod:            {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectMethod(java.lang.String)[selectMethod]
+:DiscoverySelectors_selectModule:            {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectModule(java.lang.String)[selectModule]
+:DiscoverySelectors_selectNestedClass:       {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectNestedClass(java.util.List,java.lang.Class)[selectNestedClass]
+:DiscoverySelectors_selectNestedMethod:      {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectNestedMethod(java.util.List,java.lang.Class,java.lang.String)[selectNestedMethod]
+:DiscoverySelectors_selectPackage:           {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectPackage(java.lang.String)[selectPackage]
+:DiscoverySelectors_selectUniqueId:          {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectUniqueId(java.lang.String)[selectUniqueId]
+:DiscoverySelectors_selectUri:               {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectUri(java.lang.String)[selectUri]
+:FileSelector:                               {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/FileSelector.html[FileSelector]
 :HierarchicalTestEngine:                     {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/support/hierarchical/HierarchicalTestEngine.html[HierarchicalTestEngine]
+:IterationSelector:                          {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/IterationSelector.html[IterationSelector]
+:MethodSelector:                             {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/MethodSelector.html[MethodSelector]
+:ModuleSelector:                             {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ModuleSelector.html[ModuleSelector]
+:NestedClassSelector:                        {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/NestedClassSelector.html[NestedClassSelector]
+:NestedMethodSelector:                       {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/NestedMethodSelector.html[NestedMethodSelector]
+:PackageSelector:                            {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/PackageSelector.html[PackageSelector]
 :ParallelExecutionConfigurationStrategy:     {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/support/hierarchical/ParallelExecutionConfigurationStrategy.html[ParallelExecutionConfigurationStrategy]
+:UniqueIdSelector:                           {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/UniqueIdSelector.html[UniqueIdSelector]
+:UriSelector:                                {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/UriSelector.html[UriSelector]
 :TestEngine:                                 {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/TestEngine.html[TestEngine]
 // Platform Launcher API
 :junit-platform-launcher:                    {javadoc-root}/org.junit.platform.launcher/org/junit/platform/launcher/package-summary.html[junit-platform-launcher]
@@ -51,6 +77,15 @@ endif::[]
 // 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]
+:Select:                                     {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/Select.html[@Select]
+:SelectClasspathResource:                    {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/SelectClasspathResource.html[@SelectClasspathResource]
+:SelectClasses:                              {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/SelectClasses.html[@SelectClasses]
+:SelectDirectories:                          {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/SelectDirectories.html[@SelectDirectories]
+:SelectFile:                                 {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/SelectFile.html[@SelectFile]
+:SelectMethod:                               {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/SelectMethod.html[@SelectMethod]
+:SelectModules:                              {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/SelectModules.html[@SelectModules]
+:SelectPackages:                             {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/SelectPackages.html[@SelectPackages]
+:SelectUris:                                 {javadoc-root}/org.junit.platform.suite.api/org/junit/platform/suite/api/SelectUris.html[@SelectUris]
 // 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.11.0-M2.adoc

@@ -36,6 +36,19 @@ repository on GitHub.
 [[release-notes-5.11.0-M2-junit-platform-new-features-and-improvements]]
 ==== New Features and Improvements
 
+* All Platform implementations of `DiscoverySelector` now have a parseable string
+  representation that can be generated by calling the new
+  `DiscoverySelector.toIdentifier()` method and `toString()` on the returned
+  `DiscoverySelectorIdentifier`. This string representation can be used to reconstruct
+  the original `DiscoverySelector` by calling the new `DiscoverySelectors.parse()` method.
+  This change will allow build tools and IDEs to provide generic mechanisms for specifying
+  selectors on the command line or in configuration files without having to support each
+  selector type individually.
+  - The Console Launcher supports specifying selectors via their identifiers using the
+    `--select` option. For example, `--select class:foo.Bar` will run all tests in the
+    `foo.Bar` class.
+  - Similarly, the JUnit Platform Suite engine provides a new `@Select("<identifier>)`
+    annotation.
 * `NamespacedHierarchicalStore` now throws an `IllegalStateException` for any attempt to
   modify or query the store after it has been closed. In addition, an attempt to close a
   store that has already been closed will have no effect.

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

@@ -704,18 +704,21 @@ The `{ConsoleLauncher}` provides the following subcommands:
 include::{consoleLauncherOptionsFile}[]
 ----
 
+[[running-tests-console-launcher-options-discovering-tests]]
 ===== Discovering tests
 
 ----
 include::{consoleLauncherDiscoverOptionsFile}[]
 ----
 
+[[running-tests-console-launcher-options-executing-tests]]
 ===== Executing tests
 
 ----
 include::{consoleLauncherExecuteOptionsFile}[]
 ----
 
+[[running-tests-console-launcher-options-listing-test-engines]]
 ===== Listing test engines
 
 ----
@@ -887,6 +890,38 @@ WARNING: Test classes and suites annotated with `@RunWith(JUnitPlatform.class)`
 documented in some IDEs). Such classes and suites can only be executed using JUnit 4
 infrastructure.
 
+[[running-tests-discovery-selectors]]
+=== Discovery Selectors
+
+The JUnit Platform provides a rich set of discovery selectors that can be used to specify
+which tests should be discovered or executed.
+
+Discovery selectors can be created programmatically using the factory methods in the
+`{DiscoverySelectors}` class, specified declaratively via annotations when using the
+<<junit-platform-suite-engine>>, via options of the <<running-tests-console-launcher>>, or
+generically as strings via their identifiers.
+
+The following discovery selectors are provided out of the box:
+
+|===
+| Java Type                     | API                                            | Annotation                  | Console Launcher                                 | Identifier
+
+| `{ClasspathResourceSelector}` | `{DiscoverySelectors_selectClasspathResource}` | `{SelectClasspathResource}` | `--select-resource /foo.csv`                     | `resource:/foo.csv`
+| `{ClasspathRootSelector}`     | `{DiscoverySelectors_selectClasspathRoots}`    | --                          | `--scan-classpath bin`                           | `classpath-root:bin`
+| `{ClassSelector}`             | `{DiscoverySelectors_selectClass}`             | `{SelectClasses}`           | `--select-class com.acme.Foo`                    | `class:com.acme.Foo`
+| `{DirectorySelector}`         | `{DiscoverySelectors_selectDirectory}`         | `{SelectDirectories}`       | `--select-directory foo/bar`                     | `directory:foo/bar`
+| `{FileSelector}`              | `{DiscoverySelectors_selectFile}`              | `{SelectFile}`              | `--select-file dir/foo.txt`                      | `file:dir/foo.txt`
+| `{IterationSelector}`         | `{DiscoverySelectors_selectIteration}`         | `{Select}("<identifier>")`  | `--select-iteration method=com.acme.Foo#m[1..2]` | `iteration:method:com.acme.Foo#m[1..2]`
+| `{MethodSelector}`            | `{DiscoverySelectors_selectMethod}`            | `{SelectMethod}`            | `--select-method com.acme.Foo#m`                 | `method:com.acme.Foo#m`
+| `{ModuleSelector}`            | `{DiscoverySelectors_selectModule}`            | `{SelectModules}`           | `--select-module com.acme`                       | `module:com.acme`
+| `{NestedClassSelector}`       | `{DiscoverySelectors_selectNestedClass}`       | `{Select}("<identifier>")`  | `--select <identifier>`                          | `nested-class:com.acme.Foo/Bar`
+| `{NestedMethodSelector}`      | `{DiscoverySelectors_selectNestedMethod}`      | `{Select}("<identifier>")`  | `--select <identifier>`                          | `nested-method:com.acme.Foo/Bar#m`
+| `{PackageSelector}`           | `{DiscoverySelectors_selectPackage}`           | `{SelectPackages}`          | `--select-package com.acme.foo`                  | `package:com.acme.foo`
+| `{UniqueIdSelector}`          | `{DiscoverySelectors_selectUniqueId}`          | `{Select}("<identifier>")`  | `--select <identifier>`                          | `uid:...`
+| `{UriSelector}`               | `{DiscoverySelectors_selectUri}`               | `{SelectUris}`              | `--select-uri \file:///foo.txt`                  | `uri:file:///foo.txt`
+|===
+
+
 [[running-tests-config-params]]
 === Configuration Parameters
 

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

@@ -2401,8 +2401,8 @@ implementations.
 `MethodSource` ::
   If the `URI` contains the `method` scheme and the fully qualified method name (FQMN) --
   for example, `method:org.junit.Foo#bar(java.lang.String, java.lang.String[])`. Please
-  refer to the Javadoc for `DiscoverySelectors.selectMethod(String)` for the supported
-  formats for a FQMN.
+  refer to the Javadoc for `{DiscoverySelectors}.{DiscoverySelectors_selectMethod}` for the
+  supported formats for a FQMN.
 
 `ClassSource` ::
   If the `URI` contains the `class` scheme and the fully qualified class name --

junit-platform-commons/src/main/java/org/junit/platform/commons/util/CollectionUtils.java

@@ -25,6 +25,7 @@
 import java.util.Iterator;
 import java.util.List;
 import java.util.ListIterator;
+import java.util.Optional;
 import java.util.Set;
 import java.util.function.Consumer;
 import java.util.stream.Collector;
@@ -55,7 +56,7 @@ private CollectionUtils() {
 	}
 
 	/**
-	 * Read the only element of a collection of size 1.
+	 * Get the only element of a collection of size 1.
 	 *
 	 * @param collection the collection to get the element from
 	 * @return the only element of the collection
@@ -66,7 +67,29 @@ public static <T> T getOnlyElement(Collection<T> collection) {
 		Preconditions.notNull(collection, "collection must not be null");
 		Preconditions.condition(collection.size() == 1,
 			() -> "collection must contain exactly one element: " + collection);
-		return collection.iterator().next();
+		return firstElement(collection);
+	}
+
+	/**
+	 * Get the first element of the supplied collection unless it's empty.
+	 *
+	 * @param collection the collection to get the element from
+	 * @return the first element of the collection; empty if the collection is empty
+	 * @throws PreconditionViolationException if the collection is {@code null}
+	 * @since 1.11
+	 */
+	@API(status = INTERNAL, since = "1.11")
+	public static <T> Optional<T> getFirstElement(Collection<T> collection) {
+		Preconditions.notNull(collection, "collection must not be null");
+		return collection.isEmpty() //
+				? Optional.empty() //
+				: Optional.ofNullable(firstElement(collection));
+	}
+
+	private static <T> T firstElement(Collection<T> collection) {
+		return collection instanceof List //
+				? ((List<T>) collection).get(0) //
+				: collection.iterator().next();
 	}
 
 	/**

junit-platform-commons/src/main/java/org/junit/platform/commons/util/ReflectionUtils.java

@@ -929,13 +929,34 @@ public static String getFullyQualifiedMethodName(Class<?> clazz, Method method)
 	 * @param methodName the name of the method; never {@code null} or blank
 	 * @param parameterTypes the parameter types of the method; may be {@code null} or empty
 	 * @return fully qualified method name; never {@code null}
-	 * @see #getFullyQualifiedMethodName(Class, Method)
 	 */
 	public static String getFullyQualifiedMethodName(Class<?> clazz, String methodName, Class<?>... parameterTypes) {
 		Preconditions.notNull(clazz, "Class must not be null");
 		Preconditions.notBlank(methodName, "Method name must not be null or blank");
 
-		return String.format("%s#%s(%s)", clazz.getName(), methodName, ClassUtils.nullSafeToString(parameterTypes));
+		return getFullyQualifiedMethodName(clazz.getName(), methodName, ClassUtils.nullSafeToString(parameterTypes));
+	}
+
+	/**
+	 * Build the <em>fully qualified method name</em> for the method described by the
+	 * supplied class, method name, and parameter types.
+	 *
+	 * <p>Note that the class is not necessarily the class in which the method is
+	 * declared.
+	 *
+	 * @param className the name of the class from which the method should be referenced; never {@code null}
+	 * @param methodName the name of the method; never {@code null} or blank
+	 * @param parameterTypeNames the parameter type names of the method; may be empty but not {@code null}
+	 * @return fully qualified method name; never {@code null}
+	 * @since 1.11
+	 */
+	@API(status = INTERNAL, since = "1.11")
+	public static String getFullyQualifiedMethodName(String className, String methodName, String parameterTypeNames) {
+		Preconditions.notBlank(className, "Class name must not be null or blank");
+		Preconditions.notBlank(methodName, "Method name must not be null or blank");
+		Preconditions.notNull(parameterTypeNames, "Parameter type names must not be null");
+
+		return String.format("%s#%s(%s)", className, methodName, parameterTypeNames);
 	}
 
 	/**