Document URI TestSource support of dynamic tests in User Guide

Author: ielatif

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

@@ -1571,6 +1571,28 @@ include::{testDir}/example/DynamicTestsDemo.java[tags=user_guide]
 ----
 
 
+[[writing-tests-uris-test-source-examples]]
+==== URI Test Source Examples
+
+The JUnit Platform provide `TestSource`, a representation of the source of a test
+or container used to navigate to its location by IDEs and build tools.
+
+Some test sources can be constructed using URIs :
+
+- `ClasspathResourceSource` : uses the `classpath` scheme ex `classpath:/test/foo.xml?line=20,column=2`
+- `DirectorySource` and `FileSource` : uses filesystem paths
+- `MethodSource` : uses the `method` scheme and the fully-qualified-method-name ex
+`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.
+
+The following `TestSourceUrisDemo` class
+demonstrates several examples of dynamic tests using test source URIs.
+
+[source,java]
+----
+include::{testDir}/example/TestSourceUrisDemo.java[tags=user_guide]
+----
+
 [[writing-tests-declarative-timeouts]]
 === Timeouts
 

documentation/src/test/java/example/TestSourceUrisDemo.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2015-2019 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 static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.DynamicTest.dynamicTest;
+
+import java.io.File;
+import java.net.URI;
+import java.nio.file.Paths;
+
+import org.junit.jupiter.api.DynamicTest;
+import org.junit.jupiter.api.TestFactory;
+
+// end::user_guide[]
+// @formatter:off
+// tag::user_guide[]
+public class TestSourceUrisDemo {
+
+	@TestFactory
+	DynamicTest classpathResourceSource() {
+		return dynamicTest(
+				"class path resource source uri",
+				URI.create("classpath:/two-column.csv"), // test source uri
+				() -> assertTrue(true)); // for demo purpose
+	}
+
+	@TestFactory
+	DynamicTest directorySource() {
+		File directory = Paths.get("src/test/resources").toFile();
+		return dynamicTest("directory source uri",
+				directory.toURI(), // test source uri
+				() -> assertTrue(true)); // for demo purpose
+	}
+
+	// Inspired by https://sormuras.github.io/blog/2018-09-05-junit-5.3-dynamic-test-source.html
+	@TestFactory
+	DynamicTest fileSource() {
+		File file = Paths.get("src/test/resources/two-column.csv").toFile();
+		return dynamicTest(
+						file.getName(),
+						file.toURI(), // test source uri
+						() -> assertTrue(true)); // for demo purpose
+	}
+
+	@TestFactory
+	DynamicTest methodSource() {
+		return dynamicTest("method source uri",
+				URI.create("method:example.TestSourceUrisDemo#method()"), // test source uri
+				() -> assertTrue(true)); // for demo purpose
+	}
+
+	private void method() {
+	}
+}
+// end::user_guide[]