Introduce parseable DiscoverySelector representations

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

@@ -12,6 +12,8 @@
 
 import static org.apiguardian.api.API.Status.STABLE;
 
+import java.util.Optional;
+
 import org.apiguardian.api.API;
 
 /**
@@ -25,4 +27,16 @@
  */
 @API(status = STABLE, since = "1.0")
 public interface DiscoverySelector {
+
+	/**
+	 * Return a {@link String} representation of this selector.
+	 * <p>
+	 * The returned string has to be parsable by a corresponding
+	 * {@link org.junit.platform.engine.discovery.SelectorParser}.
+	 * <p>
+	 * @return a {@link String} representation of this selector or empty if it is not supported.
+	 */
+	default Optional<String> toSelectorString() {
+		return Optional.empty();
+	}
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/ClassSelector.java

@@ -14,6 +14,8 @@
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.util.Objects;
+import java.util.Optional;
+import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.PreconditionViolationException;
@@ -133,4 +135,26 @@ public String toString() {
 		// @formatter:on
 	}
 
+	@Override
+	public Optional<String> toSelectorString() {
+		return Optional.of(String.format("%s:%s", Parser.PREFIX, this.className));
+	}
+
+	public static class Parser implements SelectorParser {
+
+		private static final String PREFIX = "class";
+
+		public Parser() {
+		}
+
+		@Override
+		public String getPrefix() {
+			return PREFIX;
+		}
+
+		@Override
+		public Stream<DiscoverySelector> parse(TBD selector, SelectorParserContext context) {
+			return Stream.of(DiscoverySelectors.selectClass(selector.getValue()));
+		}
+	}
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/ClasspathResourceSelector.java

@@ -12,8 +12,10 @@
 
 import static org.apiguardian.api.API.Status.STABLE;
 
+import java.net.URI;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.util.ToStringBuilder;
@@ -101,4 +103,42 @@ public String toString() {
 			this.position).toString();
 	}
 
+	@Override
+	public Optional<String> toSelectorString() {
+		return Optional.of(
+			String.format("%s:%s", Parser.PREFIX, CodingUtil.normalizeDirectorySeparators(this.classpathResourceName)));
+	}
+
+	public static class Parser implements SelectorParser {
+
+		private static final String PREFIX = "classpath";
+
+		public Parser() {
+		}
+
+		@Override
+		public String getPrefix() {
+			return PREFIX;
+		}
+
+		@Override
+		public Stream<DiscoverySelector> parse(TBD selector, SelectorParserContext context) {
+			String part = selector.getValue();
+
+			// Unfortunately, URI only parses the query if you have scheme://something?query
+			int queryIndex = part.indexOf('?');
+			String resourceName;
+			FilePosition position;
+			if (queryIndex == -1) {
+				resourceName = part;
+				position = null;
+			}
+			else {
+				resourceName = part.substring(0, queryIndex);
+				position = FilePosition.fromQuery(part.substring(queryIndex + 1)).orElse(null);
+			}
+
+			return Stream.of(DiscoverySelectors.selectClasspathResource(resourceName, position));
+		}
+	}
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/ClasspathRootSelector.java

@@ -13,7 +13,11 @@
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.net.URI;
+import java.nio.file.Paths;
+import java.util.Collections;
 import java.util.Objects;
+import java.util.Optional;
+import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.util.ToStringBuilder;
@@ -82,4 +86,29 @@ public String toString() {
 		return new ToStringBuilder(this).append("classpathRoot", this.classpathRoot).toString();
 	}
 
+	@Override
+	public Optional<String> toSelectorString() {
+		return Optional.of(String.format("%s:%s", Parser.PREFIX,
+			CodingUtil.normalizeDirectorySeparators(String.valueOf(this.classpathRoot))));
+	}
+
+	public static class Parser implements SelectorParser {
+
+		private static final String PREFIX = "classpath-root";
+
+		public Parser() {
+
+		}
+
+		@Override
+		public String getPrefix() {
+			return PREFIX;
+		}
+
+		@Override
+		public Stream<DiscoverySelector> parse(TBD selector, SelectorParserContext context) {
+			return DiscoverySelectors.selectClasspathRoots(
+				Collections.singleton(Paths.get(selector.getValue()))).stream().map(DiscoverySelector.class::cast);
+		}
+	}
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/CodingUtil.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2015-2024 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 org.junit.platform.engine.discovery;
+
+import java.io.UnsupportedEncodingException;
+import java.net.URLDecoder;
+import java.net.URLEncoder;
+
+final class CodingUtil {
+	private CodingUtil() {
+	}
+
+	static String urlDecode(String encoded) {
+		try {
+			return URLDecoder.decode(encoded, "UTF-8");
+		}
+		catch (UnsupportedEncodingException e) {
+			throw new IllegalStateException("UTF-8 is not supported", e);
+		}
+	}
+
+	static String urlEncode(String plain) {
+		try {
+			return URLEncoder.encode(plain, "UTF-8");
+		}
+		catch (UnsupportedEncodingException e) {
+			throw new IllegalStateException("UTF-8 is not supported", e);
+		}
+	}
+
+	static String normalizeDirectorySeparators(String path) {
+		return path.replace('\\', '/');
+	}
+}

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DirectorySelector.java

@@ -13,11 +13,14 @@
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.io.File;
+import java.net.URI;
 import java.nio.file.FileSystem;
 import java.nio.file.FileSystems;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.Objects;
