testsuite.report.xunit

Helpers to generate testsuite reports using the XUnit XML format.

Classes

`AttachmentsSettings`	Settings for the creation of attachments of XUnit reports.
`XUnitImporter`	Helper class to import results in a xUnit report into a report index.
`XUnitImporterApp`	Helper class to implement a xUnit report import script.

Functions

`add_time_attribute`(→ None)	Optionally add a "time" attribute.
`escape_text`(→ str)	Escape non-printable characters from a string.
`postprocess_log`(→ str)	Refine a log for inclusion in a XUnit report.
`dump_xunit_report`(→ None)	Dump a testsuite report to filename in the standard XUnit XML format.
`read_xfails_from_yaml`(→ dict[str, str])	Read a XFAILs dict from a YAML file.
`convert_main`(→ None)

Module Contents

testsuite.report.xunit.add_time_attribute(elt: xml.etree.ElementTree.Element, duration: float | None) → None

Optionally add a “time” attribute.

If duration is a float, add the corresponding “time” attribute to elt.

testsuite.report.xunit.escape_text(text: str) → str

Escape non-printable characters from a string.

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

class testsuite.report.xunit.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.

output_directory: str: Output directory for attachments.

relative_root_directory: str: Root directory for attachments: references to attachment files mentioned in the XUnit report will be relative to this directory.

log_size_threshold: int: Logs larger than this size (in bytes) are written to separate files (i.e. are turned into attachments).

output_dir_argname: ClassVar[str] = '--xunit-attachments-output-dir'

relative_root_dir_argname: ClassVar[str] = '--xunit-attachments-relative-root-dir'

threshold_argname: ClassVar[str] = '--xunit-attachments-threshold'

static add_options(parser: argparse.ArgumentParser | argparse._ArgumentGroup) → None: Add command line arguments to describe attachments settings.

static from_args(args: argparse.Namespace, print_error: Callable[[str], None]) → AttachmentsSettings | None

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.

testsuite.report.xunit.postprocess_log(log: str | e3.testsuite.result.Log, attachments_settings: AttachmentsSettings | None) → str

Refine a log for inclusion in a XUnit report.

Parameters:

log – Log to include in a report.
attachments_settings – Parameters to control if/how logs are stored in separate attachment files.

testsuite.report.xunit.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.

Parameters:

name – Name for the teststuite report.
index – Report index for the testsuite results to report.
filename – Name of the text file to write.
duration – Optional number of seconds for the total duration of the testsuite run.
attachments_settings – Controls if/how to write big logs as attachment files.

class testsuite.report.xunit.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.

index

xfails

dangling_xfails: 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.

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.

run(filename: str) → None

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

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

SLUG_RE

slugify(name: str) → str

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

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

get_unique_test_name(test_name: str) → str

Return a test name that is guaranteed to be unique.

Parameters:: 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.

get_test_name(testsuite_name: str, testcase_name: str, classname: str | None = None) → str

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

Parameters:

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

class testsuite.report.xunit.XUnitImporterApp

Helper class to implement a xUnit report import script.

This class provide the basic behavior, which subclasses can override if needed.

parser

args: argparse.Namespace

index: e3.testsuite.report.index.ReportIndex

xfails: dict[str, str]

importer: XUnitImporter

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.

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.

property output_dir: str: Return the report output directory.

create_output_report_index() → e3.testsuite.report.index.ReportIndex: Create the index for the report this app must write.

get_xfails() → dict[str, str]: Return the “xfails” XUnitImporter constructor argument.

create_importer() → XUnitImporter: Create the XUnitImporter instance for this app.

iter_xunit_files() → Iterable[str]: Iterate through all the xUnit report files to import.

property gaia_report_requested: bool: Return whether a GAIA report was requested.

tear_down() → None

Clean up the importer.

Subclasses must override this for custom behavior before the app ends.

run(argv: list[str] | None = None) → None

testsuite.report.xunit.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.

testsuite.report.xunit.convert_main(argv: list[str] | None = None) → None