Introduce record_testsuite_property fixture

This exposes the functionality introduced in fa6acdc as a session-scoped fixture.

Plugins that want to remain compatible with the `xunit2`
standard should use this fixture instead of `record_property`.

Fix pytest-dev#5202

Author: nicoddemus

changelog/5202.feature.rst

@@ -0,0 +1,5 @@
+New ``record_testsuite_property`` session-scoped fixture allows users to log ``<property>`` tags at the ``testsuite``
+level with the ``junitxml`` plugin.
+
+The generated XML is compatible with the latest xunit standard, contrary to
+the properties recorded by ``record_property`` and ``record_xml_attribute``.

doc/en/reference.rst

@@ -424,6 +424,14 @@ record_property
 
 .. autofunction:: _pytest.junitxml.record_property()
 
+
+record_testsuite_property
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`record_testsuite_property example`.
+
+.. autofunction:: _pytest.junitxml.record_testsuite_property()
+
 caplog
 ~~~~~~
 

doc/en/usage.rst

@@ -522,9 +522,7 @@ Will result in:
 
 .. warning::
 
-    ``record_property`` is an experimental feature and may change in the future.
-
-    Also please note that using this feature will break any schema verification.
+    Please note that using this feature will break schema verifications for the latest JUnitXML schema.
     This might be a problem when used with some CI servers.
 
 record_xml_attribute
@@ -587,32 +585,31 @@ Instead, this will add an attribute ``assertions="REQ-1234"`` inside the generat
             </xs:complexType>
         </xs:element>
 
-LogXML: add_global_property
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. warning::
 
-.. versionadded:: 3.0
+    Please note that using this feature will break schema verifications for the latest JUnitXML schema.
+    This might be a problem when used with some CI servers.
 
-If you want to add a properties node in the testsuite level, which may contains properties that are relevant
-to all testcases you can use ``LogXML.add_global_properties``
 
-.. code-block:: python
+.. _record_testsuite_property example:
 
-    import pytest
+record_testsuite_property
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. versionadded:: 4.5
 
-    @pytest.fixture(scope="session")
-    def log_global_env_facts(f):
+If you want to add a properties node at the ``testsuite`` level, which may contains properties that are relevant
+to all tests, you can use the ``record_testsuite_property`` session-scoped fixture:
 
-        if pytest.config.pluginmanager.hasplugin("junitxml"):
-            my_junit = getattr(pytest.config, "_xml", None)
+.. code-block:: python
 
-        my_junit.add_global_property("ARCH", "PPC")
-        my_junit.add_global_property("STORAGE_TYPE", "CEPH")
+    import pytest
 
 
-    @pytest.mark.usefixtures(log_global_env_facts.__name__)
-    def start_and_prepare_env():
-        pass
+    @pytest.fixture(scope="session", autouse=True)
+    def log_global_env_facts(record_testsuite_property):
+        record_testsuite_property("ARCH", "PPC")
+        record_testsuite_property("STORAGE_TYPE", "CEPH")
 
 
     class TestMe(object):
@@ -623,19 +620,17 @@ This will add a property node below the testsuite node to the generated xml:
 
 .. code-block:: xml
 
-    <testsuite errors="0" failures="0" name="pytest" skips="0" tests="1" time="0.006">
+    <testsuite errors="0" failures="0" name="pytest" skipped="0" tests="1" time="0.006">
       <properties>
         <property name="ARCH" value="PPC"/>
         <property name="STORAGE_TYPE" value="CEPH"/>
       </properties>
       <testcase classname="test_me.TestMe" file="test_me.py" line="16" name="test_foo" time="0.000243663787842"/>
     </testsuite>
 
-.. warning::
 
-    This is an experimental feature, and its interface might be replaced
-    by something more powerful and general in future versions. The
-    functionality per-se will be kept.
+The generated XML is compatible with the latest ``xunit`` standard.
+
 
 Creating resultlog format files
 ----------------------------------------------------

src/_pytest/junitxml.py

@@ -334,6 +334,30 @@ def add_attr_noop(name, value):
     return attr_func
 
 
+@pytest.fixture(scope="session")
+def record_testsuite_property(request):
+    """
+    Records a new ``<property>`` tag as child of the root ``<testsuite>``. This is suitable to
+    writing global information regarding the entire test suite, and is compatible with ``xunit2`` JUnit family.
+
+    This is a ``session``-scoped fixture which returns a callable with ``(name, value)``. Example:
+
+    .. code-block:: python
+
+        def test_foo(record_testsuite_property):
+            record_testsuite_property("ARCH", "PPC")
+            record_testsuite_property("STORAGE_TYPE", "CEPH")
+    """
+
+    def record_func(name, value):
+        """noop function in case --junitxml was not passed in the command-line"""
+
+    xml = getattr(request.config, "_xml", None)
+    if xml is not None:
+        record_func = xml.add_global_property  # noqa
+    return record_func
+
+
 def pytest_addoption(parser):
     group = parser.getgroup("terminal reporting")
     group.addoption(
@@ -433,6 +457,7 @@ def __init__(
         self.node_reporters = {}  # nodeid -> _NodeReporter
         self.node_reporters_ordered = []
         self.global_properties = []
+
         # List of reports that failed on call but teardown is pending.
         self.open_reports = []
         self.cnt_double_fail_tests = 0

testing/test_junitxml.py

@@ -1221,6 +1221,37 @@ class Report(BaseReport):
     ), "The URL did not get written to the xml"
 
 
+def test_record_testsuite_property(testdir):
+    testdir.makepyfile(
+        """
+        def test_func1(record_testsuite_property):
+            record_testsuite_property("stats", "all good")
+
+        def test_func2(record_testsuite_property):
+            record_testsuite_property("stats", "almost good")
+    """
+    )
+    result, dom = runandparse(testdir)
+    assert result.ret == 0
+    node = dom.find_first_by_tag("testsuite")
+    properties_node = node.find_first_by_tag("properties")
+    p1_node = properties_node.find_nth_by_tag("property", 0)
+    p2_node = properties_node.find_nth_by_tag("property", 1)
+    p1_node.assert_attr(name="stats", value="all good")
+    p2_node.assert_attr(name="stats", value="almost good")
+
+
+def test_record_testsuite_property_junit_disabled(testdir):
+    testdir.makepyfile(
+        """
+        def test_func1(record_testsuite_property):
+            record_testsuite_property("stats", "all good")
+    """
+    )
+    result = testdir.runpytest()
+    assert result.ret == 0
+
+
 @pytest.mark.parametrize("suite_name", ["my_suite", ""])
 def test_set_suite_name(testdir, suite_name):
     if suite_name: