Add more docs for selecting individual test cases (#6089)

Author: lihaoyi

example/javalib/config/2-testing/build.mill

@@ -14,3 +14,25 @@ Test qux.QuxIntegrationTests#helloworld() finished...
 
 */
 //// SNIPPET:TEST
+
+//// SNIPPET:RUNSINGLE
+// e.g. the https://github.com/sbt/sbt-jupiter-interface[Junit5/Jupiter test interface]
+// used in this example lets  you pass in a selector to decide which individual test
+// case to run via:
+
+/** Usage
+
+> ./mill test 'qux.QuxTests.*'
+...qux.QuxTests...hello...
+...qux.QuxTests...world...
+Test run finished: 0 failed, 0 ignored, 2 total...
+
+> ./mill test 'qux.QuxTests.hello*'
+...qux.QuxTests...hello...
+Test run finished: 0 failed, 0 ignored, 1 total...
+
+*/
+
+// Note the trailing `*` that is necessary for the per-test selector to match.
+
+//// SNIPPET:END

example/javalib/config/2-testing/test/package.mill.yaml

@@ -1,2 +1,6 @@
 extends: [build.JavaTests, mill.javalib.TestModule.Junit5]
-mvnDeps: [org.junit.jupiter:junit-jupiter:5.8.2]
+mvnDeps: [
+  org.junit.jupiter:junit-jupiter-api:5.14.1,
+  org.junit.platform:junit-platform-launcher:1.14.1,
+  com.github.sbt.junit:jupiter-interface:0.16.0
+]

example/javalib/testing/1-test-suite/build.mill

@@ -29,3 +29,21 @@ object bar extends JavaModule {
 }
 
 //// SNIPPET:RUNSINGLE
+// e.g. the https://github.com/sbt/junit-interface[Junit4 test interface]
+// used in this example lets you pass in a selector to decide which individual test to run via:
+
+/** Usage
+
+> ./mill foo.test 'foo.FooMoreTests.*'
+...foo.FooMoreTests...hello ...
+Test run finished: 0 failed, 0 ignored, 3 total...
+
+> ./mill bar.test 'bar.BarTests.hello*'
+...bar.BarTests...hello ...
+Test run bar.BarTests finished: 0 failed, 0 ignored, 1 total...
+
+*/
+
+// Note the trailing `*` that is necessary for the per-test selector to match.
+
+//// SNIPPET:END

example/kotlinlib/config/2-testing/build.mill

@@ -14,3 +14,5 @@ Test qux.QuxIntegrationTests helloworld finished...
 
 */
 //// SNIPPET:TEST
+//// SNIPPET:RUNSINGLE
+//// SNIPPET:END

example/kotlinlib/testing/1-test-suite/build.mill

@@ -45,3 +45,4 @@ object bar extends KotlinModule {
 }
 
 //// SNIPPET:RUNSINGLE
+//// SNIPPET:END

example/scalalib/config/2-testing/build.mill

@@ -34,5 +34,26 @@
 */
 //// SNIPPET:END
 
+// === Selecting Test Classes or Test Cases
+// To select tests to run on a class or test-case granularity, you can pass parameters
+// to the test framework at the command line.
+
+//// SNIPPET:RUNSINGLE
+// e.g. {utest-github-url}[uTest framework] used in this example lets you pass in a
+// selector to decide which individual test case to run via:
+/** Usage
+
+> ./mill test qux.QuxTests
+...qux.QuxTests...hello ...
+...qux.QuxTests...world ...
+Tests: 2, Passed: 2, Failed: 0
+
+> ./mill test qux.QuxTests.hello
+...qux.QuxTests...hello ...
+Tests: 1, Passed: 1, Failed: 0
+
+*/
+
 // For more details on testing in Mill, see
 // xref:{language-small}lib/testing.adoc[Testing {language} Projects]
+//// SNIPPET:END

example/scalalib/testing/1-test-suite/build.mill

@@ -46,6 +46,8 @@ compiling 2 ... source...
 
 */
 
+// === Common Test Framework Support
+//
 // For convenience, you can also use one of the predefined test frameworks:
 //
 // * `TestModule.Junit4`, using https://github.com/sbt/junit-interface[sbt/junit-interface]
@@ -94,6 +96,8 @@ object bar extends ScalaModule {
 
 */
 
+// === Running Tests
+//
 // Mill provides three ways of running tests
 /** Usage
 > ./mill foo.test
@@ -130,25 +134,22 @@ object bar extends ScalaModule {
 // xref:javalib/module-config.adoc#_classpath_and_filesystem_resources[Classpath and Filesystem Resources]
 // for more details.
 //
-// If you want to pass any arguments to the test framework, you can pass them after
-// `foo.test` in the command line. e.g. {utest-github-url}[uTest]
-// lets you pass in a selector to decide which test to run, which in Mill would be:
+// === Selecting Test Classes or Test Cases
+// Note that `testOnly` only works at a class-level granularity. To select tests to run on a
+// finer-grained test-case or method-level granularity, you need to pass parameters to the
+// test framework at the command line.
 
 //// SNIPPET:RUNSINGLE
+// e.g. {utest-github-url}[uTest framework] used in this example lets you pass in a
+// selector to decide which individual test case to run via:
 /** Usage
 
 > ./mill foo.test foo.FooMoreTests
 ...foo.FooMoreTests...hello ...
 
-*/
-
-//// SNIPPET:END
-
-/** Usage
-
 > ./mill bar.test bar.BarTests.hello
 ...bar.BarTests...hello ...
 
 */
 
-// This command only runs the `hello` test case in the `bar.BarTests` test suite class.
+//// SNIPPET:END

libs/javalib/src/mill/javalib/TestModule.scala

@@ -162,6 +162,7 @@ trait TestModule
         val (s, t) = args.splitAt(pos)
         (s, t.tail)
     }
+
     Task.Command {
       testTask(Task.Anon { testArgs }, Task.Anon { selector })()
     }