Python script for converting xUnit/JUnit XML format to reStructuredText (.rst) with traceable items
Project description
Documentation xunit2rst
This script can convert a JUnit/xUnit (.xml) file to a reStructuredText (.rst) file with traceable items.
Goal
This script allows you to connect your test reports to your test cases via the mlx.traceability Sphinx extension.
Installation
pip3 install mlx.xunit2rst
Usage
mlx.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 [-s] [-p PREFIX]
[--trim-suffix] [--unit-or-integration UNIT_OR_INTEGRATION]
[-f] [-l LOG] [-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
-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
Optional: give value starting with 'u' or 'i' if the
the script's discernment is wrong.
-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.
-v, --version show program's version number and exit
Behavior
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.
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 --unit-or-integration 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 of the item’s test cases in its body.
Link 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mlx.xunit2rst-0.8.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a9998fd63674ea378fae52dbd8e7e6d545b34ea59fec1359286fcf21563400a2 |
|
MD5 | 4189669097990bae4d960af16d78fc79 |
|
BLAKE2b-256 | c0e27a77401d9c5b7e8cc469af1ccc4242cf71aab3b95e9c4ea339c1e957bebb |