RFR: 8340818: Add a new jtreg test root to test the generated documentation [v5]

[Magnus Ihse Bursie]

On Fri, 11 Oct 2024 12:54:42 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this change that adds a new test root `docs` dedicated to testing the documentation, which has been a work in progress for a while. Tests for links, encoding, HTML, accessibility will be later added in following PRs. 
>> 
>> We also define a new make target `test-docs` meant for local use and depends on the docs.
>> This also adds the necessary configurations needed at Oracle.
>> 
>> This patch includes a test `TestDocs` which serves to show developers how they are meant to resolve the docs to test them, I want to include it temporarily until better tests are added later.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add tidy as a dependency to `run-test-prebuilt-docs` and `docs` profiles

Ideally, we would be able to analyse what jtregs are requested to run, and add the proper dependencies. This seems unfortunately hard to do in the general case, meaning that if you run like `make test TEST=some/specific/test/in/docs` we are unlikely to be able to defer that a dependency on the docs are needed.

But otoh, we could do so at least for `test-docs_all`. 

I'm thinking as I type right now, so bear with me. But I believe what we need is not a new target (`test-docs`), but a way to express that testing needs additional dependencies. Let's introduce a `TEST_DEPS` control variable instead! Then we can basically do:

$(eval $(call SetupTarget, test, \
    MAKEFILE := RunTests, \
    ARGS := TEST="$(TEST)", \
    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 $(TEST_DEPS), \
))



Now the user will need to type `make test-docs_all TEST_DEPS=docs-jdk` (or `make test TEST=docs_all TEST_DEPS=docs-jdk`) to run the docs tests, which is flexible, but not very user friendly. So we should also need something along these lines:


test-docs: test-docs_all

to get a nice alias for testing docs.

(cont'd)

-------------

PR Comment: https://git.openjdk.org/jdk/pull/21272#issuecomment-2407653765