Documentation: confusion between `--junit-xml` and `--junitxml`

[soxofaan]

The docs and cli help are a bit confusing around the --junitxml/--junit-xml cli option (and probably some comparable options).

pytest --help only mentions --junit-xml=path (e.g. also see https://docs.pytest.org/en/7.1.x/reference/reference.html#command-line-flags):

  --junit-xml=path      Create junit-xml style report file at given path

However, most examples in the docs (and mosts tests) use --junitxml, e.g. https://github.com/pytest-dev/pytest/blob/0ded3297a9749aabad7d3c2447dce98321741dda/doc/en/how-to/output.rst#creating-junitxml-format-files :

To create result files which can be read by Jenkins_ or other Continuous
integration servers, use this invocation:

.. code-block:: bash

    pytest --junitxml=path

to create an XML file at ``path``.

This was quite confusing to me as it seemed there was a typo somewhere and I lost time just to figure out that they are aliases actually:

pytest/src/_pytest/junitxml.py

Lines 384 to 386 in 0ded329

	group.addoption(
	"--junitxml",
	"--junit-xml",

Wouldn't it be better to stick to one of the two everywhere or at least more explicitly mention that they are aliases?

[RonnyPfannschmidt]

Thanks for bringing this up, this was a oversight when unifying the argument names while leaving the old ones around

[yash2189]

Hello , I would like to give a try on this please? @RonnyPfannschmidt
Would it be a good idea to mention that these are aliases?

[soxofaan]

did some more digging and apparently DropShorterLongHelpFormatter is intentionally hiding aliases

pytest/src/_pytest/config/argparsing.py

Lines 489 to 494 in 0ded329

	class DropShorterLongHelpFormatter(argparse.HelpFormatter):
	"""Shorten help for long options that differ only in extra hyphens.
	- Collapse **long** options that are the same except for extra hyphens.
	- Shortcut if there are only two options and one of them is a short one.
	- Cache result on the action object as this is called at least 2 times.

e.g.

default argparse behavior shows both aliases

>>> import argparse
>>> cli = argparse.ArgumentParser()
>>> cli.add_argument("--foo-bar", "--foobar", help="Enable the foo bar")
>>> cli.print_help()
usage: [-h] [--foo-bar FOO_BAR]

optional arguments:
  -h, --help            show this help message and exit
  --foo-bar FOO_BAR, --foobar FOO_BAR
                        Enable the foo bar

with DropShorterLongHelpFormatter, only the longest alias is shown:

>>> import argparse
>>> from _pytest.config.argparsing import DropShorterLongHelpFormatter
>>> cli = argparse.ArgumentParser(formatter_class=DropShorterLongHelpFormatter)
>>> cli.add_argument("--foo-bar", "--foobar", help="Enable the foo bar")
>>> cli.print_help()
usage: [-h] [--foo-bar FOO_BAR]

optional arguments:
  -h, --help         show this help message and exit
  --foo-bar=FOO_BAR  Enable the foo bar

[The-Compiler]

Looks like that's coming from some 10 years ago here: 007a77c.

I'm not sure if it's worth the breakage to deprecate/remove the --nohyphen aliases, but we should certainly update the docs to only use the "newer" versions shown in the --help.