Skip to content

Commit

Permalink
Polishing
Browse files Browse the repository at this point in the history
  • Loading branch information
sbrannen authored and Cody Moore committed Sep 17, 2018
1 parent b243236 commit bb80f74
Showing 1 changed file with 23 additions and 21 deletions.
44 changes: 23 additions & 21 deletions documentation/src/docs/asciidoc/user-guide/running-tests.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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]]
Expand Down

0 comments on commit bb80f74

Please sign in to comment.