Issue a warning to prepare change of 'junit_family' default value

Fix #6179

Author: nicoddemus

changelog/6179.deprecation.rst

@@ -0,0 +1,7 @@
+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.
+
+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``.
+
+For more information, `see the docs <https://docs.pytest.org/en/latest/deprecations.html#junit-family-default-value-change-to-xunit2>`__.

doc/en/deprecations.rst

@@ -19,6 +19,24 @@ Below is a complete list of all pytest features which are considered deprecated.
 :class:`_pytest.warning_types.PytestWarning` or subclasses, which can be filtered using
 :ref:`standard warning filters <warnings>`.
 
+``junit_family`` default value change to "xunit2"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. 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.
+
+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``.
+
+In order to silence this warning, users just need to configure the ``junit_family`` option:
+
+.. code-block:: ini
+
+    [pytest]
+    junit_family=legacy
+
 
 ``funcargnames`` alias for ``fixturenames``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/_pytest/deprecated.py

@@ -34,3 +34,8 @@
     "Passing arguments to pytest.fixture() as positional arguments is deprecated - pass them "
     "as a keyword argument instead."
 )
+
+JUNIT_XML_DEFAULT_FAMILY = PytestDeprecationWarning(
+    "The 'junit_family' default value will change to 'xunit2' in pytest 6.0.\n"
+    "Add 'junit_family=legacy' to your pytest.ini file to silence this warning and make your suite compatible."
+)

src/_pytest/junitxml.py

@@ -19,8 +19,10 @@
 import py
 
 import pytest
+from _pytest import deprecated
 from _pytest import nodes
 from _pytest.config import filename_arg
+from _pytest.warnings import _issue_warning_captured
 
 
 class Junit(py.xml.Namespace):
@@ -421,23 +423,25 @@ def pytest_addoption(parser):
         default="total",
     )  # choices=['total', 'call'])
     parser.addini(
-        "junit_family",
-        "Emit XML for schema: one of legacy|xunit1|xunit2",
-        default="xunit1",
+        "junit_family", "Emit XML for schema: one of legacy|xunit1|xunit2", default=None
     )
 
 
 def pytest_configure(config):
     xmlpath = config.option.xmlpath
     # prevent opening xmllog on slave nodes (xdist)
     if xmlpath and not hasattr(config, "slaveinput"):
+        junit_family = config.getini("junit_family")
+        if not junit_family:
+            _issue_warning_captured(deprecated.JUNIT_XML_DEFAULT_FAMILY, config.hook, 2)
+            junit_family = "xunit1"
         config._xml = LogXML(
             xmlpath,
             config.option.junitprefix,
             config.getini("junit_suite_name"),
             config.getini("junit_logging"),
             config.getini("junit_duration_report"),
-            config.getini("junit_family"),
+            junit_family,
             config.getini("junit_log_passing_tests"),
         )
         config.pluginmanager.register(config._xml)

testing/deprecated_test.py

@@ -44,3 +44,32 @@ def test_external_plugins_integrated(testdir, plugin):
 
     with pytest.warns(pytest.PytestConfigWarning):
         testdir.parseconfig("-p", plugin)
+
+
+@pytest.mark.parametrize("junit_family", [None, "legacy", "xunit2"])
+def test_warn_about_imminent_junit_family_default_change(testdir, junit_family):
+    """Show a warning if junit_family is not defined and --junitxml is used (#6179)"""
+    testdir.makepyfile(
+        """
+        def test_foo():
+            pass
+    """
+    )
+    if junit_family:
+        testdir.makeini(
+            """
+            [pytest]
+            junit_family={junit_family}
+        """.format(
+                junit_family=junit_family
+            )
+        )
+
+    result = testdir.runpytest("--junit-xml=foo.xml")
+    warning_msg = (
+        "*PytestDeprecationWarning: The 'junit_family' default value will change*"
+    )
+    if junit_family:
+        result.stdout.no_fnmatch_line(warning_msg)
+    else:
+        result.stdout.fnmatch_lines([warning_msg])