RFR: Initial section on testing [v2]

[Jesper Wilhelmsson]

On Fri, 16 Oct 2020 16:49:20 GMT, Igor Ignatyev <iignatyev at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Updates suggested by Phil and Igor
>
> 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).

Excellent comment!  This is exactly the kind of information that needs to be documented. I see no mention of this is
the documents in /doc/ so I've added a sentence about this here. There's another example that I was thinking about but
I can't recall right now - there's some tag that if specified needs to be placed before the first @run tag. I have it
on some wiki page somewhere so it will turn up eventually :-)

> 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.

Good catch!

> 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)

Ok. I've updated the text. Thanks!

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

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