diff options
Diffstat (limited to 'jtreg/doc')
| -rw-r--r-- | jtreg/doc/jtreg/faq.html | 216 | ||||
| -rw-r--r-- | jtreg/doc/jtreg/usage.txt | 52 |
2 files changed, 158 insertions, 110 deletions
diff --git a/jtreg/doc/jtreg/faq.html b/jtreg/doc/jtreg/faq.html index 2a7733f..efc6a66 100644 --- a/jtreg/doc/jtreg/faq.html +++ b/jtreg/doc/jtreg/faq.html @@ -508,8 +508,8 @@ <a href="tag-spec.txt">JDK Test Framework: Tag Language Specification</a> provides the needed descriptions. <code>regtest</code> refers to extensions for the JavaTest harness that - implement this specification, and is an older name for what is now known as - "jtreg".</p> + implement this specification, and is an older name for what is now known as + "jtreg".</p> <h3> <a name="question1.6">1.6. @@ -1582,11 +1582,11 @@ public class OneZero { JDK regression test suite assume that MKS is available. So, when you are writing tests for that test suite, you should make sure that your test at least works with MKS. If you prefer to use Cygwin, and can make - your test run with both, so much the better.</p> + your test run with both, so much the better.</p> <p> <strong>Note:</strong> as of JDK 8, the - tests assume the use of Cygwin by default.</p> + tests assume the use of Cygwin by default.</p> <h3> <a name="question3.14">3.14. @@ -1626,10 +1626,10 @@ public class OneZero { the JDK being tested. For example, Linux does not currently support 64-bit operation. Thus, the option <code>-d64</code> is not valid on Linux and will be rejected.</p> - + <p>You can also use the <code>-vmoption</code> or <code>-vmoptions</code> - option to pass one or a space-separated list of options to the JVM used - to run the test. </p> + option to pass one or a space-separated list of options to the JVM used + to run the test. </p> <p></p> <hr> @@ -1642,15 +1642,15 @@ public class OneZero { </a> </h3> -<p>The "test root directory", or "test suite root directory" is the - root directory of the overall test suite. - In OpenJDK terms, this means either of the "jdk/test/" or +<p>The "test root directory", or "test suite root directory" is the + root directory of the overall test suite. + In OpenJDK terms, this means either of the "jdk/test/" or "langtools/test/" directories in an OpenJDK forest.</p> <p>The "test root directory" for any test is determined by finding - the smallest enclosing directory containing a marker file called - TEST.ROOT. - The TEST.ROOT file can also be used to define some global properties + the smallest enclosing directory containing a marker file called + TEST.ROOT. + The TEST.ROOT file can also be used to define some global properties for the test suite.</p> <h3> @@ -1659,14 +1659,14 @@ public class OneZero { </a> </h3> -<p>Within the test suite, tests are uniquely identified by their path - relative to the test root directory. - This relative path is used to generate test-specific directories - and files within the work directory, and to identify test results +<p>Within the test suite, tests are uniquely identified by their path + relative to the test root directory. + This relative path is used to generate test-specific directories + and files within the work directory, and to identify test results within the report directory.</p> <p>However, note that tests can be specified on the command line - by any valid file system path, either absolute or relative to the + by any valid file system path, either absolute or relative to the current directory. </p> @@ -1676,14 +1676,14 @@ public class OneZero { </a> </h3> -<p>In general, no. Each test is uniquely associated with - exactly one test root directory, which is the the smallest - enclosing directory containing a marker file called TEST.ROOT. - In general, a test run will consist of tests from a single +<p>In general, no. Each test is uniquely associated with + exactly one test root directory, which is the the smallest + enclosing directory containing a marker file called TEST.ROOT. + In general, a test run will consist of tests from a single test suite, identified by a single test root directory. </p> -<p>It <em>is</em> possible to run tests from multiple test suites +<p>It <em>is</em> possible to run tests from multiple test suites (such as jdk/test and langtools/test) but this is not common. </p> <h3> @@ -1692,17 +1692,17 @@ public class OneZero { </a> </h3> -<p>"package root" refers the root of the package hierarchy in - which a Java source is placed. It is the directory you would - put on the javac source path if you wanted javac to compile +<p>"package root" refers the root of the package hierarchy in + which a Java source is placed. It is the directory you would + put on the javac source path if you wanted javac to compile the file explicitly.</p> -<p>Most jtreg tests are written in the "unnamed package" - (i.e. without a package statement) and so for most jtreg tests, - the directory directly containing the test is the package root - for the test. This is different from other test suites using - other test harnesses (such as TestNG) in which all the tests - of a test suite are placed in a single package hierarchy, +<p>Most jtreg tests are written in the "unnamed package" + (i.e. without a package statement) and so for most jtreg tests, + the directory directly containing the test is the package root + for the test. This is different from other test suites using + other test harnesses (such as TestNG) in which all the tests + of a test suite are placed in a single package hierarchy, often mirroring the package hierarchy of API being tested.</p> <h3> @@ -1711,40 +1711,40 @@ public class OneZero { </a> </h3> -<p>jtreg supports TestNG tests in two ways.</p> +<p>jtreg supports TestNG tests in two ways.</p> <ol> <li> -<p>Tests can be written with a full test description - (the comment beginning /* @test....*/) and can use the following +<p>Tests can be written with a full test description + (the comment beginning /* @test....*/) and can use the following action tag to run the test with TestNG: </p> -<pre>"@run testng classname args"</pre> +<pre>"@run testng classname args"</pre> -<p>Such a test would otherwise be similar to a standard test - using "@run main". You can use other tags such as @library and - @build, just as you would for "@run main". - These tests would normally be in the unnamed directory - (i.e. no package statement.) - These tests can be freely intermixed with other tests using +<p>Such a test would otherwise be similar to a standard test + using "@run main". You can use other tags such as @library and + @build, just as you would for "@run main". + These tests would normally be in the unnamed directory + (i.e. no package statement.) + These tests can be freely intermixed with other tests using "@run main", "@run shell", "@run applet" and so on. </p> -</li> +</li> <li> -<p>If you have a group of TestNG tests written in their own - package hierarchy, you can include that entire package - hierarchy as a subdirectory under the main test root directory. - If you do this, you must identify the root directory of that - package hierarchy to jtreg, so that it knows to treat all the - files in that package hierarchy specially. - In such a group of tests, you do not need to provide test - descriptions in each test. - You may optionally provide a test description if you choose to - do so, if you wish to specify information tags such as - @bug, @summary and @keyword. - You must not specify any action tags, such as @run, @compile, - etc, since the actions are implicit for every test in the group +<p>If you have a group of TestNG tests written in their own + package hierarchy, you can include that entire package + hierarchy as a subdirectory under the main test root directory. + If you do this, you must identify the root directory of that + package hierarchy to jtreg, so that it knows to treat all the + files in that package hierarchy specially. + In such a group of tests, you do not need to provide test + descriptions in each test. + You may optionally provide a test description if you choose to + do so, if you wish to specify information tags such as + @bug, @summary and @keyword. + You must not specify any action tags, such as @run, @compile, + etc, since the actions are implicit for every test in the group of tests. </p> </li> @@ -1754,25 +1754,25 @@ public class OneZero { <a name="question4.6">4.6. How do I identify a group of TestNG tests in their own directory? </a> -</h3> +</h3> <p>Add a line specifying the directory to TEST.ROOT</p> <pre>TestNG.dirs = dir1 dir2 dir3 ...</pre> <p>Include the package root directory for each group of TestNG - tests, and specify the package root directory relative to the test + tests, and specify the package root directory relative to the test root directory. </p> -<p>You can also override the value in TEST.ROOT by using the - TEST.properties file in any subdirectory of the test root directory - that contains the package root. +<p>You can also override the value in TEST.ROOT by using the + TEST.properties file in any subdirectory of the test root directory + that contains the package root. If you put the declaration in a TEST.properties file, you can specify the path relative to the directory containing the TEST.properties file. - In particular, instead of declaring the directory in TEST.ROOT, - you could place the declaration in a TEST.properties file in the + In particular, instead of declaring the directory in TEST.ROOT, + you could place the declaration in a TEST.properties file in the package root directory for the group of tests, in which case the declaration would be simply: </p> @@ -1783,17 +1783,17 @@ public class OneZero { <a name="question4.7">4.7. How does jtreg run TestNG tests? </a> -</h3> - -<p>Tests using "@run testng" are compiled in the standard way, - with TestNG libraries on the classpath. - The test is run using the class <code>org.testng.TestNG</code>. - For any TestNG test in a group of TestNG tests, any tests in the - group that need compiling are compiled together before any - test in the group is run. - Then, the selected test classes are run one at a time using - <code>org.testng.TestNG</code>. - Each test that is run will have its results stored in a +</h3> + +<p>Tests using "@run testng" are compiled in the standard way, + with TestNG libraries on the classpath. + The test is run using the class <code>org.testng.TestNG</code>. + For any TestNG test in a group of TestNG tests, any tests in the + group that need compiling are compiled together before any + test in the group is run. + Then, the selected test classes are run one at a time using + <code>org.testng.TestNG</code>. + Each test that is run will have its results stored in a corresponding *.jtr file. </p> @@ -1801,28 +1801,28 @@ public class OneZero { <a name="question4.8">4.8. How do I specify any libraries I want to use in TestNG tests? </a> -</h3> +</h3> -<p>Tests using "@run testng" can use @library and @build in - the standard way. - For any test in a group of TestNG tests, you can specify the - library by adding a line specifying the library in the - TEST.properties file in the package root directory for the group of +<p>Tests using "@run testng" can use @library and @build in + the standard way. + For any test in a group of TestNG tests, you can specify the + library by adding a line specifying the library in the + TEST.properties file in the package root directory for the group of tests. </p> <pre>lib.dirs = path-to-library ...</pre> -<p>As with the @library tag, if the path begins with "/", - it will be evaluated relative to the test root directory; - otherwise, it will be evaluated relative to the directory +<p>As with the @library tag, if the path begins with "/", + it will be evaluated relative to the test root directory; + otherwise, it will be evaluated relative to the directory containing the TEST.properties file. </p> -<p>For any particular group of TestNG tests, you can only - specify libraries for the entire group: you cannot specify one - library for some of the tests and another library for other tests. - This is because the all the source files in the group are +<p>For any particular group of TestNG tests, you can only + specify libraries for the entire group: you cannot specify one + library for some of the tests and another library for other tests. + This is because the all the source files in the group are compiled together. </p> @@ -1952,10 +1952,10 @@ public class OneZero { What is "agent VM" mode, and why would I want to use it?</a> </h3> -<p>It's like "same VM" mode, but better. By default, tests will run in - the same JVM. In between tests, jtreg will try to reset the JVM to - a standard state, and if it cannot, it will discard the JVM and - start another. </p> +<p>It's like "same VM" mode, but better. By default, tests will run in + the same JVM. In between tests, jtreg will try to reset the JVM to + a standard state, and if it cannot, it will discard the JVM and + start another. </p> <h3> <a name="question5.7">5.7. @@ -2040,7 +2040,7 @@ public class OneZero { Linux ) echo "Linux" ;; SunOS ) - echo "Solaris" ;; + echo "Solaris" ;; Windows* ) echo "Windows" ;; * ) @@ -2828,28 +2828,28 @@ public class OneZero { <a name="question8.8">8.8. <code>Error. JUnit not available</code></a> </h3> - + <p>To run JUnit tests within jtreg, you must have a copy of junit.jar - available. To do this, you should do one of the following:</p> - + available. To do this, you should do one of the following:</p> + <ul> - + <li>Put junit.jar on the classpath used to run jtreg.</li> - + <li>You can specify the location by setting the system property - <code>junit.jar</code> -</li> - -<li>Install a copy in the <em>jtreg</em><code>/lib</code> directory - if it is not already present.</li> - + <code>junit.jar</code> +</li> + +<li>Install a copy in the <em>jtreg</em><code>/lib</code> directory + if it is not already present.</li> + </ul> - + <p> - If you do not have a copy of junit.jar on your system, you can download - it from <a href="http://junit.org/">http://junit.org/</a>. - </p> - + If you do not have a copy of junit.jar on your system, you can download + it from <a href="http://junit.org/">http://junit.org/</a>. + </p> + <hr> <dl> <dt> diff --git a/jtreg/doc/jtreg/usage.txt b/jtreg/doc/jtreg/usage.txt index bf40276..1ee8537 100644 --- a/jtreg/doc/jtreg/usage.txt +++ b/jtreg/doc/jtreg/usage.txt @@ -1,7 +1,8 @@ Usage: jtreg options... tests... -Tests can be given as files or folders containing test files. +Tests can be given as files or folders containing test files, or by means of +test groups. Long lists of options and tests may be encapsulated in "at-files". Verbose Options @@ -30,6 +31,7 @@ Verbose Options Documentation Options Options for additional documentation + -h [words...] | -help [words...] | -usage [words...] Command line help. Give words to see help info containing those or use "-help all" to see all available help. @@ -71,6 +73,9 @@ General Options then give an "Error" result. run Run the test, as though the @ignore tag were not present. + -l | -listtests + List the tests that would be executed instead of executing + them. -lock:<file> Lock file to use for tests in "exclusive access" directories when running tests in multiple concurrent instances of jtreg. @@ -112,6 +117,11 @@ General Options re-run any tests. A work directory containing the results of the executed tests must be provided. The default location is "./JTwork". To specify an alternate directory, use -workDir. + -show:Name of information in the results file, such as "rerun". + Show selected information from the results file for a test + -showGroups Show the expansion (to files and directories) of the groups + given on the command line. To see the expansion of all the + groups in a test suite, specify the name of the test suite. -startHttpd Start the http server to view test results -timeout:<number> | -timeoutFactor:<number> A scaling factor to extend the default timeout of all tests. @@ -273,6 +283,44 @@ JDK-related Options -XX* | -Xms* | -Xmx* Non-standard VM Options +Tests Specifying collections of tests. + + at-files Long lists of options and tests may be encapsulated in + "at-files". Place the options and/or tests in a file and + specify the name of the file on the command line with @file. + Options or tests that include white space should be enclosed + within either single or double quote characters. Comments + may be included in the file by prefixing them with '#'. To + specify an option beginning with '@' on the command line, + use "@@" to avoid @file expansion. + + Groups A test suite may define named groups of tests. To specify + the name of a group of tests on the command line, use + test-suite-dir:group-name, where test-suite-dir is a path to + the root directory of the test suite (i.e the directory + containing the TEST.ROOT file), and where group-name is the + name of the group of tests defined in the test suite. If + test-suite-dir is omitted it defaults to the value of the + -dir option, if given, or to the current directory + otherwise. + (Note: on Windows, to avoid confusion with absolute path + names including a drive specifier, the test-suite-dir must + not be specified with a relative path consisting of a single + letter.) + + Groups are defined in a test suite using one or more Java + properties files. The names of these files must be listed in + the "groups" entry in TEST.ROOT. If the filename is enclosed + in square brackets, no error message will be given if the + file cannot be found. Within the property files, each entry + specifies items to be included or excluded from the group. + To include a test or directory of tests, simply specify the + name of the test or directory. To exclude a test or + directory of tests, use '-' followed by the name of the test + or directory. To include the contents of another group, use + ':' followed by the name of the group. There must be no + spaces between the "-" or ":" and the name that follows. + For more details and examples, see the online help. You can access this directly from the command line with "-onlineHelp <word>...", or you can start the @@ -281,6 +329,6 @@ JavaTest harness and use the Help menu. jtreg can also be run with Ant. See the online help for details. For example, use the "-onlineHelp ant" command line option. -Copyright (c) 1999, 2012, Oracle and/or its affiliates. All rights reserved. +Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. |