Add example for using Java's source launcher

[sormuras]

Overview

Please review this change to add an example for using Java's source launcher using the org.junit.start module in a compact source file.

|
| junit-source-launcher
|
| java init/DownloadRequiredModules.java
|
Downloading 1 module
org.junit.start <- https://central.sonatype.com/repos
Downloading 5 modules
org.jspecify <- https://repo.maven.apache.org/maven2/
org.apiguardian.api <- https://repo.maven.apache.org/
org.junit.platform.console <- https://central.sonatyp/
org.junit.jupiter <- https://central.sonatype.com/rep
org.junit.platform.launcher <- https://central.sonaty/
Downloading 6 modules
org.junit.jupiter.engine <- https://central.sonatype/.
org.junit.platform.engine <- https://central.sonatype/
org.junit.jupiter.params <- https://central.sonatype/.
org.junit.platform.commons <- https://central.sonatyp/
org.junit.jupiter.api <- https://central.sonatype.com/
org.junit.platform.reporting <- https://central.sonat/
Downloading 2 modules
org.opentest4j <- https://repo.maven.apache.org/maven
org.opentest4j.reporting.tooling.spi <- https://repo/.

List modules of lib directory
org.apiguardian.api@1.1.2
org.jspecify
org.junit.jupiter.api@6.1.0-SNAPSHOT
org.junit.jupiter.engine@6.1.0-SNAPSHOT
org.junit.jupiter.params@6.1.0-SNAPSHOT
org.junit.jupiter@6.1.0-SNAPSHOT
org.junit.platform.commons@6.1.0-SNAPSHOT
org.junit.platform.console@6.1.0-SNAPSHOT
org.junit.platform.engine@6.1.0-SNAPSHOT
org.junit.platform.launcher@6.1.0-SNAPSHOT
org.junit.platform.reporting@6.1.0-SNAPSHOT
org.junit.start@6.1.0-SNAPSHOT
org.opentest4j.reporting.tooling.spi@0.2.5
org.opentest4j@1.3.0
    14 modules


|
| junit-source-launcher
|
| java --module-path lib --add-modules org.junit.start src/HelloTests.java
|
╷
└─ JUnit Jupiter ✔
   └─ HelloTests ✔
      └─ stringLength() ✔

Work Items

• Add example with documentation
• Include example in "Build All" program
• Include example module version(s) Updater.java and StagingRepoInjector.java

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

[mpkorstanje]

I noticed that with a failing test, the user experience is quite noisy (scary!).

mpkorstanje@nyx:~/Projects/junit-team/junit-examples/junit-source-launcher$ java --module-path lib --add-modules org.junit.start src/HelloTests.java
╷
└─ JUnit Jupiter ✔
   └─ HelloTests ✔
      └─ stringLength() ✘ expected: <11> but was: <12>

Failures (1):
  JUnit Jupiter:HelloTests:stringLength()
    MethodSource [className = 'HelloTests', methodName = 'stringLength', methodParameterTypes = '']
    => org.opentest4j.AssertionFailedError: expected: <11> but was: <12>
       org.junit.jupiter.api@6.1.0-SNAPSHOT/org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:158)
       org.junit.jupiter.api@6.1.0-SNAPSHOT/org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:139)
       org.junit.jupiter.api@6.1.0-SNAPSHOT/org.junit.jupiter.api.AssertEquals.failNotEqual(AssertEquals.java:201)
       org.junit.jupiter.api@6.1.0-SNAPSHOT/org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:152)
       org.junit.jupiter.api@6.1.0-SNAPSHOT/org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:147)
       org.junit.jupiter.api@6.1.0-SNAPSHOT/org.junit.jupiter.api.Assertions.assertEquals(Assertions.java:558)
       HelloTests.stringLength(HelloTests.java:19)
       java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:104)
       java.base/java.lang.reflect.Method.invoke(Method.java:565)
       org.junit.platform.commons@6.1.0-SNAPSHOT/org.junit.platform.commons.util.ReflectionUtils.invokeMethod(ReflectionUtils.java:701)
       [...]
Exception in thread "main" org.junit.platform.commons.JUnitException: JUnit run finished with 1 failure
        at org.junit.start@6.1.0-SNAPSHOT/org.junit.start.JUnit.run(JUnit.java:70)
        at org.junit.start@6.1.0-SNAPSHOT/org.junit.start.JUnit.run(JUnit.java:37)

1. Instead of throwing an exception, JUnit.run could exit with System.exit.
2. The tail of the exception is quite noisy. I'd expect the stacktrace to start at HelloTests.stringLength(HelloTests.java:19). Now it starts at HelloTest.main because that is the first method that involves the class (Prune org.junit.start from exceptions junit-framework#5158).
3. The start of the stack trace is also quite noisy. I don't think anything after the first Assertions.assertEquals is useful information. But that is unrelated to the the source launcher. (Trim internal frames from AssertionFailedError junit-framework#5159).

[sormuras]

Here, I'd like to keep some detailed information about where the control flow was and where the exception was generated. Hiding too much details hinders to understand which part of the software was in control. So, only pruning extra frames in 1. and 2. that don't contain interesting information is a good thing, while I totally agree with 3.