Package: mlx.xunit2rst
Documentation xunit2rstThis script can convert a JUnit/xUnit (.xml) file to a reStructuredText (.rst) file with traceable items.ContentsGoalInstallationUsageBehaviorItemizationItem IDsPrefixDistinction Between Unit and Integration Test ReportsInclude Message of Failure(s)Add Content to Test ReportsLinks to Log FileColor Test ResultsGoalThis script allows you to connect your test reports to your test cases via themlx.traceabilitySphinx extension.Installationpip3 install mlx.xunit2rstUsagemlx.xunit2rst -i itest_report.xml -o my_lib_report.rst --prefix ITEST_MY_LIB-

mlx.xunit2rst --help

usage: xunit2rst [-h] -i INPUT_FILE -o RST_OUTPUT_FILE [--only EXPRESSION] [-s] [-p PREFIX]
                 [--trim-suffix] [--unit-or-integration UNIT_OR_INTEGRATION] [-t TYPE] [-f]
                 [-l LOG] [--links] [-v]


optional arguments:
  -h, --help            show this help message and exit
  -i INPUT_FILE, --input INPUT_FILE
                        The input XML file
  -o RST_OUTPUT_FILE, --output RST_OUTPUT_FILE
                        The output RST file
  --only EXPRESSION     Expression of tags for Sphinx' `only` directive that surrounds all
                        RST content. By default, no `only` directive is generated.
  -s, --itemize-suites  Flag to itemize testsuite elements instead of testcase
                        elements.
  -p PREFIX, --prefix PREFIX
                        Optional prefix to add to item IDs
  --trim-suffix         If the suffix of the --prefix argument ends with '_-' it gets
                        trimmed to '-'
  --unit-or-integration UNIT_OR_INTEGRATION
                        Deprecated alternative to --type; to be removed in version
                        2.0.0.
  -t TYPE, --type TYPE  Optional: give value starting with 'u', 'i' or 'q' to
                        explicitly define the type of test:
                        unit/integration/qualification test
  -f, --failure-message
                        Include the error message in case of test failure in the item's
                        body.
  -l LOG, --log LOG     Optional: path to the HTML log file, relative to where Sphinx
                        will put the --output, to create a link to.
  --links               Optional: inserts a link to the RobotFramework HTML log file
                        for each test case as ext_robotframeworklog link id.
  -v, --version         show program's version number and exitIf you use the--onlyinput argument, you should also add'sphinx_selective_exclude.eager_only'to theextensionslist to preventmlx.traceabilityfrom parsing the content and ignoring the effect of theonlydirective.BehaviorItemizationBy default, alltestcaseelements from the input file are used to created treaceability items. This may not always be
desired. The-s,--itemize-suitesflag lets the script itemizetestsuiteelements instead. In this case, thetestcaseelements will still be parsed to determine whether the testsuite passed or failed or skipped.Test Result of Itemized SuitesPass (passes)No test cases have failed. Some might be skipped.Fail (fails)At least one test case has failed.Skip (skipped)All test cases have been skipped.Item IDsThenameattribute of the element to be itemized is used to build the item ID. Lower case letters get converted to
upper case, whitespaces get converted to underscores, and&characters get converted toAND. A valid prefix must
end with a hyphen to be recognized by the script. If there is an additional string prepended to this name by means of a
dot, this string won’t be taken into account. Example below:MY_LIB.ITEST_MY_LIB-myfunction & keywordXML element name results in item IDITEST_MY_LIB-MY_FUNCTION_AND_KEYWORDPrefixTraceability item IDs have a prefix that is unique for the group they belong to, e.g.ITEST_MY_LIB-. The--prefixinput argument lets you configure this prefix. It will be prepended to the item names found in the input file to build
the item ID. By default, the script addsITEST-orUTEST-for integration or unit test reports, unless the prefixes
already exist in the input file.Distinction Between Unit and Integration Test ReportsTest reports that have atestsuiteselement as root in XML are treated as unit test reports. Otherwise the script
treats the input file as an integration test report. This discerning behavior gets overridden when prefixes are found in
the input file or the--prefixinput argument is used. The script looks for aUorIas the first letter of the
prefix. Lastly, you can explicitly define the type by using the--typeinput argument.
Its value should start withuoriand gets parsed case-insensitively.Include Message of Failure(s)When the-f,--failure-messageflag is set, the tool includes the messages of all failures and reasons for skipping
of the item’s test cases in its body.Add Content to Test ReportsExtra reStructuredText content for the generated test reports can be defined in aYAMLfile that contains a
mapping, akadictionary, of case insensitive test case names (or test suite names for-s,--itemize-suites) as
keys and reStructuredText strings as values.Multiline stringsare supported. This feature is used in theexample
documentation.The path to the YAML file, an absolute path or relative to the input XML file, must be added as a metadata element to
the XML content, with the stringxunit2rst content fileas name and the path as value.Examples of valid metadata in XML:<properties><propertyname="xunit2rst content file"value="../extra_content.yml"/></properties><traits><traitname="xUnit2rst Content File"value="/home/user/git/test_project/extra_content.yml"/></traits>When using Robot Framework v5 or greater, this path can be provided asFree test suite metadata.Links to Log FileUse input parameter-l,--logPATH_TO_FILEto add a link to the HTML log file. This path should be relative to the
location where Sphinx outputs the HTML version of the RST file generated by this tool. Be sure to put this log file
in Sphinx’ source directory and add it tohtml_extra_pathin yourconf.py. This way, the log file will end up in
the root of Sphinx’ output location.The--linksflag adds a link to each generated traceability item in the form of anexternal relationship.
This requires you to configure the relationshipext_robotframeworklogin yourconf.pylike this:traceability_relationships={'ext_robotframeworklog':'',}traceability_relationship_to_string={'ext_robotframeworklog':'Details in log file',}traceability_external_relationship_to_url={'ext_robotframeworklog':'field1#field2'}Color Test ResultsYou can highlight each test result (pass, fail and skip) in a different color so that they stand out
more from the rest of the report.
The element with the test result text contains two classes:xunit2rstand the test result itself.
For HTML documentation, you can use the CSSstylesheet, provided with the Python package,
by passing it to Sphinx withadd_css_file, or by adding its contents manually to your own stylesheet.This feature is demonstrated in thetest reportsof the example documentation.