This version is still in development and is not considered stable yet.
For the latest stable version, please use JUnit 6.0.1!

Console Launcher

The ConsoleLauncher is a command-line Java application that lets you launch the JUnit Platform from the console. For example, it can be used to run JUnit Vintage and JUnit Jupiter tests and print test execution results to the console.

An executable Fat JAR (junit-platform-console-standalone-6.0.2-SNAPSHOT.jar) that contains the contents of all of its dependencies is published in the Maven Central repository under the junit-platform-console-standalone directory. It contains the contents of the following artifacts:

  • junit:junit:4.13.2

  • org.apiguardian:apiguardian-api:1.1.2

  • org.hamcrest:hamcrest-core:1.3

  • org.junit.jupiter:junit-jupiter-api:6.0.2-SNAPSHOT

  • org.junit.jupiter:junit-jupiter-engine:6.0.2-SNAPSHOT

  • org.junit.jupiter:junit-jupiter-params:6.0.2-SNAPSHOT

  • org.junit.platform:junit-platform-commons:6.0.2-SNAPSHOT

  • org.junit.platform:junit-platform-console:6.0.2-SNAPSHOT

  • org.junit.platform:junit-platform-engine:6.0.2-SNAPSHOT

  • org.junit.platform:junit-platform-launcher:6.0.2-SNAPSHOT

  • org.junit.platform:junit-platform-reporting:6.0.2-SNAPSHOT

  • org.junit.platform:junit-platform-suite-api:6.0.2-SNAPSHOT

  • org.junit.platform:junit-platform-suite-engine:6.0.2-SNAPSHOT

  • org.junit.vintage:junit-vintage-engine:6.0.2-SNAPSHOT

  • org.opentest4j.reporting:open-test-reporting-tooling-spi:0.2.4

  • org.opentest4j:opentest4j:1.3.0

Since the junit-platform-console-standalone JAR contains the contents of all of its dependencies, its Maven POM does not declare any dependencies.

Furthermore, it is not very likely that you would need to include a dependency on the junit-platform-console-standalone artifact in your project’s Maven POM or Gradle build script. On the contrary, the executable junit-platform-console-standalone JAR is typically invoked directly from the command line or a shell script without a build script.

If you need to declare dependencies in your build script on some of the artifacts contained in the junit-platform-console-standalone artifact, you should declare dependencies only on the JUnit artifacts that are used in your project. To simplify dependency management of JUnit artifacts in your build, you may wish to use the junit-jupiter aggregator artifact or junit-bom. See Dependency Metadata for details.

You can run the standalone ConsoleLauncher as shown below.

$ java -jar junit-platform-console-standalone-6.0.2-SNAPSHOT.jar execute <OPTIONS>

├─ JUnit Vintage
│  └─ example.JUnit4Tests
│     └─ standardJUnit4Test ✔
└─ JUnit Jupiter
   ├─ StandardTests
   │  ├─ succeedingTest() ✔
   │  └─ skippedTest() ↷ for demonstration purposes
   └─ A special test case
      ├─ Custom test name containing spaces ✔
      ├─ ╯°□°)╯ ✔
      └─ 😱 ✔

Test run finished after 64 ms
[         5 containers found      ]
[         0 containers skipped    ]
[         5 containers started    ]
[         0 containers aborted    ]
[         5 containers successful ]
[         0 containers failed     ]
[         6 tests found           ]
[         1 tests skipped         ]
[         5 tests started         ]
[         0 tests aborted         ]
[         5 tests successful      ]
[         0 tests failed          ]

You can also run the standalone ConsoleLauncher as shown below (for example, to include all jars in a directory):

