Improvements to examples and integration tests (#6254)

* Move spring-boot examples to config-based `build.mill.yaml` syntax. I
leave one programmatic example so people know you can use it, but as a
getting started experience the config-based syntax is probably superior

* Make plugin examples publish against Mill1.0.0/Scala3.7.4/Java11, with
an explanation of why

* Use `IntegrationTester.EvalResult` in `ExampleTester` to improve
readability of command line error output

Author: lihaoyi

example/extending/plugins/1-writing-mill-plugins/build.mill

@@ -1,18 +1,20 @@
-//| mill-jvm-version: 17
 // This example demonstrates how to write and test Mill plugin, and publish it to
 // Sonatype's Maven Central so it can be used by other developers over the internet
 // via xref:extending/import-mvn-plugins.adoc[//| mvnDeps].
 
 // == Project Configuration
 package build
 import mill.*, scalalib.*, publish.*
-import mill.util.BuildInfo.{millVersion, millBinPlatform}
 
 object myplugin extends ScalaModule, PublishModule {
-  def scalaVersion = "3.8.0-RC1"
+  def millVersion = "1.0.6"
+
+  def scalaVersion = "3.7.4"
+
+  def jvmId = "11"
 
   // Set the `platformSuffix` so the name indicates what Mill version it is compiled for
-  def platformSuffix = s"_mill$millBinPlatform"
+  def platformSuffix = s"_mill1"
 
   // Depend on `mill-libs` so we can compile against Mill APIs
   def mvnDeps = Seq(mvn"com.lihaoyi::mill-libs:$millVersion")
@@ -45,11 +47,12 @@ object myplugin extends ScalaModule, PublishModule {
 // It looks like any other Scala project, except for a few dependencies on `mill-libs`
 // and `mill-testkit` to bring in the appropriate libraries
 
-// Note that when publishing artifacts to Maven repositories, the JVM version used to build the
-// artifacts will be the minimum version that downstream projects will need to use in order to
-// use your artifacts. Thus it is best to set your `mill-jvm-version` to the lowest version
-// possible, e.g. `mill-jvm-version: 17` in this example which is the lowest version supported
-// by Mill.
+// NOTE: that Mill 1.x is _backwards compatible_ but not _forwards compatible_ with regard to plugins,
+// so a plugin published for a particular version of Mill will work on _newer_ versions of Mill,
+// but not _older_ versions. Thus when publishing plugins it is usually best to publish for as
+// old a 1.x version of Mill as you can, to ensure maximal compatibility with downstream projects.
+// In this example, we publish for Mill-1.0.6/Scala-3.7.4/JDK11, even though our plugins own build
+// may be on a version of Mill 1.1.0 or later.
 
 // == Plugin Implementation
 
@@ -115,7 +118,7 @@ compiling 1 Scala source...
 > sed -i.bak 's/0.0.1/0.0.2/g' build.mill
 
 > ./mill myplugin.publishLocal
-Publishing Artifact(com.lihaoyi,myplugin_millSNAPSHOT_3,0.0.2) to ivy repo...
+Publishing Artifact(com.lihaoyi,myplugin_mill1_3,0.0.2) to ivy repo...
 
 */
 // Mill plugins are JVM libraries like any other library written in Java or Scala. Thus they

example/extending/plugins/2-plugin-integration-tests/build.mill

@@ -6,13 +6,16 @@
 
 package build
 import mill.*, scalalib.*, publish.*
-import mill.util.BuildInfo.{millVersion, millBinPlatform}
 
 object myplugin extends ScalaModule, PublishModule {
-  def scalaVersion = "3.8.0-RC1"
+  def millVersion = "1.0.6"
+
+  def scalaVersion = "3.7.4"
+
+  def jvmId = "11"
 
   // Set the `platformSuffix` so the name indicates what Mill version it is compiled for
-  def platformSuffix = s"_mill$millBinPlatform"
+  def platformSuffix = s"_mill1"
 
   // Depend on `mill-libs` so we can compile against Mill APIs
   def mvnDeps = Seq(mvn"com.lihaoyi::mill-libs:$millVersion")

example/javalib/springboot/2-hello-spring-boot-programmatic/build.mill

@@ -0,0 +1,32 @@
+//| mill-jvm-version: 17
+
+// Spring boot projects can also be built using Mill's programmatic `build.mill` syntax,
+// as shown below:
+
+package build
+import mill.*, javalib.*
+
+object `package` extends JavaModule {
+  def mvnDeps = Seq(
+    mvn"org.springframework.boot:spring-boot-starter-web:2.5.6",
+    mvn"org.springframework.boot:spring-boot-starter-actuator:2.5.6"
+  )
+
+  object test extends JavaTests, TestModule.Junit5 {
+    def mvnDeps = Seq(mvn"org.springframework.boot:spring-boot-starter-test:2.5.6")
+  }
+}
+
+/** Usage
+
+> ./mill test
+...com.example.HelloSpringBootTest#shouldReturnDefaultMessage() finished...
+
+> ./mill runBackground
+
+> curl http://localhost:8086
+...<h1>Hello, World!</h1>...
+
+> ./mill clean runBackground
+
+*/

example/javalib/springboot/2-hello-spring-boot-programmatic/resources/application.properties

@@ -0,0 +1 @@
+server.port=8086

example/javalib/springboot/2-hello-spring-boot-programmatic/src/com/example/HelloSpringBoot.java

@@ -0,0 +1,22 @@
+package com.example;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@SpringBootApplication
+public class HelloSpringBoot {
+
+  public static void main(String[] args) {
+    SpringApplication.run(HelloSpringBoot.class, args);
+  }
+
+  @RestController
+  class HelloController {
+    @GetMapping("/")
+    public String hello() {
+      return "<h1>Hello, World!</h1>";
+    }
+  }
+}

example/javalib/springboot/2-hello-spring-boot-programmatic/test/src/com/example/HelloSpringBootTest.java

@@ -0,0 +1,25 @@
+package com.example;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.client.TestRestTemplate;
+import org.springframework.boot.web.server.LocalServerPort;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+public class HelloSpringBootTest {
+
+  @LocalServerPort
+  private int port;
+
+  @Autowired
+  private TestRestTemplate restTemplate;
+
+  @Test
+  public void shouldReturnDefaultMessage() {
+    String response = restTemplate.getForObject("http://localhost:" + port + "/", String.class);
+    assertEquals("<h1>Hello, World!</h1>", response);
+  }
+}

example/javalib/springboot/2-todo-spring-boot/build.mill

@@ -0,0 +1,31 @@
+/** See Also: build.mill.yaml */
+
+// This is a larger example using Spring Boot, using Mill's
+// xref:javalib/intro.adoc#_programmatic_modules[programmatic build.mill] syntax,
+// implementing the well known https://todomvc.com/[TodoMVC] example app. Apart from
+// running a webserver, this example also demonstrates:
+//
+// * Serving HTML templates using Thymeleaf
+// * Serving static Javascript and CSS using Webjars
+// * Querying a SQL database using JPA and H2
+// * Unit testing using a H2 in-memory database
+// * Integration testing using Testcontainers Postgres in Docker
+
+/** Usage
+
+> ./mill test
+...com.example.TodomvcTests#homePageLoads() finished...
+...com.example.TodomvcTests#addNewTodoItem() finished...
+
+> ./mill integration
+...com.example.TodomvcIntegrationTests#homePageLoads() finished...
+...com.example.TodomvcIntegrationTests#addNewTodoItem() finished...
+
+> ./mill test.runBackground
+
+> curl http://localhost:8087
+...<h1>todos</h1>...
+
+> ./mill clean runBackground
+
+*/

example/javalib/springboot/3-todo-spring-boot/build.mill

@@ -0,0 +1,28 @@
+mill-jvm-version: 17
+extends: [mill.javalib.JavaModule]
+mvnDeps:
+- org.springframework.boot:spring-boot-starter-data-jpa:2.5.4
+- org.springframework.boot:spring-boot-starter-thymeleaf:2.5.4
+- org.springframework.boot:spring-boot-starter-validation:2.5.4
+- org.springframework.boot:spring-boot-starter-web:2.5.4
+- javax.xml.bind:jaxb-api:2.3.1
+- org.webjars:webjars-locator:0.41
+- org.webjars.npm:todomvc-common:1.0.5
+- org.webjars.npm:todomvc-app-css:2.4.1
+
+object test:
+  extends: [JavaTests, mill.javalib.TestModule.Junit5]
+  mainClass: com.example.TodomvcApplication
+  mvnDeps:
+  - com.h2database:h2:2.3.230
+  - org.springframework.boot:spring-boot-starter-test:2.5.6
+
+object integration:
+  extends: [JavaTests, mill.javalib.TestModule.Junit5]
+  mainClass: com.example.TodomvcApplication
+  mvnDeps:
+  - org.testcontainers:testcontainers:1.18.0
+  - org.testcontainers:junit-jupiter:1.18.0
+  - org.testcontainers:postgresql:1.18.0
+  - org.postgresql:postgresql:42.6.0
+  - org.springframework.boot:spring-boot-starter-test:2.5.6