Introduce parseable DiscoverySelector representations

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.of(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

@@ -887,13 +887,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);
 	}
 
 	/**

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

@@ -14,6 +14,9 @@
 import static org.apiguardian.api.API.Status.INTERNAL;
 
 import java.util.Arrays;
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import java.util.function.Supplier;
 import java.util.regex.Pattern;
 
 import org.apiguardian.api.API;
@@ -256,4 +259,106 @@ public static String replaceWhitespaceCharacters(String str, String replacement)
 		return str == null ? null : WHITESPACE_PATTERN.matcher(str).replaceAll(replacement);
 	}
 
+	/**
+	 * Split the supplied {@link String} into up to two parts using the supplied
+	 * separator character.
+	 *
+	 * @param separator the separator character
+	 * @param value the value to split; never {@code null}
+	 * @since 1.11
+	 */
+	@API(status = INTERNAL, since = "1.11")
+	public static TwoPartSplitResult splitIntoTwo(char separator, String value) {
+		Preconditions.notNull(value, "value must not be null");
+		return splitIntoTwo(value, value.indexOf(separator), 1);
+	}
+
+	/**
+	 * Split the supplied {@link String} into up to two parts using the supplied
+	 * separator string.
+	 *
+	 * @param separator the separator string; never {@code null}
+	 * @param value the value to split; never {@code null}
+	 * @since 1.11
+	 */
+	@API(status = INTERNAL, since = "1.11")
+	public static TwoPartSplitResult splitIntoTwo(String separator, String value) {
+		Preconditions.notNull(separator, "separator must not be null");
+		Preconditions.notNull(value, "value must not be null");
+		return splitIntoTwo(value, value.indexOf(separator), separator.length());
+	}
+
+	private static TwoPartSplitResult splitIntoTwo(String value, int index, int length) {
+		if (index == -1) {
+			return new OnePart(value);
+		}
+		return new TwoParts(value.substring(0, index), value.substring(index + length));
+	}
+
+	/**
+	 * The result of splitting a string into up to two parts.
+	 *
+	 * @since 1.11
+	 * @see StringUtils#splitIntoTwo(char, String)
+	 * @see StringUtils#splitIntoTwo(String, String)
+	 */
+	@API(status = INTERNAL, since = "1.11")
+	public interface TwoPartSplitResult {
+
+		/**
+		 * Maps the result of splitting a string into two parts or throw an exception.
+		 *
+		 * @param onePartExceptionCreator the exception creator to use if the string was split into a single part
+		 * @param twoPartsMapper the mapper to use if the string was split into two parts
+		 */
+		default <T> T mapTwo(Supplier<? extends RuntimeException> onePartExceptionCreator,
+				BiFunction<String, String, ? extends T> twoPartsMapper) {
+			Function<String, ? extends T> onePartMapper = __ -> {
+				throw onePartExceptionCreator.get();
+			};
+			return map(onePartMapper, twoPartsMapper);
+		}
+
+		/**
+		 * Maps the result of splitting a string into up to two parts.
+		 *
+		 * @param onePartMapper the mapper to use if the string was split into a single part
+		 * @param twoPartsMapper the mapper to use if the string was split into two parts
+		 */
+		<T> T map(Function<String, ? extends T> onePartMapper, BiFunction<String, String, ? extends T> twoPartsMapper);
+
+	}
+
+	private static final class OnePart implements TwoPartSplitResult {
+
+		private final String value;
+
+		OnePart(String value) {
+			this.value = value;
+		}
+
+		@Override
+		public <T> T map(Function<String, ? extends T> onePartMapper,
+				BiFunction<String, String, ? extends T> twoPartsMapper) {
+			return onePartMapper.apply(value);
+		}
+	}
+
+	private static final class TwoParts implements TwoPartSplitResult {
+
+		private final String first;
+		private final String second;
+
+		TwoParts(String first, String second) {
+			this.first = first;
+			this.second = second;
+		}
+
+		@Override
+		public <T> T map(Function<String, ? extends T> onePartMapper,
+				BiFunction<String, String, ? extends T> twoPartsMapper) {
+			return twoPartsMapper.apply(first, second);
+		}
+	}
+
 }

junit-platform-console/src/main/java/org/junit/platform/console/options/SelectorConverter.java

