From da6aa2a86c86ba5fce747b36dcb2d6001cfcc44e Mon Sep 17 00:00:00 2001 From: Mikael Vidstedt Date: Tue, 28 May 2024 17:07:27 +0000 Subject: [PATCH] 8332849: Update doc/testing.{md,html} (spelling and stale information) Reviewed-by: iris, ihse, erikj, djelinski --- doc/testing.html | 28 ++++++++-------------------- doc/testing.md | 30 +++++++----------------------- 2 files changed, 15 insertions(+), 43 deletions(-) diff --git a/doc/testing.html b/doc/testing.html index f907ef3a838..c56dfa31188 100644 --- a/doc/testing.html +++ b/doc/testing.html @@ -177,10 +177,10 @@ is equivalent to make test TEST="tier1", but the latter is more tab-completion friendly. For more complex test runs, the test TEST="x" solution needs to be used.

The test specifications given in TEST is parsed into -fully qualified test descriptors, which clearly and unambigously show +fully qualified test descriptors, which clearly and unambiguously show which tests will be run. As an example, :tier1 will expand -to include all subcomponent test directories that define `tier1`, -for example: +to include all subcomponent test directories that define +tier1, for example: jtreg:$(TOPDIR)/test/hotspot/jtreg:tier1 jtreg:$(TOPDIR)/test/jdk:tier1 jtreg:$(TOPDIR)/test/langtools:tier1 .... You can always submit a list of fully qualified test descriptors in the TEST variable if you want to shortcut the parser.

@@ -228,7 +228,7 @@ tests.

These contain, among other things, tests that either run for too long to be at tier1, or may require special configuration, or tests that are less stable, or cover the broader range of non-core JVM and JDK -features/components(for example, XML).

