RFR: Initial section on testing [v2]

[Igor Ignatyev]

On Mon, 19 Oct 2020 20:55:28 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> It's a start.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Updates suggested by Phil and Igor

Changes requested by iignatyev (no project role).

src/index.md line 382:

> 380: Note that you can have several `@run` tags in the same test with different command line options.
> 381:
> 382: JTReg also have support for labeling tests with arbitrary keys using the `@key` tag. These keywords can then be
> used to filter the test selection. For instance if you have a UI test which needs to display a window you'll want to
> make sure the test harness doesn't try to run this test on a system which doesn't support headful tests. You do this by
> specifying

JTReg doesn't support arbitrary keywords in `@key`, all keywords are to be registered in `TEST.ROOT` file.

src/index.md line 441:

> 439:     EXPECT_GT(val1, val2);
> 440:     EXPECT_GE(val1, val2);
> 441:     EXPECT_STREQ(expected_str, actual_str);

do we really need to list these guys here? referring to google test documentations seems to be enough.

in case there is a good reason to have this list here, `ASSERT_TRUE` and `ASSERT_FALSE` can be removed b/c the
following paragraph explains that all these macros have an `ASSERT` variant.

src/index.md line 443:

> 441:     EXPECT_STREQ(expected_str, actual_str);
> 442:
> 443: `ASSERT` is a fatal assertion and will give you fast failure. That means that test execution will be stopped and
> the failure will be reported. `EXPECT` is a nonfatal assertion and will report the error but continues to run the test.
> All assertions have both an `ASSERT` and an `EXPECT` variant.

strictly speaking, `ASSERT` stops execution of the current method (as in fact it's just: change test's status, print
message, `return`), so if a test uses `ASSERT` in a subroutine, its _main test code_ has to call a subroutine within
`ASSERT_NO_FATAL_FAILURE` macro. it's explained in greater detail in `doc/hotspot-unit-tests.md`.

src/index.md line 445:

> 443: `ASSERT` is a fatal assertion and will give you fast failure. That means that test execution will be stopped and
> the failure will be reported. `EXPECT` is a nonfatal assertion and will report the error but continues to run the test.
> All assertions have both an `ASSERT` and an `EXPECT` variant. 444:  445: For more information on how to write good
> GTests in OpenJDK, see
> [`doc/hotspot-unit-tests.md`](https://github.com/openjdk/jdk/blob/master/doc/hotspot-unit-tests.md).

just to avoid confusion, I'd prefer to be explicit here and say that `doc/hotspot-unit-tests.md` provides information
about how to write good gtest tests for hotspot.

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

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