Improve docs and using warning system for record_xml_property fixture

CHANGELOG

@@ -138,8 +138,8 @@
 - fix issue890: changed extension of all documentation files from ``txt`` to
   ``rst``. Thanks to Abhijeet for the PR.
 
-- implement feature on issue951: support to log additional information on xml
-  output.
+- issue951: add new record_xml_property fixture, that supports logging
+  additional information on xml output. Thanks David Diaz for the PR.
 
 2.7.3 (compared to 2.7.2)
 -----------------------------

_pytest/junitxml.py

@@ -56,11 +56,17 @@ def bin_xml_escape(arg):
 
 @pytest.fixture
 def record_xml_property(request):
-    if hasattr(request.config, "_xml"):
-        return request.config._xml.record_property
-    def dummy(*args, **kwargs):
-        pass
-    return dummy
+    """Fixture that adds extra xml properties to the tag for the calling test.
+    The fixture is callable with (name, value), with value being automatically
+    xml-encoded.
+    """
+    def inner(name, value):
+        if hasattr(request.config, "_xml"):
+            request.config._xml.add_custom_property(name, value)
+        msg = 'record_xml_property is an experimental feature'
+        request.config.warn(code='C3', message=msg,
+                            fslocation=request.node.location[:2])
+    return inner
 
 def pytest_addoption(parser):
     group = parser.getgroup("terminal reporting")
@@ -99,7 +105,7 @@ class LogXML(object):
         self.failed = self.errors = 0
         self.custom_properties = {}
 
-    def record_property(self, name, value):
+    def add_custom_property(self, name, value):
         self.custom_properties[str(name)] = bin_xml_escape(str(value))
 
     def _opentestcase(self, report):

doc/en/usage.rst

@@ -153,18 +153,35 @@ integration servers, use this invocation::
 
 to create an XML file at ``path``.
 
-If you want to log additional information for a test, you can use
-record_property("key", value)::
+record_xml_property
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    import pytest
-    def test_function():
-        ...
-        pytest.record_property("example_key", 1)
-        ...
+.. versionadded:: 2.8
 
-Warning:
- - This is a preliminary feature.
- - Using this feature will break any schema verification.
+If you want to log additional information for a test, you can use the
+``record_xml_property`` fixture:
+
+.. code-block:: python
+
+    def test_function(record_xml_property):
+        record_xml_property("example_key", 1)
+        assert 0
+
+This will add an extra property ``example_key="1"`` to the generated
+``testcase`` tag:
+
+.. code-block:: xml
+
+    <testcase classname="test_function" example_key="1" file="test_function.py" line="0" name="test_function" time="0.0009">
+
+.. 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, however.
+
+    Also please note that using this feature will break any schema verification.
+    This might be a problem when used with some CI servers.
 
 Creating resultlog format files
 ----------------------------------------------------

testing/test_junitxml.py

@@ -557,7 +557,8 @@ def test_record_property(testdir):
         def test_record(record_xml_property):
             record_xml_property("foo", "<1");
     """)
-    result, dom = runandparse(testdir)
+    result, dom = runandparse(testdir, '-rw')
     node = dom.getElementsByTagName("testsuite")[0]
     tnode = node.getElementsByTagName("testcase")[0]
     assert_attr(tnode, foo="<1")
+    result.stdout.fnmatch_lines('*C3*test_record_property.py*experimental*')