RFR: Initial section on testing

Igor Ignatyev iignatyev at openjdk.java.net
Fri Oct 16 17:15:14 UTC 2020


On Fri, 16 Oct 2020 15:58:52 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> It's a start.

Although I understand the desire to have as much relative information in the guide, I don't think we need to repeat
ourselves, most of the information presented here is already available in `doc/testing.md` and
`doc/hotspot-unit-tests.md`. the former document provides more comprehensive documentation about all
available/supported testing in OpenJDK, different modes of test execution; the latter gives an overview of different
`TEST*` macros available in hotspot gtest, defines _good_ tests, provides guidelines on writing such tests, etc.

I think we need to find some middle ground here, so we won't duplicate documentation and at the same time, we won't
force people to gather required information from N different places. With that in mind, I think it's important to 1st
define the goal of 'testing' section of the Guide.

src/index.md line 348:

> 346:     /*
> 347:      * @test
> 348:      * @summary Make sure feature X handles Y correctly

b/c one might not realize that implicit `@run` exists only if there are no other `@run` tags, jtreg tests w/o `@run`
can (and indeed did in the past) cause confusing and effective make test useless when someone decides to add `@compile`
tags or other _auxilary_ tags, thus in most cases, such test descriptions should be considered as anti-patterns and
avoided (despite the fact that there are numbers of such test descriptions in our testbases).

src/index.md line 436:

> 434: ### Running OpenJDK GTests
> 435:
> 436: To run GTests in OpenJDK use make:

in order to get gtest tests built, you actually need to specify the path to gtest framework source via `--with-gtest`
configure flag.

src/index.md line 438:

> 436: To run GTests in OpenJDK use make:
> 437:
> 438:     make test-hotspot-gtest

`make test TEST=gtest` is a more appropriate way to run gtest tests. it also supports test name-based filtering:
 * `make test TEST=gtest` and  `make test TEST=gtest:all` run all gtest tests
 * `make test TEST=gtest:code.*:os.*` runs gtest whose name matches `code.*:os.*` regexp (actually `code.*:os.*.*`)
 *  `make test TEST=gtest:$X/$variant` runs tests which match `$X.*` regexp on `$variant` of VM (client, server, etc)

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

Changes requested by iignatyev (no project role).

PR: https://git.openjdk.java.net/guide/pull/30


More information about the guide-dev mailing list