stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8332849: Update doc/testing.{md,html} (spelling and stale information)

Browse Source 
Reviewed-by: iris, ihse, erikj, djelinski
This commit is contained in:
Mikael Vidstedt 2024-05-28 17:07:27 +00:00
parent b8f2ec9091
commit da6aa2a86c
2 changed files with 15 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/testing.html
View File

@ -177,10 +177,10 @@ is equivalent to <code>make test TEST="tier1"</code>, but the latter is
more tab-completion friendly. For more complex test runs, the more tab-completion friendly. For more complex test runs, the
<code>test TEST="x"</code> solution needs to be used.</p> <code>test TEST="x"</code> solution needs to be used.</p>
<p>The test specifications given in <code>TEST</code> is parsed into <p>The test specifications given in <code>TEST</code> 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, <code>:tier1</code> will expand which tests will be run. As an example, <code>:tier1</code> will expand
to include all subcomponent test directories that define `tier1`, to include all subcomponent test directories that define
for example: <code>tier1</code>, for example:
<code>jtreg:$(TOPDIR)/test/hotspot/jtreg:tier1 jtreg:$(TOPDIR)/test/jdk:tier1 jtreg:$(TOPDIR)/test/langtools:tier1 ...</code>. <code>jtreg:$(TOPDIR)/test/hotspot/jtreg:tier1 jtreg:$(TOPDIR)/test/jdk:tier1 jtreg:$(TOPDIR)/test/langtools:tier1 ...</code>.
You can always submit a list of fully qualified test descriptors in the You can always submit a list of fully qualified test descriptors in the
<code>TEST</code> variable if you want to shortcut the parser.</p> <code>TEST</code> variable if you want to shortcut the parser.</p>
@ -228,7 +228,7 @@ tests.</p></li>
These contain, among other things, tests that either run for too long to These contain, among other things, tests that either run for too long to
be at <code>tier1</code>, or may require special configuration, or tests be at <code>tier1</code>, or may require special configuration, or tests
that are less stable, or cover the broader range of non-core JVM and JDK that are less stable, or cover the broader range of non-core JVM and JDK
features/components(for example, XML).</p></li> features/components (for example, XML).</p></li>
<li><p><code>tier3</code>: This test group includes more stressful <li><p><code>tier3</code>: This test group includes more stressful
tests, the tests for corner cases not covered by previous tiers, plus 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 the tests that require GUIs. As such, this suite should either be run
@ -368,7 +368,7 @@ would give an error, while <code>JTREG_TMIEOUT_FACTOR=8</code> would
just pass unnoticed.</p> just pass unnoticed.</p>
<p>To separate multiple keyword=value pairs, use <code>;</code> <p>To separate multiple keyword=value pairs, use <code>;</code>
(semicolon). Since the shell normally eats <code>;</code>, the (semicolon). Since the shell normally eats <code>;</code>, the
recommended usage is to write the assignment inside qoutes, e.g. recommended usage is to write the assignment inside quotes, e.g.
<code>JTREG="...;..."</code>. This will also make sure spaces are <code>JTREG="...;..."</code>. This will also make sure spaces are
preserved, as in preserved, as in
<code>JTREG="JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"</code>.</p> <code>JTREG="JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"</code>.</p>
@ -397,10 +397,8 @@ TEST_OPTS keywords.</p>
<p>Applies to JTReg, GTest and Micro.</p> <p>Applies to JTReg, GTest and Micro.</p>
<h4 id="vm_options">VM_OPTIONS</h4> <h4 id="vm_options">VM_OPTIONS</h4>
<p>Applies to JTReg, GTest and Micro.</p> <p>Applies to JTReg, GTest and Micro.</p>
<h4 id="aot_modules">AOT_MODULES</h4>
<p>Applies to JTReg and GTest.</p>
<h4 id="jcov">JCOV</h4> <h4 id="jcov">JCOV</h4>
<p>This keywords applies globally to the test runner system. If set to <p>This keyword applies globally to the test runner system. If set to
<code>true</code>, it enables JCov coverage reporting for all tests run. <code>true</code>, 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 To be useful, the JDK under test must be run with a JDK built with JCov
instrumentation instrumentation
@ -500,11 +498,6 @@ options to your test classes, use <code>JAVA_OPTIONS</code>.</p>
<h4 id="launcher_options">LAUNCHER_OPTIONS</h4> <h4 id="launcher_options">LAUNCHER_OPTIONS</h4>
<p>Additional Java options that are sent to the java launcher that <p>Additional Java options that are sent to the java launcher that
starts the JTReg harness.</p> starts the JTReg harness.</p>
<h4 id="aot_modules-1">AOT_MODULES</h4>
<p>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
<code>%20</code>).</p>
<h4 id="retry_count">RETRY_COUNT</h4> <h4 id="retry_count">RETRY_COUNT</h4>
<p>Retry failed tests up to a set number of times, until they pass. This <p>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.</p> allows to pass the tests with intermittent failures. Defaults to 0.</p>
@ -527,11 +520,6 @@ intermittent problem.</p>
<p>Additional options to the Gtest test framework.</p> <p>Additional options to the Gtest test framework.</p>
<p>Use <code>GTEST="OPTIONS=--help"</code> to see all available Gtest <p>Use <code>GTEST="OPTIONS=--help"</code> to see all available Gtest
options.</p> options.</p>
<h4 id="aot_modules-2">AOT_MODULES</h4>
<p>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
<code>%20</code>).</p>
<h3 id="microbenchmark-keywords">Microbenchmark keywords</h3> <h3 id="microbenchmark-keywords">Microbenchmark keywords</h3>
<h4 id="fork">FORK</h4> <h4 id="fork">FORK</h4>
<p>Override the number of benchmark forks to spawn. Same as specifying <p>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
<p>If your locale is non-US, some tests are likely to fail. To work <p>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 around this you can set the locale to US. On Unix platforms simply
setting <code>LANG="en_US"</code> in the environment before running setting <code>LANG="en_US"</code> in the environment before running
tests should work. On Windows or MacOS, setting tests should work. On Windows or macOS, setting
<code>JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"</code> <code>JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"</code>
helps for most, but not all test cases.</p> helps for most, but not all test cases.</p>
<p>For example:</p> <p>For example:</p>
@ -610,7 +598,7 @@ provided below.</p>
Shortcuts; select or deselect desired shortcut.</p> Shortcuts; select or deselect desired shortcut.</p>
<p>For example, <p>For example,
test/jdk/javax/swing/TooltipManager/JMenuItemToolTipKeyBindingsTest/JMenuItemToolTipKeyBindingsTest.java test/jdk/javax/swing/TooltipManager/JMenuItemToolTipKeyBindingsTest/JMenuItemToolTipKeyBindingsTest.java
fails on MacOS because it uses <code>CTRL + F1</code> key sequence to fails on macOS because it uses <code>CTRL + F1</code> key sequence to
show or hide tooltip message but the key combination is reserved by the show or hide tooltip message but the key combination is reserved by the
operating system. To run the test correctly the default global key operating system. To run the test correctly the default global key
shortcut should be disabled using the steps described above, and then shortcut should be disabled using the steps described above, and then