$ java -cp classes:testlib/* org.junit.platform.console.ConsoleLauncher <OPTIONS>

Subcommands and Options

The ConsoleLauncher provides the following subcommands:

Usage: junit [OPTIONS] COMMAND
Launches the JUnit Platform for test discovery and execution.
      [@<filename>...]   One or more argument files containing options.
  -h, --help             Display help information.
      --version          Display version information.
      --disable-ansi-colors
                         Disable ANSI colors in output (not supported by all terminals).
Commands:
  discover  Discover tests
  execute   Execute tests
  engines   List available test engines

For more information, please refer to the JUnit User Guide at
https://docs.junit.org/snapshot/user-guide/

Discovering tests

Usage: junit discover [OPTIONS]
Discover tests
      [@<filename>...]       One or more argument files containing options.
      --disable-ansi-colors  Disable ANSI colors in output (not supported by all terminals).
      --disable-banner       Disable print out of the welcome message.
  -h, --help                 Display help information.
      --version              Display version information.

SELECTORS

      --scan-classpath, --scan-class-path[=PATH]
                             Scan all directories on the classpath or explicit classpath
                               roots. Without arguments, only directories on the system
                               classpath as well as additional classpath entries supplied via
                               -cp (directories and JAR files) are scanned. Explicit classpath
                               roots that are not on the classpath will be silently ignored.
                               This option can be repeated.
      --scan-modules         Scan all resolved modules for test discovery.
  -u, --select-uri=URI...    Select a URI for test discovery. This option can be repeated.
  -f, --select-file=FILE...  Select a file for test discovery. The line and column numbers can
                               be provided as URI query parameters (e.g. foo.txt?
                               line=12&column=34). This option can be repeated.
  -d, --select-directory=DIR...
                             Select a directory for test discovery. This option can be
                               repeated.
  -o, --select-module=NAME...
                             Select single module for test discovery. This option can be
                               repeated.
  -p, --select-package=PKG...
                             Select a package for test discovery. This option can be repeated.
  -c, --select-class=CLASS...
                             Select a class for test discovery. This option can be repeated.
  -m, --select-method=NAME...
                             Select a method for test discovery. This option can be repeated.
  -r, --select-resource=RESOURCE...
                             Select a classpath resource for test discovery. This option can
                               be repeated.
  -i, --select-iteration=PREFIX:VALUE[INDEX(..INDEX)?(,INDEX(..INDEX)?)*]...
                             Select iterations for test discovery via a prefixed identifier
                               and a list of indexes or index ranges (e.g. method:com.acme.
                               Foo#m()[1..2] selects the first and second iteration of the m()
                               method in the com.acme.Foo class). This option can be repeated.
      --uid, --select-unique-id=UNIQUE-ID...
                             Select a unique id for test discovery. This option can be
                               repeated.
      --select=PREFIX:VALUE...
                             Select via a prefixed identifier (e.g. method:com.acme.Foo#m
                               selects the m() method in the com.acme.Foo class). This option
                               can be repeated.

  For more information on selectors including syntax examples, see
  https://docs.junit.org/snapshot/user-guide/#running-tests-discovery-selectors

FILTERS

  -n, --include-classname=PATTERN
                             Provide a regular expression to include only classes whose fully
                               qualified names match. To avoid loading classes unnecessarily,
                               the default pattern only includes class names that begin with
                               "Test" or end with "Test" or "Tests". When this option is
                               repeated, all patterns will be combined using OR semantics.
                               Default: ^(Test.*|.+[.$]Test.*|.*Tests?)$
  -N, --exclude-classname=PATTERN
                             Provide a regular expression to exclude those classes whose fully
                               qualified names match. When this option is repeated, all
                               patterns will be combined using OR semantics.
      --include-package=PKG  Provide a package to be included in the test run. This option can
                               be repeated.
      --exclude-package=PKG  Provide a package to be excluded from the test run. This option
                               can be repeated.
      --include-methodname=PATTERN
                             Provide a regular expression to include only methods whose fully
                               qualified names without parameters match. When this option is
                               repeated, all patterns will be combined using OR semantics.
      --exclude-methodname=PATTERN
                             Provide a regular expression to exclude those methods whose fully
                               qualified names without parameters match. When this option is
                               repeated, all patterns will be combined using OR semantics.
  -t, --include-tag=TAG      Provide a tag or tag expression to include only tests whose tags
                               match. When this option is repeated, all patterns will be
                               combined using OR semantics.
  -T, --exclude-tag=TAG      Provide a tag or tag expression to exclude those tests whose tags
                               match. When this option is repeated, all patterns will be
                               combined using OR semantics.
  -e, --include-engine=ID    Provide the ID of an engine to be included in the test run. This
                               option can be repeated.
  -E, --exclude-engine=ID    Provide the ID of an engine to be excluded from the test run.
                               This option can be repeated.

RUNTIME CONFIGURATION

      -cp, --classpath, --class-path=PATH
                             Provide additional classpath entries -- for example, for adding
                               engines and their dependencies. This option can be repeated.
      --config-resource=PATH Set configuration parameters for test discovery and execution via
                               a classpath resource. This option can be repeated.
      --config=KEY=VALUE     Set a configuration parameter for test discovery and execution.
                               This option can be repeated.

CONSOLE OUTPUT

      --color-palette=FILE   Specify a path to a properties file to customize ANSI style of
                               output (not supported by all terminals).
      --single-color         Style test output using only text attributes, no color (not
                               supported by all terminals).
      --details=MODE         Select an output details mode for when tests are executed. Use
                               one of: none, summary, flat, tree, verbose, testfeed. If 'none'
                               is selected, then only the summary and test failures are shown.
                               Default: tree.
      --details-theme=THEME  Select an output details tree theme for when tests are executed.
                               Use one of: ascii, unicode. Default is detected based on
                               default character encoding.
      --redirect-stdout=FILE Redirect test output to stdout to a file.
      --redirect-stderr=FILE Redirect test output to stderr to a file.

For more information, please refer to the JUnit User Guide at
https://docs.junit.org/snapshot/user-guide/

Executing tests

Exit Code
On successful runs, the ConsoleLauncher exits with a status code of 0. All non-zero codes indicate an error of some sort. For example, status code 1 is returned if any containers or tests failed. If no tests are discovered and the --fail-if-no-tests command-line option is supplied, the ConsoleLauncher exits with a status code of 2. Unexpected or invalid user input yields a status code of 3. An exit code of -1 indicates an unspecified error condition. 
Usage: junit execute [OPTIONS]
Execute tests
      [@<filename>...]       One or more argument files containing options.
      --disable-ansi-colors  Disable ANSI colors in output (not supported by all terminals).
      --disable-banner       Disable print out of the welcome message.
  -h, --help                 Display help information.
      --version              Display version information.

SELECTORS

      --scan-classpath, --scan-class-path[=PATH]
                             Scan all directories on the classpath or explicit classpath
                               roots. Without arguments, only directories on the system
                               classpath as well as additional classpath entries supplied via
                               -cp (directories and JAR files) are scanned. Explicit classpath
                               roots that are not on the classpath will be silently ignored.
                               This option can be repeated.
      --scan-modules         Scan all resolved modules for test discovery.
  -u, --select-uri=URI...    Select a URI for test discovery. This option can be repeated.
  -f, --select-file=FILE...  Select a file for test discovery. The line and column numbers can
                               be provided as URI query parameters (e.g. foo.txt?
                               line=12&column=34). This option can be repeated.
  -d, --select-directory=DIR...
                             Select a directory for test discovery. This option can be
                               repeated.
  -o, --select-module=NAME...
                             Select single module for test discovery. This option can be
                               repeated.
  -p, --select-package=PKG...
                             Select a package for test discovery. This option can be repeated.
  -c, --select-class=CLASS...
                             Select a class for test discovery. This option can be repeated.
  -m, --select-method=NAME...
                             Select a method for test discovery. This option can be repeated.
  -r, --select-resource=RESOURCE...
                             Select a classpath resource for test discovery. This option can
                               be repeated.
  -i, --select-iteration=PREFIX:VALUE[INDEX(..INDEX)?(,INDEX(..INDEX)?)*]...
                             Select iterations for test discovery via a prefixed identifier
                               and a list of indexes or index ranges (e.g. method:com.acme.
                               Foo#m()[1..2] selects the first and second iteration of the m()
                               method in the com.acme.Foo class). This option can be repeated.
      --uid, --select-unique-id=UNIQUE-ID...
                             Select a unique id for test discovery. This option can be
                               repeated.
      --select=PREFIX:VALUE...
                             Select via a prefixed identifier (e.g. method:com.acme.Foo#m
                               selects the m() method in the com.acme.Foo class). This option
                               can be repeated.

  For more information on selectors including syntax examples, see
  https://docs.junit.org/snapshot/user-guide/#running-tests-discovery-selectors

FILTERS

  -n, --include-classname=PATTERN
                             Provide a regular expression to include only classes whose fully
                               qualified names match. To avoid loading classes unnecessarily,
                               the default pattern only includes class names that begin with
                               "Test" or end with "Test" or "Tests". When this option is
                               repeated, all patterns will be combined using OR semantics.
                               Default: ^(Test.*|.+[.$]Test.*|.*Tests?)$
  -N, --exclude-classname=PATTERN
                             Provide a regular expression to exclude those classes whose fully
                               qualified names match. When this option is repeated, all
                               patterns will be combined using OR semantics.
      --include-package=PKG  Provide a package to be included in the test run. This option can
                               be repeated.
      --exclude-package=PKG  Provide a package to be excluded from the test run. This option
                               can be repeated.
      --include-methodname=PATTERN
                             Provide a regular expression to include only methods whose fully
                               qualified names without parameters match. When this option is
                               repeated, all patterns will be combined using OR semantics.
      --exclude-methodname=PATTERN
                             Provide a regular expression to exclude those methods whose fully
                               qualified names without parameters match. When this option is
                               repeated, all patterns will be combined using OR semantics.
  -t, --include-tag=TAG      Provide a tag or tag expression to include only tests whose tags
                               match. When this option is repeated, all patterns will be
                               combined using OR semantics.
  -T, --exclude-tag=TAG      Provide a tag or tag expression to exclude those tests whose tags
                               match. When this option is repeated, all patterns will be
                               combined using OR semantics.
  -e, --include-engine=ID    Provide the ID of an engine to be included in the test run. This
                               option can be repeated.
  -E, --exclude-engine=ID    Provide the ID of an engine to be excluded from the test run.
                               This option can be repeated.

RUNTIME CONFIGURATION

      -cp, --classpath, --class-path=PATH
                             Provide additional classpath entries -- for example, for adding
                               engines and their dependencies. This option can be repeated.
      --config-resource=PATH Set configuration parameters for test discovery and execution via
                               a classpath resource. This option can be repeated.
      --config=KEY=VALUE     Set a configuration parameter for test discovery and execution.
                               This option can be repeated.

CONSOLE OUTPUT

      --color-palette=FILE   Specify a path to a properties file to customize ANSI style of
                               output (not supported by all terminals).
      --single-color         Style test output using only text attributes, no color (not
                               supported by all terminals).
      --details=MODE         Select an output details mode for when tests are executed. Use
                               one of: none, summary, flat, tree, verbose, testfeed. If 'none'
                               is selected, then only the summary and test failures are shown.
                               Default: tree.
      --details-theme=THEME  Select an output details tree theme for when tests are executed.
                               Use one of: ascii, unicode. Default is detected based on
                               default character encoding.
      --redirect-stdout=FILE Redirect test output to stdout to a file.
      --redirect-stderr=FILE Redirect test output to stderr to a file.

REPORTING

      --fail-if-no-tests     Fail and return exit status code 2 if no tests are found.
      --fail-fast            Stops test execution after the first failed test.
      --reports-dir=DIR      Enable report output into a specified local directory (will be
                               created if it does not exist).

For more information, please refer to the JUnit User Guide at
https://docs.junit.org/snapshot/user-guide/

Listing test engines

Usage: junit engines [OPTIONS]
List available test engines
      [@<filename>...]   One or more argument files containing options.
      --disable-ansi-colors
                         Disable ANSI colors in output (not supported by all terminals).
      --disable-banner   Disable print out of the welcome message.
  -h, --help             Display help information.
      --version          Display version information.

For more information, please refer to the JUnit User Guide at
https://docs.junit.org/snapshot/user-guide/

Argument Files (@-files)

On some platforms you may run into system limitations on the length of a command line when creating a command line with lots of options or with long arguments.

The ConsoleLauncher supports argument files, also known as @-files. Argument files are files that themselves contain arguments to be passed to the command. When the underlying picocli command line parser encounters an argument beginning with the character @, it expands the contents of that file into the argument list.

The arguments within a file can be separated by spaces or newlines. If an argument contains embedded whitespace, the whole argument should be wrapped in double or single quotes — for example, "-f=My Files/Stuff.java".

If the argument file does not exist or cannot be read, the argument will be treated literally and will not be removed. This will likely result in an "unmatched argument" error message. You can troubleshoot such errors by executing the command with the picocli.trace system property set to DEBUG.

Multiple @-files may be specified on the command line. The specified path may be relative to the current directory or absolute.

You can pass a real parameter with an initial @ character by escaping it with an additional @ symbol. For example, @@somearg will become @somearg and will not be subject to expansion.

Redirecting Standard Output/Error to Files

You can redirect the System.out (stdout) and System.err (stderr) output streams to files using the --redirect-stdout and --redirect-stderr options:

$ java -jar junit-platform-console-standalone-6.0.2-SNAPSHOT.jar <OPTIONS> \
  --redirect-stdout=stdout.txt \
  --redirect-stderr=stderr.txt

If the --redirect-stdout and --redirect-stderr arguments point to the same file, both output streams will be redirected to that file.

The default charset is used for writing to the files.

Color Customization

The colors used in the output of the ConsoleLauncher can be customized. The option --single-color will apply a built-in monochrome style, while --color-palette will accept a properties file to override the ANSI SGR color styling. The properties file below demonstrates the default style:

SUCCESSFUL = 32
ABORTED = 33
FAILED = 31
SKIPPED = 35
CONTAINER = 35
TEST = 34
DYNAMIC = 35
REPORTED = 37