+features/components (for example, XML).

  • tier3: This test group includes more stressful tests, the tests for corner cases not covered by previous tiers, plus the tests that require GUIs. As such, this suite should either be run @@ -368,7 +368,7 @@ would give an error, while JTREG_TMIEOUT_FACTOR=8 would just pass unnoticed.

    To separate multiple keyword=value pairs, use ; (semicolon). Since the shell normally eats ;, the -recommended usage is to write the assignment inside qoutes, e.g. +recommended usage is to write the assignment inside quotes, e.g. JTREG="...;...". This will also make sure spaces are preserved, as in JTREG="JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug".

    @@ -397,10 +397,8 @@ TEST_OPTS keywords.

    Applies to JTReg, GTest and Micro.

    VM_OPTIONS

    Applies to JTReg, GTest and Micro.

    -

    AOT_MODULES

    -

    Applies to JTReg and GTest.

    JCOV

    -

    This keywords applies globally to the test runner system. If set to +

    This keyword applies globally to the test runner system. If set to true, it enables JCov coverage reporting for all tests run. To be useful, the JDK under test must be run with a JDK built with JCov instrumentation @@ -500,11 +498,6 @@ options to your test classes, use JAVA_OPTIONS.

    LAUNCHER_OPTIONS

    Additional Java options that are sent to the java launcher that starts the JTReg harness.

    -

    AOT_MODULES

    -

    Generate AOT modules before testing for the specified module, or set -of modules. If multiple modules are specified, they should be separated -by space (or, to help avoid quoting issues, the special value -%20).

    RETRY_COUNT

    Retry failed tests up to a set number of times, until they pass. This allows to pass the tests with intermittent failures. Defaults to 0.

    @@ -527,11 +520,6 @@ intermittent problem.

    Additional options to the Gtest test framework.

    Use GTEST="OPTIONS=--help" to see all available Gtest options.

    -

    AOT_MODULES

    -

    Generate AOT modules before testing for the specified module, or set -of modules. If multiple modules are specified, they should be separated -by space (or, to help avoid quoting issues, the special value -%20).

    Microbenchmark keywords

    FORK

    Override the number of benchmark forks to spawn. Same as specifying @@ -575,7 +563,7 @@ docker image are required on Ubuntu 18.04 by using

    If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting LANG="en_US" in the environment before running -tests should work. On Windows or MacOS, setting +tests should work. On Windows or macOS, setting JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US" helps for most, but not all test cases.

    For example:

    @@ -610,7 +598,7 @@ provided below.

    Shortcuts; select or deselect desired shortcut.

    For example, test/jdk/javax/swing/TooltipManager/JMenuItemToolTipKeyBindingsTest/JMenuItemToolTipKeyBindingsTest.java -fails on MacOS because it uses CTRL + F1 key sequence to +fails on macOS because it uses CTRL + F1 key sequence to show or hide tooltip message but the key combination is reserved by the operating system. To run the test correctly the default global key shortcut should be disabled using the steps described above, and then diff --git a/doc/testing.md b/doc/testing.md index 9a45283a98b..351745c9293 100644 --- a/doc/testing.md +++ b/doc/testing.md @@ -102,8 +102,8 @@ TEST="tier1"`, but the latter is more tab-completion friendly. For more complex test runs, the `test TEST="x"` solution needs to be used. The test specifications given in `TEST` is parsed into fully qualified test -descriptors, which clearly and unambigously show which tests will be run. As an -example, `:tier1` will expand to include all subcomponent test directories +descriptors, which clearly and unambiguously show which tests will be run. As +an example, `:tier1` will expand to include all subcomponent test directories that define `tier1`, for example: `jtreg:$(TOPDIR)/test/hotspot/jtreg:tier1 jtreg:$(TOPDIR)/test/jdk:tier1 jtreg:$(TOPDIR)/test/langtools:tier1 ...`. You can always submit a list of fully qualified test descriptors in the `TEST` @@ -151,7 +151,7 @@ A brief description of the tiered test groups: - `tier2`: This test group covers even more ground. These contain, among other things, tests that either run for too long to be at `tier1`, or may require special configuration, or tests that are less stable, or cover the broader - range of non-core JVM and JDK features/components(for example, XML). + range of non-core JVM and JDK features/components (for example, XML). - `tier3`: This test group includes more stressful tests, the tests for corner cases not covered by previous tiers, plus the tests that require GUIs. As @@ -294,7 +294,7 @@ would just pass unnoticed. To separate multiple keyword=value pairs, use `;` (semicolon). Since the shell normally eats `;`, the recommended usage is to write the assignment inside -qoutes, e.g. `JTREG="...;..."`. This will also make sure spaces are preserved, +quotes, e.g. `JTREG="...;..."`. This will also make sure spaces are preserved, as in `JTREG="JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"`. (Other ways are possible, e.g. using backslash: @@ -334,13 +334,9 @@ Applies to JTReg, GTest and Micro. Applies to JTReg, GTest and Micro. -#### AOT_MODULES - -Applies to JTReg and GTest. - #### JCOV -This keywords applies globally to the test runner system. If set to `true`, it +This keyword applies globally to the test runner system. If set to `true`, it enables JCov coverage reporting for all tests run. To be useful, the JDK under test must be run with a JDK built with JCov instrumentation (`configure --with-jcov=`, `make jcov-image`). @@ -480,12 +476,6 @@ your test classes, use `JAVA_OPTIONS`. Additional Java options that are sent to the java launcher that starts the JTReg harness. -#### AOT_MODULES - -Generate AOT modules before testing for the specified module, or set of -modules. If multiple modules are specified, they should be separated by space -(or, to help avoid quoting issues, the special value `%20`). - #### RETRY_COUNT Retry failed tests up to a set number of times, until they pass. This allows to @@ -517,12 +507,6 @@ Additional options to the Gtest test framework. Use `GTEST="OPTIONS=--help"` to see all available Gtest options. -#### AOT_MODULES - -Generate AOT modules before testing for the specified module, or set of -modules. If multiple modules are specified, they should be separated by space -(or, to help avoid quoting issues, the special value `%20`). - ### Microbenchmark keywords #### FORK @@ -587,7 +571,7 @@ $ make test TEST="jtreg:test/hotspot/jtreg/containers/docker" \ If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting `LANG="en_US"` -in the environment before running tests should work. On Windows or MacOS, +in the environment before running tests should work. On Windows or macOS, setting `JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"` helps for most, but not all test cases. @@ -635,7 +619,7 @@ select or deselect desired shortcut. For example, test/jdk/javax/swing/TooltipManager/JMenuItemToolTipKeyBindingsTest/JMenuItemToolTipKeyBindingsTest.java -fails on MacOS because it uses `CTRL + F1` key sequence to show or hide tooltip +fails on macOS because it uses `CTRL + F1` key sequence to show or hide tooltip message but the key combination is reserved by the operating system. To run the test correctly the default global key shortcut should be disabled using the steps described above, and then deselect "Turn keyboard access on or off"