doc/testing.html
author shurailine
Thu, 29 Nov 2018 06:34:46 -0800
changeset 52774 56ca125c973b
parent 52595 16609197022c
child 52941 a430555c3d4e
permissions -rw-r--r--
8214309: Enhance makefiles to allow generating JCov instrumented build Reviewed-by: erikj
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
45227
97be1bcd7b25 8180472: Pandoc should generate html5 from markdown
ihse
parents: 45103
diff changeset
     1
<!DOCTYPE html>
51644
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
     2
<html>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
     3
<head>
51644
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
     4
  <meta charset="utf-8">
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
     5
  <meta name="generator" content="pandoc">
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
     6
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50267
diff changeset
     7
  <title>Testing the JDK</title>
51644
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
     8
  <style type="text/css">code{white-space: pre;}</style>
47217
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
     9
  <link rel="stylesheet" href="../make/data/docs-resources/resources/jdk-default.css">
45227
97be1bcd7b25 8180472: Pandoc should generate html5 from markdown
ihse
parents: 45103
diff changeset
    10
  <!--[if lt IE 9]>
97be1bcd7b25 8180472: Pandoc should generate html5 from markdown
ihse
parents: 45103
diff changeset
    11
    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
97be1bcd7b25 8180472: Pandoc should generate html5 from markdown
ihse
parents: 45103
diff changeset
    12
  <![endif]-->
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    13
  <style type="text/css">pre, code, tt { color: #1d6ae5; }</style>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    14
</head>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    15
<body>
45227
97be1bcd7b25 8180472: Pandoc should generate html5 from markdown
ihse
parents: 45103
diff changeset
    16
<header>
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50267
diff changeset
    17
<h1 class="title">Testing the JDK</h1>
45227
97be1bcd7b25 8180472: Pandoc should generate html5 from markdown
ihse
parents: 45103
diff changeset
    18
</header>
97be1bcd7b25 8180472: Pandoc should generate html5 from markdown
ihse
parents: 45103
diff changeset
    19
<nav id="TOC">
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    20
<ul>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    21
<li><a href="#using-make-test-the-run-test-framework">Using &quot;make test&quot; (the run-test framework)</a><ul>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
    22
<li><a href="#configuration">Configuration</a></li>
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
    23
</ul></li>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    24
<li><a href="#test-selection">Test selection</a><ul>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
    25
<li><a href="#jtreg">JTReg</a></li>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    26
<li><a href="#gtest">Gtest</a></li>
52595
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
    27
<li><a href="#microbenchmarks">Microbenchmarks</a></li>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    28
<li><a href="#special-tests">Special tests</a></li>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    29
</ul></li>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    30
<li><a href="#test-results-and-summary">Test results and summary</a></li>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    31
<li><a href="#test-suite-control">Test suite control</a><ul>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
    32
<li><a href="#jtreg-keywords">JTReg keywords</a></li>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    33
<li><a href="#gtest-keywords">Gtest keywords</a></li>
52595
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
    34
<li><a href="#microbenchmark-keywords">Microbenchmark keywords</a></li>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    35
</ul></li>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    36
</ul>
45227
97be1bcd7b25 8180472: Pandoc should generate html5 from markdown
ihse
parents: 45103
diff changeset
    37
</nav>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    38
<h2 id="using-make-test-the-run-test-framework">Using &quot;make test&quot; (the run-test framework)</h2>
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50267
diff changeset
    39
<p>This new way of running tests is developer-centric. It assumes that you have built a JDK locally and want to test it. Running common test targets is simple, and more complex ad-hoc combination of tests is possible. The user interface is forgiving, and clearly report errors it cannot resolve.</p>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    40
<p>The main target <code>test</code> uses the jdk-image as the tested product. There is also an alternate target <code>exploded-test</code> that uses the exploded image instead. Not all tests will run successfully on the exploded image, but using this target can greatly improve rebuild times for certain workflows.</p>
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    41
<p>Previously, <code>make test</code> was used invoke an old system for running test, and <code>make run-test</code> was used for the new test framework. For backward compatibility with scripts and muscle memory, <code>run-test</code> (and variants like <code>exploded-run-test</code> or <code>run-test-tier1</code>) are kept as aliases. The old system can still be accessed for some time using <code>cd test &amp;&amp; make</code>.</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    42
<p>Some example command-lines:</p>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    43
<pre><code>$ make test-tier1
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    44
$ make test-jdk_lang JTREG=&quot;JOBS=8&quot;
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    45
$ make test TEST=jdk_lang
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    46
$ make test-only TEST=&quot;gtest:LogTagSet gtest:LogTagSetDescriptions&quot; GTEST=&quot;REPEAT=-1&quot;
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    47
$ make test TEST=&quot;hotspot:hotspot_gc&quot; JTREG=&quot;JOBS=1;TIMEOUT=8;VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug&quot;
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    48
$ make test TEST=&quot;jtreg:test/hotspot:hotspot_gc test/hotspot/jtreg/native_sanity/JniVersion.java&quot;
52595
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
    49
$ make test TEST=&quot;micro:java.lang.reflect&quot; MICRO=&quot;FORK=1;WARMUP_ITER=2&quot;
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    50
$ make exploded-test TEST=tier2</code></pre>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
    51
<h3 id="configuration">Configuration</h3>
51644
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
    52
<p>To be able to run JTReg tests, <code>configure</code> needs to know where to find the JTReg test framework. If it is not picked up automatically by configure, use the <code>--with-jtreg=&lt;path to jtreg home&gt;</code> option to point to the JTReg framework. Note that this option should point to the JTReg home, i.e. the top directory, containing <code>lib/jtreg.jar</code> etc. (An alternative is to set the <code>JT_HOME</code> environment variable to point to the JTReg home before running <code>configure</code>.)</p>
52595
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
    53
<p>To be able to run microbenchmarks, <code>configure</code> needs to know where to find the JMH dependency. Use <code>--with-jmh=&lt;path to JMH jars&gt;</code> to point to a directory containing the core JMH and transitive dependencies. The recommended dependencies can be retrieved by running <code>sh make/devkit/createJMHBundle.sh</code>, after which <code>--with-jmh=build/jmh/jars</code> should work.</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    54
<h2 id="test-selection">Test selection</h2>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    55
<p>All functionality is available using the <code>test</code> make target. In this use case, the test or tests to be executed is controlled using the <code>TEST</code> variable. To speed up subsequent test runs with no source code changes, <code>test-only</code> can be used instead, which do not depend on the source and test image build.</p>
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    56
<p>For some common top-level tests, direct make targets have been generated. This includes all JTReg test groups, the hotspot gtest, and custom tests (if present). This means that <code>make test-tier1</code> is equivalent to <code>make test TEST=&quot;tier1&quot;</code>, but the latter is more tab-completion friendly. For more complex test runs, the <code>test TEST=&quot;x&quot;</code> solution needs to be used.</p>
50267
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49293
diff changeset
    57
<p>The test specifications given in <code>TEST</code> is parsed into fully qualified test descriptors, which clearly and unambigously show which tests will be run. As an example, <code>:tier1</code> will expand to <code>jtreg:$(TOPDIR)/test/hotspot/jtreg:tier1 jtreg:$(TOPDIR)/test/jdk:tier1 jtreg:$(TOPDIR)/test/langtools:tier1 jtreg:$(TOPDIR)/test/nashorn:tier1 jtreg:$(TOPDIR)/test/jaxp:tier1</code>. 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>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
    58
<h3 id="jtreg">JTReg</h3>
50267
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49293
diff changeset
    59
<p>JTReg tests can be selected either by picking a JTReg test group, or a selection of files or directories containing JTReg tests.</p>
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50267
diff changeset
    60
<p>JTReg test groups can be specified either without a test root, e.g. <code>:tier1</code> (or <code>tier1</code>, the initial colon is optional), or with, e.g. <code>hotspot:tier1</code>, <code>test/jdk:jdk_util</code> or <code>$(TOPDIR)/test/hotspot/jtreg:hotspot_all</code>. The test root can be specified either as an absolute path, or a path relative to the JDK top directory, or the <code>test</code> directory. For simplicity, the hotspot JTReg test root, which really is <code>hotspot/jtreg</code> can be abbreviated as just <code>hotspot</code>.</p>
50267
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49293
diff changeset
    61
<p>When specified without a test root, all matching groups from all test roots will be added. Otherwise, only the group from the specified test root will be added.</p>
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50267
diff changeset
    62
<p>Individual JTReg tests or directories containing JTReg tests can also be specified, like <code>test/hotspot/jtreg/native_sanity/JniVersion.java</code> or <code>hotspot/jtreg/native_sanity</code>. Just like for test root selection, you can either specify an absolute path (which can even point to JTReg tests outside the source tree), or a path relative to either the JDK top directory or the <code>test</code> directory. <code>hotspot</code> can be used as an alias for <code>hotspot/jtreg</code> here as well.</p>
50267
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49293
diff changeset
    63
<p>As long as the test groups or test paths can be uniquely resolved, you do not need to enter the <code>jtreg:</code> prefix. If this is not possible, or if you want to use a fully qualified test descriptor, add <code>jtreg:</code>, e.g. <code>jtreg:test/hotspot/jtreg/native_sanity</code>.</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    64
<h3 id="gtest">Gtest</h3>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    65
<p>Since the Hotspot Gtest suite is so quick, the default is to run all tests. This is specified by just <code>gtest</code>, or as a fully qualified test descriptor <code>gtest:all</code>.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    66
<p>If you want, you can single out an individual test or a group of tests, for instance <code>gtest:LogDecorations</code> or <code>gtest:LogDecorations.level_test_vm</code>. This can be particularly useful if you want to run a shaky test repeatedly.</p>
51644
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
    67
<p>For Gtest, there is a separate test suite for each JVM variant. The JVM variant is defined by adding <code>/&lt;variant&gt;</code> to the test descriptor, e.g. <code>gtest:Log/client</code>. If you specify no variant, gtest will run once for each JVM variant present (e.g. server, client). So if you only have the server JVM present, then <code>gtest:all</code> will be equivalent to <code>gtest:all/server</code>.</p>
52595
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
    68
<h3 id="microbenchmarks">Microbenchmarks</h3>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
    69
<p>Which microbenchmarks to run is selected using a regular expression following the <code>micro:</code> test descriptor, e.g., <code>micro:java.lang.reflect</code>. This delegates the test selection to JMH, meaning package name, class name and even benchmark method names can be used to select tests.</p>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
    70
<p>Using special characters like <code>|</code> in the regular expression is possible, but needs to be escaped multiple times: <code>micro:ArrayCopy\\\\\|reflect</code>.</p>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    71
<h3 id="special-tests">Special tests</h3>
52396
e292e94b448a 8213058: remove ExecuteInternalVMTests and VerboseInternalVMTests flags
iignatyev
parents: 52342
diff changeset
    72
<p>A handful of odd tests that are not covered by any other testing framework are accessible using the <code>special:</code> test descriptor. Currently, this includes <code>failure-handler</code> and <code>make</code>.</p>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    73
<ul>
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    74
<li><p>Failure handler testing is run using <code>special:failure-handler</code> or just <code>failure-handler</code> as test descriptor.</p></li>
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    75
<li><p>Tests for the build system, including both makefiles and related functionality, is run using <code>special:make</code> or just <code>make</code> as test descriptor. This is equivalent to <code>special:make:all</code>.</p>
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    76
<p>A specific make test can be run by supplying it as argument, e.g. <code>special:make:idea</code>. As a special syntax, this can also be expressed as <code>make-idea</code>, which allows for command lines as <code>make test-make-idea</code>.</p></li>
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    77
</ul>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    78
<h2 id="test-results-and-summary">Test results and summary</h2>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    79
<p>At the end of the test run, a summary of all tests run will be presented. This will have a consistent look, regardless of what test suites were used. This is a sample summary:</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    80
<pre><code>==============================
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    81
Test summary
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    82
==============================
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    83
   TEST                                          TOTAL  PASS  FAIL ERROR
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    84
&gt;&gt; jtreg:jdk/test:tier1                           1867  1865     2     0 &lt;&lt;
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    85
   jtreg:langtools/test:tier1                     4711  4711     0     0
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    86
   jtreg:nashorn/test:tier1                        133   133     0     0
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    87
==============================
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    88
TEST FAILURE</code></pre>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    89
<p>Tests where the number of TOTAL tests does not equal the number of PASSed tests will be considered a test failure. These are marked with the <code>&gt;&gt; ... &lt;&lt;</code> marker for easy identification.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    90
<p>The classification of non-passed tests differs a bit between test suites. In the summary, ERROR is used as a catch-all for tests that neither passed nor are classified as failed by the framework. This might indicate test framework error, timeout or other problems.</p>
52342
9341b077bd55 8210958: Rename "make run-test" to "make test"
ihse
parents: 51644
diff changeset
    91
<p>In case of test failures, <code>make test</code> will exit with a non-zero exit value.</p>
51644
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
    92
<p>All tests have their result stored in <code>build/$BUILD/test-results/$TEST_ID</code>, where TEST_ID is a path-safe conversion from the fully qualified test descriptor, e.g. for <code>jtreg:jdk/test:tier1</code> the TEST_ID is <code>jtreg_jdk_test_tier1</code>. This path is also printed in the log at the end of the test run.</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    93
<p>Additional work data is stored in <code>build/$BUILD/test-support/$TEST_ID</code>. For some frameworks, this directory might contain information that is useful in determining the cause of a failed test.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    94
<h2 id="test-suite-control">Test suite control</h2>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    95
<p>It is possible to control various aspects of the test suites using make control variables.</p>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
    96
<p>These variables use a keyword=value approach to allow multiple values to be set. So, for instance, <code>JTREG=&quot;JOBS=1;TIMEOUT=8&quot;</code> will set the JTReg concurrency level to 1 and the timeout factor to 8. This is equivalent to setting <code>JTREG_JOBS=1 JTREG_TIMEOUT=8</code>, but using the keyword format means that the <code>JTREG</code> variable is parsed and verified for correctness, so <code>JTREG=&quot;TMIEOUT=8&quot;</code> would give an error, while <code>JTREG_TMIEOUT=8</code> would just pass unnoticed.</p>
49293
9e1c1889136e 8200180: fix a typo in run-test framework documentation
iignatyev
parents: 48058
diff changeset
    97
<p>To separate multiple keyword=value pairs, use <code>;</code> (semicolon). Since the shell normally eats <code>;</code>, the recommended usage is to write the assignment inside qoutes, e.g. <code>JTREG=&quot;...;...&quot;</code>. This will also make sure spaces are preserved, as in <code>JTREG=&quot;VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug&quot;</code>.</p>
51644
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 50885
diff changeset
    98
<p>(Other ways are possible, e.g. using backslash: <code>JTREG=JOBS=1\;TIMEOUT=8</code>. Also, as a special technique, the string <code>%20</code> will be replaced with space for certain options, e.g. <code>JTREG=VM_OPTIONS=-XshowSettings%20-Xlog:gc+ref=debug</code>. This can be useful if you have layers of scripts and have trouble getting proper quoting of command line arguments through.)</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
    99
<p>As far as possible, the names of the keywords have been standardized between test suites.</p>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
   100
<h3 id="jtreg-keywords">JTReg keywords</h3>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   101
<h4 id="jobs">JOBS</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   102
<p>The test concurrency (<code>-concurrency</code>).</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   103
<p>Defaults to TEST_JOBS (if set by <code>--with-test-jobs=</code>), otherwise it defaults to JOBS, except for Hotspot, where the default is <em>number of CPU cores/2</em>, but never more than 12.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   104
<h4 id="timeout">TIMEOUT</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   105
<p>The timeout factor (<code>-timeoutFactor</code>).</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   106
<p>Defaults to 4.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   107
<h4 id="test_mode">TEST_MODE</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   108
<p>The test mode (<code>-agentvm</code>, <code>-samevm</code> or <code>-othervm</code>).</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   109
<p>Defaults to <code>-agentvm</code>.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   110
<h4 id="assert">ASSERT</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   111
<p>Enable asserts (<code>-ea -esa</code>, or none).</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   112
<p>Set to <code>true</code> or <code>false</code>. If true, adds <code>-ea -esa</code>. Defaults to true, except for hotspot.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   113
<h4 id="verbose">VERBOSE</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   114
<p>The verbosity level (<code>-verbose</code>).</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   115
<p>Defaults to <code>fail,error,summary</code>.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   116
<h4 id="retain">RETAIN</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   117
<p>What test data to retain (<code>-retain</code>).</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   118
<p>Defaults to <code>fail,error</code>.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   119
<h4 id="max_mem">MAX_MEM</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   120
<p>Limit memory consumption (<code>-Xmx</code> and <code>-vmoption:-Xmx</code>, or none).</p>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
   121
<p>Limit memory consumption for JTReg test framework and VM under test. Set to 0 to disable the limits.</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   122
<p>Defaults to 512m, except for hotspot, where it defaults to 0 (no limit).</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   123
<h4 id="options">OPTIONS</h4>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
   124
<p>Additional options to the JTReg test framework.</p>
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
   125
<p>Use <code>JTREG=&quot;OPTIONS=--help all&quot;</code> to see all available JTReg options.</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   126
<h4 id="java_options">JAVA_OPTIONS</h4>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
   127
<p>Additional Java options to JTReg (<code>-javaoption</code>).</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   128
<h4 id="vm_options">VM_OPTIONS</h4>
45618
74f490ba783a 8179537: Update testing.md for more clarity regarding JTReg configuration
ihse
parents: 45227
diff changeset
   129
<p>Additional VM options to JTReg (<code>-vmoption</code>).</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   130
<h3 id="gtest-keywords">Gtest keywords</h3>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   131
<h4 id="repeat">REPEAT</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   132
<p>The number of times to repeat the tests (<code>--gtest_repeat</code>).</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   133
<p>Default is 1. Set to -1 to repeat indefinitely. This can be especially useful combined with <code>OPTIONS=--gtest_break_on_failure</code> to reproduce an intermittent problem.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   134
<h4 id="options-1">OPTIONS</h4>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   135
<p>Additional options to the Gtest test framework.</p>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   136
<p>Use <code>GTEST=&quot;OPTIONS=--help&quot;</code> to see all available Gtest options.</p>
52595
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   137
<h3 id="microbenchmark-keywords">Microbenchmark keywords</h3>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   138
<h4 id="fork">FORK</h4>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   139
<p>Override the number of benchmark forks to spawn. Same as specifying <code>-f &lt;num&gt;</code>.</p>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   140
<h4 id="iter">ITER</h4>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   141
<p>Number of measurement iterations per fork. Same as specifying <code>-i &lt;num&gt;</code>.</p>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   142
<h4 id="time">TIME</h4>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   143
<p>Amount of time to spend in each measurement iteration, in seconds. Same as specifying <code>-r &lt;num&gt;</code></p>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   144
<h4 id="warmup_iter">WARMUP_ITER</h4>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   145
<p>Number of warmup iterations to run before the measurement phase in each fork. Same as specifying <code>-wi &lt;num&gt;</code>.</p>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   146
<h4 id="warmup_time">WARMUP_TIME</h4>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   147
<p>Amount of time to spend in each warmup iteration. Same as specifying <code>-w &lt;num&gt;</code>.</p>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   148
<h4 id="results_format">RESULTS_FORMAT</h4>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   149
<p>Specify to have the test run save a log of the values. Accepts the same values as <code>-rff</code>, i.e., <code>text</code>, <code>csv</code>, <code>scsv</code>, <code>json</code>, or <code>latex</code>.</p>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   150
<h4 id="vm_options-1">VM_OPTIONS</h4>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   151
<p>Additional VM arguments to provide to forked off VMs. Same as <code>-jvmArgs &lt;args&gt;</code></p>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   152
<h4 id="options-2">OPTIONS</h4>
16609197022c 8061281: Microbenchmark suite build support, directory layout and sample benchmarks
redestad
parents: 52396
diff changeset
   153
<p>Additional arguments to send to JMH.</p>
44511
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   154
</body>
f3c27401a860 8177955: Add testing documentation
ihse
parents:
diff changeset
   155
</html>