mlx.xunit2rst 2.0.0

Itemization

By default, all testcase elements from the input file are used to created treaceability items. This may not always be desired. The -s, --itemize-suites flag lets the script itemize testsuite elements instead. In this case, the testcase elements will still be parsed to determine whether the testsuite passed or failed or skipped.

Item IDs

The name attribute 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 to AND. 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-my function & keyword XML element name results in item ID ITEST_MY_LIB-MY_FUNCTION_AND_KEYWORD

Prefix

Traceability item IDs have a prefix that is unique for the group they belong to, e.g. ITEST_MY_LIB-. The --prefix input 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 adds ITEST- or UTEST- for integration or unit test reports, unless the prefixes already exist in the input file.

Distinction Between Unit and Integration Test Reports

Test reports that have a testsuites element 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 --prefix input argument is used. The script looks for a U or I as the first letter of the prefix. Lastly, you can explicitly define the type by using the --type input argument. Its value should start with u or i and gets parsed case-insensitively.

Include Message of Failure(s)

When the -f, --failure-message flag 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 Reports

Extra reStructuredText content for the generated test reports can be defined in a YAML file that contains a mapping, aka dictionary, of case insensitive test case names (or test suite names for -s, --itemize-suites) as keys and reStructuredText strings as values. Multiline strings are supported. This feature is used in the example 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 string xunit2rst content file as name and the path as value.

Examples of valid metadata in XML:

<properties>
  <property name="xunit2rst content file" value="../extra_content.yml"/>
</properties>

<traits>
  <trait name="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 as Free test suite metadata.

Links to Log File

Use input parameter -l, --log PATH_TO_FILE to 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 to html_extra_path in your conf.py. This way, the log file will end up in the root of Sphinx’ output location.

The --links flag adds a link to each generated traceability item in the form of an external relationship. This requires you to configure the relationship ext_robotframeworklog in your conf.py like 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 Results

You 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: xunit2rst and the test result itself. For HTML documentation, you can use the CSS stylesheet, provided with the Python package, by passing it to Sphinx with add_css_file, or by adding its contents manually to your own stylesheet.

This feature is demonstrated in the test reports of the example documentation.