Skip to content

Commit

Permalink
Improve docs about junit_family warning message
Browse files Browse the repository at this point in the history
From discussion in pytest-dev#6178
  • Loading branch information
nicoddemus committed May 2, 2020
1 parent 5afa871 commit 095a195
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 10 deletions.
32 changes: 25 additions & 7 deletions doc/en/deprecations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -80,22 +80,40 @@ Note that ``from_parent`` should only be called with keyword arguments for the p

.. deprecated:: 5.2

The default value of ``junit_family`` option will change to ``xunit2`` in pytest 6.0, given
that this is the version supported by default in modern tools that manipulate this type of file.
The default value of ``junit_family`` option will change to ``xunit2`` in pytest 6.0, which
is an update of the old ``xunit1`` format and is supported by default in modern tools
that manipulate this type of file (for example, Jenkins, Azure Pipelines, etc.).

In order to smooth the transition, pytest will issue a warning in case the ``--junitxml`` option
is given in the command line but ``junit_family`` is not explicitly configured in ``pytest.ini``::
Users are recommended to try the new ``xunit2`` format and see if their tooling that consumes the JUnit
XML file supports it.

PytestDeprecationWarning: The 'junit_family' default value will change to 'xunit2' in pytest 6.0.
Add 'junit_family=legacy' to your pytest.ini file to silence this warning and make your suite compatible.
To use the new format, update your ``pytest.ini``:

In order to silence this warning, users just need to configure the ``junit_family`` option explicitly:
.. code-block:: ini
[pytest]
junit_family=xunit2
If you discover that your tooling does not support the new format, and want to keep using the
legacy version, set the option to ``legacy`` instead:

.. code-block:: ini
[pytest]
junit_family=legacy
By using ``legacy`` you will keep using the legacy/xunit1 format when upgrading to
pytest 6.0, where the default format will be ``xunit2``.

In order to let users know about the transition, pytest will issue a warning in case
the ``--junitxml`` option is given in the command line but ``junit_family`` is not explicitly
configured in ``pytest.ini``.

Services known to support the ``xunit2`` format:

* `Jenkins <https://www.jenkins.io/>`__ with the `JUnit <https://plugins.jenkins.io/junit>`__ plugin.
* `Azure Pipelines <https://azure.microsoft.com/en-us/services/devops/pipelines>`__.


``funcargnames`` alias for ``fixturenames``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
6 changes: 3 additions & 3 deletions src/_pytest/deprecated.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,9 @@
)

JUNIT_XML_DEFAULT_FAMILY = PytestDeprecationWarning(
"The 'junit_family' default value will change to 'xunit2' in pytest 6.0.\n"
"Add 'junit_family=xunit1' to your pytest.ini file to keep the current format "
"in future versions of pytest and silence this warning."
"The 'junit_family' default value will change to 'xunit2' in pytest 6.0. See:\n"
" https://docs.pytest.org/en/latest/deprecations.html#junit-family-default-value-change-to-xunit2\n"
"for more information."
)

NO_PRINT_LOGS = PytestDeprecationWarning(
Expand Down

0 comments on commit 095a195

Please sign in to comment.