testsuite.report.xunit ====================== .. py:module:: testsuite.report.xunit .. autoapi-nested-parse:: Helpers to generate testsuite reports using the XUnit XML format. Classes ------- .. autoapisummary:: testsuite.report.xunit.AttachmentsSettings testsuite.report.xunit.XUnitImporter testsuite.report.xunit.XUnitImporterApp Functions --------- .. autoapisummary:: testsuite.report.xunit.add_time_attribute testsuite.report.xunit.escape_text testsuite.report.xunit.postprocess_log testsuite.report.xunit.dump_xunit_report testsuite.report.xunit.read_xfails_from_yaml 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:class:: AttachmentsSettings Settings for the creation of attachments of XUnit reports. Some platforms, such as GitLab, have restrictions on the size of XUnit reports. To accomodate testsuite results which have big logs for these platforms, we allow to write logs whose size exceed a given threshold as separate files in a given directory, and put a reference to these files as [[ATTACHMENT|/path/to/some/file]] stubs in the XUnit report itself. .. py:attribute:: output_directory :type: str Output directory for attachments. .. py:attribute:: relative_root_directory :type: str Root directory for attachments: references to attachment files mentioned in the XUnit report will be relative to this directory. .. py:attribute:: log_size_threshold :type: int Logs larger than this size (in bytes) are written to separate files (i.e. are turned into attachments). .. py:attribute:: output_dir_argname :type: ClassVar[str] :value: '--xunit-attachments-output-dir' .. py:attribute:: relative_root_dir_argname :type: ClassVar[str] :value: '--xunit-attachments-relative-root-dir' .. py:attribute:: threshold_argname :type: ClassVar[str] :value: '--xunit-attachments-threshold' .. py:method:: add_options(parser: argparse.ArgumentParser | argparse._ArgumentGroup) -> None :staticmethod: Add command line arguments to describe attachments settings. .. py:method:: from_args(args: argparse.Namespace, print_error: Callable[[str], None]) -> AttachmentsSettings | None :staticmethod: Create attachments settings from command line arguments. If the arguments are invalid, call ``print_error`` to display an error message and exit with status code 1. .. py:function:: postprocess_log(log: str | e3.testsuite.result.Log, attachments_settings: AttachmentsSettings | None) -> str Refine a log for inclusion in a XUnit report. :param log: Log to include in a report. :param attachments_settings: Parameters to control if/how logs are stored in separate attachment files. .. py:function:: dump_xunit_report(name: str, index: e3.testsuite.report.index.ReportIndex, filename: str, attachments_settings: AttachmentsSettings | None = None) -> 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. :param attachments_settings: Controls if/how to write big logs as attachment files. .. 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:attribute:: dangling_xfails :type: set[str] Set of tests for which a failure is expected, but that are not present in the testsuite report. Computed in the "run" method. .. py:method:: warn_dangling_xfails() -> None Print warnings for dangling entries in the "xfails" dict. This prints warnings on the standard output to mention all tests for which a failure is expected, but that are not present in the testsuite report. .. 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 element. :param testcase_name: Name associated with a xUnit element. :param classname: If applicable, name of the class that owns this testcase. .. py:class:: XUnitImporterApp Helper class to implement a xUnit report import script. This class provide the basic behavior, which subclasses can override if needed. .. py:attribute:: parser .. py:attribute:: args :type: argparse.Namespace .. py:attribute:: index :type: e3.testsuite.report.index.ReportIndex .. py:attribute:: xfails :type: dict[str, str] .. py:attribute:: importer :type: XUnitImporter .. py:method:: add_basic_options(parser: argparse.ArgumentParser) -> None Add basic command line arguments. Subclasses must override this to replace basic command line arguments. Note that most methods/properties in this class assume that these arguments are present: not adding them will likely require to override all methods/properties. .. py:method:: add_options(parser: argparse.ArgumentParser) -> None Add extra command line arguments. Subclasses must override this to add command line arguments in addition to the basic ones. .. py:property:: output_dir :type: str Return the report output directory. .. py:method:: create_output_report_index() -> e3.testsuite.report.index.ReportIndex Create the index for the report this app must write. .. py:method:: get_xfails() -> dict[str, str] Return the "xfails" XUnitImporter constructor argument. .. py:method:: create_importer() -> XUnitImporter Create the XUnitImporter instance for this app. .. py:method:: iter_xunit_files() -> Iterable[str] Iterate through all the xUnit report files to import. .. py:property:: gaia_report_requested :type: bool Return whether a GAIA report was requested. .. py:method:: tear_down() -> None Clean up the importer. Subclasses must override this for custom behavior before the app ends. .. py:method:: run(argv: list[str] | None = None) -> None .. 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