.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.4. .TH JTREG "1" "January 2017" "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: | \fB\-verbose\fR | \fB\-\-verbose\fR: 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 multirun Updates for each testsuite when tests from more than one are being executed. .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\-\-help\fR [words...] | \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\-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: 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: | \fB\-concurrency\fR: concurrency factor .TP \fB\-dir\fR: 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: 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: Lock file to use for tests in "exclusive access" directories when running tests in multiple concurrent instances of jtreg. .TP \fB\-nativepath\fR: Path to location of native libraries and programs needed by the tests. .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: | \fB\-observer\fR: 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: | \fB\-observerDir\fR: | \fB\-op\fR: | \fB\-observerPath\fR: 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: | \fB\-reportDir\fR: All report files placed here; "./JTreport" is default .TP \fB\-retain\fR | \fB\-\-retain\fR:,... 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\-w\fR: | \fB\-workDir\fR: 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 Timeout Options .IP These options control the behavior when tests run longer than their specified timeout value. .TP \fB\-th\fR: | \fB\-timeoutHandler\fR: Specifies the class to handle timeouts. The class must extend com.sun.javatest.regtest.TimeoutHandler. E.g. \fB\-th\fR:MyHandler .TP \fB\-thd\fR: | \fB\-timeoutHandlerDir\fR: Specifies the pathname of a directory or .jar file in which the timeout handler class is located. The given pathname is simply appended to the CLASSPATH used for the tests, thus care should be taken when naming an timeout handler not to collide with the names of classes internal to the JavaTest harness or the JRE, e.g., put the timeout handler class in its own named package. .TP \fB\-thtimeout\fR:<#seconds> | \fB\-timeoutHandlerTimeout\fR:<#seconds> Specifies execution time limitation for the timeout handler. If the timeout handler does not finish its actions within the specified period of time, it will be interrupted. Non\-positive values mean no limitation. The default value is 5 minutes (300 seconds). .TP \fB\-timeout\fR: | \fB\-timeoutFactor\fR: A scaling factor to extend the default timeout of all tests. Typically used when running tests on slow systems or systems with 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. .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: Run only those tests which apply to the given bugid. .TP \fB\-exclude\fR: | \fB\-Xexclude\fR: Provide a file specifying tests not to be run .TP \fB\-k\fR: | \fB\-keywords\fR: 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:,... 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 Each test consists of a series of steps, called actions. The jtreg harness provides different modes, which determine the JVM to use to execute each action. The default is to run each action in a new JVM. .TP \fB\-avm\fR | \fB\-agentvm\fR Execute each action using a pool of reusable JVMs, except when an action specifies otherwise. It provides good performance, and reasonable isolation between actions: if a JVM can be reset to a standard state after it has been used, it will be returned to the pool for reuse; otherwise, it will be discarded and replaced if and when necessary. This mode is generally recommended for all use. The JDK to use can be specified with \fB\-testjdk\fR or \fB\-jdk\fR, except for @compile actions, which use \fB\-compilejdk\fR or \fB\-jdk\fR. If values are not provided, the environment variable JAVA_HOME is used. .TP \fB\-ovm\fR | \fB\-othervm\fR Execute every action in a new JVM. This is the default. It provides the maximum isolation between actions, at a significant cost in performance. The JDK to use can be specified with \fB\-testjdk\fR or \fB\-jdk\fR, except for @compile actions, which use \fB\-compilejdk\fR or \fB\-jdk\fR. If values are not provided, the environment variable JAVA_HOME is used. .TP \fB\-s\fR | \fB\-svm\fR | \fB\-samevm\fR Execute each action in the same JVM as the jtreg harness, except when an action specifies otherwise. It provides the maximum performance, but the least isolation between actions, such that a bad test can cause all subsequent tests in the test run to fail. This mode is only suitable for well\-behaved test suites, and cannot be used in conjunction with the \fB\-concurrency\fR option. It is no longer recommended for general use. The JDK version used may be specified with \fB\-testjdk\fR or \fB\-jdk\fR. If a value 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, many 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\-\-add\-modules\fR (,)* root modules to resolve in addition to the initial module .TP \fB\-agentlib\fR:<[=] Load native agent library .TP \fB\-agentpath\fR:<[=] 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: 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: | \fB\-classpathappend\fR: 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= Define a system property .TP \fB\-debug\fR: