JTREG(1)

📦
version 8.3+1 · 21 versions
, in debian trixie

💖 JTREG(1) 💖

okay bestie, welcome to jtreg, aka the Regression Test Harness — she lives in section 1 of the User Commands manual and she is THE girl for running tests. grab a boba, we're doing this 🧋✨

🌸 NAME 🌸

jtreg — Regression Test Harness 👑

🦋 DESCRIPTION 🦋

✨ Usage ✨

jtreg options... tests...

so the vibe is: you hand her tests... and she runs them. those tests can be given as files or folders containing test files, or you can roll up by means of test groups. 🫶

and listen — long lists of options and tests may be encapsulated in "at-files". yes bestie, at-files. iconic behaviour honestly.

💅 Verbose Options 💅

These options control the amount of output written to the console while running tests. basically: how much does she yap about it 🗣️

  • -v | --v:<value> | -verbose | --verbose:<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.
    • default — Three lines of output per test: start, end, status
    • summary — One line of output per test: status, test name
    • all — Selected contents of JTR file for all tests (includes stdout/stderr)
    • pass — Selected contents of JTR file for passed tests
    • fail — Selected contents of JTR file for failed tests
    • error — Selected contents of JTR file for errored tests
    • nopass — Suppress output for tests that passed
    • time — Elapsed time per action
    • multirun — Updates for each testsuite when tests from more than one are being executed.
  • -v1 — Short for -verbose:summary
  • -va — Short for -verbose:all
  • -ve — Short for -verbose:error
  • -vf — Short for -verbose:fail
  • -vp — Short for -verbose:pass
  • -vt — Short for -verbose:time

🎀 Documentation Options 🎀

Options for additional documentation. when you just need to read about her instead of running her 📖

  • --help [words...] | -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.
  • -n | -relnote — Release notes
  • -t | -tagspec — Tag specification supported by this implementation
  • -version — Give information about the version of jtreg in use.

🌈 General Options 🌈