30
doc/testing.md
View File

@ -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. test runs, the `test TEST="x"` solution needs to be used.
The test specifications given in `TEST` is parsed into fully qualified test 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 descriptors, which clearly and unambiguously show which tests will be run. As
example, `:tier1` will expand to include all subcomponent test directories an example, `:tier1` will expand to include all subcomponent test directories
that define `tier1`, for example: `jtreg:$(TOPDIR)/test/hotspot/jtreg:tier1 that define `tier1`, for example: `jtreg:$(TOPDIR)/test/hotspot/jtreg:tier1
jtreg:$(TOPDIR)/test/jdk:tier1 jtreg:$(TOPDIR)/test/langtools:tier1 ...`. You jtreg:$(TOPDIR)/test/jdk:tier1 jtreg:$(TOPDIR)/test/langtools:tier1 ...`. You
can always submit a list of fully qualified test descriptors in the `TEST` 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 - `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 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 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 - `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 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 To separate multiple keyword=value pairs, use `;` (semicolon). Since the shell
normally eats `;`, the recommended usage is to write the assignment inside 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"`. as in `JTREG="JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"`.
(Other ways are possible, e.g. using backslash: (Other ways are possible, e.g. using backslash:
@ -334,13 +334,9 @@ Applies to JTReg, GTest and Micro.
Applies to JTReg, GTest and Micro. Applies to JTReg, GTest and Micro.
#### AOT_MODULES
Applies to JTReg and GTest.
#### JCOV #### 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 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 test must be run with a JDK built with JCov instrumentation (`configure
--with-jcov=<path to directory containing lib/jcov.jar>`, `make jcov-image`). --with-jcov=<path to directory containing lib/jcov.jar>`, `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 Additional Java options that are sent to the java launcher that starts the
JTReg harness. 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_COUNT
Retry failed tests up to a set number of times, until they pass. This allows to 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. 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 ### Microbenchmark keywords
#### FORK #### 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 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"` 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 setting `JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"` helps for
most, but not all test cases. most, but not all test cases.
@ -635,7 +619,7 @@ select or deselect desired shortcut.
For example, For example,
test/jdk/javax/swing/TooltipManager/JMenuItemToolTipKeyBindingsTest/JMenuItemToolTipKeyBindingsTest.java 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 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 test correctly the default global key shortcut should be disabled using the
steps described above, and then deselect "Turn keyboard access on or off" steps described above, and then deselect "Turn keyboard access on or off"