Explain the relationship between --format and --out

[Amoifr]

Fixes #1409, scoped to the two points @acoulton reopened it for: the option help and the error message.

Reproducing it first turned up something the issue does not say. A single --out is not applied to the first formatter, it is applied to every one, through setFormattersParameter(). The index pairing only starts once there are two or more --out. So in the reported command the console formatter receives the directory meant for junit, and complains about a path the user never intended for it.

$ behat --format=pretty --format=junit --out=some/dir

  Filename expected as `output_path` parameter, but got `/app/some/dir`.

The message now says where that directory came from, and adopts the wording the two sibling factories already use:

  A file name expected for the `output_path` option, but a directory was given.
  Note that a single `--out` is applied to every `--format`.
  Pass one `--out` per `--format`, in the same order, to send them to different places.

It is split over three lines because the Symfony error box does not wrap: as a single sentence it rendered as a box 230 characters wide. The path is no longer interpolated, matching FileOutputFactory and FilesystemOutputFactory, and it is still on the exception through getPath().

The help of --out now states the rule, and --format points at it, which is what @stof asked for:

  -f, --format=FORMAT   ...
                        You can use multiple formats at the same time. See --out
                        to send each of them to a different place.
  -o, --out=OUT         Write format output to a file/directory instead of
                        STDOUT (output_path). A single --out is applied to every
                        --format. To send formats to different places, pass one
                        --out per --format, in the same order, using std
                        for those that stay on STDOUT.
                        This option is mandatory for the junit formatter.

A scenario in features/multiple_formats.feature pins the message, using the reported command. Worth knowing for whoever reads it: -f pretty -f progress --out=file does not fail, because two console formatters both write to the file and the second simply overwrites the first. Only mixing a console formatter with junit trips it, since junit creates the directory that the console formatter then chokes on.

One thing I left alone

The symmetric case is worse and I did not touch it, since it is behaviour rather than wording:

$ behat --format=junit --format=pretty --out=report.xml

junit creates a directory named report.xml containing default.xml, and then pretty fails saying a file name was expected. The user gave a file name, so the message contradicts what they typed. Happy to open a separate issue if you think that deserves one.

[acoulton]

Thanks @Amoifr

On this point:

junit creates a directory named report.xml containing default.xml, and then pretty fails saying a file name was expected. The user gave a file name, so the message contradicts what they typed. Happy to open a separate issue if you think that deserves one.

I think we leave that. Although it could be confusing, the user didn't necessarily give a file name (report.xml is a valid directory name, even if it looks like a file). The underlying issue is the design of the --out API and we could get into quite a lot of complexity trying to work out the most meaningful exception message for every possible usage.

The main thing is that the documentation of the --out parameter is now much clearer, so if users do have errors that should allow them to understand what's gone wrong.