From 8282918eac3d124b76d2f6a6d4197e277141184b Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sun, 12 Aug 2018 12:44:26 +0200 Subject: [PATCH] Polishing Issue: #1498 --- .../asciidoc/user-guide/running-tests.adoc | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index 849f92cc3fe3..313ef93b3e43 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -543,9 +543,9 @@ link:https://ant.apache.org/manual/Tasks/junitlauncher.html[`junitlauncher` task [[running-tests-console-launcher]] === 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. +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 `junit-platform-console-standalone-{platform-version}.jar` with all dependencies included is published in the central Maven repository under the @@ -598,31 +598,33 @@ is `0`. include::{consoleLauncherOptionsFile}[] ---- -==== @-files +[[running-tests-console-launcher-argument-files]] +==== 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. -Starting from v5.3-RC1, the `ConsoleLauncher` supports "argument files" or "@-files". -Argument files are files that themselves contain arguments to the command. -When the underlying https://github.com/remkop/picocli[picocli] command line parser -encounters an argument beginning with the character `@`, it expands the contents of that -file into the argument list. +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 https://github.com/remkop/picocli[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 space-separated or newline-separated. -If an argument contains embedded whitespace, put the whole argument in double or single -quotes (`"-f=My Files\Stuff.java"`). +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 file does not exist, or cannot be read, then the argument will be treated -literally, and not removed. This will likely result in an "unmatched argument" error -message. You can troubleshoot by executing the command with system property -`picocli.trace` set to `DEBUG`. +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. +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, e.g. '@@somearg' will become '@somearg' and not be subject -to expansion. +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. [[running-tests-junit-platform-runner]]