4.3. Console Launcher

The [ConsoleLauncher](https://junit.org/junit5/docs/current/api/org.junit.platform.console/org/junit/platform/console/ConsoleLauncher.html) 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 junit-platform-console-standalone-1.7.0.jar with all dependencies included is published in the Maven Central repository under the junit-platform-console-standalone directory. You can run the standalone ConsoleLauncher as shown below.

java -jar junit-platform-console-standalone-1.7.0.jar <[Options](#running-tests-console-launcher-options)>

Here’s an example of its output:

  1. ├─ JUnit Vintage
  2. │  └─ example.JUnit4Tests
  3. │     └─ standardJUnit4Test ✔
  4. └─ JUnit Jupiter
  5.    ├─ StandardTests
  6.    │  ├─ succeedingTest() ✔
  7.    │  └─ skippedTest() ↷ for demonstration purposes
  8.    └─ A special test case
  9.       ├─ Custom test name containing spaces ✔
  10.       ├─ ╯°□°)╯ ✔
  11.       └─ 😱 ✔
  13. Test run finished after 64 ms
  14. [         5 containers found      ]
  15. [         0 containers skipped    ]
  16. [         5 containers started    ]
  17. [         0 containers aborted    ]
  18. [         5 containers successful ]
  19. [         0 containers failed     ]
  20. [         6 tests found           ]
  21. [         1 tests skipped         ]
  22. [         5 tests started         ]
  23. [         0 tests aborted         ]
  24. [         5 tests successful      ]
  25. [         0 tests failed          ]
Exit Code
The ConsoleLauncher exits with a status code of 1 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. Otherwise the exit code is 0.

4.3.1. Options

  1. Usage: ConsoleLauncher [-h] [--disable-ansi-colors] [--disable-banner]
  2.                        [--fail-if-no-tests] [--scan-modules] [--scan-classpath[=PATH[;|:
  3.                        PATH...]]]... [--details=MODE] [--details-theme=THEME]
  4.                        [--reports-dir=DIR] [-c=CLASS]... [--config=KEY=VALUE]... [-cp=PATH
  5.                        [;|:PATH...]]... [-d=DIR]... [-e=ID]... [-E=ID]...
  6.                        [--exclude-package=PKG]... [-f=FILE]... [--include-package=PKG]...
  7.                        [-m=NAME]... [-n=PATTERN]... [-N=PATTERN]... [-o=NAME]...
  8.                        [-p=PKG]... [-r=RESOURCE]... [-t=TAG]... [-T=TAG]... [-u=URI]...
  9. Launches the JUnit Platform from the console.
  10.   -h, --help                 Display help information.
  11.       --disable-ansi-colors  Disable ANSI colors in output (not supported by all
  12.                                terminals).
  13.       --disable-banner       Disable print out of the welcome message.
  14.       --details=MODE         Select an output details mode for when tests are executed.
  15.                                Use one of: none, summary, flat, tree, verbose. If 'none'
  16.                                is selected, then only the summary and test failures are
  17.                                shown. Default: tree.
  18.       --details-theme=THEME  Select an output details tree theme for when tests are
  19.                                executed. Use one of: ascii, unicode. Default: unicode.
  20.       -cp, --classpath, --class-path=PATH[;|:PATH...]
  21.                              Provide additional classpath entries -- for example, for
  22.                                adding engines and their dependencies. This option can be
  23.                                repeated.
  24.       --fail-if-no-tests     Fail and return exit status code 2 if no tests are found.
  25.       --reports-dir=DIR      Enable report output into a specified local directory (will
  26.                                be created if it does not exist).
  27.       --scan-modules         EXPERIMENTAL: Scan all resolved modules for test discovery.
  28.   -o, --select-module=NAME   EXPERIMENTAL: Select single module for test discovery. This
  29.                                option can be repeated.
  30.       --scan-classpath, --scan-class-path[=PATH[;|:PATH...]]
  31.                              Scan all directories on the classpath or explicit classpath
  32.                                roots. Without arguments, only directories on the system
  33.                                classpath as well as additional classpath entries supplied
  34.                                via -cp (directories and JAR files) are scanned. Explicit
  35.                                classpath roots that are not on the classpath will be
  36.                                silently ignored. This option can be repeated.
  37.   -u, --select-uri=URI       Select a URI for test discovery. This option can be repeated.
  38.   -f, --select-file=FILE     Select a file for test discovery. This option can be
  39.                                repeated.
  40.   -d, --select-directory=DIR Select a directory for test discovery. This option can be
  41.                                repeated.
  42.   -p, --select-package=PKG   Select a package for test discovery. This option can be
  43.                                repeated.
  44.   -c, --select-class=CLASS   Select a class for test discovery. This option can be
  45.                                repeated.
  46.   -m, --select-method=NAME   Select a method for test discovery. This option can be
  47.                                repeated.
  48.   -r, --select-resource=RESOURCE
  49.                              Select a classpath resource for test discovery. This option
  50.                                can be repeated.
  51.   -n, --include-classname=PATTERN
  52.                              Provide a regular expression to include only classes whose
  53.                                fully qualified names match. To avoid loading classes
  54.                                unnecessarily, the default pattern only includes class
  55.                                names that begin with "Test" or end with "Test" or
  56.                                "Tests". When this option is repeated, all patterns will
  57.                                be combined using OR semantics. Default: [^(Test.*|.+[.$]
  58.                                Test.*|.*Tests?)$]
  59.   -N, --exclude-classname=PATTERN
  60.                              Provide a regular expression to exclude those classes whose
  61.                                fully qualified names match. When this option is repeated,
  62.                                all patterns will be combined using OR semantics.
  63.       --include-package=PKG  Provide a package to be included in the test run. This
  64.                                option can be repeated.
  65.       --exclude-package=PKG  Provide a package to be excluded from the test run. This
  66.                                option can be repeated.
  67.   -t, --include-tag=TAG      Provide a tag or tag expression to include only tests whose
  68.                                tags match. When this option is repeated, all patterns
  69.                                will be combined using OR semantics.
  70.   -T, --exclude-tag=TAG      Provide a tag or tag expression to exclude those tests whose
  71.                                tags match. When this option is repeated, all patterns
  72.                                will be combined using OR semantics.
  73.   -e, --include-engine=ID    Provide the ID of an engine to be included in the test run.
  74.                                This option can be repeated.
  75.   -E, --exclude-engine=ID    Provide the ID of an engine to be excluded from the test
  76.                                run. This option can be repeated.
  77.       --config=KEY=VALUE     Set a configuration parameter for test discovery and
  78.                                execution. This option can be repeated.

4.3.2. 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.

Since version 1.3, 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.