e3.testsuite.report.xunit
=========================

.. py:module:: e3.testsuite.report.xunit

.. autoapi-nested-parse::

   Helpers to generate testsuite reports using the XUnit XML format.



Classes
-------

.. autoapisummary::

   e3.testsuite.report.xunit.XUnitImporter


Functions
---------

.. autoapisummary::

   e3.testsuite.report.xunit.add_time_attribute
   e3.testsuite.report.xunit.escape_text
   e3.testsuite.report.xunit.dump_xunit_report
   e3.testsuite.report.xunit.read_xfails_from_yaml
   e3.testsuite.report.xunit.convert_main


Module Contents
---------------

.. py:function:: add_time_attribute(elt: xml.etree.ElementTree.Element, duration: Optional[float]) -> None

   Optionally add a "time" attribute.

   If ``duration`` is a float, add the corresponding "time" attribute to
   ``elt``.


.. py:function:: escape_text(text: str) -> str

   Escape non-printable characters from a string.

   XML documents cannot contain null or control characters (except newlines).


.. py:function:: dump_xunit_report(name: str, index: e3.testsuite.report.index.ReportIndex, filename: str) -> None

   Dump a testsuite report to `filename` in the standard XUnit XML format.

   :param name: Name for the teststuite report.
   :param index: Report index for the testsuite results to report.
   :param filename: Name of the text file to write.
   :param duration: Optional number of seconds for the total duration of the
       testsuite run.


.. py:class:: XUnitImporter(index: e3.testsuite.report.index.ReportIndex, xfails: dict[str, str] | None = None)

   Helper class to import results in a xUnit report into a report index.


   .. py:attribute:: index


   .. py:attribute:: xfails


   .. py:method:: run(filename: str) -> None

      Read a xUnit report and import its results in the report index.

      :param filename: Filename for the XML file that contains the xUnit
          report.



   .. py:attribute:: SLUG_RE


   .. py:method:: slugify(name: str) -> str

      Normalize a string so that it is an acceptable test name component.

      :param name: Component (substring) for a name to turn into a test name
          that is acceptable for e3-testsuite.



   .. py:method:: get_unique_test_name(test_name: str) -> str

      Return a test name that is guaranteed to be unique.

      :param test_name: Candidate test name. If the report index already has
          a test result with the same test name, this method generates
          another one based on it.



   .. py:method:: get_test_name(testsuite_name: str, testcase_name: str, classname: Optional[str] = None) -> str

      Combine xUnit testsuite/testcase names into a unique test name.

      :param testsuite_name: Name associated with a xUnit <testsuite>
          element.
      :param testcase_name: Name associated with a xUnit <testcase> element.
      :param classname: If applicable, name of the class that owns this
          testcase.



.. py:function:: read_xfails_from_yaml(filename: str) -> dict[str, str]

   Read a XFAILs dict from a YAML file.

   See the "xfails" parameter for XUnitImporter's constructor for the expected
   YAML structure.


.. py:function:: convert_main(argv: list[str] | None = None) -> None