8340818: Add a new jtreg test root to test the generated documentation

Reviewed-by: erikj

make/Global.gmk

@@ -102,6 +102,7 @@ help:
 	$(info $(_)                        # method is 'auto', 'ignore' or 'fail' (default))
 	$(info $(_) TEST="test1 ..."       # Use the given test descriptor(s) for testing, e.g.)
 	$(info $(_)                        # make test TEST="jdk_lang gtest:all")
+	$(info $(_) TEST_DEPS="dependency1 ..." # Specify additional dependencies for running tests, e.g docs-jdk
 	$(info $(_) JTREG="OPT1=x;OPT2=y"  # Control the JTREG test harness, use 'make test-only JTREG=help' to list)
 	$(info $(_) GTEST="OPT1=x;OPT2=y"  # Control the GTEST test harness, use 'make test-only GTEST=help' to list)
 	$(info $(_) MICRO="OPT1=x;OPT2=y"  # Control the MICRO test harness, use 'make test-only MICRO=help' to list)

make/InitSupport.gmk

@@ -50,7 +50,7 @@ ifeq ($(HAS_SPEC), )
 
   # Make control variables, handled by Init.gmk
   INIT_CONTROL_VARIABLES += LOG CONF CONF_NAME SPEC JOBS TEST_JOBS CONF_CHECK \
-      COMPARE_BUILD JTREG GTEST MICRO TEST_OPTS TEST_VM_OPTS
+      COMPARE_BUILD JTREG GTEST MICRO TEST_OPTS TEST_VM_OPTS TEST_DEPS
 
   # All known make control variables
   MAKE_CONTROL_VARIABLES := $(INIT_CONTROL_VARIABLES) TEST JDK_FILTER SPEC_FILTER

make/Main.gmk

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -785,13 +785,13 @@ $(eval $(call SetupTarget, build-microbenchmark, \
 $(eval $(call SetupTarget, test, \
     MAKEFILE := RunTests, \
     ARGS := TEST="$(TEST)", \
-    DEPS := jdk-image test-image, \
+    DEPS := jdk-image test-image $(TEST_DEPS), \
 ))
 
 $(eval $(call SetupTarget, exploded-test, \
     MAKEFILE := RunTests, \
     ARGS := TEST="$(TEST)" JDK_IMAGE_DIR=$(JDK_OUTPUTDIR), \
-    DEPS := exploded-image test-image, \
+    DEPS := exploded-image test-image $(TEST_DEPS), \
 ))
 
 ifeq ($(JCOV_ENABLED), true)
@@ -1110,8 +1110,8 @@ else
   test-make-compile-commands: compile-commands
 
   # Declare dependency for all generated test targets
-  $(foreach t, $(filter-out test-make%, $(ALL_TEST_TARGETS)), $(eval $t: jdk-image test-image))
+  $(foreach t, $(filter-out test-make%, $(ALL_TEST_TARGETS)), $(eval $t: jdk-image test-image $(TEST_DEPS)))
-  $(foreach t, $(ALL_EXPLODED_TEST_TARGETS), $(eval $t: exploded-image test-image))
+  $(foreach t, $(ALL_EXPLODED_TEST_TARGETS), $(eval $t: exploded-image test-image $(TEST_DEPS)))
 
   interim-image: $(INTERIM_JMOD_TARGETS)
 

make/RunTests.gmk

@@ -264,6 +264,7 @@ jaxp_JTREG_PROBLEM_LIST += $(TOPDIR)/test/jaxp/ProblemList.txt
 langtools_JTREG_PROBLEM_LIST += $(TOPDIR)/test/langtools/ProblemList.txt
 hotspot_JTREG_PROBLEM_LIST += $(TOPDIR)/test/hotspot/jtreg/ProblemList.txt
 lib-test_JTREG_PROBLEM_LIST += $(TOPDIR)/test/lib-test/ProblemList.txt
+docs_JTREG_PROBLEM_LIST += $(TOPDIR)/test/docs/ProblemList.txt
 
 ################################################################################
 # Parse test selection
@@ -873,6 +874,8 @@ define SetupRunJtregTestBody
 
   $1_JTREG_BASIC_OPTIONS += -e:TEST_IMAGE_DIR=$(TEST_IMAGE_DIR)
 
+  $1_JTREG_BASIC_OPTIONS += -e:DOCS_JDK_IMAGE_DIR=$$(DOCS_JDK_IMAGE_DIR)
+
   ifneq ($$(JTREG_FAILURE_HANDLER_OPTIONS), )
     $1_JTREG_LAUNCHER_OPTIONS += -Djava.library.path="$(JTREG_FAILURE_HANDLER_DIR)"
   endif

make/common/FindTests.gmk

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -43,7 +43,7 @@ $(eval $(call IncludeCustomExtension, common/FindTests.gmk))
 TEST_BASEDIRS += $(TOPDIR)/test $(TOPDIR)
 
 # JTREG_TESTROOTS might have been set by a custom extension
-JTREG_TESTROOTS += $(addprefix $(TOPDIR)/test/, hotspot/jtreg jdk langtools jaxp lib-test)
+JTREG_TESTROOTS += $(addprefix $(TOPDIR)/test/, hotspot/jtreg jdk langtools jaxp lib-test docs)
 
 # Extract the names of the Jtreg group files from the TEST.ROOT files. The
 # TEST.ROOT files being properties files can be interpreted as makefiles so

make/conf/jib-profiles.js

@@ -957,7 +957,7 @@ var getJibProfilesProfiles = function (input, common, data) {
 
     // Profiles used to run tests using Jib for internal dependencies.
     var testedProfile = input.testedProfile;
-    if (testedProfile == null) {
+    if (testedProfile == null || testedProfile == "docs") {
         testedProfile = input.build_os + "-" + input.build_cpu;
     }
     var testedProfileJdk = testedProfile + ".jdk";
@@ -999,25 +999,38 @@ var getJibProfilesProfiles = function (input, common, data) {
         testOnlyProfilesPrebuilt["run-test-prebuilt"]["dependencies"].push(testedProfile + ".jdk_symbols");
     }
 
+    var testOnlyProfilesPrebuiltDocs = {
+        "run-test-prebuilt-docs": clone(testOnlyProfilesPrebuilt["run-test-prebuilt"])
+    };
+
+    testOnlyProfilesPrebuiltDocs["run-test-prebuilt-docs"].dependencies.push("docs.doc_api_spec", "tidy");
+    testOnlyProfilesPrebuiltDocs["run-test-prebuilt-docs"].environment["DOCS_JDK_IMAGE_DIR"]
+        = input.get("docs.doc_api_spec", "install_path");
+    testOnlyProfilesPrebuiltDocs["run-test-prebuilt-docs"].environment["TIDY"]
+        = input.get("tidy", "home_path") + "/bin/tidy";
+    testOnlyProfilesPrebuiltDocs["run-test-prebuilt-docs"].labels = "test-docs";
+
     // If actually running the run-test-prebuilt profile, verify that the input
     // variable is valid and if so, add the appropriate target_* values from
     // the tested profile. Use testImageProfile value as backup.
-    if (input.profile == "run-test-prebuilt") {
+    if (input.profile == "run-test-prebuilt" || input.profile == "run-test-prebuilt-docs") {
         if (profiles[testedProfile] == null && profiles[testImageProfile] == null) {
             error("testedProfile is not defined: " + testedProfile + " " + testImageProfile);
         }
     }
-    if (profiles[testedProfile] != null) {
+    function updateProfileTargets(profiles, testedProfile, testImageProfile, targetProfile, runTestProfile) {
-        testOnlyProfilesPrebuilt["run-test-prebuilt"]["target_os"]
+        var profileToCheck = profiles[testedProfile] || profiles[testImageProfile];
-            = profiles[testedProfile]["target_os"];
+
-        testOnlyProfilesPrebuilt["run-test-prebuilt"]["target_cpu"]
+        if (profileToCheck != null) {
-            = profiles[testedProfile]["target_cpu"];
+            targetProfile[runTestProfile]["target_os"] = profileToCheck["target_os"];
-    } else if (profiles[testImageProfile] != null) {
+            targetProfile[runTestProfile]["target_cpu"] = profileToCheck["target_cpu"];
-        testOnlyProfilesPrebuilt["run-test-prebuilt"]["target_os"]
+        }
-            = profiles[testImageProfile]["target_os"];
-        testOnlyProfilesPrebuilt["run-test-prebuilt"]["target_cpu"]
-            = profiles[testImageProfile]["target_cpu"];
     }
+
+    updateProfileTargets(profiles, testedProfile, testImageProfile, testOnlyProfilesPrebuilt, "run-test-prebuilt");
+    updateProfileTargets(profiles, testedProfile, testImageProfile, testOnlyProfilesPrebuiltDocs, "run-test-prebuilt-docs");
+
+    profiles = concatObjects(profiles, testOnlyProfilesPrebuiltDocs);
     profiles = concatObjects(profiles, testOnlyProfilesPrebuilt);
 
     // On macosx add the devkit bin dir to the path in all the run-test profiles.
@@ -1067,6 +1080,8 @@ var getJibProfilesProfiles = function (input, common, data) {
         }
         profiles["run-test-prebuilt"] = concatObjects(profiles["run-test-prebuilt"],
             runTestPrebuiltSrcFullExtra);
+        profiles["run-test-prebuilt-docs"] = concatObjects(profiles["run-test-prebuilt-docs"],
+            runTestPrebuiltSrcFullExtra);
     }
 
     // Generate the missing platform attributes

test/docs/ProblemList.txt

@@ -0,0 +1,41 @@
+###########################################################################
+#
+# Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+# This code is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 2 only, as
+# published by the Free Software Foundation.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+# or visit www.oracle.com if you need additional information or have any
+# questions.
+#
+###########################################################################
+
+#############################################################################
+#
+# List of quarantined tests -- tests that should not be run by default, because
+# they may fail due to known reason. The reason (CR#) must be mandatory specified.
+#
+# List items are testnames followed by labels, all MUST BE commented
+#   as to why they are here and use a label:
+#     generic-all   Problems on all platforms
+#     generic-ARCH  Where ARCH is one of: x64, i586, ppc64, ppc64le, s390x etc.
+#     OSNAME-all    Where OSNAME is one of: linux, windows, macosx, aix
+#     OSNAME-ARCH   Specific on to one OSNAME and ARCH, e.g. macosx-x64
+#     OSNAME-REV    Specific on to one OSNAME and REV, e.g. macosx-10.7.4
+#
+# More than one label is allowed but must be on the same line.
+#
+#############################################################################

test/docs/TEST.ROOT

@@ -0,0 +1,51 @@
+#
+# Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+# This code is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 2 only, as
+# published by the Free Software Foundation.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+# or visit www.oracle.com if you need additional information or have any
+# questions.
+#
+
+#
+
+# This file identifies the root of the test-suite hierarchy.
+# It also contains test-suite configuration information.
+
+# The list of keywords supported in the entire test suite.  The
+# "intermittent" keyword marks tests known to fail intermittently.
+# The "randomness" keyword marks tests using randomness with test
+# cases differing from run to run. (A test using a fixed random seed
+# would not count as "randomness" by this definition.) Extra care
+# should be taken to handle test failures of intermittent or
+# randomness tests.
+
+# Group definitions
+groups=TEST.groups
+
+# Minimum jtreg version
+requiredVersion=7.4+1
+
+# Use new module options
+useNewOptions=true
+
+# Use --patch-module instead of -Xmodule:
+useNewPatchModule=true
+
+# Path to libraries in the topmost test directory. This is needed so @library
+# does not need ../../ notation to reach them
+external.lib.roots = ../../

test/docs/TEST.groups

@@ -0,0 +1,29 @@
+#  Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+#  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+#  This code is free software; you can redistribute it and/or modify it
+#  under the terms of the GNU General Public License version 2 only, as
+#  published by the Free Software Foundation.
+#
+#  This code is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+#  version 2 for more details (a copy is included in the LICENSE file that
+#  accompanied this code).
+#
+#  You should have received a copy of the GNU General Public License version
+#  2 along with this work; if not, write to the Free Software Foundation,
+#  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+#  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+#  or visit www.oracle.com if you need additional information or have any
+#  questions.
+#
+
+# Docs-specific test groups
+
+docs_all = \
+    /
+
+tier2 = \
+    :docs_all

test/docs/jdk/javadoc/TestDocs.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @library /test/lib ../../tools/tester
+ * @build jtreg.SkippedException
+ * @summary example of a test on the generated documentation
+ * @run main TestDocs
+ */
+
+import java.nio.file.Files;
+
+public class TestDocs {
+    public static void main(String... args) throws Exception {
+        var docs = DocTester.resolveDocs();
+        System.err.println("Path to the docs is: " + docs);
+        System.err.println("Do docs exits?");
+        System.err.println(Files.exists(docs));
+        System.err.println("tidy location");
+        System.err.println(System.getProperty("tidy"));
+        System.err.println("End of test");
+    }
+}

test/docs/tools/tester/DocTester.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+
+import jtreg.SkippedException;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * Test framework for performing tests on the generated documentation.
+ */
+public class DocTester {
+    private final static String DIR = System.getenv("DOCS_JDK_IMAGE_DIR");
+    private static final Path firstCandidate = Path.of(System.getProperty("test.jdk"))
+            .getParent().resolve("docs");
+
+    public static Path resolveDocs() {
+        if (DIR != null && !DIR.isBlank() && Files.exists(Path.of(DIR))) {
+            return Path.of(DIR);
+        } else if (Files.exists(firstCandidate)) {
+            return firstCandidate;
+        }else {
+            throw new SkippedException("docs folder not found in either location");
+        }
+    }
+}