the main character section fr fr 💅

  • -allowSetSecurityManager | --allowSetSecurityManager:<boolean-value> — Allow agentVM tests to set a security manager. Default is "yes" if option not given or no value given for option.
    • yes — Allow agentVM tests to set a security manager
    • no — Do not allow agentVM tests to set a security manager
    • on — Allow agentVM tests to set a security manager
    • off — Do not allow agentVM tests to set a security manager
    • true — Allow agentVM tests to set a security manager
    • false — Do not allow agentVM tests to set a security manager
  • -c | -check — Verify correctness of test descriptions. Does NOT run tests. 🚨 (she's just checking, bestie, not executing!)
  • -conc:<factor> | -concurrency:<factor> — concurrency factor
  • -cygwin — (Windows only) Use Cygwin to run shell tests
  • -dir:<dir> — Specify a base directory for test files and directories
  • -e: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. 🌱
  • -g | -gui — Access regression extensions via the standard JavaTest harness gui
  • -i | --verify-exclude — Validate contents of exclude files
  • -ignore:<value> — Specify how to handle tests containing an @ignore tag.
    • quiet — Completely ignore such tests.
    • error — (Default.) Execute the actions up to the @ignore tag, 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.
  • -nativepath:<path> — Path to location of native libraries and programs needed by the tests.
  • -noignore — suppress the effect of any @ignore tags, allowing the test to proceed as if the @ignore tags were not present. Deprecated: see the -ignore option. 💀
  • -nr | -noreport — Do not generate a final report.
  • -o:<classname> | -observer:<classname> — Specifies the class to observe the progress of a test suite; the class must implement a specific interface; contact a developer for details. For example, -o:SampleRegressionObserver
  • -od:<path> | -observerDir:<path> | -op:<path> | -observerPath:<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. For example, put the observer class in its own named package. 🫶
  • -r:<directory> | -reportDir:<directory> — All report files placed here; "./JTreport" is default
  • -report:<value> — Configure the report generated after tests are run.
    • none — Do not generate a report; equivalent to -noreport.
    • executed — Include tests executed in the latest run
    • files — Include all tests specified by groups and paths on the command line, ignoring filters like status, exclude lists, and keywords.
    • all-executed — Include all tests that have been executed in current work directory
    • all — Include all tests that are present in the test suite, whether they have been executed
  • -retain | --retain:<none,lastRun,pass,fail,error,all,file-pattern>,... — Specify files to be retained after each test completes executing. If -retain is not specified or is specified with lastRun, only the files from the last test executed will be retained, in the test's scratch directory. For all other uses of -retain, files will be retained in a test-specific directory in the work-directory. If -retain is specified with no argument, all files will be retained. Otherwise, the files may be described by one or more of the following values:
    • none — Do not retain any of the files generated by each test
    • lastRun — Retain files generated by the last test that was run (default)
    • pass — Retain files generated by tests that pass
    • fail — Retain files generated by tests that fail
    • error — Retain files generated by tests that caused an error
    • all — Retain all files generated by each test
    • file-pattern — Retain files that match a specific filename. The name may contain '*' to match any sequence of characters. For example, result.* or *.err. 🔥
  • -ro | -reportOnly — 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 -workDir.
  • -show:[<section-name>/]<stream-name> — Show the contents of a stream in a specific section or in all sections of the results file for a test. The content is shown as originally written to the stream: that is, without the escape encoding used in the .jtr file. If no section name is given, the output for the named stream in all sections is shown. For example, -show:rerun -show:main/System.out ✨
  • -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
  • -ttf:<classname> | -testThreadFactory:<classname> — Specifies the class to create thread factory for test execution. The class should implement the java.util.concurrent.ThreadFactory interface.
  • -ttfp:<path> | -testThreadFactoryPath:<path> — Specifies classspath for custom test thread factory implementation. The classes from this classpath are loaded by tested JDK only using URLClassLoader.
  • -w:<directory> | -workDir:<directory> — Location for .class files, .jtr files, etc. "./JTwork" is default
  • -wsl — (Windows only) Use the Windows Subsystem for Linux (WSL) to run shell tests
  • -xml | --xml:verify — Create ant/junit xml files into the workDir. Optionally verify if the file is well-formed.

⏰ Timeout Options ⏰

These options control the behavior when tests run longer than their specified timeout value. yes she will call time on them ⏳

  • -th:<classname> | -timeoutHandler:<classname> — Specifies the class to handle timeouts. The class must extend com.sun.javatest.regtest.TimeoutHandler. For example, -th:MyHandler
  • -thd:<path> | -timeoutHandlerDir:<path> — 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 a timeout handler not to collide with the names of classes internal to the JavaTest harness or the JRE. For example, put the timeout handler class in its own named package.
  • -thtimeout:<#seconds> | -timeoutHandlerTimeout:<#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).
  • -timeout:<number> | -timeoutFactor:<number> — 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. 🐢
  • -tl:<#seconds> | -timelimit:<#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.

👑 Agent Pool Options 👑

Options to configure the size of the pool of VMs used to execute tests in agent mode. it's giving ✨pool party✨

  • --agent-attempts <number> — The number of attempts jtreg will make to access an agent with the desired characteristics, either by creating a new one, or obtaining one from the pool of reusable VMs. The minimum value, and the default value, is 1.
  • --max-pool-size <number> — The maximum number of VMs to keep available in the agent pool. The default is either 2x the concurrency.
  • --pool-idle-timeout <number> — how many seconds an idle VM can just be sitting there in the pool before it gets automatically closed. bye bestie 💤

✨ Test Selection Options ✨

Okay so these are the little filters that let you go "no, not ALL of them, just these ones" — refine the set of tests you actually execute. 🎯

  • -a | -automatic | -automagic — literally any test with /manual in it will NOT be run. manual girlies stay home 💅
  • -bug:<bugid> — run only those tests which apply to the given bugid.
  • -exclude:<file> | -Xexclude:<file> — hand it a file specifying tests that should not be run 🚫
  • -k:<keywordExpr> | -keywords:<keywordExpr> — a keyword boolean expression for test selection. the expression can contain keyword names, and you can combine them with & (and), | (or), ! (not) and parentheses. it's giving algebra class but slay 🧮
  • -m | -manual — only tests with /manual will be run. manual mode girlies rise 🙋‍♀️
  • -match:<file> — hand it a file specifying tests that can be run. it's the inverse of -exclude (iconic duo fr)
  • -noshell — any tests which contain shell actions will not be run
  • -shell — only tests which contain shell actions will be run 🐚
  • -status:<value>,... — select tests according to their result in an earlier run. value can be one or more of the values below, separated by commas:
    • pass — tests that passed ✨
    • fail — tests that failed 😭
    • notRun — tests that have not been run
    • error — tests that could not be run because of errors, or tests that were ignored 💀

✨ Test Mode Options ✨

so every test is a series of steps, and we call those steps actions. the jtreg harness ships with different modes, and the mode decides which JVM gets used to execute each action. the default? brand new JVM for every single action. ok periodt.

  • -avm | -agentvm | -s | -svm | -samevm — execute each action using a pool of reusable JVMs, except when an action specifies otherwise. it's giving good performance and reasonable isolation between actions: if a JVM can be reset to a standard state after it's been used, it gets returned to the pool for reuse; otherwise it's discarded and replaced if and when necessary. this mode is generally recommended for all use, no cap 🫶. the JDK to use can be specified with -testjdk or -jdk, except for @compile actions, which use -compilejdk or -jdk. if values are not provided, the environment variable JAVA_HOME is used.
  • -ovm | -othervm — 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 math is mathing, bestie 💸). the JDK to use can be specified with -testjdk or -jdk, except for @compile actions, which use -compilejdk or -jdk. if values are not provided, the environment variable JAVA_HOME is used.