@@ -14,22 +14,17 @@
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClasspathResource;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectDirectory;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectFile;
-import static org.junit.platform.engine.discovery.DiscoverySelectors.selectIteration;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectMethod;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectModule;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectPackage;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectUri;
 
-import java.util.Arrays;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-import java.util.stream.IntStream;
-
-import org.junit.platform.commons.util.Preconditions;
-import org.junit.platform.engine.DiscoverySelector;
+import org.junit.platform.commons.PreconditionViolationException;
+import org.junit.platform.engine.DiscoverySelectorIdentifier;
 import org.junit.platform.engine.discovery.ClassSelector;
 import org.junit.platform.engine.discovery.ClasspathResourceSelector;
 import org.junit.platform.engine.discovery.DirectorySelector;
+import org.junit.platform.engine.discovery.DiscoverySelectors;
 import org.junit.platform.engine.discovery.FileSelector;
 import org.junit.platform.engine.discovery.IterationSelector;
 import org.junit.platform.engine.discovery.MethodSelector;
@@ -99,51 +94,21 @@ public ClasspathResourceSelector convert(String value) {
 
 	static class Iteration implements ITypeConverter<IterationSelector> {
 
-		public static final Pattern PATTERN = Pattern.compile(
-			"(?<type>[a-z]+):(?<value>.*)\\[(?<indices>(\\d+)(\\.\\.\\d+)?(\\s*,\\s*(\\d+)(\\.\\.\\d+)?)*)]");
-
 		@Override
 		public IterationSelector convert(String value) {
-			Matcher matcher = PATTERN.matcher(value);
-			Preconditions.condition(matcher.matches(), "Invalid format: must be TYPE:VALUE[INDEX(,INDEX)*]");
-			DiscoverySelector parentSelector = createParentSelector(matcher.group("type"), matcher.group("value"));
-			int[] iterationIndices = Arrays.stream(matcher.group("indices").split(",")) //
-					.flatMapToInt(this::parseIndexDefinition) //
-					.toArray();
-			return selectIteration(parentSelector, iterationIndices);
+			DiscoverySelectorIdentifier identifier = DiscoverySelectorIdentifier.create(
+				IterationSelector.IdentifierParser.PREFIX, value);
+			return (IterationSelector) DiscoverySelectors.parse(identifier) //
+					.orElseThrow(() -> new PreconditionViolationException("Invalid format: Failed to parse selector"));
 		}
 
-		private IntStream parseIndexDefinition(String value) {
-			String[] parts = value.split("\\.\\.", 2);
-			int firstIndex = Integer.parseInt(parts[0]);
-			if (parts.length == 2) {
-				int lastIndex = Integer.parseInt(parts[1]);
-				return IntStream.rangeClosed(firstIndex, lastIndex);
-			}
-			return IntStream.of(firstIndex);
-		}
+	}
+
+	static class Identifier implements ITypeConverter<DiscoverySelectorIdentifier> {
 
-		private DiscoverySelector createParentSelector(String type, String value) {
-			switch (type) {
-				case "module":
-					return selectModule(value);
-				case "uri":
-					return selectUri(value);
-				case "file":
-					return selectFile(value);
-				case "directory":
-					return selectDirectory(value);
-				case "package":
-					return selectPackage(value);
-				case "class":
-					return selectClass(value);
-				case "method":
-					return selectMethod(value);
-				case "resource":
-					return selectClasspathResource(value);
-				default:
-					throw new IllegalArgumentException("Unknown type: " + type);
-			}
+		@Override
+		public DiscoverySelectorIdentifier convert(String value) {
+			return DiscoverySelectorIdentifier.parse(value);
 		}
 	}
 

junit-platform-console/src/main/java/org/junit/platform/console/options/TestDiscoveryOptions.java

@@ -25,9 +25,11 @@
 
 import org.apiguardian.api.API;
 import org.junit.platform.engine.DiscoverySelector;
+import org.junit.platform.engine.DiscoverySelectorIdentifier;
 import org.junit.platform.engine.discovery.ClassSelector;
 import org.junit.platform.engine.discovery.ClasspathResourceSelector;
 import org.junit.platform.engine.discovery.DirectorySelector;
+import org.junit.platform.engine.discovery.DiscoverySelectors;
 import org.junit.platform.engine.discovery.FileSelector;
 import org.junit.platform.engine.discovery.IterationSelector;
 import org.junit.platform.engine.discovery.MethodSelector;
@@ -56,6 +58,7 @@ public class TestDiscoveryOptions {
 	private List<MethodSelector> selectedMethods = emptyList();
 	private List<ClasspathResourceSelector> selectedClasspathResources = emptyList();
 	private List<IterationSelector> selectedIterations = emptyList();
+	private List<DiscoverySelectorIdentifier> selectorIdentifiers = emptyList();
 
 	private List<String> includedClassNamePatterns = singletonList(STANDARD_INCLUDE_PATTERN);
 	private List<String> excludedClassNamePatterns = emptyList();
@@ -176,6 +179,14 @@ public void setSelectedIterations(List<IterationSelector> selectedIterations) {
 		this.selectedIterations = selectedIterations;
 	}
 
+	public List<DiscoverySelectorIdentifier> getSelectorIdentifiers() {
+		return selectorIdentifiers;
+	}
+
+	public void setSelectorIdentifiers(List<DiscoverySelectorIdentifier> selectorIdentifiers) {
+		this.selectorIdentifiers = selectorIdentifiers;
+	}
+
 	public List<DiscoverySelector> getExplicitSelectors() {
 		List<DiscoverySelector> selectors = new ArrayList<>();
 		selectors.addAll(getSelectedUris());
@@ -187,6 +198,7 @@ public List<DiscoverySelector> getExplicitSelectors() {
 		selectors.addAll(getSelectedMethods());
 		selectors.addAll(getSelectedClasspathResources());
 		selectors.addAll(getSelectedIterations());
+		DiscoverySelectors.parseAll(getSelectorIdentifiers()).forEach(selectors::add);
 		return selectors;
 	}
 

junit-platform-console/src/main/java/org/junit/platform/console/options/TestDiscoveryOptionsMixin.java

@@ -17,6 +17,7 @@
 import java.util.List;
 import java.util.Map;
 
+import org.junit.platform.engine.DiscoverySelectorIdentifier;
 import org.junit.platform.engine.discovery.ClassNameFilter;
 import org.junit.platform.engine.discovery.ClassSelector;
 import org.junit.platform.engine.discovery.ClasspathResourceSelector;
@@ -135,6 +136,10 @@ static class SelectorOptions {
 				"-select-iteration" }, arity = "1", hidden = true, converter = SelectorConverter.Iteration.class)
 		private final List<IterationSelector> selectedIterations2 = new ArrayList<>();
 
+		@Option(names = {
+				"--select" }, arity = "1", converter = SelectorConverter.Identifier.class, description = "Select via a prefixed identifier. This option can be repeated.")
+		private final List<DiscoverySelectorIdentifier> selectorIdentifiers = new ArrayList<>();
+
 		SelectorOptions() {
 		}
 
@@ -152,6 +157,7 @@ private void applyTo(TestDiscoveryOptions result) {
 			result.setSelectedClasspathResources(
 				merge(this.selectedClasspathResources, this.selectedClasspathResources2));
 			result.setSelectedIterations(merge(this.selectedIterations, this.selectedIterations2));
+			result.setSelectorIdentifiers(this.selectorIdentifiers);
 		}
 	}
 

junit-platform-engine/src/main/java/org/junit/platform/engine/DiscoverySelector.java

@@ -10,9 +10,13 @@
 
 package org.junit.platform.engine;
 
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
+import java.util.Optional;
+
 import org.apiguardian.api.API;
+import org.junit.platform.engine.discovery.DiscoverySelectorIdentifierParser;
 
 /**
  * A selector defines what a {@link TestEngine} can use to discover tests
@@ -25,4 +29,21 @@
  */
 @API(status = STABLE, since = "1.0")
 public interface DiscoverySelector {
+
+	/**
+	 * Return the {@linkplain DiscoverySelectorIdentifier identifier} of this
+	 * selector.
+	 * <p>
+	 * The returned identifier has to be parsable by a corresponding
+	 * {@link DiscoverySelectorIdentifierParser}.
+	 * <p>
+	 * @return the identifier of this selector or empty if it is not supported;
+	 * never {@code null}
+	 * @since 1.11
+	 */
+	@API(status = EXPERIMENTAL, since = "1.11")
+	default Optional<DiscoverySelectorIdentifier> toIdentifier() {
+		return Optional.empty();
+	}
+
 }