+import java.util.Optional;
+import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.util.ToStringBuilder;
@@ -107,4 +110,25 @@ public String toString() {
 		return new ToStringBuilder(this).append("path", this.path).toString();
 	}
 
+	@Override
+	public Optional<String> toSelectorString() {
+		return Optional.of(String.format("%s:%s", Parser.PREFIX, CodingUtil.normalizeDirectorySeparators(this.path)));
+	}
+	public static class Parser implements SelectorParser {
+
+		private static final String PREFIX = "directory";
+
+		public Parser() {
+		}
+
+		@Override
+		public String getPrefix() {
+			return PREFIX;
+		}
+
+		@Override
+		public Stream<DiscoverySelector> parse(TBD selector, SelectorParserContext context) {
+			return Stream.of(DiscoverySelectors.selectDirectory(selector.getValue()));
+		}
+	}
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectors.java

@@ -23,6 +23,7 @@
 import java.nio.file.Path;
 import java.util.List;
 import java.util.Set;
+import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.PreconditionViolationException;
@@ -937,4 +938,7 @@ public static IterationSelector selectIteration(DiscoverySelector parentSelector
 		return new IterationSelector(parentSelector, iterationIndices);
 	}
 
+	public static Stream<DiscoverySelector> parse(String selector) {
+		return new SelectorParsers().parse(selector);
+	}
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/FilePosition.java

@@ -153,6 +153,14 @@ public Optional<Integer> getColumn() {
 		return Optional.ofNullable(this.column);
 	}
 
+	String toQueryPart() {
+		StringBuilder builder = new StringBuilder("line=").append(this.line);
+		if (this.column != null) {
+			builder.append("&column=").append(this.column);
+		}
+		return builder.toString();
+	}
+
 	@Override
 	public boolean equals(Object o) {
 		if (this == o) {

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/FileSelector.java

@@ -13,12 +13,14 @@
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.io.File;
+import java.net.URI;
 import java.nio.file.FileSystem;
 import java.nio.file.FileSystems;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.util.ToStringBuilder;
@@ -117,4 +119,44 @@ public String toString() {
 		return new ToStringBuilder(this).append("path", this.path).append("position", this.position).toString();
 	}
 
+	@Override
+	public Optional<String> toSelectorString() {
+		if (this.position == null) {
+			return Optional.of(
+				String.format("%s://%s", Parser.PREFIX, CodingUtil.normalizeDirectorySeparators(this.path)));
+		}
+		else {
+			return Optional.of(String.format("%s://%s?%s", Parser.PREFIX,
+				CodingUtil.normalizeDirectorySeparators(this.path), this.position.toQueryPart()));
+		}
+	}
+
+	public static class Parser implements SelectorParser {
+
+		private static final String PREFIX = "file";
+
+		public Parser() {
+		}
+
+		@Override
+		public String getPrefix() {
+			return PREFIX;
+		}
+
+		@Override
+		public Stream<DiscoverySelector> parse(TBD selector, SelectorParserContext context) {
+			// Problem: the real file url, e.g. `file:///` does not support relative paths.
+			// if we use just the schemeSpecificPart and omit the `///` we can support `file:relative/path` and `file:/absolute/path`
+			// however it won't parse the Query part of the URI anymore, which is used to specify the line and column.
+			// and it won't be a standard file URI (https://en.wikipedia.org/wiki/File_URI_scheme) anymore.
+			// For now, we misuse the host part of the uri, so when it is set, we treat it as relative path and when it is not set, we treat it as absolute path.
+
+			URI uri = URI.create(selector.getPrefix() + ":" + selector.getValue());
+			String path = uri.getHost() == null ? uri.getPath() : uri.getHost() + uri.getPath();
+
+			return FilePosition.fromQuery(uri.getQuery()).map(filePosition -> Stream.<DiscoverySelector> of(
+				DiscoverySelectors.selectFile(path, filePosition))).orElseGet(
+					() -> Stream.of(DiscoverySelectors.selectFile(path)));
+		}
+	}
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/IterationSelector.java

@@ -14,11 +14,15 @@
 import static java.util.stream.Collectors.toCollection;
 import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 
+import java.net.URI;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.SortedSet;
 import java.util.TreeSet;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.util.ToStringBuilder;
@@ -90,4 +94,34 @@ public String toString() {
 				.toString();
 		// @formatter:on
 	}
+
+	@Override
+	public Optional<String> toSelectorString() {
+		return parentSelector.toSelectorString().map(parentSelectorString -> String.format("%s:%s#%s", //
+			Parser.PREFIX, //
+			CodingUtil.urlEncode(parentSelectorString), //
+			iterationIndices.stream().map(String::valueOf).collect(Collectors.joining(","))));
+	}
+
+	public static class Parser implements SelectorParser {
+
+		private static final String PREFIX = "iteration";
+
+		public Parser() {
+		}
+
+		@Override
+		public String getPrefix() {
+			return PREFIX;
+		}
+
+		@Override
+		public Stream<DiscoverySelector> parse(TBD selector, SelectorParserContext context) {
+			int[] iterationIndices = Arrays.stream(selector.getFragment().split(",")).mapToInt(
+				Integer::parseInt).toArray();
+			String parentSelector = CodingUtil.urlDecode(selector.getValue());
+			return context.parse(parentSelector).map(
+				parent -> DiscoverySelectors.selectIteration(parent, iterationIndices));
+		}
+	}
 }