.. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
:target: https://opensource.org/licenses/Apache-2.0
:alt: Apache 2.0 License
.. image:: https://badge.fury.io/py/mlx.xunit2rst.svg
:target: https://badge.fury.io/py/mlx.xunit2rst
:alt: PyPI packaged release
.. image:: https://github.com/melexis/xunit2rst/actions/workflows/python-package.yml/badge.svg?branch=master
:target: https://github.com/melexis/xunit2rst/actions/workflows/python-package.yml
:alt: Build status
.. image:: https://img.shields.io/badge/Documentation-published-brightgreen.svg
:target: https://melexis.github.io/xunit2rst/
:alt: Documentation
.. image:: https://codecov.io/gh/melexis/xunit2rst/coverage.svg
:target: https://codecov.io/gh/melexis/xunit2rst
:alt: Code Coverage
.. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg
:target: https://github.com/melexis/xunit2rst/issues
:alt: Contributions welcome
=======================
Documentation xunit2rst
=======================
This script can convert a JUnit/xUnit (.xml) file to a reStructuredText (.rst) file with traceable items.
.. contents:: `Contents`
:depth: 2
:local:
----
Goal
----
This script allows you to connect your test reports to your test cases via the `mlx.traceability`_ Sphinx extension.
------------
Installation
------------
.. code-block:: console
pip3 install mlx.xunit2rst
-----
Usage
-----
.. code-block:: console
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 [--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 exit
If you use the ``--only`` input argument, you should also add |sphinx_selective_exclude.eager_only|_ to the
``extensions`` list to prevent `mlx.traceability`_ from parsing the content and ignoring the effect of the
``only`` directive.
.. _`mlx.traceability`: https://pypi.org/project/mlx.traceability/
.. |sphinx_selective_exclude.eager_only| replace:: ``'sphinx_selective_exclude.eager_only'``
.. _sphinx_selective_exclude.eager_only: https://pypi.org/project/sphinx-selective-exclude/
--------
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 or skipped.
Test Result of Itemized Suites
------------------------------
Pass (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 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.
.. _content:
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:
.. code:: 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:
.. code-block:: python
traceability_relationships = {
'ext_robotframeworklog': '',
}
traceability_relationship_to_string = {
'ext_robotframeworklog': 'Details in log file',
}
traceability_external_relationship_to_url = {
'ext_robotframeworklog': 'field1#field2'
}
.. _YAML: https://yaml.org/spec/1.2.2/
.. _dictionary: https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics
.. _Multiline strings: https://yaml-multiline.info/
.. _example documentation: https://melexis.github.io/xunit2rst/generated/itest_report.html#REPORT_ITEST-ANOTHER_TEST
.. _Free test suite metadata: http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#free-test-suite-metadata
.. _html_extra_path: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path
.. _external relationship: https://melexis.github.io/sphinx-traceability-extension/configuration.html#external-relationship-to-url-translation
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.
.. _test reports: https://melexis.github.io/xunit2rst/generated/itest_report.html#test-reports
.. _add_css_file: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_css_file
.. _stylesheet: mlx/xunit2rst/assets/xunit2rst.css
Raw data
{
"_id": null,
"home_page": "https://github.com/melexis/xunit2rst",
"name": "mlx.xunit2rst",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "xUnit,JUnit,XML,reStructuredText,sphinx,rst,testing,traceability,documentation",
"author": "JasperCraeghs",
"author_email": "jce@melexis.com",
"download_url": "https://files.pythonhosted.org/packages/1a/f5/1e1e8a02483d2dd59f2e7feb204dff4dc6cd7cff12a76385927bc5bda9e0/mlx.xunit2rst-2.0.0.tar.gz",
"platform": "any",
"description": ".. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg\n :target: https://opensource.org/licenses/Apache-2.0\n :alt: Apache 2.0 License\n\n.. image:: https://badge.fury.io/py/mlx.xunit2rst.svg\n :target: https://badge.fury.io/py/mlx.xunit2rst\n :alt: PyPI packaged release\n\n.. image:: https://github.com/melexis/xunit2rst/actions/workflows/python-package.yml/badge.svg?branch=master\n :target: https://github.com/melexis/xunit2rst/actions/workflows/python-package.yml\n :alt: Build status\n\n.. image:: https://img.shields.io/badge/Documentation-published-brightgreen.svg\n :target: https://melexis.github.io/xunit2rst/\n :alt: Documentation\n\n.. image:: https://codecov.io/gh/melexis/xunit2rst/coverage.svg\n :target: https://codecov.io/gh/melexis/xunit2rst\n :alt: Code Coverage\n\n.. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg\n :target: https://github.com/melexis/xunit2rst/issues\n :alt: Contributions welcome\n\n=======================\nDocumentation xunit2rst\n=======================\n\nThis script can convert a JUnit/xUnit (.xml) file to a reStructuredText (.rst) file with traceable items.\n\n.. contents:: `Contents`\n :depth: 2\n :local:\n\n----\nGoal\n----\n\nThis script allows you to connect your test reports to your test cases via the `mlx.traceability`_ Sphinx extension.\n\n------------\nInstallation\n------------\n\n.. code-block:: console\n\n pip3 install mlx.xunit2rst\n\n-----\nUsage\n-----\n\n.. code-block:: console\n\n mlx.xunit2rst -i itest_report.xml -o my_lib_report.rst --prefix ITEST_MY_LIB-\n\n mlx.xunit2rst --help\n\n usage: xunit2rst [-h] -i INPUT_FILE -o RST_OUTPUT_FILE [--only EXPRESSION] [-s] [-p PREFIX]\n [--trim-suffix] [--unit-or-integration UNIT_OR_INTEGRATION] [-t TYPE] [-f]\n [-l LOG] [--links] [-v]\n\n\n optional arguments:\n -h, --help show this help message and exit\n -i INPUT_FILE, --input INPUT_FILE\n The input XML file\n -o RST_OUTPUT_FILE, --output RST_OUTPUT_FILE\n The output RST file\n --only EXPRESSION Expression of tags for Sphinx' `only` directive that surrounds all\n RST content. By default, no `only` directive is generated.\n -s, --itemize-suites Flag to itemize testsuite elements instead of testcase\n elements.\n -p PREFIX, --prefix PREFIX\n Optional prefix to add to item IDs\n --trim-suffix If the suffix of the --prefix argument ends with '_-' it gets\n trimmed to '-'\n --unit-or-integration UNIT_OR_INTEGRATION\n Deprecated alternative to --type; to be removed in version\n 2.0.0.\n -t TYPE, --type TYPE Optional: give value starting with 'u', 'i' or 'q' to\n explicitly define the type of test:\n unit/integration/qualification test\n -f, --failure-message\n Include the error message in case of test failure in the item's\n body.\n -l LOG, --log LOG Optional: path to the HTML log file, relative to where Sphinx\n will put the --output, to create a link to.\n --links Optional: inserts a link to the RobotFramework HTML log file\n for each test case as ext_robotframeworklog link id.\n -v, --version show program's version number and exit\n\nIf you use the ``--only`` input argument, you should also add |sphinx_selective_exclude.eager_only|_ to the\n``extensions`` list to prevent `mlx.traceability`_ from parsing the content and ignoring the effect of the\n``only`` directive.\n\n.. _`mlx.traceability`: https://pypi.org/project/mlx.traceability/\n.. |sphinx_selective_exclude.eager_only| replace:: ``'sphinx_selective_exclude.eager_only'``\n.. _sphinx_selective_exclude.eager_only: https://pypi.org/project/sphinx-selective-exclude/\n\n--------\nBehavior\n--------\n\nItemization\n===========\n\nBy default, all *testcase* elements from the input file are used to created treaceability items. This may not always be\ndesired. The ``-s, --itemize-suites`` flag lets the script itemize *testsuite* elements instead. In this case, the\n*testcase* elements will still be parsed to determine whether the testsuite passed or failed or skipped.\n\nTest Result of Itemized Suites\n------------------------------\n\nPass (passes)\n No test cases have failed. Some might be skipped.\n\nFail (fails)\n At least one test case has failed.\n\nSkip (skipped)\n All test cases have been skipped.\n\nItem IDs\n========\n\nThe *name* attribute of the element to be itemized is used to build the item ID. Lower case letters get converted to\nupper case, whitespaces get converted to underscores, and *&* characters get converted to *AND*. A valid prefix must\nend with a hyphen to be recognized by the script. If there is an additional string prepended to this name by means of a\ndot, this string won't be taken into account. Example below:\n\n``MY_LIB.ITEST_MY_LIB-my function & keyword`` XML element name results in item ID\n``ITEST_MY_LIB-MY_FUNCTION_AND_KEYWORD``\n\nPrefix\n======\n\nTraceability item IDs have a prefix that is unique for the group they belong to, e.g. *ITEST_MY_LIB-*. The ``--prefix``\ninput argument lets you configure this prefix. It will be prepended to the item names found in the input file to build\nthe item ID. By default, the script adds *ITEST-* or *UTEST-* for integration or unit test reports, unless the prefixes\nalready exist in the input file.\n\nDistinction Between Unit and Integration Test Reports\n=====================================================\n\nTest reports that have a *testsuites* element as root in XML are treated as unit test reports. Otherwise the script\ntreats the input file as an integration test report. This discerning behavior gets overridden when prefixes are found in\nthe input file or the ``--prefix`` input argument is used. The script looks for a *U* or *I* as the first letter of the\nprefix. Lastly, you can explicitly define the type by using the ``--type`` input argument.\nIts value should start with *u* or *i* and gets parsed case-insensitively.\n\nInclude Message of Failure(s)\n=============================\n\nWhen the ``-f, --failure-message`` flag is set, the tool includes the messages of all failures and reasons for skipping\nof the item's test cases in its body.\n\n.. _content:\n\nAdd Content to Test Reports\n===========================\n\nExtra reStructuredText content for the generated test reports can be defined in a YAML_ file that contains a\nmapping, aka `dictionary`_, of case insensitive test case names (or test suite names for ``-s, --itemize-suites``) as\nkeys and reStructuredText strings as values. `Multiline strings`_ are supported. This feature is used in the `example\ndocumentation`_.\n\nThe path to the YAML file, an absolute path or relative to the input XML file, must be added as a metadata element to\nthe XML content, with the string ``xunit2rst content file`` as name and the path as value.\n\nExamples of valid metadata in XML:\n\n.. code:: xml\n\n <properties>\n <property name=\"xunit2rst content file\" value=\"../extra_content.yml\"/>\n </properties>\n\n <traits>\n <trait name=\"xUnit2rst Content File\" value=\"/home/user/git/test_project/extra_content.yml\"/>\n </traits>\n\nWhen using Robot Framework v5 or greater, this path can be provided as `Free test suite metadata`_.\n\nLinks to Log File\n=================\n\nUse input parameter ``-l, --log PATH_TO_FILE`` to add a link to the HTML log file. This path should be relative to the\nlocation where Sphinx outputs the HTML version of the RST file generated by this tool. Be sure to put this log file\nin Sphinx' source directory and add it to html_extra_path_ in your *conf.py*. This way, the log file will end up in\nthe root of Sphinx' output location.\n\nThe ``--links`` flag adds a link to each generated traceability item in the form of an `external relationship`_.\nThis requires you to configure the relationship `ext_robotframeworklog` in your *conf.py* like this:\n\n.. code-block:: python\n\n traceability_relationships = {\n 'ext_robotframeworklog': '',\n }\n traceability_relationship_to_string = {\n 'ext_robotframeworklog': 'Details in log file',\n }\n traceability_external_relationship_to_url = {\n 'ext_robotframeworklog': 'field1#field2'\n }\n\n.. _YAML: https://yaml.org/spec/1.2.2/\n.. _dictionary: https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics\n.. _Multiline strings: https://yaml-multiline.info/\n.. _example documentation: https://melexis.github.io/xunit2rst/generated/itest_report.html#REPORT_ITEST-ANOTHER_TEST\n.. _Free test suite metadata: http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#free-test-suite-metadata\n.. _html_extra_path: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path\n.. _external relationship: https://melexis.github.io/sphinx-traceability-extension/configuration.html#external-relationship-to-url-translation\n\nColor Test Results\n==================\n\nYou can highlight each test result (pass, fail and skip) in a different color so that they stand out\nmore from the rest of the report.\nThe element with the test result text contains two classes: `xunit2rst` and the test result itself.\nFor HTML documentation, you can use the CSS stylesheet_, provided with the Python package,\nby passing it to Sphinx with `add_css_file`_, or by adding its contents manually to your own stylesheet.\n\nThis feature is demonstrated in the `test reports`_ of the example documentation.\n\n.. _test reports: https://melexis.github.io/xunit2rst/generated/itest_report.html#test-reports\n.. _add_css_file: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_css_file\n.. _stylesheet: mlx/xunit2rst/assets/xunit2rst.css\n",
"bugtrack_url": null,
"license": "Apache License Version 2.0",
"summary": "Python script for converting xUnit/JUnit XML format to reStructuredText (.rst) with traceable items",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/melexis/xunit2rst"
},
"split_keywords": [
"xunit",
"junit",
"xml",
"restructuredtext",
"sphinx",
"rst",
"testing",
"traceability",
"documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c959ef690eec0315e0d04de994e53df2ef7f200706759fa56200dbcdfadfa6a4",
"md5": "157f3f95027a47a172fd7d45ca86a6c3",
"sha256": "80afd000befe7af5969804ce8699d7c547b43b4b76b60cae0a38d77d6514df2a"
},
"downloads": -1,
"filename": "mlx.xunit2rst-2.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "157f3f95027a47a172fd7d45ca86a6c3",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 22445,
"upload_time": "2024-01-12T22:19:02",
"upload_time_iso_8601": "2024-01-12T22:19:02.750990Z",
"url": "https://files.pythonhosted.org/packages/c9/59/ef690eec0315e0d04de994e53df2ef7f200706759fa56200dbcdfadfa6a4/mlx.xunit2rst-2.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1af51e1e8a02483d2dd59f2e7feb204dff4dc6cd7cff12a76385927bc5bda9e0",
"md5": "908845d6bac43d5e84c52ac7462841de",
"sha256": "4b65673832189c42ea05d96ca04207968f7c77706477779598ce326c8baed450"
},
"downloads": -1,
"filename": "mlx.xunit2rst-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "908845d6bac43d5e84c52ac7462841de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35262,
"upload_time": "2024-01-12T22:19:04",
"upload_time_iso_8601": "2024-01-12T22:19:04.297139Z",
"url": "https://files.pythonhosted.org/packages/1a/f5/1e1e8a02483d2dd59f2e7feb204dff4dc6cd7cff12a76385927bc5bda9e0/mlx.xunit2rst-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-12 22:19:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "melexis",
"github_project": "xunit2rst",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "mlx.xunit2rst"
}
JSON
