.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.45.1.
.TH JTREG "1" "July 2014" "jtreg Usage:" "User Commands"
.SH NAME
jtreg \- Regression Test Harness
.SH DESCRIPTION
.SS "Usage:"
.IP
jtreg options... tests...
.PP
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".
.PP
Verbose Options
.IP
These options control the amount of output written to the
console while running tests
.TP
\fB\-v\fR | \fB\-v\fR:<value> | \fB\-verbose\fR | \fB\-verbose\fR:<value>
Increase the amount of output written to the console. A
value, or selected combinations of values separated by
commas, may be given to select the type of output desired.
.TP
default
Three lines of output per test: start, end, status
.TP
summary
One line of output per test: status, test name
.TP
all
Selected contents of JTR file for all tests (includes
stdout/stderr)
.TP
pass
Selected contents of JTR file for passed tests
.TP
fail
Selected contents of JTR file for failed tests
.TP
error
Selected contents of JTR file for errored tests
.TP
nopass
Suppress output for tests that passed
.TP
time
Elapsed time per action
.TP
\fB\-v1\fR
Short for \fB\-verbose\fR:summary
.TP
\fB\-va\fR
Short for \fB\-verbose\fR:all
.TP
\fB\-ve\fR
Short for \fB\-verbose\fR:error
.TP
\fB\-vf\fR
Short for \fB\-verbose\fR:fail
.TP
\fB\-vp\fR
Short for \fB\-verbose\fR:pass
.TP
\fB\-vt\fR
Short for \fB\-verbose\fR:time
.PP
Documentation Options
.IP
Options for additional documentation
.TP
\fB\-h\fR [words...] | \fB\-help\fR [words...] | \fB\-usage\fR [words...]
Command line help. Give words to see help info containing
those or use "\-help all" to see all available help.
.TP
\fB\-n\fR | \fB\-relnote\fR
Release notes
.TP
\fB\-onlineHelp\fR [words...]
Show the online help. You can also show the online help from
the desktop Help menu.
.TP
\fB\-t\fR | \fB\-tagspec\fR
Tag specification supported by this implementation
.TP
\fB\-version\fR
Give information about the version of jtreg in use.
.PP
General Options
.TP
\fB\-allowSetSecurityManager\fR | \fB\-allowSetSecurityManager\fR:<boolean\-value>
Allow sameVM tests to set a security manager. Default is
"yes" if option not given or no value given for option.
.TP
yes
Allow sameVM tests to set a security manager
.TP
no
Do not allow sameVM tests to set a security manager
.TP
on
Allow sameVM tests to set a security manager
.TP
off
Do not allow sameVM tests to set a security manager
.TP
true
Allow sameVM tests to set a security manager
.TP
false
Do not allow sameVM tests to set a security manager
.TP
\fB\-c\fR | \fB\-check\fR
Verify correctness of test descriptions. Does NOT run tests.
.TP
\fB\-conc\fR:<factor> | \fB\-concurrency\fR:<factor>
concurrency factor
.TP
\fB\-dir\fR:<dir>
Specify a base directory for test files and directories
.TP
\fB\-e\fR:name[=value][,name[=value]...]
Specify additional environment variables to be passed to
each test. If a value is not given for a name, the current
value of the environment variable will be used. Standard
environment variables, like DISPLAY, LANG, windir,
SystemRoot, etc, will automatically be given to each test,
if they are set in the current environment.
.TP
\fB\-g\fR | \fB\-gui\fR
Access regression extensions via the standard JavaTest
harness gui
.TP
\fB\-ignore\fR:<value>
Specify how to handle tests containing an @ignore tag.
.TP
quiet
Completely ignore such tests.
.TP
error
(Default.) Execute the actions up to the @ignore tag,
then give an "Error" result.
.TP
run
Run the test, as though the @ignore tag were not
present.
.TP
\fB\-l\fR | \fB\-listtests\fR
List the tests that would be executed instead of executing
them.
.TP
\fB\-lock\fR:<file>
Lock file to use for tests in "exclusive access" directories
when running tests in multiple concurrent instances of
jtreg.
.TP
\fB\-noignore\fR
suppress the effect of any @ignore tags, allowing the test
to proceed as if the @ignore tags were not present.
Deprecated: see the \fB\-ignore\fR option.
.TP
\fB\-nr\fR | \fB\-noreport\fR
Do not generate a final report.
.TP
\fB\-o\fR:<classname> | \fB\-observer\fR:<classname>
Specifies the class to observe the progress of a test suite;
the class must implement a specific interface; contact a
developer for details. E.g. \fB\-o\fR:SampleRegressionObserver
.TP
\fB\-od\fR:<path> | \fB\-observerDir\fR:<path> | \fB\-op\fR:<path> | \fB\-observerPath\fR:<path>
Specifies the pathname of a directory or .JAR file in which
the observer class is located. The given pathname is simply
appended to the CLASSPATH used for the tests, thus care
should be taken when naming an observer not to collide with
the names of classes internal to the JavaTest harness or the
JRE, e.g., put the observer class in its own named package.
.TP
\fB\-r\fR:<directory> | \fB\-reportDir\fR:<directory>
All report files placed here; "./JTreport" is default
.TP
\fB\-retain\fR | \fB\-retain\fR:<pass,fail,error,all,file\-pattern>,...
Specify files to be retained after each test completes
executing. If \fB\-retain\fR is not specified, only the files from
the last test executed will be retained. If \fB\-retain\fR is
specified with no argument, all files will be retained.
Otherwise, the files may be described by one or more of the
following values:
.TP
none
Do not retain any of the files generated by each test
.TP
pass
Retain files generated by tests that pass
.TP
fail
Retain files generated by tests that fail
.TP
error
Retain files generated by tests that caused an error
.TP
all
Retain all files generated by each test
.TP
file\-pattern
Retain files that match a specific filename. The name
may contain '*' to match any sequence of characters. For
example, result.* or *.err.
.TP
\fB\-ro\fR | \fB\-reportOnly\fR
Generate report for previously executed tests. This does not
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 \fB\-workDir\fR.
.TP
\fB\-show\fR:Name of information in the results file, such as "rerun".
Show selected information from the results file for a test
.TP
\fB\-showGroups\fR
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.
.TP
\fB\-startHttpd\fR
Start the http server to view test results
.TP
\fB\-timeout\fR:<number> | \fB\-timeoutFactor\fR:<number>
A scaling factor to extend the default timeout of all tests.
Typically used when running on slow file systems.
.TP
\fB\-tl\fR:<#seconds> | \fB\-timelimit\fR:<#seconds>
Do not run tests which specify a timeout longer than a given
value. The comparison is done against any values specified
in the test, before any timeout factor is applied.
.TP
\fB\-w\fR:<directory> | \fB\-workDir\fR:<directory>
Location for .class files, .jtr files, etc. "./JTwork" is
default
.TP
\fB\-xml\fR | \fB\-xml\fR:verify
Create ant/junit xml files into the workDir. Optionally
verify if the file is well formed.
.PP
Test Selection Options
.IP
These options can be used to refine the set of tests to be
executed.
.TP
\fB\-a\fR | \fB\-automatic\fR | \fB\-automagic\fR
Any test with \fI\,/manual\/\fP will not be run
.TP
\fB\-bug\fR:<bugid>
Run only those tests which apply to the given bugid.
.TP
\fB\-exclude\fR:<file> | \fB\-Xexclude\fR:<file>
Provide a file specifying tests not to be run
.TP
\fB\-k\fR:<keywordExpr> | \fB\-keywords\fR:<keywordExpr>
A keyword boolean expression for test selection. The
expression can contain keyword names, combined with & (and),
| (or), ! (not) and parentheses.
.TP
\fB\-m\fR | \fB\-manual\fR
Only tests with \fI\,/manual\/\fP will be run
.TP
\fB\-noshell\fR
Any tests which contain shell actions will not be run
.TP
\fB\-shell\fR
Only tests which contain shell actions will be run
.TP
\fB\-status\fR:<value>,...
Select tests according to their result in an earlier run.
The value can be one or more of the following values,
separated by commas.
.TP
pass
Tests that passed
.TP
fail
Tests that failed
.TP
notRun
Tests that have not been run
.TP
error
Tests that could not be run because of errors, or tests
that were ignored
.PP
Test Mode Options
.IP
When the JavaTest harness is used to run tests, two possibly
different versions of the JDK are used: the JDK version used to
run the harness and the JDK version used to run the test(s). The
following options provide a means to specify the JDK version
used to run the tests. The default is to use the same JDK
version (provided by JAVA_HOME) for both the harness and the
tests, and for each test to run in its own JVM.
.TP
\fB\-avm\fR | \fB\-agentvm\fR
Run tests using a pool of reusable JVMs.
.TP
\fB\-ovm\fR | \fB\-othervm\fR
Run every test in its own JVM. The JDK version for the tests
may be specified via the \fB\-testjdk\fR option. If not provided,
then the JDK version specified by the JAVA_HOME environment
variable will be used.
.TP
\fB\-s\fR | \fB\-svm\fR | \fB\-samevm\fR
If possible, run each test in the same JVM as the JavaTest
harness. The JDK version used may be specified with
\fB\-testjdk\fR. If \fB\-testjdk\fR is not provided, then the JDK version
will be determined by the environment variable JT_JAVA if it
is set. Otherwise, the environment variable JAVA_HOME is
used.
.PP
JDK\-related Options
.IP
By default, tests will be run using the default JVM in the test
JDK. You can pass all applicable JVM options via using
\fB\-vmoption\fR; in addition, most common JVM options are also
supported directly. For full details of any option, consult the
documentation for that version of the JDK, or try using "java
\fB\-help\fR" or "java \fB\-X\fR". If an option is not applicable to a
particular platform or JDK release, it will be rejected.
.TP
\fB\-agentlib\fR:<libname><[=<options>]
Load native agent library
.TP
\fB\-agentpath\fR:<pathname><[=<options>]
Load native agent library by full pathname
.TP
\fB\-classic\fR | \fB\-green\fR | \fB\-native\fR | \fB\-hotspot\fR | \fB\-client\fR | \fB\-server\fR | \fB\-d32\fR | \fB\-d64\fR
VM Options
.TP
\fB\-compilejdk\fR:<java.home>
Compile all tests using specified JDK. If not specified,
tests are compiled with the JDK used to run the tests. See
also \fB\-jdk\fR. e.g. \fB\-jdk\fR:/usr/local/java/jdk1.5/solaris\-sparc
.TP
\fB\-cpa\fR:<path> | \fB\-classpathappend\fR:<path>
Append the provided classPath to the CLASSPATH of every
test. This is designed to be used primarily for tests which
require non\-core JDK functionality. For example, to test
Swing, which is not part of core JDK1.1, the following
addition to the the CLASSPATH would be necessary:
\fB\-cpa\fR:/usr/local/java/swing\-1.0.3/swingall.jar
.TP
\fB\-D\fR<name>=<value>
Define a system property
.HP
\fB\-enableassertions\fR | \fB\-enableassertions\fR:* | \fB\-ea\fR | \fB\-ea\fR:* | \fB\-disableassertions\fR |
.TP
\fB\-disableassertions\fR:* | \fB\-da\fR | \fB\-da\fR:*
Enable or disable assertions
.TP
\fB\-enablesystemassertions\fR | \fB\-esa\fR | \fB\-disablesystemassertions\fR | \fB\-dsa\fR
Enable or disable system assertions
.TP
\fB\-javaagent\fR:<jarpath><[=<options>]
Load Java programming language agent
.TP
\fB\-javacoption\fR:<option>
Additional compiler option. You can give this option
multiple times. Any embedded filenames must be given with
absolute paths.
.TP
\fB\-javacoptions\fR:<option>...
Additional compiler options. You can give this option
multiple times, or give many values together, separated by
spaces. If you give multiple values, you may need to enclose
them in quotes, depending on the shell you use. Any embedded
filenames must be given with absolute paths. Warning: do not
use this form if any of the options has an argument such as
a filename that might contain spaces. In that case, use one
or more \fB\-javacoption\fR options instead.
.TP
\fB\-javaoption\fR:<option>
Additional java option for running test classes. You can
give this option multiple times. Any embedded filenames must
be given with absolute paths. See also \fB\-vmoption\fR.
.TP
\fB\-javaoptions\fR:<option>...
Additional java options for running test classes. You can
give this option multiple times, or give many values
together, separated by spaces. If you give multiple values,
you may need to enclose them in quotes, depending on the
shell you use. Any embedded filenames must be given with
absolute paths. Warning: do not use this form if any of the
options has an argument such as a filename that might
contain spaces. In that case, use one or more \fB\-javaoption\fR
options instead. See also \fB\-vmoptions\fR.
.TP
\fB\-jdk\fR:<java.home> | \fB\-testjdk\fR:<java.home>
Run all tests using specified JDK. e.g.
\fB\-jdk\fR:/usr/local/java/jdk1.5/solaris\-sparc
.TP
\fB\-jit\fR
Enable the JIT for the tests. The JIT is turned on by
default.
.TP
\fB\-nojit\fR
Disable the JIT for the tests.
.TP
\fB\-vmoption\fR:<option>
Any other VM option. You can give this option multiple
times. Any embedded filenames must be given with absolute
paths. This option will be used when compiling and running
classes. See also \fB\-javaoption\fR.
.TP
\fB\-vmoptions\fR:<option>...
Any other VM options. You can give this option multiple
times, or give many values together, separated by spaces. If
you give multiple values, you may need to enclose them in
quotes, depending on the shell you use. Any embedded
filenames must be given with absolute paths. Warning: do not
use this form if any of the options has an argument such as
a filename that might contain spaces. In that case, use one
or more \fB\-vmption\fR options instead. This option will be used
when compiling and running classes. See also \fB\-javaoptions\fR.
.TP
\fB\-X\fR*
Non\-standard VM Options.
.TP
\fB\-Xbootclasspath\fR:<path>
Set search path for bootstrap classes and resources
.TP
\fB\-Xbootclasspath\fR/a:<path>
Append to end of bootstrap class path
.TP
\fB\-Xbootclasspath\fR/p:<path>
Prepend in front of bootstrap class path
.TP
\fB\-Xint\fR* | \fB\-Xmixed\fR* | \fB\-Xcomp\fR*
Non\-standard VM Options
.TP
\fB\-Xrunjcov\fR*
Options for running jcov
.TP
\fB\-XX\fR* | \fB\-Xms\fR* | \fB\-Xmx\fR*
Non\-standard VM Options
.PP
Tests           Specifying collections of tests.
.TP
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.
.TP
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
\fB\-dir\fR 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.)
.TP
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.
.PP
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
JavaTest harness and use the Help menu.
.PP
jtreg can also be run with Ant. See the online help for details. For example,
use the "\-onlineHelp ant" command line option.
.SH COPYRIGHT
Copyright \(co 1999, 2013, Oracle and/or its affiliates. All rights reserved.
Use is subject to license terms.
.IP
jtreg options... tests...
.PP
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".
.PP
For brief details about a topic, use "\-help <term> ...". The argument <term> is
a command option or other word related to the topic. Use "\-help all" to show all
of the help entries.
.PP
Information is available for the following topics.
.PP
Verbose Options
.IP
These options control the amount of output written to the
console while running tests
.PP
Documentation Options
.IP
Options for additional documentation
.PP
General Options
.PP
Test Selection Options
.IP
These options can be used to refine the set of tests to be
executed.
.PP
Test Mode Options
.IP
When the JavaTest harness is used to run tests, two possibly
different versions of the JDK are used: the JDK version used to
run the harness and the JDK version used to run the test(s). The
following options provide a means to specify the JDK version
used to run the tests. The default is to use the same JDK
version (provided by JAVA_HOME) for both the harness and the
tests, and for each test to run in its own JVM.
.PP
JDK\-related Options
.IP
By default, tests will be run using the default JVM in the test
JDK. You can pass all applicable JVM options via using
\fB\-vmoption\fR; in addition, most common JVM options are also
supported directly. For full details of any option, consult the
documentation for that version of the JDK, or try using "java
\fB\-help\fR" or "java \fB\-X\fR". If an option is not applicable to a
particular platform or JDK release, it will be rejected.
.PP
Tests           Specifying collections of tests.
.PP
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
JavaTest harness and use the Help menu.
.PP
jtreg can also be run with Ant. See the online help for details. For example,
use the "\-onlineHelp ant" command line option.
.PP
.br
Copyright \(co 1999, 2013, Oracle and/or its affiliates. All rights reserved.
Use is subject to license terms.
.SH "SEE ALSO"
The full documentation for
.B jtreg
is maintained as a Texinfo manual.  If the
.B info
and
.B jtreg
programs are properly installed at your site, the command
.IP
.B info jtreg
.PP
should give you access to the complete manual.