.. _UNITTEST:

Unit Test Summary
#################

🚧 This is a work-in-progress feature. 🚧

.. #:term:`Unittests` checks if a source code was used during execution. Usually, testcases are run by a testcase
   execution framework like `pytest <https://github.com/pytest-dev/pytest>`__.

.. rubric:: Supported report generators

* `pytest <https://github.com/pytest-dev/pytest>`__
* `OSVVM-Scripts <https://github.com/OSVVM/OSVVM-Scripts>`__


.. _UNITTEST/Quick:

Quick Configuration
*******************

See the :ref:`overview page <OVER>` on how to setup and enable the Sphinx extension in general.

.. note:: This is a quick and minimal configuration. See below detailed explanations.

1. Configure one or more unitest summary reports in :file:`conf.py` by adding a new 'section' defining some
   configuration variables. Each summary report is identified by an ID, which is later referred to by the report
   directive. Here, the ID is called ``src`` (dictionary key). Each analysis report needs 2 configuration entries:

   ``name``
     Name of the Python package[#PkgNameVsPkgDir]_.

   ``xml_report``
     The code coverage report as JSON file as generated by *Coverage.py*.

   .. code-block:: Python

      # ==============================================================================
      # Sphinx-reports - Unittest
      # ==============================================================================
      report_codecov_packages = {
         "src": {
            "name":       "myPackage",
            "xml_report": "../report/unit/unittest.xml",
         }
      }

2. Add the :rst:dir:`report:unittest-summary` directive into your Restructured Text (ReST) document.

   .. code-block:: ReST

      .. report:unittest-summary::
         :reportid: src


.. _UNITTEST/Example:

Example Document
****************

The following ``unittest/index`` document is an example on how this documentation uses the :rst:dir:`report:unittest-summary`
directive. The first file consists of three parts: At first, a headline; at second second a short introduction paragraph
and at third, the report generating directive. The second file shows how to integrate that document into the navigation
bar.

.. admonition:: :file:`unittest/index.rst`

   .. code-block:: ReST

      Unittest Summary Report
      #######################

      Code coverage report generated with `pytest <https://github.com/pytest-dev/pytest>`__.

      .. report:unittest-summary::
         :reportid: src

.. admonition:: :file:`index.rst`

   .. code-block:: ReST

      .. toctree::
         :caption: References and Reports
         :hidden:

         Python Class Reference <sphinx_reports/sphinx_reports>
         unittests/index
         coverage/index
         Doc. Coverage Report <DocCoverage>
         Static Type Check Report ➚ <typing/index>

      .. toctree::
         :caption: Appendix
         :hidden:


.. _UNITTEST/Directives:

Directives
**********

.. rst:directive:: report:unittest-summary

   Add a table summarizing the unittest results.

   .. rst:directive:option:: reportid

      An identifier referencing a dictionary entry in the configuration variable ``report_unittest_testsuites`` defined
      in :file:`conf.py`.

   .. rst:directive:option:: no-assertions

      If flag is present, no assertions column with be shown.


.. _UNITTEST/Roles:

Roles
*****

*There are no roles defined.*