by default, tests will be run using the default JVM in the test JDK. you can pass all applicable JVM options via -vmoption; and 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 java -help or java -X. if an option is not applicable to a particular platform or JDK release, it will be rejected. cold. ❄️

  • --add-modules <module>(,<module>)* — root modules to resolve in addition to the initial module
  • -agentlib:<libname><[=<options>] — load native agent library
  • -agentpath:<pathname><[=<options>] — load native agent library by full pathname
  • -classic | -green | -native | -hotspot | -client | -server | -d32 | -d64 — VM Options
  • -compilejdk:<java.home> — compile all tests using the specified JDK. if not specified, tests are compiled with the JDK used to run the tests. see also -jdk. for example, -jdk:/usr/local/java/jdk1.5/solaris-sparc
  • -cpa:<path> | -classpathappend:<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 CLASSPATH would be necessary: -cpa:/usr/local/java/swing-1.0.3/swingall.jar
  • -D<name>=<value> — define a system property
  • -debug:<option>... — use this to specify VM options to attach a debugger to a VM running a test. it's similar to -vmoptions except that it is not used when starting VMs used to query the properties of that VM. any timeout for a test is automatically disabled when this option is used 🛑⏰. see also -javaoptions and -vmoptions.
  • -enableassertions | --enableassertions:* | -ea | --ea:* | -disableassertions | --disableassertions:* | -da | --da:* — enable or disable assertions
  • -enablesystemassertions | -esa | -disablesystemassertions | -dsa — enable or disable system assertions
  • -javaagent:<jarpath><[=<options>] — load Java programming language agent
  • -javacoption:<option> — additional compiler option. you can give this option multiple times. any embedded filenames must be given with absolute paths.
  • -javacoptions:<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 -javacoption options instead. ⚠️
  • -javaoption:<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 -vmoption.
  • -javaoptions:<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. see also -vmoptions.
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 -javaoption options instead. ⚠️
  • -jdk:<java.home> | -testjdk:<java.home> — run all tests using the specified JDK. for example, -jdk:/usr/local/java/jdk1.5/solaris-sparc
  • -jit — enable the JIT for the tests. the JIT is turned on by default.
  • --limit-modules <module>(,<module>)* — limit the universe of observable modules
  • -nojit — disable the JIT for the tests.
  • --patch-module <module>=<path> — specify classes to override module classes
  • -vmoption:<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 -javaoption.
  • -vmoptions:<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. this option will be used when compiling and running classes. see also -javaoptions.
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 -vmption options instead. ⚠️
  • -X* — non-standard VM Options.
  • -Xbootclasspath:<path> — set search path for bootstrap classes and resources
  • -Xbootclasspath/a:<path> — append to end of bootstrap class path
  • -Xbootclasspath/p:<path> — prepend in front of bootstrap class path
  • -Xint* | -Xmixed* | -Xcomp* — non-standard VM Options
  • -XX* | -Xms* | -Xmx* — non-standard VM Options

