Add ITs for Java 17 and 21 (#126) (#133)

Uses Maven profiles to configure ITs to validate the Java version
and run specific test suits for each Java version.

Closes #126

.github/workflows/ci-development-branch.yml

@@ -20,13 +20,16 @@ on:
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         os:
           - ubuntu-latest
           - windows-latest
           - macos-latest
         java-version:
           - 11
+          - 17
+          - 21
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
@@ -38,4 +41,4 @@ jobs:
           cache: 'maven'
           cache-dependency-path: 'pom.xml'
       - name: Build & Test
-        run: mvn -B clean verify
+        run: mvn -B clean verify -Prun-its

.github/workflows/ci-maintenance-branch.yml

@@ -20,6 +20,7 @@ on:
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         os:
           - ubuntu-latest

pom.xml

@@ -35,6 +35,8 @@
         <currentYear>${maven.build.timestamp}</currentYear>
         <maven.build.timestamp.format>yyyy</maven.build.timestamp.format>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <integration-tests.path>src/it/java-11</integration-tests.path>
+        <expected.java>11</expected.java>
     </properties>
 
     <dependencies>
@@ -230,7 +232,7 @@
                         <include>src/**/*.java</include>
                     </includes>
                     <excludes>
-                        <exclude>src/it/**/*.*</exclude>
+                        <exclude>${integration-tests.path}/**/*.*</exclude>
                     </excludes>
                     <properties>
                         <startYear>2013</startYear>
@@ -245,6 +247,27 @@
     </build>
 
     <profiles>
+        <!-- Both use the same java-17 folder -->
+        <profile>
+            <id>java-17</id>
+            <activation>
+                <jdk>17</jdk>
+            </activation>
+            <properties>
+                <integration-tests.path>src/it/java-17</integration-tests.path>
+                <expected.java>17</expected.java>
+            </properties>
+        </profile>
+        <profile>
+            <id>java-21</id>
+            <activation>
+                <jdk>21</jdk>
+            </activation>
+            <properties>
+                <integration-tests.path>src/it/java-17</integration-tests.path>
+                <expected.java>21</expected.java>
+            </properties>
+        </profile>
         <profile>
             <!--
               To release, define environment variables:
@@ -301,7 +324,7 @@
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-invoker-plugin</artifactId>
                         <configuration>
-                            <projectsDirectory>src/it</projectsDirectory>
+                            <projectsDirectory>${integration-tests.path}</projectsDirectory>
                             <cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
                             <pomIncludes>
                                 <pomInclude>*/pom.xml</pomInclude>
@@ -316,6 +339,9 @@
                                 <goal>clean</goal>
                                 <goal>process-sources</goal>
                             </goals>
+                            <scriptVariables>
+                                <expected_java>${expected.java}</expected_java>
+                            </scriptVariables>
                         </configuration>
                         <executions>
                             <execution>

src/it/class-comments/pom.xml → src/it/java-11/class-comments/pom.xml

@@ -32,7 +32,6 @@
 							<groupId>org.asciidoctor</groupId>
 							<artifactId>asciidoclet</artifactId>
 							<version>@project.version@</version>
-							<classifier>shaded</classifier>
 						</docletArtifact>
 					</docletArtifacts>
 					<overview>src/main/java/overview.adoc</overview>

src/it/class-comments/validate.groovy → src/it/java-11/class-comments/validate.groovy

@@ -1,6 +1,10 @@
 import java.nio.file.Files
 import java.nio.file.Path
 
+String javaVersion = System.getProperty('java.version').split("\\.")[0]
+if (javaVersion != expected_java) {
+    throw new Exception("Invalid Java version. Expected ${expected_java}, found $javaVersion")
+}
 
 def javadocExpectedPath = Path.of((String) basedir).resolve('target/site/apidocs')
 def expectedJavadoc = javadocExpectedPath.resolve('example/StringUtils.html')
@@ -23,7 +27,7 @@ def expectMethodArgument2 = Html.dd(Html.code('needle') + " - it stings")
 assertStringContains(javadocContent, expectMethodArgument1)
 assertStringContains(javadocContent, expectMethodArgument2)
 
-def expectMethodReturn = Html.dt(Html.span("Returns:", "returnLabel")) + "\n" + Html.dd('true if lucky')
+def expectMethodReturn = Html.dt(Html.span("Returns:", "returnLabel")) + System.lineSeparator() + Html.dd('true if lucky')
 
 assertStringContains(javadocContent, expectMethodReturn)
 

src/it/java-17/class-comments/invoker.properties

@@ -0,0 +1 @@
+invoker.goals=clean javadoc:javadoc

src/it/java-17/class-comments/pom.xml

@@ -0,0 +1,49 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<groupId>org.asciidoctor</groupId>
+	<artifactId>test</artifactId>
+	<version>1.0.0-SNAPSHOT</version>
+	<description>Integration Test: generate Javadoc for class and method</description>
+
+	<properties>
+		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+	</properties>
+
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<version>3.6.3</version>
+				<configuration>
+					<source>17</source>
+					<additionalJOptions>
+						<additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
+						<additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</additionalJOption>
+						<additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED</additionalJOption>
+						<additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED</additionalJOption>
+						<additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</additionalJOption>
+						<additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</additionalJOption>
+						<additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
+					</additionalJOptions>
+					<doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>
+					<docletArtifacts>
+						<docletArtifact>
+							<groupId>org.asciidoctor</groupId>
+							<artifactId>asciidoclet</artifactId>
+							<version>@project.version@</version>
+						</docletArtifact>
+					</docletArtifacts>
+					<overview>src/main/java/overview.adoc</overview>
+					<additionalOptions>
+						--base-dir ${project.basedir}
+						--attribute "project_name=${project.name}"
+						--attribute "project_description=${project.description}"
+					</additionalOptions>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
+</project>

src/it/java-17/class-comments/src/main/java/example/StringUtils.java

@@ -0,0 +1,18 @@
+package example;
+
+/**
+ * Class comment for "{project_description}".
+ */
+public class StringUtils {
+
+    /**
+     * This is a method comment.
+     *
+     * @param haystack the haystack
+     * @param needle   it stings
+     * @return true if lucky
+     */
+    public boolean contains(String haystack, String needle) {
+        return haystack.contains(needle);
+    }
+}

src/it/java-17/class-comments/validate.groovy

@@ -0,0 +1,64 @@
+import java.nio.file.Files
+import java.nio.file.Path
+
+String javaVersion = System.getProperty('java.version').split("\\.")[0]
+if (javaVersion != expected_java) {
+    throw new Exception("Invalid Java version. Expected ${expected_java}, found $javaVersion")
+}
+
+def javadocExpectedPath = Path.of((String) basedir).resolve('target/site/apidocs')
+def expectedJavadoc = javadocExpectedPath.resolve('example/StringUtils.html')
+
+if (Files.list(javadocExpectedPath).count() == 0) {
+    throw new Exception("${javadocExpectedPath.toFile().getAbsolutePath()} path cannot me empty")
+}
+
+def javadocContent = Files.readString(expectedJavadoc)
+
+def expectClassDescription = Html.div(Html.p('Class comment for "Integration Test: generate Javadoc for class and method".'), 'block')
+def expectMethodDescription = Html.div(Html.p('This is a method comment.'), 'block')
+
+assertStringContains(javadocContent, expectClassDescription)
+assertStringContains(javadocContent, expectMethodDescription)
+
+def expectMethodArgument1 = Html.dd(Html.code('haystack') + " - the haystack")
+def expectMethodArgument2 = Html.dd(Html.code('needle') + " - it stings")
+
+assertStringContains(javadocContent, expectMethodArgument1)
+assertStringContains(javadocContent, expectMethodArgument2)
+
+def expectMethodReturn = Html.dt("Returns:") + System.lineSeparator() + Html.dd('true if lucky')
+
+assertStringContains(javadocContent, expectMethodReturn)
+
+
+void assertStringContains(String value, String expected) {
+    if (!value.contains(expected)) {
+        throw new Exception("'$expected' expected to be present")
+    }
+}
+
+class Html {
+
+    static String div(String text, String classname) {
+        return "<div class=\"${classname}\">${text}</div>"
+    }
+
+    static String p(String text) {
+        return "<p>${text}</p>"
+    }
+
+    static String code(String text) {
+        return "<code>${text}</code>"
+    }
+
+    static String dd(String text) {
+        return "<dd>${text}</dd>"
+    }
+
+    static String dt(String text) {
+        return "<dt>${text}</dt>"
+    }
+}
+
+return true