✨ Tests ✨

Specifying collections of tests. 🧪

  • Tests — Specifying collections of tests.
  • 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. sneaky little escape hatch, love that for us 🙈

Tests

Specifying collections of tests.

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 (that is, 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. ok careful bestie, spacing matters here ✋

Summary

the following kinds of arguments can be used to specify tests to be executed. in these examples, square brackets are used to indicate optional parts.

  • directory — all tests found in and under the given directory.
  • file[#id][?string] — bestie, this one's the multitasker 💅. Give it just a file and you get every single test in that file — because yes, one file can hold a whole squad of tests, as long as each test description sits in its own separate comment block. Throw in an id and it narrows down to exactly that one test, no cap.

And then there's ?string 🦋 — if you tack it on, that string gets handed off to the test so it can filter which parts of itself actually run. Typically the string is the name of a method you want executed, iykyk. Oh, and if you give conflicting values for the string on a specific test? The last one you gave wins — no takebacks, periodt.

  • [path]:group-name — a whole group of tests, defined in the TEST.groups file sitting in the testsuite root directory. If you give a path, that's your testsuite root directory, queen ✨. If you don't give one, it defaults to the directory enclosing the current directory. It's giving "I'll find my own way home" energy.
  • @file — a file stuffed with values that get treated as if they were right there on the command-line. Sneaky, iconic, lowkey my fave 🎀.

Where is this thing even living, and what's it running on 🫶

Installed in /build/reproducible-path/jtreg8-8.3+1+ds1/build/images/jtreg/lib/jtreg.jar

Running on platform version 21.0.12.1 from /usr/lib/jvm/java-21-openjdk-amd64.

Built with Java(TM) 2 SDK, Version 21.0.12.1+1-1-deb13u1-De on Fri, 23 Oct 2026 12:27:33 +0200.

Then the receipts keep coming 💀 — JT Harness, version 6.0 ea b24 (January 25, 1970), %%PRODUCT_NAME_LONG%%, version %%PRODUCT_VERSION%% %%PRODUCT_MILESTONE%% %%PRODUCT_BUILDNUMBER%% (%%BUILD_DATE%%).

TestNG: testng.jar, guice.jar, jcommander.jar, slf4j-simple.jar, slf4j-api.jar

  • TestNG (testng.jar): version 7.5
  • TestNG (guice.jar): version 5.1.0
  • TestNG (jcommander.jar): version unknown
  • TestNG (slf4j-simple.jar): version 1.7.32
  • TestNG (slf4j-api.jar): version 1.7.32

JUnit: junit-platform-console-standalone.jar

JUnit: version unknown

🌈 SEE ALSO 🌈

Okay so the full✨deluxe✨documentation for jtreg lives as a Texinfo manual — the main character of docs, honestly 👑. And if the info and jtreg programs are properly installed at your site, then this command:

info jtreg

should give you access to the complete manual. Go get your girl 🦋💖.

That's a wrap, bestie! This gorgeous little page is from jtreg 8.3-src+1, dated October 2026, and yes she is still out here being section JTREG(1) like the icon she is. Slay, read your man pages, stay curious 🌸💅✨

📦 where this page comes from